From 1b6c764ac5d87fd9b6997488fa3547e1cd4afa12 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Sun, 15 Nov 2026 16:30:08 +0000 Subject: [PATCH] Update ASPIRECOMPUTE002 docs for narrowed scope --- .../docs/diagnostics/aspirecompute002.mdx | 58 ++++++++----------- .../src/content/docs/diagnostics/overview.mdx | 2 +- 2 files changed, 25 insertions(+), 35 deletions(-) diff --git a/src/frontend/src/content/docs/diagnostics/aspirecompute002.mdx b/src/frontend/src/content/docs/diagnostics/aspirecompute002.mdx index 2b34602f58..8554c81416 100644 --- a/src/frontend/src/content/docs/diagnostics/aspirecompute002.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspirecompute002.mdx @@ -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'; -> The 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 + -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 @@ -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 ``` diff --git a/src/frontend/src/content/docs/diagnostics/overview.mdx b/src/frontend/src/content/docs/diagnostics/overview.mdx index b7ee24986a..5fbeaf39e5 100644 --- a/src/frontend/src/content/docs/diagnostics/overview.mdx +++ b/src/frontend/src/content/docs/diagnostics/overview.mdx @@ -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. |