Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 24 additions & 34 deletions src/frontend/src/content/docs/diagnostics/aspirecompute002.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
---
title: Compiler Warning ASPIRECOMPUTE002
seoTitle: "ASPIRECOMPUTE002: The GetHostAddressExpression method is for"
seoTitle: "ASPIRECOMPUTE002: Kubernetes persistent volume APIs are for"
description: Learn what causes the Aspire compiler warning ASPIRECOMPUTE002 and how to fix it so your AppHost builds cleanly.
---

import { Badge } from '@astrojs/starlight/components';
import ApiReference from '@components/ApiReference.astro';
import { Aside, Badge } from '@astrojs/starlight/components';

<Badge
text="Version introduced: 13.0"
Expand All @@ -14,39 +13,33 @@ import ApiReference from '@components/ApiReference.astro';
class:list={'mb-1'}
/>

> The <ApiReference name="Aspire.Hosting.Docker.DockerComposeEnvironmentResource.GetHostAddressExpression" /> method is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
> Kubernetes persistent volume APIs are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed.

This diagnostic warning is reported when using the experimental `GetHostAddressExpression` method from the `IComputeEnvironmentResource` interface.
This diagnostic warning is reported when using the experimental Kubernetes persistent volume APIs: `KubernetesPersistentVolumeExtensions`, `KubernetesPersistentVolumeResource`, `PersistentVolumeAccessMode`, and `AzureKubernetesPersistentVolumeExtensions`.

## Example
<Aside type="note">
Starting in Aspire 17.0, the compute environment endpoint-mapping contracts `IComputeEnvironmentResource.GetHostAddressExpression` and `IComputeEnvironmentResource.GetEndpointPropertyExpression` are stable and no longer report `ASPIRECOMPUTE002`. You can remove suppressions that were added only for those members. Suppressions for persistent volume APIs are still required.
</Aside>

The following code generates `ASPIRECOMPUTE002`:
## Endpoint-mapping contracts

```csharp title="Using GetHostAddressExpression"
var builder = DistributedApplication.CreateBuilder(args);

var computeEnv = builder.AddAzureContainerAppEnvironment("env");

// Accessing GetHostAddressExpression on a compute environment resource
var endpoint = computeEnv.Resource.GetEndpoint("http");
var hostAddress = computeEnv.Resource.GetHostAddressExpression(endpoint);
```

## Understanding GetHostAddressExpression
`GetHostAddressExpression` returns a `ReferenceExpression` for the host only, without scheme, port, or path. It isn't a full URL. `GetEndpointPropertyExpression` composes the host, scheme, and port expressions by default, and compute environments can override it with platform-specific mappings.

The `GetHostAddressExpression` method is part of the `IComputeEnvironmentResource` interface and provides a way to retrieve the host address or hostname for a specified endpoint reference as a `ReferenceExpression`.
The default `GetHostAddressExpression` implementation throws `NotImplementedException`, so environments that don't provide host mapping (for example, `AzureKubernetesEnvironmentResource`) still inherit that behavior.

### Key characteristics

- **Returns host only** — The returned value contains only the hostname or address, without scheme, port, or path information
- **Reference expression** — Returns a `ReferenceExpression` that can be evaluated in different contexts
- **Compute environment specific** — Designed for use with compute environment resources like Azure Container Apps, Kubernetes, or Docker Compose
```csharp title="No suppression required"
var builder = DistributedApplication.CreateBuilder(args);

This method is useful when you need to configure resources with just the hostname rather than a full URL, which is common in scenarios like:
var environment = builder.AddDockerComposeEnvironment("env");
var api = builder.AddContainer("api", "nginx")
.WithHttpEndpoint(targetPort: 80);

- Configuring service-to-service communication within a compute environment
- Setting up DNS-based service discovery
- Configuring load balancers or ingress controllers
IComputeEnvironmentResource compute = environment.Resource;
var endpoint = api.GetEndpoint("http");
ReferenceExpression host = compute.GetHostAddressExpression(endpoint);
ReferenceExpression url = compute.GetEndpointPropertyExpression(
endpoint.Property(EndpointProperty.Url));
```

## To suppress this warning

Expand All @@ -72,13 +65,10 @@ Suppress the warning with either of the following methods:
- Suppress in code with the `#pragma warning disable ASPIRECOMPUTE002` directive:

```csharp title="Suppressing the warning"
var builder = DistributedApplication.CreateBuilder(args);

var computeEnv = builder.AddAzureContainerAppEnvironment("env");

#pragma warning disable ASPIRECOMPUTE002
var endpoint = computeEnv.Resource.GetEndpoint("http");
var hostAddress = computeEnv.Resource.GetHostAddressExpression(endpoint);
var k8s = builder.AddKubernetesEnvironment("k8s");
var data = k8s.AddPersistentVolume("data")
.WithAccessMode(PersistentVolumeAccessMode.ReadWriteOnce);
#pragma warning restore ASPIRECOMPUTE002
```

Expand Down
2 changes: 1 addition & 1 deletion src/frontend/src/content/docs/diagnostics/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ The following table lists the possible MSBuild and analyzer warnings and errors
| [ASPIRECERTIFICATES001](/diagnostics/aspirecertificates001/) | (Experimental) Warning | Certificate configuration types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIRECOMMAND001](/diagnostics/aspirecommand001/) | (Experimental) Warning | Required command validation types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIRECOMPUTE001](/diagnostics/aspirecompute001/) | (Experimental) Error | Compute related types and members are for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECOMPUTE002](/diagnostics/aspirecompute002/) | (Experimental) Warning | The GetHostAddressExpression method is for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECOMPUTE002](/diagnostics/aspirecompute002/) | (Experimental) Warning | Kubernetes persistent volume APIs are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIRECOMPUTE003](/diagnostics/aspirecompute003/) | (Experimental) Warning | The ContainerRegistryResource type is for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECONTAINERRUNTIME001](/diagnostics/aspirecontainerruntime001/) | (Experimental) Warning | Type is for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECONTAINERSHELLEXECUTION001](/diagnostics/aspirecontainershellexecution001/) | (Experimental) Warning | Container shell execution property is for evaluation purposes only and is subject to change or removal in future updates. |
Expand Down
Loading