Skip to content
Merged
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
10 changes: 0 additions & 10 deletions src/frontend/src/content/docs/app-host/withdockerfile.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -129,12 +129,6 @@ await pgsql.withPgAdmin(); // Still works because it's still a PostgreSQL resour

Use <ApiReference name="Aspire.Hosting.ContainerResourceBuilderExtensions.AddDockerfileBuilder" /> or <ApiReference name="Aspire.Hosting.ContainerResourceBuilderExtensions.WithDockerfileBuilder" /> when you need Aspire to generate a Dockerfile from AppHost code. These APIs are useful when the Dockerfile depends on AppHost configuration, when you want to compose Dockerfile fragments, or when you want to keep multi-stage image build logic near the resource definition.

<Aside type="caution">
The Dockerfile builder APIs are experimental and may change in future
releases. In C# AppHosts, suppress diagnostic
[`ASPIREDOCKERFILEBUILDER001`](/diagnostics/aspiredockerfilebuilder001/) when you choose to use them.
</Aside>

`AddDockerfileBuilder` creates a new container resource and configures the generated Dockerfile in one step:

<Tabs syncKey='aspire-lang'>
Expand All @@ -144,7 +138,6 @@ using Aspire.Hosting.ApplicationModel.Docker;

var builder = DistributedApplication.CreateBuilder(args);

#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddDockerfileBuilder("frontend", "../frontend", context =>
{
var build = context.Builder.From("node:22-alpine", "build");
Expand All @@ -160,7 +153,6 @@ builder.AddDockerfileBuilder("frontend", "../frontend", context =>

return Task.CompletedTask;
}, stage: "runtime");
#pragma warning restore ASPIREDOCKERFILEBUILDER001

builder.Build().Run();
```
Expand Down Expand Up @@ -207,7 +199,6 @@ using Aspire.Hosting.ApplicationModel.Docker;

var builder = DistributedApplication.CreateBuilder(args);

#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddContainer("frontend", "nginx:alpine")
.WithDockerfileBuilder("../frontend", context =>
{
Expand All @@ -217,7 +208,6 @@ builder.AddContainer("frontend", "nginx:alpine")

return Task.CompletedTask;
}, stage: "runtime");
#pragma warning restore ASPIREDOCKERFILEBUILDER001

builder.Build().Run();
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,8 @@ During publishing and deployment, the container image manager is available to cr

These APIs give you fine-grained control over the image building process and provide real-time feedback to users during lengthy build operations.

<Aside type="note">
These APIs are designed for advanced scenarios where you need custom control
over container image building and progress reporting. For more information,
see [Compiler Error ASPIREPIPELINES001](/diagnostics/aspirepipelines001/) and
[Compiler Error ASPIREPIPELINES003](/diagnostics/aspirepipelines003/).
</Aside>
Some pipeline APIs remain experimental. See
[Compiler Error ASPIREPIPELINES003](/diagnostics/aspirepipelines003/).

## When to use these APIs

Expand Down
8 changes: 0 additions & 8 deletions src/frontend/src/content/docs/deployment/docker-compose.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -222,12 +222,6 @@ If you commit these artifacts to source control, you can check that they stay in

Docker Compose deployments can build images from Dockerfiles that are generated by your AppHost. Use <ApiReference name="Aspire.Hosting.ContainerResourceBuilderExtensions.AddDockerfileBuilder" /> to create a new container resource from a generated Dockerfile, or <ApiReference name="Aspire.Hosting.ContainerResourceBuilderExtensions.WithDockerfileBuilder" /> to replace the image for an existing container resource with a generated Dockerfile build.

<Aside type="caution">
The Dockerfile builder APIs are experimental and may change in future
releases. In C# AppHosts, suppress diagnostic
[`ASPIREDOCKERFILEBUILDER001`](/diagnostics/aspiredockerfilebuilder001/) when you choose to use them.
</Aside>

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
```csharp title="AppHost.cs"
Expand All @@ -237,7 +231,6 @@ var builder = DistributedApplication.CreateBuilder(args);

builder.AddDockerComposeEnvironment("env");

#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddDockerfileBuilder("frontend", "../frontend", context =>
{
var build = context.Builder.From("node:22-alpine", "build");
Expand All @@ -253,7 +246,6 @@ builder.AddDockerfileBuilder("frontend", "../frontend", context =>

return Task.CompletedTask;
}, stage: "runtime");
#pragma warning restore ASPIREDOCKERFILEBUILDER001

builder.Build().Run();
```
Expand Down
18 changes: 0 additions & 18 deletions src/frontend/src/content/docs/deployment/javascript-apps.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,6 @@ To deploy a JavaScript app, choose which resource owns the public HTTP surface i
- Use a JavaScript publish method when the JavaScript app resource should become the deployed static website or Node.js server.
- Use `AddNextJsApp(...)` for a Next.js app that publishes as a standalone Next.js server.

:::caution[Experimental]
The JavaScript app resource publish methods and `AddNextJsApp` are marked `[Experimental]` and require suppressing the `ASPIREJAVASCRIPT001` diagnostic.
:::

If you only add a Vite or JavaScript app and reference backend services, Aspire still needs one of these production hosting patterns to know who serves requests in deployment. During publish or deploy, Aspire validates that build-only containers are either consumed by another resource through `PublishWithContainerFiles(...)` or `PublishWithStaticFiles(...)`, or converted into a deployable JavaScript resource with a JavaScript publish method. An unconsumed build-only container does not participate in deployment.

<Aside type="note">
Expand Down Expand Up @@ -280,8 +276,6 @@ Choose this shape instead of `PublishWithStaticFiles(...)` when you do not alrea
<TabItem id='csharp' label='C#'>

```csharp title="AppHost.cs"
#pragma warning disable ASPIREJAVASCRIPT001

var builder = DistributedApplication.CreateBuilder(args);
builder.AddDockerComposeEnvironment("compose");

Expand Down Expand Up @@ -372,8 +366,6 @@ Choose this method instead of `PublishAsPackageScript` when the build output doe
<TabItem id='csharp' label='C#'>

```csharp title="AppHost.cs"
#pragma warning disable ASPIREJAVASCRIPT001

var builder = DistributedApplication.CreateBuilder(args);
builder.AddDockerComposeEnvironment("compose");

Expand Down Expand Up @@ -434,8 +426,6 @@ Choose this method instead of `PublishAsNodeServer` when the production server i
<TabItem id='csharp' label='C#'>

```csharp title="AppHost.cs"
#pragma warning disable ASPIREJAVASCRIPT001

var builder = DistributedApplication.CreateBuilder(args);
builder.AddDockerComposeEnvironment("compose");

Expand Down Expand Up @@ -496,8 +486,6 @@ The generated container sets `HOST=0.0.0.0` and `HOSTNAME=0.0.0.0` so the server
- **Bun**: The runtime stage reuses the Bun build image rather than switching to a Node.js image, because `bun run <script>` requires the Bun runtime at startup.

```csharp title="AppHost.cs — pnpm package-script publish"
#pragma warning disable ASPIREJAVASCRIPT001

var builder = DistributedApplication.CreateBuilder(args);
builder.AddDockerComposeEnvironment("compose");

Expand Down Expand Up @@ -527,8 +515,6 @@ Choose this method instead of `AddJavaScriptApp(...).PublishAsPackageScript(...)
<TabItem id='csharp' label='C#'>

```csharp title="AppHost.cs"
#pragma warning disable ASPIREJAVASCRIPT001

var builder = DistributedApplication.CreateBuilder(args);
builder.AddDockerComposeEnvironment("compose");

Expand Down Expand Up @@ -1216,8 +1202,6 @@ To disable the validation for the whole app, call `DisableBuildOnlyContainerVali
<TabItem id='csharp' label='C#'>

```csharp title="AppHost.cs"
#pragma warning disable ASPIREPIPELINES001

using Aspire.Hosting.Pipelines;

var builder = DistributedApplication.CreateBuilder(args);
Expand Down Expand Up @@ -1247,8 +1231,6 @@ await builder.build().run();
</TabItem>
</Tabs>

The `DisableBuildOnlyContainerValidation` method is marked experimental with the `ASPIREPIPELINES001` diagnostic.

`AddNextJsApp` is different because it represents the Next.js standalone-server publish model directly. Use it when the app is a Next.js app with `output: "standalone"` rather than modeling the app with `AddJavaScriptApp` and choosing a generic package-script publish method.

### Run script and existing Dockerfile conflict
Expand Down
2 changes: 0 additions & 2 deletions src/frontend/src/content/docs/deployment/pipelines.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -281,15 +281,13 @@ using Aspire.Hosting.Pipelines;

var builder = DistributedApplication.CreateBuilder(args);

#pragma warning disable ASPIREPIPELINES001
// Add custom deployment validation
builder.Pipeline.AddStep("validate-deployment", async context =>
{
// Custom validation logic
await ValidateApiHealth(context);
await ValidateDatabaseConnection(context);
}, requiredBy: WellKnownPipelineSteps.Deploy);
#pragma warning restore ASPIREPIPELINES001

// Define resources
var database = builder.AddPostgres("myapp-db");
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Compiler Warning ASPIREACANAMING001
seoTitle: 'ASPIREACANAMING001: WithCompactResourceNaming is for evaluation'
description: Learn what causes the Aspire compiler warning ASPIREACANAMING001 and how to fix it so your AppHost builds cleanly.
title: Retired compiler warning ASPIREACANAMING001
seoTitle: "ASPIREACANAMING001 retired in Aspire 17.0"
description: ASPIREACANAMING001 was retired in Aspire 17.0 when WithCompactResourceNaming became stable. Learn what to do if you still see this warning.
---

import { Badge } from '@astrojs/starlight/components';
Expand All @@ -14,6 +14,10 @@ import ApiReference from '@components/ApiReference.astro';
class:list={'mb-1'}
/>

:::note[Retired in Aspire 17.0]
Starting with Aspire 17.0, <ApiReference name="Aspire.Hosting.AzureContainerAppExtensions.WithCompactResourceNaming" /> is stable and no longer reports `ASPIREACANAMING001`. After you upgrade, remove any `ASPIREACANAMING001` suppressions from _.editorconfig_ files, project files, and `#pragma warning` directives. The rest of this page describes the diagnostic as it applied to earlier versions.
:::

> WithCompactResourceNaming is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

This diagnostic warning is reported when using the experimental <ApiReference name="Aspire.Hosting.AzureContainerAppExtensions.WithCompactResourceNaming" /> extension method on an Azure Container App environment. This API opts the environment into shorter, compact names for the volume-backing Azure Storage resources that Aspire provisions, which avoids storage-account name-length collisions when the environment name is long. It doesn't rename the Container App environment, container registry, Log Analytics workspace, or managed identity.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Compiler Error ASPIREACANAMING002
seoTitle: "ASPIREACANAMING002: WithUniqueResourceNaming is for evaluation"
description: Learn what causes the Aspire compiler error ASPIREACANAMING002 and how to fix it so your AppHost builds cleanly.
title: Retired compiler error ASPIREACANAMING002
seoTitle: "ASPIREACANAMING002 retired in Aspire 17.0"
description: ASPIREACANAMING002 was retired in Aspire 17.0 when WithUniqueResourceNaming became stable. Learn what to do if you still see this error.
---

import { Badge } from '@astrojs/starlight/components';
Expand All @@ -13,6 +13,10 @@ import { Badge } from '@astrojs/starlight/components';
class:list={'mb-1'}
/>

:::note[Retired in Aspire 17.0]
Starting with Aspire 17.0, `WithUniqueResourceNaming` is stable and no longer reports `ASPIREACANAMING002`. After you upgrade, remove any `ASPIREACANAMING002` suppressions from _.editorconfig_ files, project files, and `#pragma warning` directives. The rest of this page describes the diagnostic as it applied to earlier versions.
:::

> WithUniqueResourceNaming is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

## Example
Expand Down
10 changes: 7 additions & 3 deletions src/frontend/src/content/docs/diagnostics/aspireazure001.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Compiler Error ASPIREAZURE001
seoTitle: "ASPIREAZURE001: Publishers are for evaluation purposes only"
description: Learn what causes the Aspire compiler error ASPIREAZURE001 — publishers are for evaluation purposes only and are subject to change or removal in future updates.
title: Retired compiler error ASPIREAZURE001
seoTitle: "ASPIREAZURE001 retired in Aspire 17.0"
description: ASPIREAZURE001 was retired in Aspire 17.0 when the Azure environment and publishing APIs became stable. Learn what to do if you still see this error.
---

import { Badge } from '@astrojs/starlight/components';
Expand All @@ -13,6 +13,10 @@ import { Badge } from '@astrojs/starlight/components';
class:list={'mb-1'}
/>

:::note[Retired in Aspire 17.0]
Starting with Aspire 17.0, the Azure environment and publishing APIs (`AzureEnvironmentResource`, `AddAzureEnvironment`, `WithLocation`, `WithResourceGroup`, and `AzurePublishingContext`) are stable and no longer report `ASPIREAZURE001`. After you upgrade, remove any `ASPIREAZURE001` suppressions from _.editorconfig_ files, project files, and `#pragma warning` directives. The rest of this page describes the diagnostic as it applied to earlier versions.
:::

> Publishers are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed.

The Aspire Azure hosting integration now ships with a publisher. If you're using any of the `Aspire.Hosting.AzurePublisherExtensions.AddAzurePublisher*` APIs, you might see a compiler error/warning indicating that the API is experimental. This behavior is expected, as the API is still in preview and the shape of this API is expected to change in the future.
Expand Down
10 changes: 7 additions & 3 deletions src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Compiler Warning ASPIRECOMMAND001
seoTitle: 'ASPIRECOMMAND001: Required command validation types and members'
description: Learn what causes the Aspire compiler warning ASPIRECOMMAND001 and how to fix it so your AppHost builds cleanly.
title: Retired compiler warning ASPIRECOMMAND001
seoTitle: "ASPIRECOMMAND001 retired in Aspire 17.0"
description: ASPIRECOMMAND001 was retired in Aspire 17.0 when required-command validation became stable. Learn what to do if you still see this warning.
---

import { Badge } from '@astrojs/starlight/components';
Expand All @@ -14,6 +14,10 @@ import ApiReference from '@components/ApiReference.astro';
class:list={'mb-1'}
/>

:::note[Retired in Aspire 17.0]
Starting with Aspire 17.0, the required-command validation APIs (the `WithRequiredCommand` overload that accepts a validation callback, `RequiredCommandAnnotation`, `IRequiredCommandValidator`, `RequiredCommandValidationContext`, and `RequiredCommandValidationResult`) are stable and no longer report `ASPIRECOMMAND001`. After you upgrade, remove any `ASPIRECOMMAND001` suppressions from _.editorconfig_ files, project files, and `#pragma warning` directives. The rest of this page describes the diagnostic as it applied to earlier versions.
:::

> Required command validation types and members 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 required-command validation APIs. These APIs let an AppHost run custom validation against a resource's required command or executable before the resource starts.
Expand Down
56 changes: 23 additions & 33 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';

<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.
:::note[Changed in Aspire 17.0]
Starting with Aspire 17.0, the compute environment endpoint-mapping contracts `IComputeEnvironmentResource.GetHostAddressExpression` and `IComputeEnvironmentResource.GetEndpointPropertyExpression` are stable and no longer report `ASPIRECOMPUTE002`. After you upgrade, remove suppressions that were added only for those members. The persistent volume APIs listed on this page remain experimental and still require suppression.
:::

This diagnostic warning is reported when using the experimental `GetHostAddressExpression` method from the `IComputeEnvironmentResource` interface.
> Kubernetes persistent volume APIs are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed.

## Example
This diagnostic warning is reported when using the experimental Kubernetes persistent volume APIs: `KubernetesPersistentVolumeExtensions`, `KubernetesPersistentVolumeResource`, `PersistentVolumeAccessMode`, and `AzureKubernetesPersistentVolumeExtensions`.

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
Loading
Loading