From fcfd361f841cb8de8b50315d81907344e60c6030 Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
<268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Sat, 10 Oct 2026 12:55:08 +0000
Subject: [PATCH 01/12] docs: document dashboard startup telemetry
Document the aspire/dashboard/startup product telemetry event added in
microsoft/aspire#20846: startup result, duration, launch context, and
failure error type. Add the Dashboard:LaunchContext configuration
option to the dashboard configuration reference.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../src/content/docs/dashboard/configuration.mdx | 1 +
.../microsoft-collected-dashboard-telemetry.mdx | 13 +++++++++++++
2 files changed, 14 insertions(+)
diff --git a/src/frontend/src/content/docs/dashboard/configuration.mdx b/src/frontend/src/content/docs/dashboard/configuration.mdx
index ce52bc5db..0439b93b6 100644
--- a/src/frontend/src/content/docs/dashboard/configuration.mdx
+++ b/src/frontend/src/content/docs/dashboard/configuration.mdx
@@ -317,6 +317,7 @@ Telemetry limits have different scopes depending upon the telemetry type:
| Option | Description |
|--------|-------------|
| `Dashboard:ApplicationName`
Date: Mon, 12 Oct 2026 08:21:19 -0500
Subject: [PATCH 02/12] docs: migrate standalone dashboard image references
(#1679)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
## Summary
Update active dashboard image references to the published canonical
Aspire repositories. The previous draft/publication warnings are
resolved: all exact image tags consumed by this PR returned HTTP 200 on
October 12, 2026. The PR is ready for review and conflict-free; an
explicit user-directed merge hold remains in effect.
- Audit all 2,475 tracked files, including 611 documentation pages and
every available localization, plus generated data, runnable examples,
configuration, scripts, and workflows. All active tagged references now
use canonical names; legacy names remain only in migration explanations.
Historical release pages and the hosting-integration image catalog are
unchanged.
- Use `mcr.microsoft.com/aspire/dashboard:latest` in all standalone
Docker examples, including the newly added persistence examples.
Preserve container names, ports, authentication, telemetry limits, CORS,
volumes, and persistence settings.
- Keep the English Compose examples on the intentional floating
`mcr.microsoft.com/aspire/nightly/dashboard:latest` selection, with an
explicit publisher-output caveat. Align both Japanese generated-output
examples with the current publisher's version-line selection,
`mcr.microsoft.com/aspire/nightly/dashboard:13.6`, rather than
introducing a new manual translation.
- Preserve the upstream sample's nightly `13.6` pin in its command and
explanation, in both generated README fields. Retain current-main
screenshots and metadata; no other sample fields change semantically.
After the source change merged, normal-main generation verified that the
entire 29-sample catalog is semantically identical to this committed
data.
- Explain repository mappings, tag availability, immutable digests, and
Aspire 13 servicing compatibility. Do not silently upgrade a
version-constrained example when its old tag is unavailable in the new
repository.
- Merge canonical `main` (`1a61517655b4fd7811ef63fb5913f6fb623d9d6a`)
while preserving the original PR commits. Resolve the generated catalog
conflict through the existing updater and extend regression coverage to
persistence commands, all active documentation locales, and arbitrary
valid Docker image tags.
### Feedback addressed
Both actionable inline findings were fixed in
`728e2b88638808155fe10d8f9b0e5f078aa71635`, replied to, and resolved
after pushing to the existing upstream head:
- Match Docker tag grammar rather than three hard-coded tags. Regression
fixtures cover versions, architecture/preview tags, underscores, mixed
case, 128-character tags, end-of-input, and tag-plus-digest references
in both legacy channels. Historical release-page exclusions remain
intact.
- Align both Japanese Compose output examples to canonical nightly
`13.6`; retain the English guide's explicit floating-nightly
explanation. Browser clipboard verification confirms the final
language-specific selections.
A fully paginated feedback refresh returned two resolved threads, no
further thread/comment pages, and zero unresolved findings. No
additional actionable general comments were present.
### Dependencies and merge gates
- Publisher prerequisite
[dotnet/dotnet-docker#7337](https://github.com/dotnet/dotnet-docker/pull/7337)
merged on September 15, 2026. Publisher manifests use `aspire/dashboard`
on `main` (`f731d8c7f1049741a025a3ed8c034f6921c8af5e`) and
`aspire/nightly/dashboard` on `nightly`
(`f1f5cc1b0a02f0dd4538d013cca20a89d4ada83e`); actual publication is
independently confirmed below.
- Source synchronization is fulfilled:
[microsoft/aspire-samples#1952](https://github.com/microsoft/aspire-samples/pull/1952)
merged as `9e83d52d2f0e8be2c5cc61e87e2a3d9b010f1fc3`. This catalog was
initially generated from corrected head
`d9ee93a5ef275919aa81956794ad34285a262199` with the supported
`SAMPLES_BRANCH` override; running the existing generator against normal
`main` after the merge produced semantically identical data for all 29
samples. No needless follow-up catalog edit was made.
- Companion
[microsoft/aspire#20177](https://github.com/microsoft/aspire/pull/20177)
is coordinated separately. At current product `main`
(`b1d4824f1249ea4297b818a3f67c48f0cdb5a3ef`),
`src/Shared/DashboardImage.cs` and the Docker publisher select the
canonical nightly name and resolve a build override or the running
product's major/minor tag. This documentation does not claim that manual
image edits rewrite installed tooling's output.
- **Do not merge, enable auto-merge, or enqueue while the user-directed
incident hold is active.** GitHub auto-merge is disabled and the PR has
no queue entry.
- A valid human approval of the final work and green required/relevant
exact-head CI are mandatory after the hold is lifted. `mitchdenny`
approved the preceding head `e55de41c1d28522ef5f40aa22a53f19134e36017`;
GitHub retains that approval after the feedback push, so a summary
`APPROVED` state must not be mistaken for review of the current head. No
self-approval or bypass was performed.
### Exact published image decisions
| Use | Image | Manifest verification |
| --- | --- | --- |
| Standalone guides | `mcr.microsoft.com/aspire/dashboard:latest` | HTTP
200;
`sha256:613f297a274958abd85e7b71664f51fb42b0ddeb697ebd4c159677774433345b`
|
| Explicitly illustrative English Compose examples |
`mcr.microsoft.com/aspire/nightly/dashboard:latest` | HTTP 200;
`sha256:03a6f96028282634e3e957fb0b146e83fcc88e98f34aa3d689a38cd8ac31e5e7`
|
| Japanese publisher-output examples and upstream sample |
`mcr.microsoft.com/aspire/nightly/dashboard:13.6` | HTTP 200;
`sha256:03a6f96028282634e3e957fb0b146e83fcc88e98f34aa3d689a38cd8ac31e5e7`
|
Both canonical tag lists contain `13`, `13.6`, and `latest`, but earlier
minors such as `13.0` are absent. Exact canonical `13.0`–`13.3` requests
returned 404 while their legacy counterparts returned 200. A repository
rename is not a reason to change an intentionally pinned version or
switch release channels.
## Third-party links and affiliations
None. Added catalog links point to Microsoft's own Microsoft Container
Registry.
## Validation
Validated/pushed head: `728e2b88638808155fe10d8f9b0e5f078aa71635`.
- `pnpm --dir .\src\frontend exec vitest run --config vitest.config.ts
tests/unit/dashboard-image-references.vitest.test.ts
tests/unit/dashboard-agent-commands.vitest.test.ts
tests/unit/update-samples.vitest.test.ts`: **69 passed** after the
feedback fixes. Earlier extended coverage reproduced three stale
persistence/sample-reference failures before correction.
- `pnpm --dir .\src\frontend exec eslint
tests\unit\dashboard-image-references.vitest.test.ts --max-warnings 0`:
**passed**.
- `$env:SAMPLES_BRANCH = 'd9ee93a5ef275919aa81956794ad34285a262199';
pnpm --dir .\src\frontend update:samples`: **passed**, all 29 samples
fetched; only the standalone-dashboard README fields changed
semantically versus the base. Its `readmeRaw` exactly matches the pinned
source bytes. Post-merge execution of the same `update-samples.ts` with
`SAMPLES_BRANCH=main` in a temporary output directory: **passed**, all
29 generated sample objects matched the committed catalog; temporary
assets were removed.
- `git diff upstream/main HEAD --check`: **passed**. Final PR diff: nine
intended files, 215 insertions and 20 deletions. Existing PR history and
the latest base ancestry are preserved.
- `pnpm dev --host 127.0.0.1 --port 4389` with telemetry disabled:
**started successfully**. Playwright CLI verified all seven affected
documentation routes, Bash/PowerShell
standalone/configuration/CORS/persistence variants, C#/TypeScript
deployment variants, migration anchors, both image catalogs, and
`/reference/samples/standalone-dashboard/`. Final Japanese and sample
clipboard checks passed. The owned browser/scratch artifacts and preview
server were cleaned up; port 4389 has no listener.
- `docker manifest inspect mcr.microsoft.com/aspire/dashboard:latest`,
`docker manifest inspect
mcr.microsoft.com/aspire/nightly/dashboard:latest`, and `docker manifest
inspect mcr.microsoft.com/aspire/nightly/dashboard:13.6`: **passed**,
each advertises Linux AMD64 and ARM64. Exact registry manifests were
**HTTP 200** with the digests above.
- Container execution/login/OTLP/persistence runtime checks were
**blocked by the unavailable local Docker Desktop Linux engine**, not
claimed as passed. Four copied Compose examples also exposed
pre-existing `environment must be a mapping` schema failures; a byte
comparison verified their unchanged content against canonical main apart
from dashboard image references. Those unrelated baseline defects were
not altered.
- No full local build was run. Current-head
[CI](https://github.com/microsoft/aspire.dev/actions/runs/38249739333)
has passed frontend Build, frontend lint/unit validation, release-sync,
and change detection;
[CodeQL](https://github.com/microsoft/aspire.dev/actions/runs/38249739086),
forbidden words, and CLA are green. E2E/downstream gates must finish
before merge. Previous-head checks are not reused.
---------
Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
.../content/docs/dashboard/configuration.mdx | 4 +-
.../enable-browser-telemetry/index.mdx | 8 +-
.../src/content/docs/dashboard/index.mdx | 4 +-
.../src/content/docs/dashboard/standalone.mdx | 36 +++-
.../docs/get-started/deploy-first-app.mdx | 8 +-
.../docs/ja/get-started/deploy-first-app.mdx | 4 +-
.../content/docs/whats-new/upgrade-aspire.mdx | 8 +
src/frontend/src/data/samples.json | 6 +-
.../dashboard-image-references.vitest.test.ts | 157 ++++++++++++++++++
9 files changed, 215 insertions(+), 20 deletions(-)
create mode 100644 src/frontend/tests/unit/dashboard-image-references.vitest.test.ts
diff --git a/src/frontend/src/content/docs/dashboard/configuration.mdx b/src/frontend/src/content/docs/dashboard/configuration.mdx
index ce52bc5db..b20124ca4 100644
--- a/src/frontend/src/content/docs/dashboard/configuration.mdx
+++ b/src/frontend/src/content/docs/dashboard/configuration.mdx
@@ -85,7 +85,7 @@ docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-
-e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT='1000' \
-e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT='1000' \
-e DASHBOARD__TELEMETRYLIMITS__MAXMETRICSCOUNT='1000' \
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
@@ -96,7 +96,7 @@ docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-
-e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT='1000' `
-e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT='1000' `
-e DASHBOARD__TELEMETRYLIMITS__MAXMETRICSCOUNT='1000' `
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
diff --git a/src/frontend/src/content/docs/dashboard/enable-browser-telemetry/index.mdx b/src/frontend/src/content/docs/dashboard/enable-browser-telemetry/index.mdx
index b131c2e55..e897fd9d5 100644
--- a/src/frontend/src/content/docs/dashboard/enable-browser-telemetry/index.mdx
+++ b/src/frontend/src/content/docs/dashboard/enable-browser-telemetry/index.mdx
@@ -97,7 +97,7 @@ docker run --rm -it -d \
-p 4317:18889 \
-p 4318:18890 \
--name aspire-dashboard \
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
@@ -109,7 +109,7 @@ docker run --rm -it -d `
-p 4317:18889 `
-p 4318:18890 `
--name aspire-dashboard `
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
@@ -135,7 +135,7 @@ docker run --rm -it -d \
-p 4318:18890 \
-e DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=https://localhost:8080 \
--name aspire-dashboard \
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
@@ -148,7 +148,7 @@ docker run --rm -it -d `
-p 4318:18890 `
-e DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=https://localhost:8080 `
--name aspire-dashboard `
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
diff --git a/src/frontend/src/content/docs/dashboard/index.mdx b/src/frontend/src/content/docs/dashboard/index.mdx
index 776647d21..98e117f2b 100644
--- a/src/frontend/src/content/docs/dashboard/index.mdx
+++ b/src/frontend/src/content/docs/dashboard/index.mdx
@@ -95,7 +95,7 @@ Or run the same standalone dashboard from its container image:
```bash
docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-dashboard \
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
@@ -103,7 +103,7 @@ docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-
```powershell
docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-dashboard `
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
diff --git a/src/frontend/src/content/docs/dashboard/standalone.mdx b/src/frontend/src/content/docs/dashboard/standalone.mdx
index 5c91ea115..9cb162d46 100644
--- a/src/frontend/src/content/docs/dashboard/standalone.mdx
+++ b/src/frontend/src/content/docs/dashboard/standalone.mdx
@@ -65,7 +65,7 @@ The dashboard also ships as a standalone container image. Use this option when a
```bash
docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-dashboard \
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
@@ -73,7 +73,7 @@ docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-
```powershell
docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-dashboard `
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
@@ -81,12 +81,38 @@ docker run --rm -it -p 18888:18888 -p 4317:18889 -p 4318:18890 -d --name aspire-
The preceding Docker command:
-- Starts a container from the `mcr.microsoft.com/dotnet/aspire-dashboard:latest` image.
+- Starts a container from the `mcr.microsoft.com/aspire/dashboard:latest` image.
- The container exposes three ports:
- Mapping the dashboard's port `18888` to the host's port `18888`. Port `18888` has the dashboard UI. Navigate to `http://localhost:18888` in the browser to view the dashboard.
- Mapping the dashboard's OTLP/gRPC port `18889` to the host's port `4317`. Port `4317` receives OpenTelemetry data from apps using [OTLP/gRPC](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc).
- Mapping the dashboard's OTLP/HTTP port `18890` to the host's port `4318`. Port `4318` receives OpenTelemetry data from apps using [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp).
+### Container image repositories and migration
+
+The dashboard images are published to Microsoft Container Registry (MCR) under the `aspire` product family:
+
+| Channel | Repository | Use |
+| --- | --- | --- |
+| Stable | `mcr.microsoft.com/aspire/dashboard` | Released dashboard images; recommended for standalone use. |
+| Nightly | `mcr.microsoft.com/aspire/nightly/dashboard` | Preview builds for testing upcoming changes. |
+
+Use the [stable image catalog](https://mcr.microsoft.com/en-us/product/aspire/dashboard/tags) or [nightly image catalog](https://mcr.microsoft.com/en-us/product/aspire/nightly/dashboard/tags) to check available tags. Nightly builds aren't a substitute for stable releases.
+
+If you manage a dashboard container yourself, update the image repository in your Docker commands, Compose files, Kubernetes manifests, and image-mirroring or allowlist configuration:
+
+| Previous repository | New repository |
+| --- | --- |
+| `mcr.microsoft.com/dotnet/aspire-dashboard` | `mcr.microsoft.com/aspire/dashboard` |
+| `mcr.microsoft.com/dotnet/nightly/aspire-dashboard` | `mcr.microsoft.com/aspire/nightly/dashboard` |
+
+Preserve your stable or nightly channel and verify that your chosen tag exists in the new repository before changing it. The migration doesn't guarantee that all historical tags are available at the new names. If a version-specific tag isn't available in the new repository, keep the legacy reference rather than silently upgrading the dashboard. The `latest` tag follows the latest image in its repository; choose a published version tag to stay on a version line, or a digest when you need an immutable image reference.
+
+:::note[Aspire 13 compatibility]
+Aspire 13 images continue to be published to the legacy repositories for servicing and security updates. This compatibility covers the published fixed, minor, major, and architecture-specific tags. Legacy `latest` stays on the Aspire 13 line; it isn't a permanent alias for the new repository's `latest`. Subsequent major versions use the new repositories without this legacy syndication.
+:::
+
+The repository change doesn't rename the `aspire-dashboard` container, change its ports or environment variables, or change `aspire dashboard run`. Docker Compose and Kubernetes output generated by an older Aspire release can still contain a legacy image reference. Keep that output aligned with the publisher version rather than assuming the image repository migration changes installed tooling.
+
## Login to the dashboard
Data displayed in the dashboard can be sensitive. By default, the dashboard is secured with authentication that requires a token to login.
@@ -257,7 +283,7 @@ docker run --rm -d --name aspire-dashboard \
-e ASPIRE_DASHBOARD_APPLICATION_NAME=my-app \
-e ASPIRE_DASHBOARD_DATA_DIRECTORY=/dashboard-data \
-e ASPIRE_DASHBOARD_PERSISTENCE_MODE=run \
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
@@ -274,7 +300,7 @@ docker run --rm -d --name aspire-dashboard `
-e ASPIRE_DASHBOARD_APPLICATION_NAME=my-app `
-e ASPIRE_DASHBOARD_DATA_DIRECTORY=/dashboard-data `
-e ASPIRE_DASHBOARD_PERSISTENCE_MODE=run `
- mcr.microsoft.com/dotnet/aspire-dashboard:latest
+ mcr.microsoft.com/aspire/dashboard:latest
```
diff --git a/src/frontend/src/content/docs/get-started/deploy-first-app.mdx b/src/frontend/src/content/docs/get-started/deploy-first-app.mdx
index ff6d60fdc..0d31e0b24 100644
--- a/src/frontend/src/content/docs/get-started/deploy-first-app.mdx
+++ b/src/frontend/src/content/docs/get-started/deploy-first-app.mdx
@@ -20,6 +20,10 @@ import csharpStarterPng from '@assets/get-started/csharp-starter.png';
import javascriptStarterDarkPng from '@assets/get-started/javascript-starter-dark.png';
import javascriptStarterLightPng from '@assets/get-started/javascript-starter-light.png';
+:::note[Dashboard image in these examples]
+The Docker Compose examples on this page intentionally select `mcr.microsoft.com/aspire/nightly/dashboard:latest`. This floating tag follows the latest nightly dashboard image; it isn't an immutable digest or a stable release. Your installed Aspire publisher can generate a different repository or pin a version-line tag, so these examples don't guarantee its default output. For image selection and compatibility guidance, see [Container image repositories and migration](/dashboard/standalone/#container-image-repositories-and-migration).
+:::
+
+## Update standalone dashboard container references
+
+If you manage the standalone dashboard as a container, its stable image repository is now `mcr.microsoft.com/aspire/dashboard`; nightly images use `mcr.microsoft.com/aspire/nightly/dashboard`. Updating the Aspire CLI or packages doesn't rewrite image references in your own Docker commands, Compose files, or Kubernetes manifests.
+
+Before replacing a legacy `dotnet/aspire-dashboard` or `dotnet/nightly/aspire-dashboard` reference, verify that the tag you use exists in the new repository. Legacy repositories continue to receive Aspire 13 servicing images, but their `latest` tag stays on the Aspire 13 line rather than following future major releases. Generated deployment output remains specific to the Aspire publisher version.
+
+For the repository mapping, tag selection, and compatibility details, see [Container image repositories and migration](/dashboard/standalone/#container-image-repositories-and-migration).
+
## Update the VS Code extension (optional)
If you have the Aspire extension installed, you can update it to get the latest tooling support:
diff --git a/src/frontend/src/data/samples.json b/src/frontend/src/data/samples.json
index 41b155cf4..e15de1136 100644
--- a/src/frontend/src/data/samples.json
+++ b/src/frontend/src/data/samples.json
@@ -488,8 +488,8 @@
"title": "Standalone Aspire dashboard sample app",
"description": "View telemetry from any app in the Aspire dashboard. The dashboard supports running standalone, and apps configured with an [OpenTelemetry SDK](https://opentelemetry.io/docs/getting-started/dev/) can send it data.\n\nThis sample is a .NET console app that downloads data from [NuGet](https://nuget.org/). The app sends telemetry to the Aspire dashboard which is viewed in the dashboard telemetry UI.",
"href": "https://github.com/microsoft/aspire-samples/tree/main/samples/standalone-dashboard",
- "readme": "# Standalone Aspire dashboard sample app\n\nView telemetry from any app in the Aspire dashboard. The dashboard supports running standalone, and apps configured with an [OpenTelemetry SDK](https://opentelemetry.io/docs/getting-started/dev/) can send it data.\n\nThis sample is a .NET console app that downloads data from [NuGet](https://nuget.org/). The app sends telemetry to the Aspire dashboard which is viewed in the dashboard telemetry UI.\n\n\n\n\n## Demonstrates\n\n- How to run the Aspire dashboard from a Docker container\n- How to configure a .NET app to export telemetry to the dashboard\n- How to view telemetry in the Aspire dashboard\n\n## Sample prerequisites\n\nThis sample is written in C# and targets .NET 10.0. It requires the [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later.\n\nThis sample runs the Aspire dashboard from a Docker container. It requires Docker to be installed.\n\n## Start Aspire dashboard\n\nThe following command starts the Aspire dashboard in a Docker container:\n\n``` bash\ndocker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard mcr.microsoft.com/dotnet/nightly/aspire-dashboard:13.6\n```\n\nThe docker command:\n\n- Starts a container from the `mcr.microsoft.com/dotnet/nightly/aspire-dashboard:13.6` prerelease image.\n- The container has two ports:\n - Port `4317` receives OpenTelemetry data from apps. Apps send data using [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/).\n - Port `18888` has the dashboard UI. Navigate to http://localhost:18888 in the browser to view the dashboard.\n\n> [!NOTE]\n> The dashboard currently only supports the [OTLP/gRPC protocol](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc). Apps sending telemetry to the dashboard must be configured to use the `grpc` protocol. There are a couple of options for configuring apps:\n>\n> - Configure the OpenTelemetry SDK inside the app to use the gRPC OTLP protocol, or\n> - Start the app with the [`OTEL_EXPORTER_OTLP_PROTOCOL` environment variable](https://opentelemetry.io/docs/specs/otel/protocol/exporter/#configuration-options) with a value of `grpc`.\n\n## Login to the Aspire dashboard\n\nData displayed in the dashboard can be sensitive. By default, the dashboard is secured with authentication that requires a token to login.\n\nWhen the dashboard is run from a standalone container the login token is printed to the container logs. After copying the highlighted token into the login page, select the *Login* button.\n\n\n\nFor more information about logging into the dashboard, see [Dashboard authentication](https://aspire.dev/dashboard/explore/#dashboard-authentication).\n\n## Running the sample\n\nTo download and run the sample, follow these steps:\n\n1. Clone the `dotnet/aspire-samples` repository.\n2. Navigate to the folder that holds the sample code.\n3. At the command line, type [`dotnet run ConsoleApp.cs`](https://learn.microsoft.com/dotnet/core/tools/dotnet-run).\n\nRun the .NET app by executing the following at the command prompt (opened to the base directory of the sample):\n\n``` bash\ndotnet run ConsoleApp.cs\n```\n\n1. The console app launches, downloads information about the top NuGet packages and then exits.\n2. View the Aspire dashboard at http://localhost:18888 to see app telemetry.\n 1. View structured logs to see the list of top NuGet packages.\n 2. View traces to see HTTP requests made.\n 3. View metrics to see numeric data about the app such as average HTTP request duration.\n\n## Configure OpenTelemetry\n\nThe telemetry export endpoint is configured with the `OTEL_EXPORTER_OTLP_ENDPOINT` setting. This value is set to `http://localhost:4317` in the sample's `ConsoleApp.run.json` file. Removing the `OTEL_EXPORTER_OTLP_ENDPOINT` value disables exporting telemetry.\n",
- "readmeRaw": "# Standalone Aspire dashboard sample app\n\nView telemetry from any app in the Aspire dashboard. The dashboard supports running standalone, and apps configured with an [OpenTelemetry SDK](https://opentelemetry.io/docs/getting-started/dev/) can send it data.\n\nThis sample is a .NET console app that downloads data from [NuGet](https://nuget.org/). The app sends telemetry to the Aspire dashboard which is viewed in the dashboard telemetry UI.\n\n\n\n\n## Demonstrates\n\n- How to run the Aspire dashboard from a Docker container\n- How to configure a .NET app to export telemetry to the dashboard\n- How to view telemetry in the Aspire dashboard\n\n## Sample prerequisites\n\nThis sample is written in C# and targets .NET 10.0. It requires the [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later.\n\nThis sample runs the Aspire dashboard from a Docker container. It requires Docker to be installed.\n\n## Start Aspire dashboard\n\nThe following command starts the Aspire dashboard in a Docker container:\n\n``` bash\ndocker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard mcr.microsoft.com/dotnet/nightly/aspire-dashboard:13.6\n```\n\nThe docker command:\n\n- Starts a container from the `mcr.microsoft.com/dotnet/nightly/aspire-dashboard:13.6` prerelease image.\n- The container has two ports:\n - Port `4317` receives OpenTelemetry data from apps. Apps send data using [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/).\n - Port `18888` has the dashboard UI. Navigate to http://localhost:18888 in the browser to view the dashboard.\n\n> [!NOTE]\n> The dashboard currently only supports the [OTLP/gRPC protocol](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc). Apps sending telemetry to the dashboard must be configured to use the `grpc` protocol. There are a couple of options for configuring apps:\n>\n> - Configure the OpenTelemetry SDK inside the app to use the gRPC OTLP protocol, or\n> - Start the app with the [`OTEL_EXPORTER_OTLP_PROTOCOL` environment variable](https://opentelemetry.io/docs/specs/otel/protocol/exporter/#configuration-options) with a value of `grpc`.\n\n## Login to the Aspire dashboard\n\nData displayed in the dashboard can be sensitive. By default, the dashboard is secured with authentication that requires a token to login.\n\nWhen the dashboard is run from a standalone container the login token is printed to the container logs. After copying the highlighted token into the login page, select the *Login* button.\n\n\n\nFor more information about logging into the dashboard, see [Dashboard authentication](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/explore#dashboard-authentication).\n\n## Running the sample\n\nTo download and run the sample, follow these steps:\n\n1. Clone the `dotnet/aspire-samples` repository.\n2. Navigate to the folder that holds the sample code.\n3. At the command line, type [`dotnet run ConsoleApp.cs`](https://learn.microsoft.com/dotnet/core/tools/dotnet-run).\n\nRun the .NET app by executing the following at the command prompt (opened to the base directory of the sample):\n\n``` bash\ndotnet run ConsoleApp.cs\n```\n\n1. The console app launches, downloads information about the top NuGet packages and then exits.\n2. View the Aspire dashboard at http://localhost:18888 to see app telemetry.\n 1. View structured logs to see the list of top NuGet packages.\n 2. View traces to see HTTP requests made.\n 3. View metrics to see numeric data about the app such as average HTTP request duration.\n\n## Configure OpenTelemetry\n\nThe telemetry export endpoint is configured with the `OTEL_EXPORTER_OTLP_ENDPOINT` setting. This value is set to `http://localhost:4317` in the sample's `ConsoleApp.run.json` file. Removing the `OTEL_EXPORTER_OTLP_ENDPOINT` value disables exporting telemetry.\n",
+ "readme": "# Standalone Aspire dashboard sample app\n\nView telemetry from any app in the Aspire dashboard. The dashboard supports running standalone, and apps configured with an [OpenTelemetry SDK](https://opentelemetry.io/docs/getting-started/dev/) can send it data.\n\nThis sample is a .NET console app that downloads data from [NuGet](https://nuget.org/). The app sends telemetry to the Aspire dashboard which is viewed in the dashboard telemetry UI.\n\n\n\n\n## Demonstrates\n\n- How to run the Aspire dashboard from a Docker container\n- How to configure a .NET app to export telemetry to the dashboard\n- How to view telemetry in the Aspire dashboard\n\n## Sample prerequisites\n\nThis sample is written in C# and targets .NET 10.0. It requires the [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later.\n\nThis sample runs the Aspire dashboard from a Docker container. It requires Docker to be installed.\n\n## Start Aspire dashboard\n\nThe following command starts the Aspire dashboard in a Docker container:\n\n``` bash\ndocker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard mcr.microsoft.com/aspire/nightly/dashboard:13.6\n```\n\nThe docker command:\n\n- Starts a container from the `mcr.microsoft.com/aspire/nightly/dashboard:13.6` prerelease image.\n- The container has two ports:\n - Port `4317` receives OpenTelemetry data from apps. Apps send data using [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/).\n - Port `18888` has the dashboard UI. Navigate to http://localhost:18888 in the browser to view the dashboard.\n\n> [!NOTE]\n> The dashboard currently only supports the [OTLP/gRPC protocol](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc). Apps sending telemetry to the dashboard must be configured to use the `grpc` protocol. There are a couple of options for configuring apps:\n>\n> - Configure the OpenTelemetry SDK inside the app to use the gRPC OTLP protocol, or\n> - Start the app with the [`OTEL_EXPORTER_OTLP_PROTOCOL` environment variable](https://opentelemetry.io/docs/specs/otel/protocol/exporter/#configuration-options) with a value of `grpc`.\n\n## Login to the Aspire dashboard\n\nData displayed in the dashboard can be sensitive. By default, the dashboard is secured with authentication that requires a token to login.\n\nWhen the dashboard is run from a standalone container the login token is printed to the container logs. After copying the highlighted token into the login page, select the *Login* button.\n\n\n\nFor more information about logging into the dashboard, see [Dashboard authentication](https://aspire.dev/dashboard/explore/#dashboard-authentication).\n\n## Running the sample\n\nTo download and run the sample, follow these steps:\n\n1. Clone the `dotnet/aspire-samples` repository.\n2. Navigate to the folder that holds the sample code.\n3. At the command line, type [`dotnet run ConsoleApp.cs`](https://learn.microsoft.com/dotnet/core/tools/dotnet-run).\n\nRun the .NET app by executing the following at the command prompt (opened to the base directory of the sample):\n\n``` bash\ndotnet run ConsoleApp.cs\n```\n\n1. The console app launches, downloads information about the top NuGet packages and then exits.\n2. View the Aspire dashboard at http://localhost:18888 to see app telemetry.\n 1. View structured logs to see the list of top NuGet packages.\n 2. View traces to see HTTP requests made.\n 3. View metrics to see numeric data about the app such as average HTTP request duration.\n\n## Configure OpenTelemetry\n\nThe telemetry export endpoint is configured with the `OTEL_EXPORTER_OTLP_ENDPOINT` setting. This value is set to `http://localhost:4317` in the sample's `ConsoleApp.run.json` file. Removing the `OTEL_EXPORTER_OTLP_ENDPOINT` value disables exporting telemetry.\n",
+ "readmeRaw": "# Standalone Aspire dashboard sample app\n\nView telemetry from any app in the Aspire dashboard. The dashboard supports running standalone, and apps configured with an [OpenTelemetry SDK](https://opentelemetry.io/docs/getting-started/dev/) can send it data.\n\nThis sample is a .NET console app that downloads data from [NuGet](https://nuget.org/). The app sends telemetry to the Aspire dashboard which is viewed in the dashboard telemetry UI.\n\n\n\n\n## Demonstrates\n\n- How to run the Aspire dashboard from a Docker container\n- How to configure a .NET app to export telemetry to the dashboard\n- How to view telemetry in the Aspire dashboard\n\n## Sample prerequisites\n\nThis sample is written in C# and targets .NET 10.0. It requires the [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later.\n\nThis sample runs the Aspire dashboard from a Docker container. It requires Docker to be installed.\n\n## Start Aspire dashboard\n\nThe following command starts the Aspire dashboard in a Docker container:\n\n``` bash\ndocker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard mcr.microsoft.com/aspire/nightly/dashboard:13.6\n```\n\nThe docker command:\n\n- Starts a container from the `mcr.microsoft.com/aspire/nightly/dashboard:13.6` prerelease image.\n- The container has two ports:\n - Port `4317` receives OpenTelemetry data from apps. Apps send data using [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/).\n - Port `18888` has the dashboard UI. Navigate to http://localhost:18888 in the browser to view the dashboard.\n\n> [!NOTE]\n> The dashboard currently only supports the [OTLP/gRPC protocol](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc). Apps sending telemetry to the dashboard must be configured to use the `grpc` protocol. There are a couple of options for configuring apps:\n>\n> - Configure the OpenTelemetry SDK inside the app to use the gRPC OTLP protocol, or\n> - Start the app with the [`OTEL_EXPORTER_OTLP_PROTOCOL` environment variable](https://opentelemetry.io/docs/specs/otel/protocol/exporter/#configuration-options) with a value of `grpc`.\n\n## Login to the Aspire dashboard\n\nData displayed in the dashboard can be sensitive. By default, the dashboard is secured with authentication that requires a token to login.\n\nWhen the dashboard is run from a standalone container the login token is printed to the container logs. After copying the highlighted token into the login page, select the *Login* button.\n\n\n\nFor more information about logging into the dashboard, see [Dashboard authentication](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/explore#dashboard-authentication).\n\n## Running the sample\n\nTo download and run the sample, follow these steps:\n\n1. Clone the `dotnet/aspire-samples` repository.\n2. Navigate to the folder that holds the sample code.\n3. At the command line, type [`dotnet run ConsoleApp.cs`](https://learn.microsoft.com/dotnet/core/tools/dotnet-run).\n\nRun the .NET app by executing the following at the command prompt (opened to the base directory of the sample):\n\n``` bash\ndotnet run ConsoleApp.cs\n```\n\n1. The console app launches, downloads information about the top NuGet packages and then exits.\n2. View the Aspire dashboard at http://localhost:18888 to see app telemetry.\n 1. View structured logs to see the list of top NuGet packages.\n 2. View traces to see HTTP requests made.\n 3. View metrics to see numeric data about the app such as average HTTP request duration.\n\n## Configure OpenTelemetry\n\nThe telemetry export endpoint is configured with the `OTEL_EXPORTER_OTLP_ENDPOINT` setting. This value is set to `http://localhost:4317` in the sample's `ConsoleApp.run.json` file. Removing the `OTEL_EXPORTER_OTLP_ENDPOINT` value disables exporting telemetry.\n",
"tags": [
"csharp",
"dashboard",
@@ -621,4 +621,4 @@
"appHostPath": "VolumeMount.AppHost/AppHost.cs",
"appHostCode": "var builder = DistributedApplication.CreateBuilder(args);\n\nvar sqlserver = builder.AddSqlServer(\"sqlserver\")\n .WithDataVolume()\n .WithLifetime(ContainerLifetime.Persistent);\n\nvar sqlDatabase = sqlserver.AddDatabase(\"sqldb\");\n\nvar blobs = builder.AddAzureStorage(\"Storage\")\n // Use the Azurite storage emulator for local development\n .RunAsEmulator(emulator => emulator.WithDataVolume())\n .AddBlobs(\"BlobConnection\");\n\nvar migration = builder.AddProject(\"migration\")\n .WithReference(sqlDatabase)\n .WaitFor(sqlDatabase);\n\nbuilder.AddProject(\"blazorweb\")\n .WithReference(sqlDatabase)\n .WaitForCompletion(migration)\n .WithReference(blobs)\n .WaitFor(blobs);\n\nbuilder.Build().Run();"
}
-]
+]
\ No newline at end of file
diff --git a/src/frontend/tests/unit/dashboard-image-references.vitest.test.ts b/src/frontend/tests/unit/dashboard-image-references.vitest.test.ts
new file mode 100644
index 000000000..a4960b889
--- /dev/null
+++ b/src/frontend/tests/unit/dashboard-image-references.vitest.test.ts
@@ -0,0 +1,157 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'vitest';
+import samples from '@data/samples.json';
+
+const testsDir = path.dirname(fileURLToPath(import.meta.url));
+const docsRoot = path.resolve(testsDir, '..', '..', 'src', 'content', 'docs');
+const stableImage = 'mcr.microsoft.com/aspire/dashboard:latest';
+const nightlyImage = 'mcr.microsoft.com/aspire/nightly/dashboard:latest';
+const versionedNightlyImage = 'mcr.microsoft.com/aspire/nightly/dashboard:13.6';
+
+function readDoc(file: string): string {
+ return readFileSync(path.join(docsRoot, file), 'utf8');
+}
+
+function dockerCommands(source: string): string[] {
+ return [...source.matchAll(/```(?:bash|powershell)[^\n]*\n([\s\S]*?)```/g)].flatMap(
+ (match) => match[1].match(/^docker run[^\n]*(?:\n[ \t]+[^\n]*)*/gm) ?? []
+ );
+}
+
+function legacyImageReferences(source: string): string[] {
+ return (
+ source.match(
+ /mcr\.microsoft\.com\/dotnet\/(?:nightly\/)?aspire-dashboard:\w[\w.-]{0,127}(?=$|[\s`"'@])/g
+ ) ?? []
+ );
+}
+
+describe('standalone dashboard container images', () => {
+ test.each([
+ ['dashboard/standalone.mdx', 4],
+ ['dashboard/index.mdx', 2],
+ ['dashboard/configuration.mdx', 2],
+ ['dashboard/enable-browser-telemetry/index.mdx', 4],
+ ])('%s uses the stable image in both shell variants', (file, count) => {
+ const source = readDoc(file);
+ const commands = dockerCommands(source);
+
+ expect(commands).toHaveLength(count);
+ expect(source.match(//g)?.length).toBeGreaterThanOrEqual(
+ count / 2
+ );
+ for (const command of commands) {
+ expect(command.match(/mcr\.microsoft\.com\/\S+/g)).toEqual([stableImage]);
+ expect(command).toContain('--name aspire-dashboard');
+ for (const port of ['18888:18888', '4317:18889', '4318:18890']) {
+ expect(command).toContain(`-p ${port}`);
+ }
+ }
+ expect(source.match(/```bash\b/g)?.length).toBeGreaterThanOrEqual(count / 2);
+ expect(source.match(/```powershell\b/g)?.length).toBeGreaterThanOrEqual(count / 2);
+ });
+
+ test('preserves telemetry limits and CORS settings', () => {
+ for (const command of dockerCommands(readDoc('dashboard/configuration.mdx'))) {
+ for (const setting of ['MAXLOGCOUNT', 'MAXTRACECOUNT', 'MAXMETRICSCOUNT']) {
+ expect(command).toContain(`-e DASHBOARD__TELEMETRYLIMITS__${setting}='1000'`);
+ }
+ }
+ const browserCommands = dockerCommands(readDoc('dashboard/enable-browser-telemetry/index.mdx'));
+ expect(
+ browserCommands.filter((command) =>
+ command.includes('-e DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=https://localhost:8080')
+ )
+ ).toHaveLength(2);
+ });
+
+ test('keeps the command explanation and container log name consistent', () => {
+ const source = readDoc('dashboard/standalone.mdx');
+ expect(source).toContain(`Starts a container from the \`${stableImage}\` image.`);
+ expect(source).toContain('docker container logs aspire-dashboard');
+ expect(source).toContain('aspire dashboard run');
+ });
+
+ test('preserves the volume and persistence settings in both shell variants', () => {
+ const commands = dockerCommands(readDoc('dashboard/standalone.mdx')).filter((command) =>
+ command.includes('--mount')
+ );
+ expect(commands).toHaveLength(2);
+ for (const command of commands) {
+ expect(command).toContain(
+ '--mount type=volume,source=aspire-dashboard-data,target=/dashboard-data'
+ );
+ expect(command).toContain('-e ASPIRE_DASHBOARD_APPLICATION_NAME=my-app');
+ expect(command).toContain('-e ASPIRE_DASHBOARD_DATA_DIRECTORY=/dashboard-data');
+ expect(command).toContain('-e ASPIRE_DASHBOARD_PERSISTENCE_MODE=run');
+ }
+ });
+
+ test.each([
+ 'latest',
+ '13',
+ '13.6',
+ '13.5',
+ '14.0',
+ '13.6.1',
+ '13.6.1-amd64',
+ 'preview_1',
+ 'Preview.1',
+ '_build',
+ 'a'.repeat(128),
+ ])('detects the legacy Docker tag %s in both channels', (tag) => {
+ for (const repository of ['dotnet/aspire-dashboard', 'dotnet/nightly/aspire-dashboard']) {
+ const image = `mcr.microsoft.com/${repository}:${tag}`;
+ expect(legacyImageReferences(`image: "${image}"`)).toEqual([image]);
+ expect(legacyImageReferences(image)).toEqual([image]);
+ expect(legacyImageReferences(`${image}@sha256:${'a'.repeat(64)}`)).toEqual([image]);
+ }
+ });
+
+ test('uses canonical tagged image references throughout active docs in all locales', () => {
+ const legacyImages: string[] = [];
+ for (const file of readdirSync(docsRoot, { recursive: true, encoding: 'utf8' })) {
+ if (!/\.mdx?$/.test(file) || /(?:^|[\\/])whats-new[\\/]aspire-\d/.test(file)) {
+ continue;
+ }
+ const images = legacyImageReferences(readDoc(file));
+ legacyImages.push(...images.map((image) => `${file}: ${image}`));
+ }
+ expect(legacyImages).toEqual([]);
+ });
+});
+
+describe('deployment example dashboard image references', () => {
+ test.each([
+ ['get-started/deploy-first-app.mdx', nightlyImage],
+ ['ja/get-started/deploy-first-app.mdx', versionedNightlyImage],
+ ])('%s preserves its documented nightly image selection', (file, image) => {
+ const images = [...readDoc(file).matchAll(/image: "(mcr\.microsoft\.com\/[^"]+)"/g)].map(
+ (match) => match[1]
+ );
+ expect(images).toEqual([image, image]);
+ });
+
+ test('distinguishes the English floating examples from installed publisher output', () => {
+ const source = readDoc('get-started/deploy-first-app.mdx');
+ expect(source).toContain(`intentionally select \`${nightlyImage}\``);
+ expect(source).toContain('Your installed Aspire publisher can generate a different repository');
+ expect(source).toContain('/dashboard/standalone/#container-image-repositories-and-migration');
+ });
+});
+
+describe('standalone dashboard sample image', () => {
+ test('preserves the upstream nightly version pin in both README fields', () => {
+ const sample = samples.find((entry) => entry.name === 'standalone-dashboard');
+ expect(sample).toBeDefined();
+ for (const field of ['readme', 'readmeRaw'] as const) {
+ const source = sample![field];
+ const images = source.match(/mcr\.microsoft\.com\/[^\s`]+/g);
+ expect(images).toEqual([versionedNightlyImage, versionedNightlyImage]);
+ expect(source).toContain(`--name aspire-dashboard ${versionedNightlyImage}`);
+ expect(source).toContain(`\`${versionedNightlyImage}\` prerelease image.`);
+ }
+ });
+});
From 5c9d532cfc803eb1844f782bd05c5eb4d6cd903f Mon Sep 17 00:00:00 2001
From: James Newton-King
Date: Mon, 12 Oct 2026 22:13:30 +0800
Subject: [PATCH 03/12] Apply batched suggestions from code review
Co-authored-by: James Newton-King
---
src/frontend/src/content/docs/dashboard/configuration.mdx | 2 +-
.../docs/dashboard/microsoft-collected-dashboard-telemetry.mdx | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/src/frontend/src/content/docs/dashboard/configuration.mdx b/src/frontend/src/content/docs/dashboard/configuration.mdx
index 0439b93b6..6bcb9b460 100644
--- a/src/frontend/src/content/docs/dashboard/configuration.mdx
+++ b/src/frontend/src/content/docs/dashboard/configuration.mdx
@@ -317,7 +317,7 @@ Telemetry limits have different scopes depending upon the telemetry type:
| Option | Description |
|--------|-------------|
| `Dashboard:ApplicationName`
Date: Mon, 12 Oct 2026 22:14:11 +0800
Subject: [PATCH 04/12] Apply suggestion from @JamesNK
---
.../microsoft-collected-dashboard-telemetry.mdx | 13 -------------
1 file changed, 13 deletions(-)
diff --git a/src/frontend/src/content/docs/dashboard/microsoft-collected-dashboard-telemetry.mdx b/src/frontend/src/content/docs/dashboard/microsoft-collected-dashboard-telemetry.mdx
index dd88f6b8b..5fe75aab4 100644
--- a/src/frontend/src/content/docs/dashboard/microsoft-collected-dashboard-telemetry.mdx
+++ b/src/frontend/src/content/docs/dashboard/microsoft-collected-dashboard-telemetry.mdx
@@ -45,19 +45,6 @@ Alternatively, you can opt-out of telemetry collection by disabling telemetry co
When dashboard usage telemetry is enabled, there's a disclosure statement at the bottom of the settings panel, informing you that telemetry is enabled. This disclosure statement appears when usage telemetry is enabled.
-## Startup telemetry
-
-Separately from the IDE-scoped usage telemetry described above, the dashboard always records an `aspire/dashboard/startup` event when it starts, regardless of how it's launched (AppHost, the `aspire dashboard run` CLI command, standalone, or a deployed container). This event records:
-
-- The startup result (success or failure).
-- The elapsed startup duration, in milliseconds.
-- The launch context: `apphost`, `cli`, `container`, or `unknown`.
-- For failed startups, an error type: `invalid_config` for options validation failures, `address_in_use` for address conflicts, `canceled` for token-driven startup cancellation, or the exception type for other failures.
-
-The launch context is read from the `Dashboard:LaunchContext` configuration option (`DASHBOARD__LAUNCHCONTEXT` environment variable). The AppHost and the `aspire dashboard run` CLI command set this automatically; container deployments can set it explicitly to `container`. Values are matched case-insensitively, and missing or unrecognized values are reported as `unknown`. See [dashboard configuration](/dashboard/configuration/#other).
-
-Startup telemetry is sent using the same Azure Monitor reporting path, and the same `ASPIRE_DASHBOARD_TELEMETRY_OPTOUT` opt-out described above, as other dashboard usage and error telemetry.
-
## Data points
Aspire dashboard usage telemetry doesn't collect personal data, such as, IP addresses or use browser fingerprinting. It doesn't scan your code and doesn't extract source code, authorship, or deployment configuration. The data is sent securely to Microsoft using Azure Monitor through existing telemetry APIs in Visual Studio and Visual Studio Code.
From 32f2d1c895952771c0d58924ef8c9115a37b3a0a Mon Sep 17 00:00:00 2001
From: Samson Amaugo
Date: Mon, 12 Oct 2026 15:33:12 +0100
Subject: [PATCH 05/12] Fix the dashboard container persistence example: mount
the volume where the non-root user can write (#1869)
## Summary
The Docker example under "Persist data between container runs" on the
standalone dashboard page does not work as written. The container exits
a few seconds after starting.
**Steps to reproduce**
Run the two commands from that section unchanged:
docker volume create aspire-dashboard-data
docker run --rm -d --name aspire-dashboard -p 18888:18888 -p 4317:18889
-p 4318:18890 --mount
type=volume,source=aspire-dashboard-data,target=/dashboard-data -e
ASPIRE_DASHBOARD_APPLICATION_NAME=my-app -e
ASPIRE_DASHBOARD_DATA_DIRECTORY=/dashboard-data -e
ASPIRE_DASHBOARD_PERSISTENCE_MODE=run
mcr.microsoft.com/dotnet/aspire-dashboard:latest
**Result**
The container exits with code 100. Because the example uses `--rm`, the
container and its logs are removed, so the reader sees no error. Running
it without `--rm` shows:
Aspire dashboard version: 13.6.1
System.UnauthorizedAccessException: Access to the path
'/dashboard-data/runs' is denied.
**Cause**
The image runs as a non-root user (uid 1654). `/dashboard-data` does not
exist in the image, so Docker creates the new named volume owned by
root, and the dashboard cannot create its `runs` directory in it.
**Change**
- Mount the volume at `/home/app`, the container user's home directory.
Docker gives a new volume the ownership of the directory it is mounted
over, so the volume is writable by the dashboard.
- Set `ASPIRE_DASHBOARD_DATA_DIRECTORY=/home/app/dashboard-data`.
- Add one sentence under the example explaining why this path is used.
Both the Bash and PowerShell tabs are updated.
An alternative would be to create `/dashboard-data` in the image with
the right owner, which would make the original example work unchanged.
I'm happy to adjust this PR if that is preferred.
## Third-party links and affiliations
None
## Validation
- Reproduced the failure with the original example on
`mcr.microsoft.com/dotnet/aspire-dashboard:latest` (13.6.1), Docker
29.4.3, Docker Desktop on macOS, and on Docker on Linux.
- Ran the corrected example twice in a row in `run` mode: the container
started with no errors both times, and the volume contained the saved
run from the first start.
- Also ran it in `Resume` mode with an application sending OTLP
telemetry, removed the container, started a new one on the same volume,
and confirmed the earlier traces were still shown.
Co-authored-by: Claude Opus 5.5
---
src/frontend/src/content/docs/dashboard/standalone.mdx | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/src/frontend/src/content/docs/dashboard/standalone.mdx b/src/frontend/src/content/docs/dashboard/standalone.mdx
index 9cb162d46..3c7811156 100644
--- a/src/frontend/src/content/docs/dashboard/standalone.mdx
+++ b/src/frontend/src/content/docs/dashboard/standalone.mdx
@@ -279,9 +279,9 @@ docker run --rm -d --name aspire-dashboard \
-p 18888:18888 \
-p 4317:18889 \
-p 4318:18890 \
- --mount type=volume,source=aspire-dashboard-data,target=/dashboard-data \
+ --mount type=volume,source=aspire-dashboard-data,target=/home/app \
-e ASPIRE_DASHBOARD_APPLICATION_NAME=my-app \
- -e ASPIRE_DASHBOARD_DATA_DIRECTORY=/dashboard-data \
+ -e ASPIRE_DASHBOARD_DATA_DIRECTORY=/home/app/dashboard-data \
-e ASPIRE_DASHBOARD_PERSISTENCE_MODE=run \
mcr.microsoft.com/aspire/dashboard:latest
```
@@ -296,9 +296,9 @@ docker run --rm -d --name aspire-dashboard `
-p 18888:18888 `
-p 4317:18889 `
-p 4318:18890 `
- --mount type=volume,source=aspire-dashboard-data,target=/dashboard-data `
+ --mount type=volume,source=aspire-dashboard-data,target=/home/app `
-e ASPIRE_DASHBOARD_APPLICATION_NAME=my-app `
- -e ASPIRE_DASHBOARD_DATA_DIRECTORY=/dashboard-data `
+ -e ASPIRE_DASHBOARD_DATA_DIRECTORY=/home/app/dashboard-data `
-e ASPIRE_DASHBOARD_PERSISTENCE_MODE=run `
mcr.microsoft.com/aspire/dashboard:latest
```
@@ -306,6 +306,8 @@ docker run --rm -d --name aspire-dashboard `
+The dashboard container runs as a non-root user, so the volume is mounted at that user's home directory, `/home/app`. Docker gives a new volume the ownership of the directory it's mounted over. A volume mounted at a path that doesn't exist in the image is owned by root, and the dashboard fails to start with an "Access to the path is denied" error.
+
Stop the container and run the same `docker run` command again to access the retained data. Keep the volume, application name, and persistence mode unchanged between container runs.
Persisted telemetry can contain sensitive data. Restrict access to the volume and see [Aspire dashboard data persistence](/dashboard/data-persistence/) for persistence behavior and [Dashboard security considerations](/dashboard/security-considerations/#protect-persisted-data) for security requirements.
From 8929ab18b0631c82de22ae94aa9049412cdd7316 Mon Sep 17 00:00:00 2001
From: James Newton-King
Date: Mon, 12 Oct 2026 22:41:40 +0800
Subject: [PATCH 06/12] Apply suggestion from @JamesNK
---
.../docs/dashboard/microsoft-collected-dashboard-telemetry.mdx | 1 -
1 file changed, 1 deletion(-)
diff --git a/src/frontend/src/content/docs/dashboard/microsoft-collected-dashboard-telemetry.mdx b/src/frontend/src/content/docs/dashboard/microsoft-collected-dashboard-telemetry.mdx
index 5fe75aab4..a98ac1d4d 100644
--- a/src/frontend/src/content/docs/dashboard/microsoft-collected-dashboard-telemetry.mdx
+++ b/src/frontend/src/content/docs/dashboard/microsoft-collected-dashboard-telemetry.mdx
@@ -63,7 +63,6 @@ The Aspire dashboard doesn't collect telemetry on Visual Studio versions `< 17.1
| 9.3 | Resource restart times. | — |
| 9.3 | OTel data processing times. | — |
| 9.3 | Dashboard-related unhandled exceptions. | — |
-| 9.3 | GitHub Copilot usage statistics. | — |
| 17.0 | Dashboard startup. | — |
## See also
From c1e2e160c74deb62576d5cb360131b03b55b2bea Mon Sep 17 00:00:00 2001
From: David Pine
Date: Tue, 13 Oct 2026 08:27:49 -0500
Subject: [PATCH 07/12] Restore landing page performance and serve the site
over HTTP/2 (#1836)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
## Summary
The landing page's Lighthouse score slipped from the high 80s to the
high 70s (mobile, simulated slow 4G), and PageSpeed Insights reported
70. Rather than guess, I built a production-like lab (the production
build output served over HTTPS + **HTTP/1.1** + Brotli with the same
cache headers, because that is what `aspire.dev` serves today), ran
Lighthouse 13 with the mobile preset (simulated Slow 4G, 4× CPU) in a
fresh browser profile per run, and bisected the page across the commits
that changed it. Every number below is the median of five cold runs.
There is one commit per cause (plus one review fix to the banner
script), so any of them can be reverted on its own.
### Where it regressed
| Build (HTTP/1.1) | Score | FCP | LCP | CLS | Requests |
| --- | --- | --- | --- | --- | --- |
| Before the redesign (`0b54dce5`) | 87 | 2.33 s | 3.60 s | 0.004 | 43 |
| Landing redesign (#1420) | 84 | 2.63 s | 3.96 s | 0.005 | 75 |
| Release 13.5 content (includes the banner auto-expiry, #1448) | 82 |
2.63 s | 3.84 s | 0.093 | 75 |
| `main` (`a097c7e7`) | 78 | 2.78 s | 4.28 s | 0.105 | 88 |
| **This PR** | **86** (85, 86 and 87 in three separate batches) |
**2.25 s** | **3.77 s** | **0.001** | **61** |
Serving the same bytes over HTTP/2: `main` 90 → this PR 93.
### Causes and fixes
I measured each lever on `main` in isolation before changing any code.
| Cause | Fix | Alone |
| --- | --- | --- |
| The banner (#1448) is rendered `hidden` and a bundled script reveals
it after first paint, shifting the whole page down (CLS 0.09). | Render
it visible and hide it with a tiny pre-paint script when the reader
dismissed it or its sunset/auto-dismiss window has passed (the absolute
sunset is checked before storage is read, so blocked storage cannot
paint an expired banner). A test runs the emitted script against
`resolveBannerVisibility` so the two cannot drift. | 78 → 80 |
| Poppins is declared in `site.css`, so it is only discovered after that
stylesheet downloads; text re-flows when it swaps in (CLS 0.08). |
Preload the three weights the first viewport uses. Each is still fetched
once. | 78 → 81 (FCP −0.30 s) |
| The redesign set `loading="eager"` on 35 icons thousands of pixels
below the fold; on HTTP/1.1 they compete with CSS and fonts for six
connections. | Use the default lazy loading again. Native lazy loading
never starts for `display: none` content, so a small helper
(`loadLazyImagesNearViewport`) loads the icons in hidden environment
panels and the inactive AppHost language as their section nears the
viewport, and switching panels or language stays instant. | 78 → 81 (LCP
−0.32 s, 88 → 61 requests) |
| `AsciinemaPlayer` imported its CSS from a bundled `
)
}
@@ -79,6 +110,7 @@ const firstSeenKey = bannerHash
// so shipped behavior can't diverge from the tests. This bundled module reads
// its per-banner config from `data-*` attributes on the element (a bundled
// script can't use `define:vars`), leaving only DOM/localStorage plumbing here.
+ // The pre-paint script above applies the same decision before first paint.
import { parseFirstSeen, resolveBannerVisibility } from '@utils/banner-expiry';
const initializeBanner = () => {
diff --git a/src/frontend/src/components/starlight/Head.astro b/src/frontend/src/components/starlight/Head.astro
index 9fce57471..ef3ae838a 100644
--- a/src/frontend/src/components/starlight/Head.astro
+++ b/src/frontend/src/components/starlight/Head.astro
@@ -1,5 +1,8 @@
---
import 'tippy.js/dist/tippy.css';
+import poppinsRegular from '@fontsource/poppins/files/poppins-latin-400-normal.woff2?url';
+import poppinsSemiBold from '@fontsource/poppins/files/poppins-latin-600-normal.woff2?url';
+import poppinsBold from '@fontsource/poppins/files/poppins-latin-700-normal.woff2?url';
import DefaultHead from '@astrojs/starlight/components/Head.astro';
import { ClientRouter } from 'astro:transitions';
import AccessibleCodeButtons from '../AccessibleCodeButtons.astro';
@@ -7,6 +10,10 @@ import SiteTour from '../SiteTour.astro';
import { getStructuredData } from '@utils/structured-data';
import { getOgMetadata } from '@utils/page-metadata';
+// The Poppins weights that text in the first viewport renders with. The same files back the
+// @font-face rules in site.css, so these resolve to the already-emitted assets.
+const preloadedFonts = [poppinsRegular, poppinsSemiBold, poppinsBold];
+
const repoUrl = (
import.meta.env.PUBLIC_REPO_URL ||
import.meta.env.REPO_URL ||
@@ -40,6 +47,18 @@ function computeSourceUrl() {
Date: Tue, 13 Oct 2026 17:07:33 +0100
Subject: [PATCH 08/12] Propagate the API Reference Astro component (#1849)
## Summary
The API Reference Astro component is complete and deployed but only used
in **Get Started** Aspire.dev content. This PR propagates its usage to
all other content files where appropriate:
- It's only used on the first reference to a given API on each page.
- It's only used where there is both a C# and a JavaScript version of
the referenced API.
Fixes: #1848
## Third-party links and affiliations
None
## Validation
- `pnpm test:unit:api-reference`
- `pnpm run dev` and manually check some instances of the `ApiReference`
component.
---------
Co-authored-by: David Pine
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Copilot-Session: 92354b96-5c95-491b-93fe-453cb0e1499d
---
.../app-host/certificate-configuration.mdx | 11 ++---
.../content/docs/app-host/container-files.mdx | 9 ++--
.../docs/app-host/container-registry.mdx | 5 ++-
.../src/content/docs/app-host/eventing.mdx | 13 +++---
.../docs/app-host/executable-resources.mdx | 9 ++--
.../app-host/migrate-from-docker-compose.mdx | 23 +++++-----
.../docs/app-host/resource-lifetimes.mdx | 15 ++++---
.../docs/app-host/typescript-apphost.mdx | 5 ++-
.../content/docs/app-host/with-terminal.mdx | 7 +--
.../content/docs/app-host/withdockerfile.mdx | 11 ++---
.../multi-language-architecture.mdx | 5 ++-
.../architecture/resource-api-patterns.mdx | 3 +-
.../docs/architecture/resource-examples.mdx | 2 +
.../architecture/resource-hierarchies.mdx | 7 +--
.../docs/architecture/resource-publishing.mdx | 3 +-
.../docs/dashboard/ephemeral-terminals.mdx | 4 +-
.../src/content/docs/dashboard/explore.mdx | 5 ++-
.../dashboard/telemetry-after-deployment.mdx | 3 +-
.../src/content/docs/dashboard/terminals.mdx | 5 ++-
.../docs/deployment/azure/app-service.mdx | 5 ++-
.../deployment/azure/azure-developer-cli.mdx | 5 ++-
.../azure/azure-security-best-practices.mdx | 5 ++-
.../docs/deployment/azure/container-apps.mdx | 9 ++--
.../docs/deployment/azure/sandboxes.mdx | 15 ++++---
.../docs/deployment/custom-deployments.mdx | 5 ++-
.../docs/deployment/deploy-with-aspire.mdx | 3 +-
.../docs/deployment/docker-compose.mdx | 23 +++++-----
.../content/docs/deployment/environments.mdx | 5 ++-
.../docs/deployment/javascript-apps.mdx | 27 +++++------
.../deployment/kubernetes-gateway-aks.mdx | 9 ++--
.../deployment/kubernetes-ingress-aks.mdx | 9 ++--
.../docs/deployment/kubernetes-ingress.mdx | 7 +--
.../docs/deployment/kubernetes/aks.mdx | 25 ++++++-----
.../docs/deployment/kubernetes/clusters.mdx | 9 ++--
.../deployment/kubernetes/helm-charts.mdx | 3 +-
.../kubernetes/persistent-volumes.mdx | 5 ++-
.../src/content/docs/deployment/pipelines.mdx | 9 ++--
.../docs/diagnostics/aspireacadomains001.mdx | 3 +-
.../docs/diagnostics/aspireacanaming001.mdx | 3 +-
.../docs/diagnostics/aspireazure002.mdx | 3 +-
.../docs/diagnostics/aspireazure003.mdx | 3 +-
.../docs/diagnostics/aspireblazor001.mdx | 3 +-
.../docs/diagnostics/aspirebrowserlogs001.mdx | 3 +-
.../diagnostics/aspirecertificates001.mdx | 5 ++-
.../docs/diagnostics/aspirecommand001.mdx | 3 +-
.../docs/diagnostics/aspirecompute002.mdx | 3 +-
.../docs/diagnostics/aspirecompute003.mdx | 3 +-
.../docs/diagnostics/aspirecosmosdb001.mdx | 3 +-
.../docs/diagnostics/aspirecsharpapps001.mdx | 3 +-
.../aspiredockerfilebuilder001.mdx | 3 +-
.../diagnostics/aspiredotnetproject001.mdx | 5 ++-
.../docs/diagnostics/aspiredotnettool001.mdx | 3 +-
.../docs/diagnostics/aspiredurabletask001.mdx | 11 ++---
.../docs/diagnostics/aspireextension001.mdx | 3 +-
.../diagnostics/aspirehostingpython001.mdx | 3 +-
.../docs/diagnostics/aspirejavascript001.mdx | 11 ++---
.../content/docs/diagnostics/aspiremcp001.mdx | 3 +-
.../docs/diagnostics/aspirepersistence001.mdx | 9 ++--
.../docs/diagnostics/aspirepipelines003.mdx | 3 +-
.../docs/diagnostics/aspirepostgres001.mdx | 5 ++-
.../docs/diagnostics/aspireprobes001.mdx | 3 +-
.../diagnostics/aspireprocesscommand001.mdx | 3 +-
.../docs/diagnostics/aspireprojects001.mdx | 3 +-
.../docs/diagnostics/aspireradius003.mdx | 1 +
.../docs/diagnostics/aspireterminal001.mdx | 3 +-
.../docs/diagnostics/aspireusersecrets001.mdx | 5 ++-
.../src/content/docs/diagnostics/overview.mdx | 14 +++---
.../docs/extensibility/custom-resources.mdx | 5 ++-
.../extensibility/interaction-service.mdx | 3 +-
.../multi-language-integration-authoring.mdx | 3 +-
.../fundamentals/annotations-overview.mdx | 9 ++--
.../fundamentals/container-networking.mdx | 3 +-
.../fundamentals/custom-resource-commands.mdx | 5 ++-
.../fundamentals/custom-resource-urls.mdx | 11 ++---
.../fundamentals/environment-variables.mdx | 5 ++-
.../docs/fundamentals/external-parameters.mdx | 13 +++---
.../docs/fundamentals/health-checks.mdx | 7 +--
.../docs/fundamentals/http-commands.mdx | 3 +-
.../docs/fundamentals/networking-overview.mdx | 9 ++--
.../fundamentals/persist-data-volumes.mdx | 13 +++---
.../docs/fundamentals/service-discovery.mdx | 5 ++-
.../get-started/add-aspire-existing-app.mdx | 2 +-
.../docs/get-started/ai-coding-agents.mdx | 1 +
.../content/docs/get-started/aspire-sdk.mdx | 3 +-
.../get-started/aspire-vscode-extension.mdx | 1 +
.../ai/github-models/github-models-host.mdx | 5 ++-
.../integrations/ai/ollama/ollama-connect.mdx | 3 +-
.../integrations/ai/ollama/ollama-host.mdx | 9 ++--
.../integrations/ai/openai/openai-host.mdx | 9 ++--
.../caching/garnet/garnet-connect.mdx | 3 +-
.../caching/garnet/garnet-host.mdx | 7 +--
.../redis-distributed-get-started.mdx | 3 +-
.../redis-distributed-host.mdx | 11 ++---
.../integrations/caching/redis-extensions.mdx | 5 ++-
.../caching/redis/redis-connect.mdx | 3 +-
.../integrations/caching/redis/redis-host.mdx | 9 ++--
.../caching/valkey/valkey-connect.mdx | 3 +-
.../caching/valkey/valkey-host.mdx | 9 ++--
.../integrations/cloud/azure/aks/index.mdx | 9 ++--
.../azure-ai-foundry-connect.mdx | 3 +-
.../azure-ai-foundry-get-started.mdx | 5 ++-
.../azure-ai-foundry-host.mdx | 43 +++++++++---------
.../azure-ai-inference-host.mdx | 3 +-
.../azure-ai-search/azure-ai-search-host.mdx | 9 ++--
.../azure-app-configuration-host.mdx | 19 ++++----
.../azure-app-service-get-started.mdx | 3 +-
.../azure-app-service-host.mdx | 13 +++---
.../azure/azure-application-insights.mdx | 9 ++--
.../azure-cache-redis-connect.mdx | 5 ++-
.../azure-cache-redis-host.mdx | 13 +++---
.../cloud/azure/azure-connector-namespace.mdx | 5 ++-
.../azure-container-registry-connect.mdx | 5 ++-
.../azure-container-registry-get-started.mdx | 3 +-
.../azure-container-registry-host.mdx | 15 ++++---
.../azure-cosmos-db-connect.mdx | 5 ++-
.../azure-cosmos-db/azure-cosmos-db-host.mdx | 27 +++++------
.../cloud/azure/azure-data-explorer.mdx | 11 ++---
.../cloud/azure/azure-default-credential.mdx | 3 +-
.../azure-event-hubs-host.mdx | 19 ++++----
.../cloud/azure/azure-front-door.mdx | 11 ++---
.../azure-functions-connect.mdx | 3 +-
.../azure-functions-get-started.mdx | 3 +-
.../azure-functions/azure-functions-host.mdx | 15 ++++---
.../azure-key-vault/azure-key-vault-host.mdx | 17 +++----
.../cloud/azure/azure-log-analytics.mdx | 7 +--
.../azure/azure-openai/azure-openai-host.mdx | 13 +++---
.../azure-postgresql-connect.mdx | 3 +-
.../azure-postgresql-get-started.mdx | 3 +-
.../azure-postgresql-host.mdx | 19 ++++----
.../azure-service-bus-host.mdx | 21 ++++-----
.../azure-signalr/azure-signalr-connect.mdx | 3 +-
.../azure-signalr/azure-signalr-host.mdx | 13 +++---
.../azure-sql-database-connect.mdx | 5 ++-
.../azure-sql-database-get-started.mdx | 5 ++-
.../azure-sql-database-host.mdx | 19 ++++----
.../azure-storage-blobs-connect.mdx | 7 +--
.../azure-storage-blobs-host.mdx | 21 ++++-----
.../cloud/azure/azure-storage-datalake.mdx | 7 +--
.../azure-storage-queues-connect.mdx | 3 +-
.../azure-storage-queues-get-started.mdx | 3 +-
.../azure-storage-queues-host.mdx | 13 +++---
.../azure-storage-tables-connect.mdx | 3 +-
.../azure-storage-tables-get-started.mdx | 3 +-
.../azure-storage-tables-host.mdx | 21 ++++-----
.../cloud/azure/azure-virtual-network.mdx | 37 +++++++--------
.../azure-web-pubsub-connect.mdx | 3 +-
.../azure-web-pubsub-host.mdx | 13 +++---
.../cloud/azure/configure-container-apps.mdx | 17 +++----
.../cloud/azure/container-app-jobs.mdx | 9 ++--
.../cloud/azure/customize-resources.mdx | 13 +++---
.../cloud/azure/local-provisioning.mdx | 5 ++-
.../integrations/cloud/azure/overview.mdx | 13 +++---
.../cloud/azure/user-assigned-identity.mdx | 7 +--
.../docs/integrations/compute/docker.mdx | 31 ++++++-------
.../docs/integrations/compute/floci.mdx | 7 +--
.../content/docs/integrations/compute/k3s.mdx | 17 +++----
.../docs/integrations/compute/kubernetes.mdx | 13 +++---
.../hosting-integrations.mdx | 7 +--
.../secure-communication.mdx | 3 +-
.../clickhouse/clickhouse-connect.mdx | 3 +-
.../databases/clickhouse/clickhouse-host.mdx | 5 ++-
.../azure-cosmos-db/azure-cosmos-db-host.mdx | 11 ++---
.../azure-sql/azure-sql-get-started.mdx | 3 +-
.../efcore/azure-sql/azure-sql-host.mdx | 11 ++---
.../databases/efcore/migrations.mdx | 9 ++--
.../efcore/mongodb/mongodb-efcore-connect.mdx | 3 +-
.../databases/efcore/mysql/mysql-connect.mdx | 3 +-
.../databases/efcore/oracle/oracle-host.mdx | 9 ++--
.../efcore/postgres/postgresql-connect.mdx | 3 +-
.../databases/efcore/seed-database.mdx | 5 ++-
.../efcore/sql-server/sql-server-connect.mdx | 3 +-
.../elasticsearch/elasticsearch-connect.mdx | 5 ++-
.../elasticsearch/elasticsearch-host.mdx | 3 +-
.../databases/kurrentdb/kurrentdb-connect.mdx | 3 +-
.../meilisearch/meilisearch-connect.mdx | 3 +-
.../meilisearch/meilisearch-host.mdx | 7 +--
.../databases/milvus/milvus-host.mdx | 5 ++-
.../databases/mongodb/mongodb-extensions.mdx | 5 ++-
.../databases/mongodb/mongodb-host.mdx | 25 ++++++-----
.../databases/mysql/mysql-extensions.mdx | 7 +--
.../databases/mysql/mysql-get-started.mdx | 3 +-
.../databases/mysql/mysql-host.mdx | 9 ++--
.../databases/postgres/postgres-host.mdx | 13 +++---
.../postgres/postgresql-extensions.mdx | 9 ++--
.../databases/ravendb/ravendb-connect.mdx | 3 +-
.../databases/ravendb/ravendb-host.mdx | 3 +-
.../sql-server/sql-server-extensions.mdx | 7 +--
.../databases/sql-server/sql-server-host.mdx | 9 ++--
.../databases/sqlite/sqlite-connect.mdx | 3 +-
.../databases/sqlite/sqlite-get-started.mdx | 3 +-
.../databases/sqlite/sqlite-host.mdx | 5 ++-
.../databases/surrealdb/surrealdb-connect.mdx | 3 +-
.../databases/surrealdb/surrealdb-host.mdx | 7 +--
.../integrations/devtools/browser-logs.mdx | 3 +-
.../integrations/devtools/dab/dab-host.mdx | 3 +-
.../integrations/devtools/dev-tunnels.mdx | 7 +--
.../devtools/flagd/flagd-host.mdx | 5 ++-
.../devtools/goff/goff-connect.mdx | 3 +-
.../integrations/devtools/goff/goff-host.mdx | 9 ++--
.../docs/integrations/devtools/k6/k6-host.mdx | 11 ++---
.../devtools/mailpit/mailpit-connect.mdx | 3 +-
.../sql-projects/sql-projects-host.mdx | 13 +++---
.../integrations/dotnet/blazor-connect.mdx | 3 +-
.../dotnet/blazor-get-started.mdx | 5 ++-
.../integrations/dotnet/blazor-hosting.mdx | 2 +-
.../dotnet/csharp-file-based-apps.mdx | 5 ++-
.../dotnet/dotnet-tool-resources.mdx | 15 ++++---
.../integrations/dotnet/launch-profiles.mdx | 7 +--
.../content/docs/integrations/dotnet/maui.mdx | 5 ++-
.../integrations/dotnet/project-resources.mdx | 15 ++++---
.../docs/integrations/frameworks/bun-apps.mdx | 5 ++-
.../frameworks/deno/deno-get-started.mdx | 3 +-
.../frameworks/deno/deno-host.mdx | 11 ++---
.../frameworks/dotnet/dotnet-get-started.mdx | 5 ++-
.../frameworks/dotnet/dotnet-host.mdx | 9 ++--
.../frameworks/go/go-get-started.mdx | 3 +-
.../integrations/frameworks/go/go-host.mdx | 19 ++++----
.../frameworks/java/java-connect.mdx | 4 +-
.../integrations/frameworks/javascript.mdx | 31 ++++++-------
.../frameworks/nodejs-extensions.mdx | 11 ++---
.../docs/integrations/frameworks/orleans.mdx | 5 ++-
.../frameworks/perl/perl-get-started.mdx | 3 +-
.../frameworks/perl/perl-host.mdx | 23 +++++-----
.../frameworks/powershell/powershell-host.mdx | 11 ++---
.../docs/integrations/frameworks/python.mdx | 25 ++++++-----
.../frameworks/rust/rust-host.mdx | 2 +-
.../integrations/frameworks/wpf-winforms.mdx | 3 +-
.../apache-kafka/apache-kafka-host.mdx | 3 +-
.../messaging/lavinmq/lavinmq-host.mdx | 5 ++-
.../messaging/nats/nats-get-started.mdx | 3 +-
.../integrations/messaging/nats/nats-host.mdx | 3 +-
.../messaging/rabbitmq/rabbitmq-connect.mdx | 3 +-
.../messaging/rabbitmq/rabbitmq-host.mdx | 7 +--
.../observability/seq/seq-connect.mdx | 3 +-
.../integrations/reverse-proxies/yarp.mdx | 11 ++---
.../docs/integrations/security/keycloak.mdx | 19 ++++----
.../ja/app-host/certificate-configuration.mdx | 11 ++---
.../docs/ja/app-host/container-files.mdx | 9 ++--
.../docs/ja/app-host/container-registry.mdx | 5 ++-
.../src/content/docs/ja/app-host/eventing.mdx | 13 +++---
.../docs/ja/app-host/executable-resources.mdx | 9 ++--
.../app-host/migrate-from-docker-compose.mdx | 21 ++++-----
.../docs/ja/app-host/resource-lifetimes.mdx | 5 ++-
.../docs/ja/app-host/withdockerfile.mdx | 9 ++--
.../multi-language-architecture.mdx | 5 ++-
.../ja/architecture/resource-api-patterns.mdx | 3 +-
.../ja/architecture/resource-examples.mdx | 2 +
.../ja/architecture/resource-hierarchies.mdx | 7 +--
.../ja/architecture/resource-publishing.mdx | 3 +-
.../content/docs/ja/deployment/pipelines.mdx | 9 ++--
.../ja/extensibility/custom-resources.mdx | 5 ++-
.../ja/extensibility/interaction-service.mdx | 3 +-
.../multi-language-integration-authoring.mdx | 3 +-
.../fundamentals/custom-resource-commands.mdx | 3 +-
.../ja/fundamentals/custom-resource-urls.mdx | 11 ++---
.../ja/fundamentals/external-parameters.mdx | 13 +++---
.../docs/ja/fundamentals/health-checks.mdx | 7 +--
.../docs/ja/fundamentals/http-commands.mdx | 3 +-
.../ja/fundamentals/networking-overview.mdx | 9 ++--
.../ja/fundamentals/persist-data-volumes.mdx | 13 +++---
.../ja/fundamentals/service-discovery.mdx | 5 ++-
.../get-started/add-aspire-existing-app.mdx | 9 ++--
.../docs/ja/get-started/aspire-mcp-server.mdx | 3 +-
.../get-started/aspire-vscode-extension.mdx | 1 +
.../docs/ja/get-started/deploy-first-app.mdx | 9 ++--
.../src/content/docs/ja/get-started/faq.mdx | 6 ++-
.../content/docs/ja/get-started/first-app.mdx | 17 +++----
.../ja/get-started/resource-mcp-servers.mdx | 5 ++-
.../docs/ja/get-started/troubleshooting.mdx | 5 ++-
.../integrations/dotnet/launch-profiles.mdx | 7 +--
.../docs/ja/testing/accessing-resources.mdx | 3 +-
.../docs/ja/testing/write-your-first-test.mdx | 3 +-
.../content/docs/ja/whats-new/aspire-13-1.mdx | 11 ++---
.../content/docs/ja/whats-new/aspire-13-2.mdx | 33 +++++++-------
.../content/docs/ja/whats-new/aspire-13-3.mdx | 33 +++++++-------
.../content/docs/ja/whats-new/aspire-13.mdx | 43 +++++++++---------
.../cli/commands/aspire-docs-api-search.mdx | 3 +-
.../reference/cli/commands/aspire-init.mdx | 3 +-
.../docs/testing/accessing-resources.mdx | 3 +-
.../docs/testing/advanced-scenarios.mdx | 7 +--
.../docs/testing/write-your-first-test.mdx | 3 +-
.../content/docs/whats-new/aspire-13-1.mdx | 11 ++---
.../content/docs/whats-new/aspire-13-2.mdx | 35 ++++++++-------
.../content/docs/whats-new/aspire-13-3.mdx | 33 +++++++-------
.../content/docs/whats-new/aspire-13-4.mdx | 33 +++++++-------
.../content/docs/whats-new/aspire-13-5.mdx | 19 ++++----
.../content/docs/whats-new/aspire-13-6.mdx | 43 +++++++++---------
.../src/content/docs/whats-new/aspire-13.mdx | 45 ++++++++++---------
.../src/content/docs/whats-new/aspire-9-1.mdx | 5 ++-
.../src/content/docs/whats-new/aspire-9-2.mdx | 11 ++---
.../src/content/docs/whats-new/aspire-9-3.mdx | 33 +++++++-------
.../src/content/docs/whats-new/aspire-9-4.mdx | 21 ++++-----
.../src/content/docs/whats-new/aspire-9-5.mdx | 23 +++++-----
.../src/content/docs/whats-new/aspire-9.mdx | 13 +++---
.../tests/unit/api-reference.vitest.test.ts | 12 +++++
.../dashboard-image-references.vitest.test.ts | 4 +-
296 files changed, 1444 insertions(+), 1137 deletions(-)
diff --git a/src/frontend/src/content/docs/app-host/certificate-configuration.mdx b/src/frontend/src/content/docs/app-host/certificate-configuration.mdx
index 7acf8fc54..3ade07657 100644
--- a/src/frontend/src/content/docs/app-host/certificate-configuration.mdx
+++ b/src/frontend/src/content/docs/app-host/certificate-configuration.mdx
@@ -6,13 +6,14 @@ description: Configure HTTPS endpoints and certificate trust for Aspire resource
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import OsAwareTabs from '@components/OsAwareTabs.astro';
+import ApiReference from '@components/ApiReference.astro';
Aspire provides two complementary sets of certificate APIs:
1. **HTTPS endpoint APIs**: Configure the certificates that resources use for their own HTTPS endpoints (server authentication)
2. **Certificate trust APIs**: Configure which certificates resources trust when making outbound HTTPS connections (client authentication)
-Both sets of APIs work together to enable secure HTTPS communication during local development. For example, a Vite frontend might use `WithHttpsDeveloperCertificate` to serve HTTPS traffic, while also using `WithDeveloperCertificateTrust` to trust the dashboard's OTLP endpoint certificate.
+Both sets of APIs work together to enable secure HTTPS communication during local development. For example, a Vite frontend might use OTLP endpoint certificate.
Certificate customization only applies at run time. Custom certificates aren't
@@ -151,7 +152,7 @@ HTTPS endpoint configuration determines which certificate a resource presents wh
### Default behavior
-For resources that have a certificate configuration defined with `WithHttpsCertificateConfiguration`, Aspire attempts to configure it to use the development certificate if available. This automatic configuration works for many common resource types including YARP, Redis, and Keycloak containers; Vite based JavaScript apps; and Python apps using Uvicorn.
+For resources that have a certificate configuration defined with
@@ -436,7 +437,7 @@ The `withContainerFiles` API is not yet available in the TypeScript AppHost SDK.
-Use `ClearContainerFilesSources` to remove any previously configured source paths before adding new ones.
+Use
-Use the `AddContainerRegistry` method to configure a generic container registry for your application. This works with any Docker-compatible registry including DockerHub, GitHub Container Registry, Harbor, and private registries.
+Use the
diff --git a/src/frontend/src/content/docs/app-host/eventing.mdx b/src/frontend/src/content/docs/app-host/eventing.mdx
index ba6dafd55..f45685daa 100644
--- a/src/frontend/src/content/docs/app-host/eventing.mdx
+++ b/src/frontend/src/content/docs/app-host/eventing.mdx
@@ -6,6 +6,7 @@ description: Use the Aspire AppHost eventing APIs for lifecycle events, custom e
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
In Aspire, eventing allows you to publish and subscribe to events during various AppHost life cycles. Eventing is more flexible than life cycle events. Both let you run arbitrary code during event callbacks, but eventing offers finer control of event timing, publishing, and provides supports for custom events.
@@ -110,7 +111,7 @@ builder.Eventing.Subscribe(
`builder.Eventing.Subscribe()` API. Use the named callback APIs
generated for each supported event, such as `subscribeBeforeStart`,
`subscribeAfterResourcesCreated`, `addEventingSubscriber`, and resource
- callbacks like `onResourceReady`.
+ callbacks like
@@ -278,12 +279,12 @@ The preceding code subscribes to the `InitializeResourceEvent`, `ResourceReadyEv
and `await event.services()` when you need the resource or service provider.
-- `OnInitializeResource` / `onInitializeResource`: Subscribes to the `InitializeResourceEvent`.
-- `OnResourceEndpointsAllocated` / `onResourceEndpointsAllocated`: Subscribes to the `ResourceEndpointsAllocatedEvent` event.
-- `OnConnectionStringAvailable` / `onConnectionStringAvailable`: Subscribes to the `ConnectionStringAvailableEvent` event.
-- `OnBeforeResourceStarted` / `onBeforeResourceStarted`: Subscribes to the `BeforeResourceStartedEvent` event.
+-
-When one resource depends on another, `WithReference` passes along environment variables containing the dependent resource's connection details. For example, the `worker` executable's reference to `redis` and `postgres` provides it with the `ConnectionStrings__cache` and `ConnectionStrings__appdb` environment variables, which contain connection strings to these resources.
+When one resource depends on another,
@@ -353,7 +354,7 @@ When working with executable resources:
1. **Use explicit paths**: For better reliability, use full paths to executables when possible.
1. **Handle dependencies**: Use `WithReference` to establish proper dependency relationships.
-1. **Configure explicit start**: Use `WithExplicitStart()` for executables that shouldn't start automatically.
+1. **Configure explicit start**: Use
-In Docker Compose, the `build:` directive creates container images from Dockerfiles. In Aspire, .NET services are added directly as project references with `AddProject()`, providing better debugging, hot reload, and telemetry integration. For services that still build from Dockerfiles, use `AddDockerfile()` for an existing Dockerfile or `AddDockerfileBuilder()` when the AppHost should generate the Dockerfile programmatically.
+In Docker Compose, the `build:` directive creates container images from Dockerfiles. In Aspire, .NET services are added directly as project references with
**Key differences explained:**
- **Build vs. project** — Docker Compose `build:` services become `AddProject()` for .NET apps, which runs them directly instead of in containers
- **Ports** — Both examples explicitly map ports (3000 and 5000)
-- **Startup order** — Docker Compose uses `depends_on` with health conditions; Aspire uses `WaitFor()` for startup ordering
-- **Service discovery** — `WithReference()` only configures service discovery and connection strings; it doesn't control startup order
-- **Connection strings** — By default, `WithReference(database)` provides `ConnectionStrings__myapp` using the resource name from `AddDatabase()`. To match a different name like `DefaultConnection`, use a named reference: `.WithReference(database, "DefaultConnection")`
-- **Volumes** — `WithDataVolume()` must be called explicitly to add persistent storage; it's not automatic
+- **Startup order** — Docker Compose uses `depends_on` with health conditions; Aspire uses ;Database=main`
-If your application expects URL-format environment variables, construct them manually with `WithEnvironment()`. See [Environment variables and configuration](#environment-variables-and-configuration) for details.
+If your application expects URL-format environment variables, construct them manually with
@@ -305,7 +306,7 @@ The dependent resource's lifetime is evaluated when Aspire prepares the applicat
## Scope cleanup to a parent process
-Use `WithParentProcessLifetime` when a resource should survive AppHost restarts but be cleaned up when another process exits. Aspire records the parent process identity instead of retaining a live process handle, so the cleanup scope follows the specific process instance instead of a reused process ID.
+Use
@@ -413,7 +414,7 @@ For example, if you have a service named `"postgres"` in an AppHost project loca
### Custom container names
-For advanced scenarios, you can set a custom container name using the `WithContainerName` method:
+For advanced scenarios, you can set a custom container name using the
diff --git a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx
index 27c4a361c..6728fe5fc 100644
--- a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx
+++ b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx
@@ -7,6 +7,7 @@ description: Learn the files and configuration that make up a TypeScript AppHost
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import FileTree from 'starlight-plugin-icons/components/FileTree.astro';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
When you create a TypeScript AppHost with `aspire new`, the CLI scaffolds a project with the following structure:
@@ -295,7 +296,7 @@ The Aspire CLI supports the following package managers at the **AppHost root**
| Deno | `packageManager`, `deno.lock`, `deno.json`, or `deno.jsonc` | Deno 2 or later |
| Yarn Classic (v1) | `yarn.lock` with `# yarn lockfile v1` or `packageManager` with `yarn@1.x` | Not supported |
-This policy governs the **AppHost root only**. Apps the AppHost orchestrates — for example, a Node.js service added with `addNodeApp`, a Bun guest app, or a workspace package — can use any package manager their own tooling requires; they are independent of the AppHost-root toolchain.
+This policy governs the **AppHost root only**. Apps the AppHost orchestrates — for example, a Node.js service added with
diff --git a/src/frontend/src/content/docs/app-host/withdockerfile.mdx b/src/frontend/src/content/docs/app-host/withdockerfile.mdx
index df30b8257..0c1cbab72 100644
--- a/src/frontend/src/content/docs/app-host/withdockerfile.mdx
+++ b/src/frontend/src/content/docs/app-host/withdockerfile.mdx
@@ -5,8 +5,9 @@ description: Add Dockerfiles to your Aspire app model with WithDockerfile — bu
---
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
-With Aspire it's possible to specify a _Dockerfile_ to build when the [AppHost](/get-started/app-host/) is started using either the `AddDockerfile` or `WithDockerfile` extension methods.
+With Aspire it's possible to specify a _Dockerfile_ to build when the [AppHost](/get-started/app-host/) is started using either the
The Dockerfile builder APIs are experimental and may change in future
@@ -249,7 +250,7 @@ await builder.build().run();
## Generate a Dockerfile with a factory function
-Use `AddDockerfileFactory` or `WithDockerfileFactory` when you need to generate a Dockerfile as a string from AppHost code. Unlike the [Dockerfile builder APIs](#generate-a-dockerfile-programmatically) that use a fluent API to compose Dockerfile instructions, the factory APIs let you return Dockerfile content directly as a string — useful when you already have string-based Dockerfile generation logic or want to construct content conditionally.
+Use
@@ -419,7 +420,7 @@ CMD ["./mygoapp"]
## Pass build secrets
-In addition to build arguments it's possible to specify build secrets using `WithBuildSecret` which are made selectively available to individual commands in the _Dockerfile_ using the `--mount=type=secret` syntax on `RUN` commands.
+In addition to build arguments it's possible to specify build secrets using
diff --git a/src/frontend/src/content/docs/architecture/multi-language-architecture.mdx b/src/frontend/src/content/docs/architecture/multi-language-architecture.mdx
index 0709757d1..241dafec2 100644
--- a/src/frontend/src/content/docs/architecture/multi-language-architecture.mdx
+++ b/src/frontend/src/content/docs/architecture/multi-language-architecture.mdx
@@ -5,6 +5,7 @@ description: Understand how Aspire uses a guest/host architecture, ATS, SDK gene
---
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
Aspire supports writing AppHosts in multiple languages. While the orchestration engine is built on .NET, a guest/host architecture allows AppHosts written in TypeScript today, and additional languages in the future, to access Aspire integrations, service discovery, and the dashboard.
@@ -12,7 +13,7 @@ Aspire supports writing AppHosts in multiple languages. While the orchestration
Aspire's hosting integrations and deployment publishers are written in .NET and have already accumulated the runtime behavior needed for local orchestration, diagnostics, and publishing. Rewriting those integrations for every guest language would duplicate a large amount of behavior and significantly increase maintenance cost.
-Instead, guest languages only declare resources such as `addRedis`, `addPostgres`, and `withReference`, while the .NET host handles orchestration concerns such as starting containers, wiring service discovery, running health checks, and generating deployment artifacts. The trade-off is a local IPC hop, which is much cheaper than maintaining the same integration surface independently in multiple languages.
+Instead, guest languages only declare resources such as References { get; }` | Both (if needed) | Declare dependencies on other resources |
- **Implement** `IValueProvider` and `IManifestExpressionProvider` on all structured value types.
-- **Implement** `IExpressionValue` when a structured value type should be accepted by APIs such as `WithEnvironment(...)`.
+- **Implement** `IExpressionValue` when a structured value type should be accepted by APIs such as
- The overloads of `WithEnvironment` that take a callback run after endpoints
+ The overloads of
diff --git a/src/frontend/src/content/docs/architecture/resource-publishing.mdx b/src/frontend/src/content/docs/architecture/resource-publishing.mdx
index eece9edb0..ff91418a8 100644
--- a/src/frontend/src/content/docs/architecture/resource-publishing.mdx
+++ b/src/frontend/src/content/docs/architecture/resource-publishing.mdx
@@ -5,6 +5,7 @@ description: Learn how Aspire publishes resource manifests as JSON for deploymen
---
import { Steps } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
Aspire provides a flexible mechanism for publishing resource manifests, enabling seamless integration with various deployment environments. Resources are serialized into JSON format, which can be consumed by deployment tools.
@@ -18,7 +19,7 @@ Custom resources that publish JSON manifest entries must:
-Resources can opt-out of being included in the publishing manifest entirely by calling the `ExcludeFromManifest()` extension method on the `IResourceBuilder`. Resources marked this way will be omitted when generating publishing assets like Docker Compose files or Kubernetes manifests.
+Resources can opt-out of being included in the publishing manifest entirely by calling the `. Resources marked this way will be omitted when generating publishing assets like Docker Compose files or Kubernetes manifests.
## Registering the callback
diff --git a/src/frontend/src/content/docs/dashboard/ephemeral-terminals.mdx b/src/frontend/src/content/docs/dashboard/ephemeral-terminals.mdx
index 219df7417..f946cd2c9 100644
--- a/src/frontend/src/content/docs/dashboard/ephemeral-terminals.mdx
+++ b/src/frontend/src/content/docs/dashboard/ephemeral-terminals.mdx
@@ -3,6 +3,8 @@ title: Create ephemeral terminals from your AppHost
description: Use TerminalService to launch interactive processes, display docked terminals, and manage their lifetime independently of resources in your AppHost.
---
+import ApiReference from '@components/ApiReference.astro';
+
Ephemeral terminals let AppHost code launch an interactive process for a specific task and display it in the dashboard. Redis's `WithRepl()` is one example: it adds a resource command that opens an authenticated `redis-cli` session inside the running container.
The same building blocks are available for your own commands. Use `Aspire.Hosting.ApplicationModel.TerminalService` to create a terminal, configure its executable and placement, start its process, and show it in the dock. The [custom docked SQL REPL sample](https://github.com/microsoft/aspire-samples/tree/main/samples/terminals/docked-repl-csharp) demonstrates this with rqlite's SQL client.
@@ -75,7 +77,7 @@ The same mechanism can launch other interactive programs, not just REPLs. For ex
## Open a database or cache REPL
-A read-eval-print loop (REPL) accepts commands and displays their results interactively. The built-in `WithRepl()` methods are examples of this command-driven experience: they add an opt-in **REPL** resource command that opens the integration's bundled client in the dashboard terminal dock. They don't replace the database server's process or require `WithTerminal()`.
+A read-eval-print loop (REPL) accepts commands and displays their results interactively. The built-in `WithRepl()` methods are examples of this command-driven experience: they add an opt-in **REPL** resource command that opens the integration's bundled client in the dashboard terminal dock. They don't replace the database server's process or require
-For a standard App Service deployment, you only need the environment and a supported app resource. Use `PublishAsAzureAppServiceWebsite` only when you want to customize the generated website or deployment slot.
+For a standard App Service deployment, you only need the environment and a supported app resource. Use
diff --git a/src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx b/src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx
index 9a271f313..db4e35a43 100644
--- a/src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx
+++ b/src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx
@@ -9,6 +9,7 @@ topic: deployment
import { Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
The Azure Developer CLI (`azd`) is still supported with Aspire for existing workflows, but it is no longer the recommended default deployment path.
@@ -37,7 +38,7 @@ This page does not duplicate `azd`'s full operational workflow. For install, ini
## Resource naming
-The `aspire deploy` path and `azd` use different resource naming schemes by default. If you're upgrading from an existing `azd` deployment to `aspire deploy`, use `WithAzdResourceNaming()` to preserve the original naming convention. This avoids creating duplicate Azure resources:
+The `aspire deploy` path and `azd` use different resource naming schemes by default. If you're upgrading from an existing `azd` deployment to `aspire deploy`, use
@@ -85,7 +86,7 @@ Aspire parameters and `azd` inputs follow different paths:
| Parameter type | How it reaches Azure resources |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Aspire parameters** (`AddParameter`) | Resolved by the AppHost through .NET configuration when generating the manifest. Use `appsettings.{env}.json` or environment variables. |
+| **Aspire parameters** (
@@ -278,7 +279,7 @@ await builder.build().run();
### Internal service discovery
-Services deployed to Azure Container Apps use internal DNS for service discovery. Use `WithExternalHttpEndpoints()` only for endpoints you want reachable outside the Container Apps environment.
+Services deployed to Azure Container Apps use internal DNS for service discovery. Use
@@ -358,7 +359,7 @@ await env.withDashboard(false);
Express environments are experimental and may change in future releases. The
- `AsExpress` API reports [ASPIREACAEXPRESS001](/diagnostics/aspireacaexpress001/),
+
@@ -267,15 +268,15 @@ When you run `aspire deploy` directly, Aspire binds the role assignment to the a
For a new sandbox group, Aspire creates a dedicated user-assigned managed identity, attaches it to the sandbox group, and grants it only the `AcrPull` role on the group's Azure Container Registry. The service uses this identity to import private images from the registry. Public registry images are imported without it, and registry credentials aren't sent to the service or stored in deployment state.
-Use `WithAcrPullIdentity` to supply a different user-assigned identity. For sandbox groups that Aspire creates, the identity is attached automatically, but you're responsible for granting it `AcrPull` on the registry.
+Use
diff --git a/src/frontend/src/content/docs/deployment/custom-deployments.mdx b/src/frontend/src/content/docs/deployment/custom-deployments.mdx
index 0b7e34ff6..4838e50f5 100644
--- a/src/frontend/src/content/docs/deployment/custom-deployments.mdx
+++ b/src/frontend/src/content/docs/deployment/custom-deployments.mdx
@@ -5,6 +5,7 @@ description: Build container images from your Aspire resources and create custom
---
import { Aside } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
Aspire provides powerful APIs for building container images from your resources during publishing and deployment operations. This article covers the key components that enable programmatic container image creation and progress reporting.
@@ -46,7 +47,7 @@ The `IResourceContainerImageManager` is the core service in the `Aspire.Hosting.
### Configure container builds
-Configure each compute resource with `WithContainerBuildOptions`. The callback receives a `ContainerBuildOptionsCallbackContext` that allows you to specify:
+Configure each compute resource with ` are different ways of entering that pipeline.
@@ -162,7 +163,7 @@ The placeholder name in published output is target-specific, but the mapping sta
This `.env` example is specific to Docker Compose publish output. It illustrates the **publish artifact handoff** path. `aspire deploy` does not consume this `.env` file; Aspire resolves the parameter before applying changes directly.
-Because this example has only one matching compute environment, the project resource attaches to it automatically. Use `WithComputeEnvironment` only when you need to disambiguate between multiple matching targets.
+Because this example has only one matching compute environment, the project resource attaches to it automatically. Use
@@ -217,7 +218,7 @@ When you publish or deploy, Aspire generates the following artifacts in the `asp
## Generate Dockerfiles from your AppHost
-Docker Compose deployments can build images from Dockerfiles that are generated by your AppHost. Use `AddDockerfileBuilder` to create a new container resource from a generated Dockerfile, or `WithDockerfileBuilder` to replace the image for an existing container resource with a generated Dockerfile build.
+Docker Compose deployments can build images from Dockerfiles that are generated by your AppHost. Use
The Dockerfile builder APIs are experimental and may change in future
@@ -301,7 +302,7 @@ The Docker hosting integration captures environment variables from your app mode
### Customize environment file
-For advanced scenarios, use `ConfigureEnvFile` to customize the generated `.env` file:
+For advanced scenarios, use
@@ -346,7 +347,7 @@ This is useful when you need to add custom environment variables to the generate
## Customize the Docker Compose file
-Use `ConfigureComposeFile` to customize the generated `docker-compose.yml` model before Aspire writes it to disk:
+Use
@@ -390,7 +391,7 @@ await builder.build().run();
## Customize Docker Compose services
-To customize the generated Docker Compose service for a specific resource, use the `PublishAsDockerComposeService` method. This is optional — all resources are automatically included in the Docker Compose output. Use this method only when you need to modify the generated service definition:
+To customize the generated Docker Compose service for a specific resource, use the
@@ -437,11 +438,11 @@ await builder.build().run();
-The `configure` callback receives the `DockerComposeServiceResource` and the generated `Service` object, allowing you to modify properties like labels, restart policy, container name, or other Docker Compose service settings. Use `AsEnvironmentPlaceholder` for values that should be written as Compose environment variable placeholders in the generated YAML and `.env` files.
+The `configure` callback receives the `DockerComposeServiceResource` and the generated `Service` object, allowing you to modify properties like labels, restart policy, container name, or other Docker Compose service settings. Use
@@ -476,7 +477,7 @@ const apiHost = await compose.getHostAddressExpression(apiEndpoint);
## Image pull policy
-Container resources support an `ImagePullPolicy` that controls when the container runtime pulls an image. Use the `WithImagePullPolicy` extension method to set the policy on a container resource:
+Container resources support an `ImagePullPolicy` that controls when the container runtime pulls an image. Use the
@@ -520,7 +521,7 @@ When deploying containers, you can customize how container images are named, tag
### Set remote image name and tag
-Use `WithRemoteImageName` and `WithRemoteImageTag` to customize the image reference:
+Use
@@ -556,7 +557,7 @@ await api.withRemoteImageTag('v1.0.0');
### Advanced customization with callbacks
-For more complex scenarios, use `WithImagePushOptions` to register a callback that dynamically configures push options:
+For more complex scenarios, use
@@ -606,7 +607,7 @@ Multiple callbacks can be registered on the same resource, and they are invoked
### Configure a container registry
-Use the `AddContainerRegistry` method to define a container registry and `WithContainerRegistry` to associate resources with it:
+Use the
diff --git a/src/frontend/src/content/docs/deployment/environments.mdx b/src/frontend/src/content/docs/deployment/environments.mdx
index 49b6366cb..9ed32e74c 100644
--- a/src/frontend/src/content/docs/deployment/environments.mdx
+++ b/src/frontend/src/content/docs/deployment/environments.mdx
@@ -6,6 +6,7 @@ description: Use Aspire environments to configure your application for developme
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
When you run or deploy an Aspire application, the **environment** determines how the AppHost configures resources, what parameter values are used, and how your deployment is organized. Environments let you use the same AppHost to target different deployment contexts — development, staging, production, or any custom name — without duplicating your application model.
@@ -121,7 +122,7 @@ The following convenience methods are available:
### Set environment variables on child resources
-Your services often need to know which environment they're running in. Different frameworks use different environment variables — use `WithEnvironment` to set the appropriate one for each service:
+Your services often need to know which environment they're running in. Different frameworks use different environment variables — use
@@ -197,7 +198,7 @@ Common environment variable conventions by framework and ecosystem:
| Java (Spring) | `SPRING_PROFILES_ACTIVE` | `dev`, `test`, `prod` |
- `AddNodeApp` automatically sets `NODE_ENV` to `development` or `production`
+ _` in upper case. For a backend resource named `api` with an `http` endpoint, that's `API_HTTP`. If you rename the resource, for example `weather`, or use `https`, the variable becomes `WEATHER_HTTP` or `API_HTTPS`. `apiTarget` adds the reference for you, so no extra `WithReference` call is required when you use `PublishAsStaticWebsite(apiPath, apiTarget)`.
+When the frontend references a backend resource, either explicitly through _` in upper case. For a backend resource named `api` with an `http` endpoint, that's `API_HTTP`. If you rename the resource, for example `weather`, or use `https`, the variable becomes `WEATHER_HTTP` or `API_HTTPS`. `apiTarget` adds the reference for you, so no extra `WithReference` call is required when you use `PublishAsStaticWebsite(apiPath, apiTarget)`.
Each framework reads that variable from its own dev-server config:
@@ -518,7 +519,7 @@ ENTRYPOINT ["sh", "-c", "exec pnpm run start"]
## Next.js standalone apps
-Use `AddNextJsApp` for Next.js apps that use [standalone output](https://nextjs.org/docs/pages/api-reference/next-config-js/output). It is more specific than `AddJavaScriptApp` because it configures the Next.js development server port argument and publish-time standalone container shape, and it validates that the Next.js configuration enables `output: "standalone"`.
+Use `AddNextJsApp` for Next.js apps that use [standalone output](https://nextjs.org/docs/pages/api-reference/next-config-js/output). It is more specific than
diff --git a/src/frontend/src/content/docs/deployment/kubernetes-gateway-aks.mdx b/src/frontend/src/content/docs/deployment/kubernetes-gateway-aks.mdx
index 42630e28b..3bae82442 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes-gateway-aks.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes-gateway-aks.mdx
@@ -11,8 +11,9 @@ sidebar:
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import OsAwareTabs from '@components/OsAwareTabs.astro';
+import ApiReference from '@components/ApiReference.astro';
-This walkthrough shows how to use `AddGateway` to expose Aspire services on Azure Kubernetes Service (AKS) with **Application Gateway for Containers (AGC)** and automatic TLS certificate provisioning via **cert-manager HTTP-01** challenges.
+This walkthrough shows how to use
-**Using `AddAzureKubernetesEnvironment`?** The integrated walkthrough at [Deploy to AKS — Expose your app to the internet](/deployment/kubernetes/aks/#expose-your-app-to-the-internet) covers Gateway API + AGC + cert-manager (HTTP-01) end to end with the Aspire-provisioned cluster. Use this page only if you have a pre-existing AKS cluster that wasn't provisioned by Aspire.
+**Using
@@ -495,7 +496,7 @@ builder.build().run();
-The `WithTls()` call with no arguments auto-generates the TLS secret name (`ingress-tls`) and adds a cert-manager annotation to the Gateway referencing the `ClusterIssuer` specified via the `clusterIssuer` parameter.
+The
diff --git a/src/frontend/src/content/docs/deployment/kubernetes-ingress-aks.mdx b/src/frontend/src/content/docs/deployment/kubernetes-ingress-aks.mdx
index aaa507eac..d94af4ea2 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes-ingress-aks.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes-ingress-aks.mdx
@@ -11,13 +11,14 @@ sidebar:
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import OsAwareTabs from '@components/OsAwareTabs.astro';
+import ApiReference from '@components/ApiReference.astro';
-This walkthrough shows how to use `AddIngress` to expose Aspire services on
+This walkthrough shows how to use
-**Using `AddAzureKubernetesEnvironment`?** The integrated walkthrough at [Deploy to AKS — Expose your app to the internet](/deployment/kubernetes/aks/#expose-your-app-to-the-internet) covers AGC + cert-manager end to end without any of the manual `az aks`, `az network alb`, or `helm install` ceremony below. Use this page only if you have a pre-existing AKS cluster that wasn't provisioned by Aspire, or if you need DNS-01 certificate issuance against an Azure DNS zone.
+**Using
@@ -726,7 +727,7 @@ After the deployment completes, verify the ingress is working:
## How TLS works with Ingress on AGC
When you deploy an ingress with the `cert-manager.io/cluster-issuer` annotation
-and `WithTls`, the following sequence occurs:
+and
@@ -807,7 +808,7 @@ const ingress = k8s.addIngress("ingress")
Deploy without a custom hostname
-When you omit `WithHostname`, AGC automatically assigns a generated FQDN to the
+When you omit
diff --git a/src/frontend/src/content/docs/deployment/kubernetes-ingress.mdx b/src/frontend/src/content/docs/deployment/kubernetes-ingress.mdx
index 624015c67..647a860e0 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes-ingress.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes-ingress.mdx
@@ -7,6 +7,7 @@ sidebar:
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
When you deploy an Aspire application to Kubernetes, your services are accessible only within the cluster by default. To expose services to external traffic — such as a web frontend that users access from the internet — you need to configure an **Ingress** or **Gateway** resource that routes traffic from outside the cluster to your services.
@@ -29,7 +30,7 @@ Aspire provides first-class APIs for defining Ingress and Gateway API resources
new traffic-routing capabilities are landing in Gateway API instead. For new
Aspire deployments, prefer
[`AddGateway(...)`](/deployment/kubernetes-gateway-aks/) over
- `AddIngress(...)` unless your cluster or controller doesn't yet support
+
This inheritance behavior applies from Aspire 13.6 onward. In earlier
diff --git a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
index 6894a47ea..47b09314e 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
@@ -7,6 +7,7 @@ description: Deploy your Aspire application to Azure Kubernetes Service with ful
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import OsAwareTabs from '@components/OsAwareTabs.astro';
+import ApiReference from '@components/ApiReference.astro';
Deploy your Aspire application to Azure Kubernetes Service (AKS). Aspire provisions the AKS cluster, Azure Container Registry (ACR), and any Azure resources your app depends on — then deploys your application in a single command.
@@ -88,7 +89,7 @@ Aspire builds your container images, pushes them to ACR, generates Helm charts,
### System node pool
-Customize the system node pool VM size and scaling using `WithSystemNodePool`:
+Customize the system node pool VM size and scaling using
@@ -107,7 +108,7 @@ await aks.withSystemNodePool('Standard_D4s_v5', 1, 5);
### Additional node pools
-Add additional node pools for workload isolation or specialized hardware, then use `WithNodePool` to schedule workloads on them:
+Add additional node pools for workload isolation or specialized hardware, then use
@@ -166,14 +167,14 @@ This walkthrough uses the integrated AGC + cert-manager APIs that ship with [
### How AGC ingress fits together
-When you opt in via `AddLoadBalancer`, Aspire flips the AKS cluster's Bicep to enable the AKS-managed Gateway API and Application Load Balancer ingress profiles. After deploy, the cluster runs the Microsoft-managed AGC controller, which watches for Aspire's generated `Gateway` and `HTTPRoute` resources and programs an Azure-hosted HTTPS frontend automatically.
+When you opt in via
@@ -329,7 +330,7 @@ This first deploy serves plain HTTP only. Continue to the next step before expos
### Add automatic HTTPS with cert-manager
-`AddCertManager` installs the upstream cert-manager Helm chart with the CRDs and Gateway API watcher enabled and the `--force-conflicts` flag set so AKS's Azure Policy add-on doesn't break subsequent upgrades. `AddIssuer` adds a typed `ClusterIssuer` parented to that installation, and `WithTls(issuer)` on a gateway adds an HTTPS listener that cert-manager will populate with a real certificate.
+
@@ -394,12 +395,12 @@ await storefront.withTls(letsencrypt, {
-Let's Encrypt's production endpoint enforces strict rate limits. While iterating on your AppHost, swap `WithLetsEncryptProduction` for `WithLetsEncryptStaging` so failed attempts don't cost you your weekly quota. Browsers will warn on staging certificates — flip back to production once everything works end-to-end.
+Let's Encrypt's production endpoint enforces strict rate limits. While iterating on your AppHost, swap
#### How the certificate gets issued
-cert-manager validates domain ownership using the **HTTP-01** challenge configured by `WithHttp01Solver` — it asks the gateway to serve a token at `/.well-known/acme-challenge/` and verifies the response. There is no DNS API access required, so this works for the auto-assigned `*.alb.azure.com` FQDN out of the box.
+cert-manager validates domain ownership using the **HTTP-01** challenge configured by ` and verifies the response. There is no DNS API access required, so this works for the auto-assigned `*.alb.azure.com` FQDN out of the box.
To break the chicken-and-egg problem where AGC won't program a Gateway whose HTTPS listener references a missing secret, Aspire pre-creates a self-signed bootstrap secret on the first deploy. Once AGC publishes the gateway's FQDN, Aspire patches the listener with the real hostname and cert-manager swaps the bootstrap certificate for a Let's Encrypt one. You may briefly see a self-signed certificate during the first deploy — this is expected.
@@ -434,7 +435,7 @@ The `*.alb.azure.com` FQDN is fine for testing but real applications need a host
### Tell the gateway about your hostname
-`WithHostname` adds the hostname to the gateway's `HTTPRoute`s and to the HTTPS listener so cert-manager issues the certificate for the right name. Use the parameter overload when the hostname differs across deployment environments.
+
@@ -551,7 +552,7 @@ After authentication, `aspire deploy` needs a target subscription and location.
### Customizing Azure resources
-Use `PublishAsKubernetesService` to customize the Kubernetes resources generated for individual services:
+Use
@@ -584,7 +585,7 @@ await api.publishAsKubernetesService(async (resource) => {
## Install external Helm charts
-Use `AddHelmChart` on the AKS environment to install pre-existing Helm charts — such as cert-manager or NGINX ingress — as post-deploy pipeline steps alongside your application.
+Use
See [Install external Helm charts](/deployment/kubernetes/helm-charts/) for a full walkthrough of adding external charts, configuring Helm values, overriding namespaces and release names, and choosing destroy-time uninstall behavior.
diff --git a/src/frontend/src/content/docs/deployment/kubernetes/clusters.mdx b/src/frontend/src/content/docs/deployment/kubernetes/clusters.mdx
index 950050ef3..3b56d6040 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes/clusters.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes/clusters.mdx
@@ -7,6 +7,7 @@ description: Publish and deploy your Aspire application to an existing Kubernete
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import FileTree from 'starlight-plugin-icons/components/FileTree.astro';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
Deploy your Aspire application to any existing Kubernetes cluster. Aspire generates a complete Helm chart from your application model, and you can either apply it yourself or let `aspire deploy` install it directly using your current `kubectl` context.
@@ -211,7 +212,7 @@ If you prefer to publish first and deploy separately — for example, in a CI/CD
### Helm settings
-Use `WithHelm` to configure Helm chart settings such as namespace, release name, and chart version:
+Use
@@ -241,7 +242,7 @@ Helm is the default deployment engine. Call `WithHelm` only when you need to cus
### Node pools
-Use `AddNodePool` to reference an existing node pool in your cluster, then `WithNodePool` to schedule specific workloads on it:
+Use
@@ -270,7 +271,7 @@ For vanilla Kubernetes, `AddNodePool` creates a named reference to a node pool t
### Per-resource customization
-Use `PublishAsKubernetesService` to modify the generated Kubernetes resources for individual services:
+Use
@@ -395,7 +396,7 @@ Kubernetes Secrets store values as base64-encoded strings. Verify that your Secr
## Install external Helm charts
-Use `AddHelmChart` on the Kubernetes environment to install pre-existing Helm charts — such as cert-manager, NGINX ingress, or monitoring tools — as post-deploy pipeline steps alongside your application's own chart.
+Use
See [Install external Helm charts](/deployment/kubernetes/helm-charts/) for a full walkthrough of adding external charts, configuring Helm values, overriding namespaces and release names, and choosing destroy-time uninstall behavior.
diff --git a/src/frontend/src/content/docs/deployment/kubernetes/helm-charts.mdx b/src/frontend/src/content/docs/deployment/kubernetes/helm-charts.mdx
index 6a4b1abd7..756766fc5 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes/helm-charts.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes/helm-charts.mdx
@@ -5,6 +5,7 @@ description: Learn how to install external Helm charts alongside your Aspire app
import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
Install pre-existing Helm charts — such as cert-manager, NGINX ingress controller, or monitoring tools — as part of your Aspire Kubernetes deployment. Aspire runs `helm upgrade --install` for each configured external chart after deploying your application's own generated Helm chart.
@@ -16,7 +17,7 @@ Install pre-existing Helm charts — such as cert-manager, NGINX ingress control
## Deployment order
-When you use `aspire deploy`, Aspire deploys your application as a Helm chart and then runs any additional install steps you have defined. `AddHelmChart` registers one of these post-deploy pipeline steps. The install order is:
+When you use `aspire deploy`, Aspire deploys your application as a Helm chart and then runs any additional install steps you have defined.
diff --git a/src/frontend/src/content/docs/deployment/kubernetes/persistent-volumes.mdx b/src/frontend/src/content/docs/deployment/kubernetes/persistent-volumes.mdx
index 32fbba5b3..4624d9c4f 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes/persistent-volumes.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes/persistent-volumes.mdx
@@ -6,8 +6,9 @@ description: Model durable storage as first-class persistent volume resources in
import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
-Stateful workloads — databases, message brokers, or any service that writes durable data — need storage that survives pod restarts and rescheduling. Call `AddPersistentVolume` on a Kubernetes environment to describe a durable disk once in your AppHost, configure its storage class, capacity, access modes, and annotations with fluent methods, then bind it to one or more workloads:
+Stateful workloads — databases, message brokers, or any service that writes durable data — need storage that survives pod restarts and rescheduling. Call
@@ -242,7 +243,7 @@ This default only applies to workloads bound through `WithPersistentVolume(...)`
### Overriding or removing the default
-The default security context is applied before any `PublishAsKubernetesService` callback runs, so a workload or cluster that needs a different group can replace it:
+The default security context is applied before any
diff --git a/src/frontend/src/content/docs/deployment/pipelines.mdx b/src/frontend/src/content/docs/deployment/pipelines.mdx
index 06608baa5..1ef11664f 100644
--- a/src/frontend/src/content/docs/deployment/pipelines.mdx
+++ b/src/frontend/src/content/docs/deployment/pipelines.mdx
@@ -9,6 +9,7 @@ lastUpdated: true
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
When you compose your distributed app in Aspire's **AppHost**, you're not just defining services for local development and orchestration—you're also setting up the foundation for deployment. The same composition you use to run and debug locally is leveraged when you publish your app, ensuring consistency from development through to production.
@@ -149,8 +150,8 @@ Dependencies in Aspire pipelines are explicit and purpose-driven, unlike traditi
Steps declare their relationships using:
-- `PipelineStep.DependsOn`: This step must run after another step completes successfully
-- `PipelineStep.RequiredBy`: Another step must run after this step (inverse dependency declaration)
+- ("api")
@@ -566,7 +567,7 @@ You can choose from two dependency types to fix the step order:
### Pipeline configuration
-Resources can also customize how they participate in the pipeline using `WithPipelineConfiguration`, which provides control over step ordering and resource-specific pipeline behavior.
+Resources can also customize how they participate in the pipeline using
The `WithPipelineConfiguration` API is experimental and may change in future releases. Refer to the [aspire do command reference](/reference/cli/commands/aspire-do/) for the latest details on pipeline configuration.
diff --git a/src/frontend/src/content/docs/diagnostics/aspireacadomains001.mdx b/src/frontend/src/content/docs/diagnostics/aspireacadomains001.mdx
index 44d4ed331..16d195946 100644
--- a/src/frontend/src/content/docs/diagnostics/aspireacadomains001.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspireacadomains001.mdx
@@ -5,6 +5,7 @@ description: Learn what causes the Aspire compiler error ASPIREACADOMAINS001 and
---
import { Badge } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
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 `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.
+This diagnostic warning is reported when using the experimental
- As of Aspire 13.4, the `PublishAsAzureContainerAppJob` and `PublishAsScheduledAzureContainerAppJob` APIs are no longer experimental and do not trigger `ASPIREAZURE002`. This diagnostic only applies if you are using an earlier version of Aspire.
+ As of Aspire 13.4, the
> Azure Container App Jobs are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed.
diff --git a/src/frontend/src/content/docs/diagnostics/aspireazure003.mdx b/src/frontend/src/content/docs/diagnostics/aspireazure003.mdx
index e781e3b80..79215edff 100644
--- a/src/frontend/src/content/docs/diagnostics/aspireazure003.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspireazure003.mdx
@@ -5,6 +5,7 @@ description: Learn what causes the Aspire compiler error ASPIREAZURE003 and how
---
import { Badge } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
Azure Virtual Network types and members 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 support for Azure Virtual Networks. If you're using any of the `Aspire.Hosting.Azure.Network` APIs such as `AddAzureVirtualNetwork`, 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.
+The Aspire Azure hosting integration now ships with support for Azure Virtual Networks. If you're using any of the `Aspire.Hosting.Azure.Network` APIs such as `, and `WithBlazorClientApp`
+- `BlazorGatewayExtensions` — >`)
+- The >`)
- `RequiredCommandAnnotation`
- `IRequiredCommandValidator`
- `RequiredCommandValidationContext` and `RequiredCommandValidationResult`
diff --git a/src/frontend/src/content/docs/diagnostics/aspirecompute002.mdx b/src/frontend/src/content/docs/diagnostics/aspirecompute002.mdx
index b3ea6cd9c..2b34602f5 100644
--- a/src/frontend/src/content/docs/diagnostics/aspirecompute002.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspirecompute002.mdx
@@ -5,6 +5,7 @@ description: Learn what causes the Aspire compiler warning ASPIRECOMPUTE002 and
---
import { Badge } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
- As of Aspire 13.6, `RunAsPreviewEmulator` and `WithDataExplorer` are no longer experimental and do not trigger `ASPIRECOSMOSDB001`. `RunAsEmulator` now defaults to the Linux-based (vNext) emulator, and `RunAsPreviewEmulator` is retained only as an obsolete compatibility alias that forwards to `RunAsEmulator`. Use `RunAsClassicEmulator` if you need the classic (Windows-based) emulator instead. This diagnostic only applies if you're using an earlier version of Aspire.
+ As of Aspire 13.6,
> `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
diff --git a/src/frontend/src/content/docs/diagnostics/aspirecsharpapps001.mdx b/src/frontend/src/content/docs/diagnostics/aspirecsharpapps001.mdx
index 2289f091c..798ba5eeb 100644
--- a/src/frontend/src/content/docs/diagnostics/aspirecsharpapps001.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspirecsharpapps001.mdx
@@ -5,6 +5,7 @@ description: Learn what causes the Aspire compiler error ASPIRECSHARPAPPS001 and
---
import { Badge } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
-The callback can also be applied to an existing container resource with `WithDockerfileBuilder`:
+The callback can also be applied to an existing container resource with
diff --git a/src/frontend/src/content/docs/diagnostics/aspiredotnetproject001.mdx b/src/frontend/src/content/docs/diagnostics/aspiredotnetproject001.mdx
index 49889017c..362eba790 100644
--- a/src/frontend/src/content/docs/diagnostics/aspiredotnetproject001.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspiredotnetproject001.mdx
@@ -5,6 +5,7 @@ description: Learn why Aspire 13.6 removed ASPIREDOTNETPROJECT001 from the prere
---
import { Badge } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
`
-- `RunAsEmulator` extension method on `IResourceBuilder`
-- `AddTaskHub` extension method on `IResourceBuilder`
-- `WithTaskHubName` extension methods on `IResourceBuilder`
+- `
+- `
+- `
+- `
- `DurableTaskSchedulerResource` class
- `DurableTaskHubResource` class
- `DurableTaskSchedulerEmulatorResource` class
diff --git a/src/frontend/src/content/docs/diagnostics/aspireextension001.mdx b/src/frontend/src/content/docs/diagnostics/aspireextension001.mdx
index b34745ecf..5e6df4170 100644
--- a/src/frontend/src/content/docs/diagnostics/aspireextension001.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspireextension001.mdx
@@ -5,6 +5,7 @@ description: Learn what causes the Aspire compiler warning ASPIREEXTENSION001 an
---
import { Badge } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
`
-- `PublishAsNodeServer`
-- `PublishAsPackageScript`
-- `AddNextJsApp`
-- `DisableBuildValidation`
+- MCP server 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 `WithMcpServer` extension method and related Model Context Protocol (MCP) server APIs. These APIs enable Aspire tooling to discover and proxy MCP servers exposed by resources.
+This diagnostic warning is reported when using the experimental The PostgreSQL MCP integration APIs are experimental and subject to change or removal in future updates. Suppress this diagnostic to proceed.
-The `WithPostgresMcp` extension method for adding Model Context Protocol (MCP) support to PostgreSQL resources is an experimental feature. This API may change or be removed in future versions.
+The ` — adds a Postgres MCP server container to a PostgreSQL database resource.
-- `WithPostgresMcp` on `IResourceBuilder` — adds a Postgres MCP server container to an Azure PostgreSQL Flexible Server database resource running as a container.
+- ` — adds a Postgres MCP server container to an Azure PostgreSQL Flexible Server database resource running as a container.
## Example
diff --git a/src/frontend/src/content/docs/diagnostics/aspireprobes001.mdx b/src/frontend/src/content/docs/diagnostics/aspireprobes001.mdx
index ed8c0fbf2..3d441c77d 100644
--- a/src/frontend/src/content/docs/diagnostics/aspireprobes001.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspireprobes001.mdx
@@ -5,6 +5,7 @@ description: Learn what causes the Aspire compiler warning ASPIREPROBES001 and h
---
import { Badge } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
Process command 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 `WithProcessCommand` extension method and related process command APIs. These APIs enable AppHost authors to expose custom resource commands backed by local processes (binaries, shell scripts, and other executables on the AppHost machine).
+This diagnostic warning is reported when using the experimental MCP server types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIREPERSISTENCE001](/diagnostics/aspirepersistence001/) | (Experimental) Error | Resource lifetime types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIREPIPELINES001](/diagnostics/aspirepipelines001/) | (Experimental) Error | Pipeline infrastructure APIs are for evaluation purposes only and are subject to change or removal in future updates. |
diff --git a/src/frontend/src/content/docs/extensibility/custom-resources.mdx b/src/frontend/src/content/docs/extensibility/custom-resources.mdx
index c0b7aba83..a73894aef 100644
--- a/src/frontend/src/content/docs/extensibility/custom-resources.mdx
+++ b/src/frontend/src/content/docs/extensibility/custom-resources.mdx
@@ -5,6 +5,7 @@ description: "Learn how to create custom resource types for the Aspire AppHost t
import { Aside } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
+import ApiReference from '@components/ApiReference.astro';
Creating custom resources allows you to extend Aspire to model components that aren't covered by built-in integrations. This guide covers the patterns and APIs for building your own resource types.
@@ -32,7 +33,7 @@ Aspire provides several interfaces that give resources specific capabilities:
| `IResourceWithEndpoints` | Resource has network endpoints |
| `IResourceWithEnvironment` | Resource can configure environment variables |
| `IResourceWithArgs` | Resource accepts command-line arguments |
-| `IResourceWithWaitSupport` | Resource supports `WaitFor` orchestration |
+| `IResourceWithWaitSupport` | Resource supports ` c
- **Custom resource types**: Gather input from users or confirm actions when you create custom resource types. Resource types are free to define dashboard interactions, such as prompting for user input or displaying messages.
-- **Custom resource commands**: Add commands to resources in the Aspire dashboard or CLI. Use the interaction service to prompt users for input or confirmation when these commands run. When you chain a call to `WithCommand` on a target `IResourceBuilder`, your callback can use the interaction service to gather input or confirm actions. For more information, see [Custom resource commands](/fundamentals/custom-resource-commands/).
+- **Custom resource commands**: Add commands to resources in the Aspire dashboard or CLI. Use the interaction service to prompt users for input or confirmation when these commands run. When you chain a call to `, your callback can use the interaction service to gather input or confirm actions. For more information, see [Custom resource commands](/fundamentals/custom-resource-commands/).
Commands might not be interactive when triggered from the Aspire CLI. Always check `IInteractionService.IsAvailable` before prompting and provide a fallback path when it returns `false`. [Command arguments](/fundamentals/custom-resource-commands/#command-arguments) are the best way to collect input in commands because they work in both the dashboard and CLI.
diff --git a/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx b/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx
index 2ea965cdc..0aeb653d2 100644
--- a/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx
+++ b/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx
@@ -5,6 +5,7 @@ description: Annotate Aspire hosting integrations so they work with TypeScript A
---
import { Aside, Steps } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
Aspire hosting integrations are C# libraries that extend the AppHost with new resource types. By default, these integrations are only available in C# AppHosts. To make them available in TypeScript AppHosts, you annotate your APIs with ATS (Aspire Type System) attributes.
@@ -651,7 +652,7 @@ Prefer getter-only properties (`=> value;` or `{ get; }` without a setter) when
## Callback context types and the ATS-first editor pattern
-When you export a method that accepts a callback (such as `withEnvironmentCallback`, `withArgsCallback`, or `withUrls`), the callback receives a _context_ object. For ATS compatibility, context types should follow the ATS-first design:
+When you export a method that accepts a callback (such as `withEnvironmentCallback`, `withArgsCallback`, or ("api")
@@ -136,7 +137,7 @@ Learn more about how Aspire uses health checks for orchestration in the [Health
### `WaitAnnotation`
-The `WaitAnnotation` declares a dependency on another resource and controls startup order. The `WaitFor`, `WaitForStart`, and `WaitForCompletion` methods add this annotation:
+The `WaitAnnotation` declares a dependency on another resource and controls startup order. The `WaitFor`, ` interface. You use the _resource builder_ API to chain calls, configuring the underlying resource, and in some situations, you might want to add custom commands to the resource. Some common scenario for creating a custom command might be running database migrations or seeding/resetting a database. In this article, you learn how to add a custom command to a Redis resource that clears the cache.
@@ -152,7 +153,7 @@ The preceding code:
-The `WithCommand` API adds the appropriate annotations to the resource, which are consumed in the [Aspire dashboard](/dashboard/overview/). The dashboard uses these annotations to render the command in the UI. Before getting too far into those details, let's ensure that you first understand the parameters of the `WithCommand` method:
+The ://:`. To omit the host port, use one of the following methods:
+Likewise, you can explicitly expose endpoints using the ://:`. To omit the host port, use one of the following methods:
-- `WithHttpEndpoint`
-- `WithHttpsEndpoint`
+-
The `ResourceUrlsCallbackContext` exposes an extension method that enables you
to easily access the underlying resource named endpoints. Call the
- `GetEndpoint` API on a context instance to achieve this.
+
## URL customization lifecycle
diff --git a/src/frontend/src/content/docs/fundamentals/environment-variables.mdx b/src/frontend/src/content/docs/fundamentals/environment-variables.mdx
index ce93d7d59..576cab33e 100644
--- a/src/frontend/src/content/docs/fundamentals/environment-variables.mdx
+++ b/src/frontend/src/content/docs/fundamentals/environment-variables.mdx
@@ -5,8 +5,9 @@ description: Learn how Aspire generates environment variable names for connectio
---
import { Aside } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
-When you use `WithReference` to connect resources in the AppHost, Aspire automatically injects environment variables into the consuming resource. This process is called _configuration injection_.
+When you use
The `addParameterFromConfiguration` API is not yet available in the TypeScript AppHost SDK.
@@ -458,7 +459,7 @@ This method is useful when:
Parameters can be used to model connection strings. When you publish the app, the value is prompted for and stored in a secure location. When you run the app locally, the value is read from the `ConnectionStrings` section of the AppHost configuration.
-Always use `AddParameter` to pass secrets to resources. Never include passwords or other sensitive data like connection strings in source code.
+Always use
- Using `WaitFor` with a connection string will implicitly wait for the resource
+ Using
@@ -468,7 +469,7 @@ await webapp.waitFor(catalogApi); // Waits for /health to return HTTP 200
-The `WithHttpHealthCheck` method can also be applied to project resources:
+The
@@ -537,7 +538,7 @@ builder.AddProject("myapp")
`builder.Services.AddHealthChecks()` is not yet available.
-The `AddCheck` method registers the health check, and `WithHealthCheck` associates it with specific resources. For more details about creating and registering custom health checks, see [Create health checks](https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks#create-health-checks).
+The `AddCheck` method registers the health check, and
@@ -156,7 +157,7 @@ Some endpoint behavior depends on the resource type. Keep those details with the
## Ports and proxies
-When defining a proxied service binding, the host port is given to the proxy that sits in front of the service. This allows single or multiple replicas of a service to behave similarly. Additionally, resource dependencies that use the `WithReference` API rely on the proxied endpoint from the environment variable unless the endpoint is configured as proxyless.
+When defining a proxied service binding, the host port is given to the proxy that sits in front of the service. This allows single or multiple replicas of a service to behave similarly. Additionally, resource dependencies that use the
@@ -164,7 +165,7 @@ This convention also applies to Kubernetes persistent volumes bound with `WithPe
## Use bind mounts
-Bind mounts enable access to the data from both within the container and from processes on the host machine. For example, once a bind mount is established, you can copy a file into it on your host computer. The file is then available at the bound path within the container for your resource. With Aspire, you configure a bind mount for each resource container using the `WithBindMount` method, which accepts three parameters:
+Bind mounts enable access to the data from both within the container and from processes on the host machine. For example, once a bind mount is established, you can copy a file into it on your host computer. The file is then available at the bound path within the container for your resource. With Aspire, you configure a bind mount for each resource container using the
@@ -246,7 +247,7 @@ const sqldb = await sql.addDatabase("sqldb");
-Since the `password` parameter isn't provided when calling `AddSqlServer`, Aspire automatically generates a password for the SQL Server resource.
+Since the `password` parameter isn't provided when calling
This isn't a persistent password! Instead, it changes every time the AppHost
@@ -273,7 +274,7 @@ The same pattern applies to the other server-based resource types, such as those
| RabbitMQ | [📦 Aspire.Hosting.RabbitMq](https://www.nuget.org/packages/Aspire.Hosting.RabbitMq) | `rabbitmq` | `Parameters:rabbitmq-password` |
| SQL Server | [📦 Aspire.Hosting.SqlServer](https://www.nuget.org/packages/Aspire.Hosting.SqlServer) | `sql` | `Parameters:sql-password` |
-By overriding the generated password, you can ensure that the password remains consistent between app launches. An alternative approach is to use the `AddParameter` method to create a parameter that can be used as a password. The following code demonstrates how to create a persistent password for a SQL Server resource:
+By overriding the generated password, you can ensure that the password remains consistent between app launches. An alternative approach is to use the
diff --git a/src/frontend/src/content/docs/fundamentals/service-discovery.mdx b/src/frontend/src/content/docs/fundamentals/service-discovery.mdx
index f44376910..79603f78e 100644
--- a/src/frontend/src/content/docs/fundamentals/service-discovery.mdx
+++ b/src/frontend/src/content/docs/fundamentals/service-discovery.mdx
@@ -5,12 +5,13 @@ description: Understand essential Aspire service discovery concepts — endpoint
---
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+import ApiReference from '@components/ApiReference.astro';
Service discovery is how your services find each other. Instead of hardcoding URLs like `http://localhost:5001`, your frontend can simply reference the `catalog` service by name—and Aspire handles resolving the actual address.
## How service discovery works
-When you connect services using `WithReference()`, Aspire sets up automatic service discovery:
+When you connect services using
-1. Calling `AddGitHubModel` (or `addGitHubModel`) creates a `GitHubModelResource`. It registers a secret parameter for the API key that defaults to the `GITHUB_TOKEN` environment variable.
+1. Calling
diff --git a/src/frontend/src/content/docs/integrations/ai/ollama/ollama-connect.mdx b/src/frontend/src/content/docs/integrations/ai/ollama/ollama-connect.mdx
index 4b34f4d0f..a0c08086a 100644
--- a/src/frontend/src/content/docs/integrations/ai/ollama/ollama-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/ai/ollama/ollama-connect.mdx
@@ -9,6 +9,7 @@ import { Image } from 'astro:assets';
import { Aside, Badge, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import ollamaIcon from '@assets/icons/ollama-icon.png';
+import ApiReference from '@components/ApiReference.astro';
- If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using `WithEnvironment`. See the Aspire AppHost documentation for details on custom environment variable injection.
+ If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using
diff --git a/src/frontend/src/content/docs/integrations/ai/ollama/ollama-host.mdx b/src/frontend/src/content/docs/integrations/ai/ollama/ollama-host.mdx
index 09690b2a5..b458ba2d0 100644
--- a/src/frontend/src/content/docs/integrations/ai/ollama/ollama-host.mdx
+++ b/src/frontend/src/content/docs/integrations/ai/ollama/ollama-host.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Badge, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import ollamaIcon from '@assets/icons/ollama-icon.png';
+import ApiReference from '@components/ApiReference.astro';
@@ -226,7 +227,7 @@ The data volume is mounted at `/root/.ollama` in the Ollama container. When a `n
## Use GPUs when available
-By default, the Ollama container runs on CPU. To enable GPU acceleration, use the `WithGPUSupport` (or `withGPUSupport`) extension method:
+By default, the Ollama container runs on CPU. To enable GPU acceleration, use the
@@ -301,7 +302,7 @@ For more information, see [GPU support in Docker Desktop](https://docs.docker.co
## Add a model from Hugging Face
-To use a model in GGUF format from [Hugging Face](https://huggingface.co/), use the `AddHuggingFaceModel` (or `addHuggingFaceModel`) extension method:
+To use a model in GGUF format from [Hugging Face](https://huggingface.co/), use the
diff --git a/src/frontend/src/content/docs/integrations/ai/openai/openai-host.mdx b/src/frontend/src/content/docs/integrations/ai/openai/openai-host.mdx
index 6fcfdab97..aeecdb7ba 100644
--- a/src/frontend/src/content/docs/integrations/ai/openai/openai-host.mdx
+++ b/src/frontend/src/content/docs/integrations/ai/openai/openai-host.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import openaiIcon from '@assets/icons/openai-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-1. Calling `AddOpenAI` (or `addOpenAI`) creates an `OpenAIResource` that models the OpenAI account. It registers a secret parameter for the API key that defaults to the `OPENAI_API_KEY` environment variable.
+1. Calling
@@ -225,7 +226,7 @@ await builder.addNodeApp("api", "./api", "index.js")
## Add a custom endpoint
-Override the default `https://api.openai.com/v1` endpoint to use a proxy, an Azure OpenAI endpoint, or any OpenAI-compatible gateway. Call `WithEndpoint` (or `withEndpoint`) on the parent resource:
+Override the default `https://api.openai.com/v1` endpoint to use a proxy, an Azure OpenAI endpoint, or any OpenAI-compatible gateway. Call
diff --git a/src/frontend/src/content/docs/integrations/caching/garnet/garnet-connect.mdx b/src/frontend/src/content/docs/integrations/caching/garnet/garnet-connect.mdx
index 359539b48..815cc226f 100644
--- a/src/frontend/src/content/docs/integrations/caching/garnet/garnet-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/caching/garnet/garnet-connect.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import garnetIcon from '@assets/icons/garnet-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-The data volume is used to persist Garnet data outside the lifecycle of its container. The data volume is mounted at the `/data` path in the Garnet container, and when a `name` parameter isn't provided, the name is generated at random. Calling `WithDataVolume` (or `withDataVolume`) also enables Garnet persistence so the in-memory state survives container restarts. For more information on data volumes and details on why they're preferred over [bind mounts](#add-garnet-resource-with-data-bind-mount), see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes).
+The data volume is used to persist Garnet data outside the lifecycle of its container. The data volume is mounted at the `/data` path in the Garnet container, and when a `name` parameter isn't provided, the name is generated at random. Calling
@@ -334,7 +335,7 @@ await builder.build().run();
## Connect to an existing Garnet instance
-To reference an externally managed Garnet instance instead of running one as a container, use `AddConnectionString`:
+To reference an externally managed Garnet instance instead of running one as a container, use
diff --git a/src/frontend/src/content/docs/integrations/caching/redis-distributed/redis-distributed-get-started.mdx b/src/frontend/src/content/docs/integrations/caching/redis-distributed/redis-distributed-get-started.mdx
index ab82c0353..bff4d7650 100644
--- a/src/frontend/src/content/docs/integrations/caching/redis-distributed/redis-distributed-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/caching/redis-distributed/redis-distributed-get-started.mdx
@@ -6,6 +6,7 @@ description: Understand why you use the Aspire Redis distributed caching integra
import { Image } from 'astro:assets';
import { LinkButton, Steps } from '@astrojs/starlight/components';
import redisIcon from '@assets/icons/redis-icon.png';
+import ApiReference from '@components/ApiReference.astro';
', 'string?', 'bool']} /> — persist Redis data outside the container lifecycle.
+- ', 'string', 'bool']} /> — bind-mount a host directory into the container.
+-
@@ -105,7 +106,7 @@ This adds a new DbGate resource to the app host which is available from the Aspi
### dbx management UI
-[dbx](https://github.com/t8y2/dbx) is a lightweight, web-based database client and an alternative management UI to DbGate and Adminer. Decorate the Redis resource with `WithDbx` / `withDbx` to add it:
+[dbx](https://github.com/t8y2/dbx) is a lightweight, web-based database client and an alternative management UI to DbGate and Adminer. Decorate the Redis resource with
diff --git a/src/frontend/src/content/docs/integrations/caching/redis/redis-connect.mdx b/src/frontend/src/content/docs/integrations/caching/redis/redis-connect.mdx
index df72e4414..df4d39dab 100644
--- a/src/frontend/src/content/docs/integrations/caching/redis/redis-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/caching/redis/redis-connect.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import redisIcon from '@assets/icons/redis-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-The data volume is used to persist Redis data outside the lifecycle of its container. The data volume is mounted at the `/data` path in the Redis container, and when a `name` parameter isn't provided, the name is generated at random. Calling `WithDataVolume` (or `withDataVolume`) also enables Redis persistence so the in-memory state survives container restarts. For more information on data volumes and details on why they're preferred over [bind mounts](#add-redis-resource-with-data-bind-mount), see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes).
+The data volume is used to persist Redis data outside the lifecycle of its container. The data volume is mounted at the `/data` path in the Redis container, and when a `name` parameter isn't provided, the name is generated at random. Calling ', 'string?', 'bool']} /> also enables Redis persistence so the in-memory state survives container restarts. For more information on data volumes and details on why they're preferred over [bind mounts](#add-redis-resource-with-data-bind-mount), see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes).
## Add Redis resource with data bind mount
@@ -203,7 +204,7 @@ Data bind mounts rely on the host machine's filesystem to persist Redis data acr
## Add Redis resource with persistence
-To configure Redis snapshot persistence explicitly, call `WithPersistence` (or `withPersistence`) alongside a data volume or bind mount:
+To configure Redis snapshot persistence explicitly, call
@@ -511,7 +512,7 @@ await builder.build().run();
## Connect to an existing Redis instance
-To reference an externally managed Redis instance instead of running one as a container, use `AddConnectionString`:
+To reference an externally managed Redis instance instead of running one as a container, use
@@ -549,7 +550,7 @@ With `AddConnectionString` and `addConnectionString`, Aspire resolves `cache` fr
## Open an interactive REPL
-In Aspire 13.6 or later, add `WithRepl()` to the Redis resource to enable a **REPL** command that opens `redis-cli` in the [terminal dock](/dashboard/terminals/#use-the-terminal-dock).
+In Aspire 13.6 or later, add
diff --git a/src/frontend/src/content/docs/integrations/caching/valkey/valkey-connect.mdx b/src/frontend/src/content/docs/integrations/caching/valkey/valkey-connect.mdx
index d729010bd..7b2d2657a 100644
--- a/src/frontend/src/content/docs/integrations/caching/valkey/valkey-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/caching/valkey/valkey-connect.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import valkeyIcon from '@assets/icons/valkey-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-The data volume is used to persist Valkey data outside the lifecycle of its container. The data volume is mounted at the `/data` path in the Valkey container, and when a `name` parameter isn't provided, the name is generated at random. Calling `WithDataVolume` (or `withDataVolume`) also enables Valkey persistence so the in-memory state survives container restarts. For more information on data volumes and details on why they're preferred over [bind mounts](#add-valkey-resource-with-data-bind-mount), see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes).
+The data volume is used to persist Valkey data outside the lifecycle of its container. The data volume is mounted at the `/data` path in the Valkey container, and when a `name` parameter isn't provided, the name is generated at random. Calling
@@ -331,7 +332,7 @@ await builder.build().run();
## Connect to an existing Valkey instance
-To reference an externally managed Valkey instance instead of running one as a container, use `AddConnectionString`:
+To reference an externally managed Valkey instance instead of running one as a container, use
@@ -369,7 +370,7 @@ With `AddConnectionString` and `addConnectionString`, Aspire resolves `cache` fr
## Open an interactive REPL
-In Aspire 13.6 or later, add `WithRepl()` to the Valkey resource to enable a **REPL** command that opens `valkey-cli` in the [terminal dock](/dashboard/terminals/#use-the-terminal-dock).
+In Aspire 13.6 or later, add
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/aks/index.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/aks/index.mdx
index 91d997c1e..09e2c05ca 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/aks/index.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/aks/index.mdx
@@ -8,6 +8,7 @@ import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallPackage from '@components/InstallPackage.astro';
import LearnMore from '@components/LearnMore.astro';
import kubernetesIcon from '@assets/icons/kubernetes.svg';
+import ApiReference from '@components/ApiReference.astro';
@@ -66,7 +67,7 @@ When an AKS environment is present, all compute resources are automatically depl
## Configure the system node pool
-Customize the system node pool VM size and scaling using `WithSystemNodePool`:
+Customize the system node pool VM size and scaling using
@@ -85,7 +86,7 @@ await aks.withSystemNodePool('Standard_D4s_v5', 1, 5);
## Add node pools
-Add additional node pools for workload isolation, GPU workloads, or specialized hardware requirements using `AddNodePool`:
+Add additional node pools for workload isolation, GPU workloads, or specialized hardware requirements using
@@ -114,7 +115,7 @@ await worker.withNodePool(gpuPool);
Persistent volume APIs are experimental. In C#, suppress the `ASPIRECOMPUTE002` diagnostic to use them.
-Call `AddPersistentVolume` directly on the AKS environment to model durable storage without reaching through to the underlying Kubernetes integration. The call forwards to the AKS environment's Kubernetes publisher, so the same configuration methods and workload-binding APIs described in [Persistent volumes on Kubernetes](/deployment/kubernetes/persistent-volumes/) apply:
+Call
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect.mdx
index c6d56e54c..ef97e7cfe 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect.mdx
@@ -9,6 +9,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png';
+import ApiReference from '@components/ApiReference.astro';
- By default, `AddFoundry(...)` provisions the Foundry account with `disableLocalAuth: true` and creates the role assignments consuming apps need, so apps authenticate via managed identity. Because Aspire only ever surfaces `Key` for Foundry Local, the examples below default to token-based authentication (`DefaultAzureCredential`) for every scenario except Foundry Local.
+ By default,
### Foundry deployment resource
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx
index e6c504591..3bbed4c09 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx
@@ -7,6 +7,7 @@ prev: false
import { Image } from 'astro:assets';
import { LinkButton, Steps } from '@astrojs/starlight/components';
import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-The preceding code adds an Azure AI Foundry resource named `foundry` to the AppHost project. The `WithReference` method passes the connection information to the `ExampleProject` project.
+The preceding code adds an Azure AI Foundry resource named `foundry` to the AppHost project. The
- When you call `AddFoundry`, it implicitly calls `AddAzureProvisioning`—which
+ When you call `AddFoundry`, it implicitly calls
@@ -240,7 +241,7 @@ await builder.build().run();
## Configure deployment properties
-You can customize deployment properties using the `WithProperties` method:
+You can customize deployment properties using the
@@ -305,7 +306,7 @@ await builder.build().run();
-The preceding code creates a Foundry project and adds a deployment through `AddModelDeployment`. When you call `WithReference(project)`, Aspire injects the standard connection string and project-specific connection properties such as the project endpoint and Application Insights connection string into the consuming resource.
+The preceding code creates a Foundry project and adds a deployment through
-`AddProject` creates a default Azure Container Registry for hosted agents only in publish mode (when deploying to Azure). In local run mode, no default registry is created. Use `WithContainerRegistry` when you want to point the project at a specific registry.
+`AddProject` creates a default Azure Container Registry for hosted agents only in publish mode (when deploying to Azure). In local run mode, no default registry is created. Use
@@ -432,14 +433,14 @@ builder.Build().Run();
Parameter details:
-The identity running `aspire run` or `aspire deploy` needs the **Foundry User** role on the project to manage Toolbox versions. Deployed compute resources that reference the Toolbox receive this role on the project automatically. The Search index named `docs` must already exist and contain data: neither `AddAzureSearch` nor `WithAISearchTool` creates or populates it. Toolbox availability depends on the Foundry service preview and its supported regions.
+The identity running `aspire run` or `aspire deploy` needs the **Foundry User** role on the project to manage Toolbox versions. Deployed compute resources that reference the Toolbox receive this role on the project automatically. The Search index named `docs` must already exist and contain data: neither
@@ -460,15 +461,15 @@ Use the existing-resource methods to validate a remote Toolbox without resolving
| Method | `aspire run` | `aspire deploy` |
| --- | --- | --- |
-| `RunAsExisting()` | Validate existing | Reconcile managed |
-| `PublishAsExisting()` | Reconcile managed | Validate existing |
-| `AsExisting()` | Validate existing | Validate existing |
+|
@@ -613,7 +614,7 @@ The defaulted `asHostedAgent` entry point and the explicit `asHostedAgentWithPro
### Add and publish a prompt agent
-For prompt-only scenarios, use `AddPromptAgent` on a Foundry project:
+For prompt-only scenarios, use
@@ -680,7 +681,7 @@ Parameter details:
| `AddPromptAgent(...)` | `model` | The Foundry model deployment resource the prompt agent uses, such as `chat` from `project.AddModelDeployment(...)`. |
| `AddPromptAgent(...)` | `name` | The Aspire resource name and Foundry agent name. This also drives generated environment variable prefixes, for example `web-researcher` becomes `WEB_RESEARCHER`. |
| `AddPromptAgent(...)` | `instructions` | Optional system instructions for the prompt agent. Use this to define behavior, tool-use guidance, and response style. |
-| `WithTool(...)` | `tool` | A Foundry tool resource created on the same Foundry project, such as `AddWebSearchTool(...)`, `AddCodeInterpreterTool(...)`, or `AddAISearchTool(...)`. |
+|
Foundry Projects aren't supported when the parent Foundry resource uses
@@ -1006,7 +1007,7 @@ The generated Bicep is a starting point and is influenced by changes to the prov
### Customize provisioning infrastructure
-All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This enables customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the `ConfigureInfrastructure` API:
+All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This enables customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-host.mdx
index 7c3d742ce..088b5cffa 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-host.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-host.mdx
@@ -7,6 +7,7 @@ import { Image } from 'astro:assets';
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import searchIcon from '@assets/icons/azure-search-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-1. When Aspire adds an Azure AI Search resource, it implicitly calls `AddAzureProvisioning`, which adds support for generating Azure resources dynamically during app startup.
+1. When Aspire adds an Azure AI Search resource, it implicitly calls
@@ -293,7 +294,7 @@ By default, the Azure AI Search hosting integration generates role assignments f
-Role assignments are generated automatically in the provisioned Bicep. To clear the default role assignments and assign custom ones, use `ClearDefaultRoleAssignments` and then configure via `ConfigureInfrastructure`:
+Role assignments are generated automatically in the provisioned Bicep. To clear the default role assignments and assign custom ones, use
- When you call `AddAzureAppConfiguration` (or `addAzureAppConfiguration`), it implicitly calls
- `AddAzureProvisioning`—which adds support for generating Azure resources
+ When you call
@@ -239,7 +240,7 @@ There are many more configuration options available to customize the Azure App C
## Add Azure App Configuration emulator resource
-Microsoft provides the Azure App Configuration emulator for developers who want a local, lightweight implementation of the Azure App Configuration service to code and test against. In Aspire, you can use this emulator by calling the `RunAsEmulator` method (or `runAsEmulator`) when you add your resource:
+Microsoft provides the Azure App Configuration emulator for developers who want a local, lightweight implementation of the Azure App Configuration service to code and test against. In Aspire, you can use this emulator by calling the
@@ -326,7 +327,7 @@ The preceding code configures the emulator container's endpoint to listen on por
#### Configure Azure App Configuration emulator with persistent lifetime
-To configure the emulator container with a persistent lifetime, call the `WithLifetime` method (or `withLifetime`) on the emulator container resource and pass `ContainerLifetime.Persistent`:
+To configure the emulator container with a persistent lifetime, call the
@@ -366,7 +367,7 @@ const appConfig = await builder.addAzureAppConfiguration("config")
#### Configure Azure App Configuration emulator with data volume
-By default, the Azure App Configuration emulator doesn't persist data between container restarts. To enable persistent storage using a Docker volume, call the `WithDataVolume` method (or `withDataVolume`) on the emulator resource:
+By default, the Azure App Configuration emulator doesn't persist data between container restarts. To enable persistent storage using a Docker volume, call the
@@ -408,7 +409,7 @@ The data volume is used to persist the emulator data outside the lifecycle of it
#### Configure Azure App Configuration emulator with data bind mount
-To persist emulator data to a specific directory on your host machine, call the `WithDataBindMount` method (or `withDataBindMount`). This is useful when you want direct access to the data files on your host system:
+To persist emulator data to a specific directory on your host machine, call the
@@ -454,7 +455,7 @@ Data bind mounts rely on the host machine's filesystem to persist the emulator d
## Use existing Azure App Configuration resource
-You might have an existing Azure App Configuration store that you want to connect to. Call the `AsExisting` method (or `asExisting`) with the config store name and resource group parameters to connect to an existing store:
+You might have an existing Azure App Configuration store that you want to connect to. Call the
@@ -499,7 +500,7 @@ For more information, see [Use existing Azure resources](/integrations/cloud/azu
## Connect to existing Azure App Configuration store
-An alternative approach to using the `AsExisting` API enables the addition of a connection string instead, where the AppHost uses configuration to resolve the connection information. To add a connection to an existing Azure App Configuration store, call the `AddConnectionString` method:
+An alternative approach to using the `AsExisting` API enables the addition of a connection string instead, where the AppHost uses configuration to resolve the connection information. To add a connection to an existing Azure App Configuration store, call the
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-get-started.mdx
index ca59ca23c..1b78e1947 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-get-started.mdx
@@ -7,6 +7,7 @@ prev: false
import { Image } from 'astro:assets';
import { Badge, LinkButton, Steps } from '@astrojs/starlight/components';
import appServiceIcon from '@assets/icons/azure-app-services.svg';
+import ApiReference from '@components/ApiReference.astro';
-1. When you call `addAzureAppServiceEnvironment` (or `AddAzureAppServiceEnvironment` in C#), Aspire implicitly enables Azure provisioning for the application.
+1. When you call
Calling `AddAzureAppServiceEnvironment` (or `addAzureAppServiceEnvironment` in
- TypeScript) implicitly calls `AddAzureProvisioning`, which adds support for
+ TypeScript) implicitly calls
@@ -275,7 +276,7 @@ The preceding code:
## Deployment slots
-[Deployment slots](https://learn.microsoft.com/azure/app-service/deploy-staging-slots) let you deploy your app to a staging environment for testing before swapping it into production. The `WithDeploymentSlot` extension method (or `withDeploymentSlot` in TypeScript) configures a deployment slot for the App Service environment:
+[Deployment slots](https://learn.microsoft.com/azure/app-service/deploy-staging-slots) let you deploy your app to a staging environment for testing before swapping it into production. The
@@ -388,7 +389,7 @@ With this configuration, provide a value for the `deploymentSlot` parameter when
slot when needed.
-When you customize App Service resources using `PublishAsAzureAppServiceWebsite` (or `publishAsAzureAppServiceWebsite`) or `ConfigureInfrastructure`, those customizations apply to the production slot by default. Apply them separately to each slot when needed using the `configureSlot` option:
+When you customize App Service resources using `PublishAsAzureAppServiceWebsite` (or `publishAsAzureAppServiceWebsite`) or
@@ -421,7 +422,7 @@ await api.publishAsAzureAppServiceWebsite({
## Regional virtual network integration
-To configure [regional virtual network integration](https://learn.microsoft.com/azure/app-service/overview-vnet-integration) for the websites in an App Service environment, add the [📦 Aspire.Hosting.Azure.Network](https://www.nuget.org/packages/Aspire.Hosting.Azure.Network) integration and delegate a subnet to the environment with `WithDelegatedSubnet` (or `withDelegatedSubnet` in TypeScript):
+To configure [regional virtual network integration](https://learn.microsoft.com/azure/app-service/overview-vnet-integration) for the websites in an App Service environment, add the [📦 Aspire.Hosting.Azure.Network](https://www.nuget.org/packages/Aspire.Hosting.Azure.Network) integration and delegate a subnet to the environment with
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-application-insights.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-application-insights.mdx
index 841b988c6..6b589b494 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-application-insights.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-application-insights.mdx
@@ -7,6 +7,7 @@ import { Image } from 'astro:assets';
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import appInsightsIcon from '@assets/icons/azure-appinsights-icon.png';
+import ApiReference from '@components/ApiReference.astro';
@@ -117,13 +118,13 @@ await builder.build().run();
1. A Log Analytics workspace is automatically created to store the telemetry data.
-1. The `WithReference` (or `withReference`) call configures a connection in the consuming project, making the Application Insights connection string available as the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable.
+1. The
When you call `AddAzureApplicationInsights` (or `addAzureApplicationInsights`), it implicitly calls
- `AddAzureProvisioning` — which adds support for generating Azure resources
+
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-connect.mdx
index c985bbbbc..50d7ae89d 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-connect.mdx
@@ -7,6 +7,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import cacheRedisIcon from '@assets/icons/azure-cacheredis-icon.png';
+import ApiReference from '@components/ApiReference.astro';
- When you call `AddAzureManagedRedis` (or `addAzureManagedRedis`), it implicitly calls `AddAzureProvisioning` — which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](/integrations/cloud/azure/local-provisioning/#configuration).
+ When you call
@@ -127,7 +128,7 @@ await builder.build().run();
The Azure Cache for Redis hosting integration supports running a local Redis container during development. This lets you develop and test your app locally without provisioning an Azure resource or connecting to an existing Azure Cache for Redis instance.
-To run the resource as a container, chain a call to `RunAsContainer` (or `runAsContainer`):
+To run the resource as a container, chain a call to
@@ -170,7 +171,7 @@ The `RunAsContainer` method accepts an optional delegate that lets you customize
## Connect to an existing Azure Cache for Redis instance
-If you already have an Azure Cache for Redis instance you want to use, call `AsExisting` (or `asExisting`) to annotate that the resource already exists rather than being provisioned:
+If you already have an Azure Cache for Redis instance you want to use, call
@@ -215,7 +216,7 @@ For more information on treating Azure resources as existing resources, see [Use
## Configure access key authentication
-By default, the Azure Managed Redis resource uses Microsoft Entra ID authentication. To switch to access key authentication (not recommended for production), call `WithAccessKeyAuthentication` (or `withAccessKeyAuthentication`):
+By default, the Azure Managed Redis resource uses Microsoft Entra ID authentication. To switch to access key authentication (not recommended for production), call
@@ -325,7 +326,7 @@ The generated Bicep provisions the Azure Cache for Redis instance and creates an
## Customize provisioning infrastructure
-All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables Bicep customization through the `ConfigureInfrastructure` API:
+All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables Bicep customization through the
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-connector-namespace.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-connector-namespace.mdx
index 822e77a35..f29360701 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-connector-namespace.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-connector-namespace.mdx
@@ -5,6 +5,7 @@ description: Model Azure Connector Namespace connections, managed MCP servers, o
import { Tabs, TabItem } from '@astrojs/starlight/components';
import InstallPackage from '@components/InstallPackage.astro';
+import ApiReference from '@components/ApiReference.astro';
Azure Connector Namespace connects applications to external services such as Office 365 and SharePoint. Aspire models the namespace, authenticated connections, managed MCP server configurations, and access policies together.
@@ -118,7 +119,7 @@ After provisioning, open `https://connectors.azure.com//
- When you call `AddAzureContainerRegistry` (or `addAzureContainerRegistry`), it implicitly calls
- `AddAzureProvisioning` — which adds support for generating Azure resources dynamically during app
+ When you call
@@ -118,7 +119,7 @@ await builder.build().run();
1. The registry resource is modeled as an `AzureContainerRegistryResource` in the Aspire resource graph.
-1. Calling `WithAzureContainerRegistry` (or `withAzureContainerRegistry`) on the compute environment attaches the registry and provisions the necessary role assignments and managed-identity bindings so the environment can pull images securely.
+1. Calling
@@ -169,7 +170,7 @@ This returns an `AzureContainerRegistryResource` builder that you can use for fu
## Reference an existing container registry
-To reference a registry your team already manages rather than provisioning a new one, use `publishAsExisting`, `runAsExisting`, or `asExisting`:
+To reference a registry your team already manages rather than provisioning a new one, use
@@ -274,7 +275,7 @@ Available roles include: `AcrPull`, `AcrPush`, `AcrDelete`, `AcrImageSigner`, `A
## Schedule image cleanup with purge tasks
-Over time, container registries accumulate old images that consume storage. Use `WithPurgeTask` (or `withPurgeTask`) to add a scheduled [ACR purge task](https://learn.microsoft.com/azure/container-registry/container-registry-auto-purge) that automatically removes old or unused images:
+Over time, container registries accumulate old images that consume storage. Use
@@ -343,7 +344,7 @@ Each purge task is given a unique name automatically. Use the `taskName` option
## Customize the provisioning infrastructure
-To make changes that go beyond what the built-in APIs expose, configure the underlying Bicep infrastructure directly via `ConfigureInfrastructure` (or `configureInfrastructure`):
+To make changes that go beyond what the built-in APIs expose, configure the underlying Bicep infrastructure directly via
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-connect.mdx
index 752ed3bf9..b7c0aeb0f 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-connect.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import cosmosDbIcon from '@assets/icons/azure-cosmosdb-icon.png';
+import ApiReference from '@components/ApiReference.astro';
- If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using `WithEnvironment`. See [Customize resources](/integrations/cloud/azure/customize-resources/) in the Azure integration reference.
+ If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host.mdx
index ea7610a0e..f4eb08f3e 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host.mdx
@@ -11,6 +11,7 @@ import ThemeImage from '@components/ThemeImage.astro';
import cosmosDbIcon from '@assets/icons/azure-cosmosdb-icon.png';
import cosmosResourceRelationships from '@assets/integrations/cloud/azure/cosmos-db/cosmos-resource-relationships.svg';
import cosmosResourceRelationshipsLight from '@assets/integrations/cloud/azure/cosmos-db/cosmos-resource-relationships-light.svg';
+import ApiReference from '@components/ApiReference.astro';
- When you call `AddAzureCosmosDB` (or `addAzureCosmosDB`), it implicitly calls `AddAzureProvisioning` — which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](/integrations/cloud/azure/local-provisioning/#configuration).
+ When you call
@@ -117,7 +118,7 @@ await builder.addNodeApp("api", "./api", "index.js")
## Run as emulator
-For local development, use the Azure Cosmos DB Emulator instead of a live Azure account. Chain `RunAsEmulator` (or `runAsEmulator`) on the resource builder:
+For local development, use the Azure Cosmos DB Emulator instead of a live Azure account. Chain
@@ -162,7 +163,7 @@ By default, the Cosmos DB emulator container exposes the following endpoint:
| -------- | -------------- | --------- |
| `https` | 8081 | dynamic |
-To configure a fixed host port, call `WithGatewayPort` (or `withGatewayPort`) inside the emulator callback:
+To configure a fixed host port, call
@@ -204,7 +205,7 @@ The Cosmos DB emulator container's port is mapped to the host port as shown in t
### Configure classic emulator partition count
-To configure the partition count for the classic Cosmos DB emulator container, call `WithPartitionCount` (or `withPartitionCount`) inside the classic emulator callback. The default Linux-based (vNext) emulator doesn't support partition counts and throws a NotSupportedException if you call this API with `RunAsEmulator` (or `runAsEmulator`).
+To configure the partition count for the classic Cosmos DB emulator container, call NotSupportedException if you call this API with `RunAsEmulator` (or `runAsEmulator`).
@@ -280,7 +281,7 @@ The data volume is mounted at `/tmp/cosmos/appdata` in the emulator container. W
### Configure emulator with persistent lifetime
-To configure the Cosmos DB emulator container with a persistent lifetime, call the `WithLifetime` method with `ContainerLifetime.Persistent`:
+To configure the Cosmos DB emulator container with a persistent lifetime, call the
@@ -330,12 +331,12 @@ await cosmos.runAsClassicEmulator();
`RunAsClassicEmulator` configures the Cosmos DB resource to use the `stable` tag of the [Azure Cosmos DB Emulator](https://learn.microsoft.com/azure/cosmos-db/emulator#authentication) container image. Unlike the default vNext emulator, the classic emulator requires a TLS/SSL certificate. For more information, see [Export the emulator's TLS/SSL certificate](https://learn.microsoft.com/azure/cosmos-db/how-to-develop-emulator?tabs=docker-linux#export-the-emulators-tlsssl-certificate).
- `RunAsPreviewEmulator` (or `runAsPreviewEmulator`) is still available but is now obsolete. It forwards to `RunAsEmulator` (the vNext emulator) so existing code keeps working, but new code should call `RunAsEmulator` directly.
+
## Configure the Data Explorer
-The Linux-based (vNext) emulator used by `RunAsEmulator` includes a built-in **Data Explorer** web UI. Call `WithDataExplorer` (or `withDataExplorer`) inside the emulator callback to expose it:
+The Linux-based (vNext) emulator used by `RunAsEmulator` includes a built-in **Data Explorer** web UI. Call
@@ -377,7 +378,7 @@ await cosmos.runAsEmulator({
## Connect to an existing Azure Cosmos DB account
-You might have an existing Azure Cosmos DB account you want to connect to. Chain a call to `AsExisting` (or `asExisting`) on the resource builder:
+You might have an existing Azure Cosmos DB account you want to connect to. Chain a call to
@@ -428,7 +429,7 @@ Aspire models parent-child relationships between Azure Cosmos DB resources. An A
### Add a database
-To add an Azure Cosmos DB database resource, call `AddCosmosDatabase` (or `addCosmosDatabase`) on the Cosmos DB account resource builder:
+To add an Azure Cosmos DB database resource, call
@@ -459,7 +460,7 @@ The `AddCosmosDatabase` call adds a logical database named `db` to your Cosmos D
### Add a container
-An Azure Cosmos DB container is where data is stored. When you create a container, you must supply a partition key path. To add an Azure Cosmos DB container resource, call `AddContainer` (or `addContainer`) on the database resource builder:
+An Azure Cosmos DB container is where data is stored. When you create a container, you must supply a partition key path. To add an Azure Cosmos DB container resource, call
@@ -556,7 +557,7 @@ When your AppHost code expresses parent-child relationships, consuming apps can
## Enable access key authentication
-By default, the Azure Cosmos DB hosting integration uses Microsoft Entra ID (role-based access). To enable access key authentication instead, call `WithAccessKeyAuthentication` (or `withAccessKeyAuthentication`):
+By default, the Azure Cosmos DB hosting integration uses Microsoft Entra ID (role-based access). To enable access key authentication instead, call
@@ -659,7 +660,7 @@ The generated Bicep is a starting point and is influenced by changes to the prov
## Customize provisioning infrastructure
-All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables fluent customization of the generated Bicep using the `ConfigureInfrastructure` (or `configureInfrastructure`) API. For example, you can configure the `kind`, `consistencyPolicy`, `locations`, and more:
+All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables fluent customization of the generated Bicep using the
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-data-explorer.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-data-explorer.mdx
index c32cab237..0cdbb13e3 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-data-explorer.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-data-explorer.mdx
@@ -8,6 +8,7 @@ import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import ContainerImages from '@components/ContainerImages.astro';
import LearnMore from '@components/LearnMore.astro';
import kustoIcon from '@assets/icons/azure-dataexplorer-icon.svg';
+import ApiReference from '@components/ApiReference.astro';
@@ -112,10 +113,10 @@ await builder.addNodeApp("api", "./api", "index.js")
-The preceding code adds an Azure Data Explorer cluster named `kusto` with a read-write database named `analytics`. The `WithReference` (or `withReference`) method injects the connection information into the consuming project.
+The preceding code adds an Azure Data Explorer cluster named `kusto` with a read-write database named `analytics`. The
- When you call `AddAzureKustoCluster`, it implicitly calls `AddAzureProvisioning` —
+ When you call `AddAzureKustoCluster`, it implicitly calls
@@ -316,7 +317,7 @@ The generated Bicep is a starting point — customise it through the C# provisio
### Customize provisioning infrastructure
-All Aspire Azure resources subclass `AzureProvisioningResource`. The `ConfigureInfrastructure` (or `configureInfrastructure`) API lets you customise the generated Bicep with a fluent callback:
+All Aspire Azure resources subclass `AzureProvisioningResource`. The
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-default-credential.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-default-credential.mdx
index bdadcb937..e1c4bdd98 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-default-credential.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-default-credential.mdx
@@ -6,6 +6,7 @@ description: Learn about the default credential behavior in Aspire Azure client
import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import azureIcon from '@assets/icons/azure-icon.png';
+import ApiReference from '@components/ApiReference.astro';
@@ -113,10 +114,10 @@ await builder.addNodeApp("api", "./api", "index.js")
-The preceding code adds an Azure Event Hubs namespace named `event-hubs` with an Event Hub named `messages`. The `WithReference` (or `withReference`) method injects the connection information into the consuming project.
+The preceding code adds an Azure Event Hubs namespace named `event-hubs` with an Event Hub named `messages`. The
- When you call `AddAzureEventHubs`, it implicitly calls `AddAzureProvisioning` —
+ When you call `AddAzureEventHubs`, it implicitly calls
@@ -219,7 +220,7 @@ By default, the emulator container exposes port `5672` mapped to a random host p
| ---------- | -------------------------------------------------------------- | -------------- | --------- |
| `emulator` | `mcr.microsoft.com/azure-messaging/eventhubs-emulator` | 5672 | dynamic |
-To fix the host port, pass a `configureContainer` callback and call `WithHostPort` (or `withHostPort`):
+To fix the host port, pass a `configureContainer` callback and call
@@ -319,7 +320,7 @@ builder.AddProject()
```
-The TypeScript AppHost doesn't currently expose `withDataBindMount` on the Event Hubs emulator resource. Use a data volume via the C# AppHost or pre-configure hubs with `withConfigurationFile` instead.
+The TypeScript AppHost doesn't currently expose `withDataBindMount` on the Event Hubs emulator resource. Use a data volume via the C# AppHost or pre-configure hubs with
@@ -403,12 +404,12 @@ builder.AddProject()
```
- `WithConfiguration` is not available in the TypeScript AppHost. Use `withConfigurationFile` to supply a fully customized configuration file instead.
+ `withConfiguration` is not available in the TypeScript AppHost. Use `withConfigurationFile` to supply a fully customized configuration file instead.
## Connect to an existing Azure Event Hubs namespace
-If you already have an Azure Event Hubs namespace, call `AsExisting` (or `asExisting`) instead of provisioning a new one:
+If you already have an Azure Event Hubs namespace, call
@@ -567,7 +568,7 @@ The generated Bicep is a starting point — customise it through the C# provisio
### Customize provisioning infrastructure
-All Aspire Azure resources subclass `AzureProvisioningResource`. The `ConfigureInfrastructure` (or `configureInfrastructure`) API lets you customise the generated Bicep with a fluent callback:
+All Aspire Azure resources subclass `AzureProvisioningResource`. The
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-front-door.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-front-door.mdx
index 29584742a..1c6725108 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-front-door.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-front-door.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallPackage from '@components/InstallPackage.astro';
import azureIcon from '@assets/icons/azure-front-door-icon.png';
+import ApiReference from '@components/ApiReference.astro';
@@ -78,14 +79,14 @@ await builder.build().run();
The preceding code:
- Adds an Azure App Service environment (a compute environment is required so Front Door can resolve the origin's hostname).
-- Adds an `api` project and exposes it externally with `withExternalHttpEndpoints`. Front Door requires an origin to expose an external HTTP or HTTPS endpoint.
+- Adds an `api` project and exposes it externally with
When you call `addAzureFrontDoor`, it implicitly calls
- `addAzureProvisioning`—which adds support for generating Azure resources
+
- **Upgrading from Aspire 13.3.0-preview:** The resource names generated for Front Door profiles, endpoints, origin groups, origins, and routes changed in Aspire 13.4. This can result in duplicate Azure resources (profiles, endpoints, origin groups, routes, and origins) during an upgrade. To avoid duplicates, either remove the existing Azure resources before redeploying, or set resource names explicitly using `ConfigureInfrastructure`.
+ **Upgrading from Aspire 13.3.0-preview:** The resource names generated for Front Door profiles, endpoints, origin groups, origins, and routes changed in Aspire 13.4. This can result in duplicate Azure resources (profiles, endpoints, origin groups, routes, and origins) during an upgrade. To avoid duplicates, either remove the existing Azure resources before redeploying, or set resource names explicitly using
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-connect.mdx
index b354da35e..dbdb76a10 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-connect.mdx
@@ -6,6 +6,7 @@ description: Learn how Azure Functions code reads Aspire-injected environment va
import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import functionsIcon from '@assets/icons/azure-functionapps-icon.png';
+import ApiReference from '@components/ApiReference.astro';
@@ -341,7 +342,7 @@ The Durable Task scheduler and task hub APIs are experimental in this release. T
To use these APIs without compiler warnings, suppress the `ASPIREDURABLETASK001` diagnostic. For suppression options, see [ASPIREDURABLETASK001](/diagnostics/aspiredurabletask001/).
:::
-The `Aspire.Hosting.Azure.Functions` package includes support for [Azure Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler), which provides a managed backend for Durable Functions orchestrations. Use `AddDurableTaskScheduler` to add a scheduler resource and `AddTaskHub` to associate a task hub with it.
+The `Aspire.Hosting.Azure.Functions` package includes support for [Azure Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler), which provides a managed backend for Durable Functions orchestrations. Use ` for securely supplying the value at runtime:
+To connect to an already-deployed Durable Task Scheduler instance instead of provisioning a new one, use ` for securely supplying the value at runtime:
```csharp title="AppHost.cs"
#pragma warning disable ASPIREDURABLETASK001
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-host.mdx
index 8cb405db4..a912ce35f 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-host.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-host.mdx
@@ -7,6 +7,7 @@ import { Image } from 'astro:assets';
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import keyVaultIcon from '@assets/icons/azure-keyvault-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-The `WithReference` (or `withReference`) method configures a connection in the consuming project named after the referenced Key Vault resource.
+The
- When you call `AddAzureKeyVault` (or `addAzureKeyVault`), it implicitly calls
- `AddAzureProvisioning`, which adds support for generating Azure resources
+ When you call
@@ -218,7 +219,7 @@ await builder.build().run();
-To clear the default role assignments and configure only specific roles, call `ClearDefaultRoleAssignments` (or `clearDefaultRoleAssignments`) before adding the roles you need.
+To clear the default role assignments and configure only specific roles, call
@@ -264,7 +265,7 @@ await builder.build().run();
### Reference an existing secret
-To reference an existing secret in the vault and pass it to a consuming resource, use `GetSecret` (or `getSecret`):
+To reference an existing secret in the vault and pass it to a consuming resource, use
@@ -371,7 +372,7 @@ The generated Bicep is a starting point and is influenced by changes to the prov
## Customize provisioning infrastructure
-All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the `ConfigureInfrastructure` (or `configureInfrastructure`) API:
+All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx
index f906a7c12..252f53e3b 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import logAnalyticsIcon from '@assets/icons/azure-loganalytics-icon.png';
+import ApiReference from '@components/ApiReference.astro';
@@ -112,7 +113,7 @@ The preceding code adds an Azure Log Analytics workspace resource named `log-ana
When you call `AddAzureLogAnalyticsWorkspace` (or
`addAzureLogAnalyticsWorkspace`), it implicitly calls
- `AddAzureProvisioning`—which adds support for generating Azure resources
+
-1. Calling `AddAzureOpenAI` (or `addAzureOpenAI`) creates an `AzureOpenAIResource` that models the Azure Cognitive Services account. It implicitly calls `AddAzureProvisioning`, which adds support for generating Azure resources dynamically during app startup.
+1. Calling
@@ -257,7 +258,7 @@ await openai.clearDefaultRoleAssignments();
## Connect to an existing Azure OpenAI service
-You might have an already-deployed Azure OpenAI account in your Azure subscription that you want to connect to. Use `AsExisting` (or `asExisting`) to point the resource at an existing account instead of provisioning a new one:
+You might have an already-deployed Azure OpenAI account in your Azure subscription that you want to connect to. Use
@@ -385,7 +386,7 @@ The generated Bicep is a starting point and is influenced by changes to the prov
## Customize provisioning infrastructure
-All Aspire Azure resources are subclasses of `AzureProvisioningResource`. This enables customization of the generated Bicep by providing a fluent API to configure Azure resources using the `ConfigureInfrastructure` API:
+All Aspire Azure resources are subclasses of `AzureProvisioningResource`. This enables customization of the generated Bicep by providing a fluent API to configure Azure resources using the
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-connect.mdx
index f75a57eca..e0c94a636 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-connect.mdx
@@ -7,6 +7,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import postgresqlIcon from '@assets/icons/azure-postgresql-icon.png';
+import ApiReference from '@components/ApiReference.astro';
- If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost. See the [AppHost reference](/get-started/app-host/) for details on `WithEnvironment` and related APIs.
+ If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost. See the [AppHost reference](/get-started/app-host/) for details on
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-get-started.mdx
index 307561b7c..9447227a1 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-get-started.mdx
@@ -6,6 +6,7 @@ description: "Use the Aspire Azure Database for PostgreSQL hosting and client in
import { Image } from 'astro:assets';
import { LinkButton, Steps } from '@astrojs/starlight/components';
import postgresqlIcon from '@assets/icons/azure-postgresql-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-The preceding code adds an Azure PostgreSQL flexible server resource named `postgres` with a database named `postgresdb`. The `withReference` / `WithReference` call injects the connection information into the consuming project.
+The preceding code adds an Azure PostgreSQL flexible server resource named `postgres` with a database named `postgresdb`. The
- When you call `AddAzurePostgresFlexibleServer` /
+ When you call
-When `RunAsContainer` / `runAsContainer` is called, Aspire uses the [`docker.io/library/postgres`](https://hub.docker.com/_/postgres) container image and generates credentials automatically. The same consuming app code and environment variable names work in both local-container and Azure modes.
+When
The `RunAsContainer` / `runAsContainer` API exposes an optional delegate
@@ -254,13 +255,13 @@ When `RunAsContainer` / `runAsContainer` is called, Aspire uses the [`docker.io/
### Cross-reference: local-container vs Azure PostgreSQL
-If you are developing against a local container and want to switch to Azure PostgreSQL for staging or production, change `AddPostgres` to `AddAzurePostgresFlexibleServer` in the AppHost. The connection information injected into consuming apps uses the same environment variable names, so no application code changes are required.
+If you are developing against a local container and want to switch to Azure PostgreSQL for staging or production, change
@@ -307,7 +308,7 @@ For more information on treating Azure resources as existing, see [Use existing
## Configure password authentication
-By default, the Azure PostgreSQL flexible server is configured to use [Microsoft Entra ID](https://learn.microsoft.com/azure/postgresql/flexible-server/concepts-azure-ad-authentication) authentication — no username or password is stored in your app configuration. If you need password authentication (for example, to connect with a legacy client that doesn't support Entra tokens), call `WithPasswordAuthentication` / `withPasswordAuthentication`:
+By default, the Azure PostgreSQL flexible server is configured to use [Microsoft Entra ID](https://learn.microsoft.com/azure/postgresql/flexible-server/concepts-azure-ad-authentication) authentication — no username or password is stored in your app configuration. If you need password authentication (for example, to connect with a legacy client that doesn't support Entra tokens), call
@@ -450,7 +451,7 @@ The generated Bicep is a starting point and is influenced by changes to the prov
## Customize provisioning infrastructure
-All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the `ConfigureInfrastructure` API:
+All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the
If a database does not appear after redeployment, verify that the
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx
index 81b0a1772..27560a583 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx
@@ -8,6 +8,7 @@ import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import ContainerImages from '@components/ContainerImages.astro';
import LearnMore from '@components/LearnMore.astro';
import serviceBusIcon from '@assets/icons/azure-servicebus-icon.png';
+import ApiReference from '@components/ApiReference.astro';
- When you call `AddAzureServiceBus` (C#) or `addAzureServiceBus` (TypeScript),
- it implicitly calls `AddAzureProvisioning`—which adds support for generating
+ When you call
@@ -185,7 +186,7 @@ For more information on treating Azure resources as existing resources, see [Use
## Add Azure Service Bus queue
-To add a queue to an Azure Service Bus namespace, call `AddServiceBusQueue` (C#) or `addServiceBusQueue` (TypeScript) on the Service Bus resource builder:
+To add a queue to an Azure Service Bus namespace, call
@@ -227,7 +228,7 @@ This expresses an explicit parent-child relationship between the `messaging` Ser
## Add Azure Service Bus topic
-To add a topic, call `AddServiceBusTopic` (C#) or `addServiceBusTopic` (TypeScript) on the Service Bus resource builder:
+To add a topic, call
@@ -263,7 +264,7 @@ The topic is created in the namespace that the `AzureServiceBusResource` represe
## Add Azure Service Bus subscription
-To add a subscription for a topic, call `AddServiceBusSubscription` (C#) or `addServiceBusSubscription` (TypeScript) on the topic resource builder:
+To add a subscription for a topic, call
@@ -343,7 +344,7 @@ builder.Build().Run();
## Add Azure Service Bus emulator resource
-For local development, Aspire can run the [Azure Service Bus Emulator](https://learn.microsoft.com/azure/service-bus-messaging/overview-emulator) as a container. Chain a call to `RunAsEmulator` (C#) or `runAsEmulator` (TypeScript) on the Service Bus resource builder:
+For local development, Aspire can run the [Azure Service Bus Emulator](https://learn.microsoft.com/azure/service-bus-messaging/overview-emulator) as a container. Chain a call to
@@ -388,7 +389,7 @@ By default, the Service Bus emulator container exposes the following endpoints:
### Configure the emulator host port
-By default, the host port is assigned dynamically. To pin it to a specific port, pass the `configureContainer` callback and call `withHostPort`:
+By default, the host port is assigned dynamically. To pin it to a specific port, pass the `configureContainer` callback and call
@@ -435,7 +436,7 @@ The preceding code maps the `emulator` endpoint to host port `7777`:
### Configure the emulator with a custom JSON file
-The Service Bus emulator generates its configuration automatically from the resources you've added. To provide a fully custom configuration file instead, call `WithConfigurationFile` (C#) or `withConfigurationFile` (TypeScript):
+The Service Bus emulator generates its configuration automatically from the resources you've added. To provide a fully custom configuration file instead, call
@@ -569,7 +570,7 @@ For more information on the assigned role, see [Azure Service Bus Data Owner](ht
### Customize provisioning infrastructure
-All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables customization of the generated Bicep using the fluent `ConfigureInfrastructure` API. For example, you can configure the SKU, location, tags, and more:
+All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables customization of the generated Bicep using the fluent ` types are hosted) and **clients** (browser or mobile apps using the SignalR client). The architecture differs from a direct database connection: the server never receives connections from clients directly — Azure SignalR Service routes all traffic.
:::note
-Aspire integrates at the **hub server** level, not the end-client level. The `WithReference` call injects the service endpoint into the server-side project so it can connect to Azure SignalR Service. End clients (browser apps, mobile apps) connect to hubs through normal SignalR client negotiation, not through Aspire.
+Aspire integrates at the **hub server** level, not the end-client level. The
- When you call `AddAzureSignalR` (or `addAzureSignalR`), it implicitly calls
- `AddAzureProvisioning` — which adds support for generating Azure resources
+ When you call
`AzureSignalRServiceMode` is not available as a TypeScript parameter. Full
service mode configuration requires modifying the Bicep object model through
- `configureInfrastructure`. See [Customize provisioning
+
@@ -198,7 +199,7 @@ The Azure SignalR Service emulator only works in _Serverless_ mode. The `AddName
The Azure SignalR Service emulator allows local development and testing without requiring an Azure subscription. The emulator only supports [_Serverless_ mode](https://learn.microsoft.com/azure/azure-signalr/concept-service-mode#serverless-mode).
-To use the emulator, chain a call to `RunAsEmulator` (or `runAsEmulator`):
+To use the emulator, chain a call to
@@ -243,7 +244,7 @@ The `RunAsEmulator` call configures the Azure SignalR Service resource to use th
## Connect to an existing Azure SignalR instance
-You might have an existing Azure SignalR Service that you want to connect to. Use `AsExisting` (or `asExisting`) to annotate that your `AzureSignalRResource` is an existing resource:
+You might have an existing Azure SignalR Service that you want to connect to. Use
@@ -413,7 +414,7 @@ For more information, see [Azure.Provisioning customization](/integrations/cloud
## Connection properties
-When you reference an Azure SignalR Service resource using `WithReference` (or `withReference`), the following connection property is made available to the consuming project:
+When you reference an Azure SignalR Service resource using
Azure SQL Database uses Azure Active Directory authentication (managed identity)
when deployed to Azure — no username or password is injected. When you use
- `RunAsContainer` for local development, the connection string includes SQL
+
- If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using `WithEnvironment` (C#) or `withEnvironment` (TypeScript).
+ If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx
index 93af903c1..7948472d6 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx
@@ -6,6 +6,7 @@ description: Understand why you use the Aspire Azure SQL Database integrations a
import { Image } from 'astro:assets';
import { LinkButton, Steps } from '@astrojs/starlight/components';
import sqlServerIcon from '@assets/icons/azure-sqlserver-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-1. The `AddAzureSqlServer` (or `addAzureSqlServer`) call models an Azure SQL Server that is provisioned in Azure when you publish your app.
+1. The
@@ -192,7 +193,7 @@ When `RunAsContainer` is active, Aspire pulls a SQL Server container image and r
## Connect to an existing Azure SQL server
-You might have an existing Azure SQL Database service that you want to connect to. Chain a call to `AsExisting` (or `asExisting`) to annotate that your resource already exists in Azure:
+You might have an existing Azure SQL Database service that you want to connect to. Chain a call to
@@ -311,7 +312,7 @@ The generated Bicep is a starting point and is influenced by changes to the prov
### Customize provisioning infrastructure
-All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables customization of the generated Bicep by providing a fluent API to configure the Azure resources using the `ConfigureInfrastructure` API. For example, you can configure the `sku`, `version`, and more. The following example demonstrates how to customize the Azure SQL Database resource:
+All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables customization of the generated Bicep by providing a fluent API to configure the Azure resources using the
@@ -408,7 +409,7 @@ await builder.build().run();
#### Specify a custom subnet
-Call `WithAdminDeploymentScriptSubnet` (or `withAdminDeploymentScriptSubnet`) to provide your own subnet for the deployment script container:
+Call
@@ -453,7 +454,7 @@ await builder.build().run();
#### Specify a custom storage account
-Call `WithAdminDeploymentScriptStorage` (or `withAdminDeploymentScriptStorage`) to provide your own storage account for the deployment script:
+Call
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-connect.mdx
index 008742ae0..a2c298b96 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-connect.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import storageIcon from '@assets/icons/azure-storagecontainer-icon.png';
+import ApiReference from '@components/ApiReference.astro';
- If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using `WithEnvironment`. See [Customize Azure resources](/integrations/cloud/azure/customize-resources/) for more information.
+ If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-host.mdx
index fce6b33fd..b30699235 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-host.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-host.mdx
@@ -10,6 +10,7 @@ import LearnMore from '@components/LearnMore.astro';
import InstallPackage from '@components/InstallPackage.astro';
import storageIcon from '@assets/icons/azure-storagecontainer-icon.png';
import storageExplorerImage from '@assets/integrations/cloud/azure/storage/azure-storage-explorer.png';
+import ApiReference from '@components/ApiReference.astro';
-When you call `AddAzureStorage` (or `addAzureStorage`), it implicitly calls `AddAzureProvisioning`—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](/integrations/cloud/azure/local-provisioning/#configuration).
+When you call
@@ -112,7 +113,7 @@ When you call `AddAzureStorage` (or `addAzureStorage`), it implicitly calls `Add
## Add blob resource
-After creating an Azure Storage resource, you can add a blob service resource to it using `AddBlobs` (or `addBlobs`):
+After creating an Azure Storage resource, you can add a blob service resource to it using
@@ -157,7 +158,7 @@ The preceding code:
## Add blob container resource
-You can add a specific named blob container resource directly using `AddBlobContainer` (or `addBlobContainer`). This is useful when your app needs access to a specific container by name:
+You can add a specific named blob container resource directly using
@@ -198,7 +199,7 @@ The `blobContainerName` option (or `options.blobContainerName` in TypeScript) se
## Configure Azurite emulator
-During local development, you can configure the Azure Storage resource to use [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite) — the open-source Azure Storage emulator — instead of a real Azure subscription. Call `RunAsEmulator` (or `runAsEmulator`) on the storage resource:
+During local development, you can configure the Azure Storage resource to use [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite) — the open-source Azure Storage emulator — instead of a real Azure subscription. Call
@@ -291,7 +292,7 @@ await builder.build().run();
### Configure Azurite container with persistent lifetime
-To configure the Azurite container with a persistent lifetime, call `WithLifetime` (or `withLifetime`) with `ContainerLifetime.Persistent`:
+To configure the Azurite container with a persistent lifetime, call
@@ -329,7 +330,7 @@ await builder.build().run();
### Configure Azurite container with data volume
-To add a data volume to the Azurite container, call `WithDataVolume` (or `withDataVolume`) on the emulator resource:
+To add a data volume to the Azurite container, call
@@ -369,7 +370,7 @@ The data volume is used to persist Azurite data outside the lifecycle of its con
### Configure Azurite container with data bind mount
-To add a data bind mount to the Azurite container, call `WithDataBindMount` (or `withDataBindMount`) on the emulator resource:
+To add a data bind mount to the Azurite container, call
@@ -413,7 +414,7 @@ Data bind mounts rely on the host machine's filesystem to persist the Azurite da
## Connect to an existing Azure Storage account
-You might have an existing Azure Storage account that you want to connect to instead of provisioning a new one. Chain a call to `AsExisting` (or `asExisting`) on the storage resource:
+You might have an existing Azure Storage account that you want to connect to instead of provisioning a new one. Chain a call to
@@ -457,7 +458,7 @@ await builder.build().run();
:::caution
-When you call `RunAsExisting`, `PublishAsExisting`, or `AsExisting` to work with resources already present in your Azure subscription, you must add certain configuration values to your AppHost so that Aspire can locate them. The necessary configuration values include **SubscriptionId**, **AllowResourceGroupCreation**, **ResourceGroup**, and **Location**. If you don't set them, "Missing configuration" errors appear in the Aspire dashboard. For more information, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources).
+When you call
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-datalake.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-datalake.mdx
index e82b72e0f..b734ee45d 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-datalake.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-datalake.mdx
@@ -8,6 +8,7 @@ import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import dataLakeIcon from '@assets/icons/azure-datalake-icon.png';
+import ApiReference from '@components/ApiReference.astro';
@@ -120,7 +121,7 @@ Azure Data Lake Storage does **not** support the Azure Storage emulator. You mus
### Add Azure Data Lake file system resource
-You can also add a Data Lake file system resource directly from the storage resource using `AddDataLakeFileSystem` (or `addDataLakeFileSystem`):
+You can also add a Data Lake file system resource directly from the storage resource using
@@ -171,7 +172,7 @@ Both `AddDataLake` and `AddDataLakeFileSystem` are called on the storage resourc
### Customize provisioning infrastructure
-The Data Lake resource is part of the Azure Storage resource, which is a subclass of `AzureProvisioningResource`. You can customize the generated Bicep using the `ConfigureInfrastructure` (or `configureInfrastructure`) API on the storage resource. For example, you can configure the storage SKU, access tier, and other properties:
+The Data Lake resource is part of the Azure Storage resource, which is a subclass of `AzureProvisioningResource`. You can customize the generated Bicep using the
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-connect.mdx
index 208008a60..6155417f6 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-connect.mdx
@@ -7,6 +7,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import queueIcon from '@assets/icons/azure-storagequeue-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using `WithEnvironment`. See [Set up Azure Queue Storage in the AppHost](../azure-storage-queues-host/) for details.
+If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started.mdx
index f8dc5c04f..a4224007a 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started.mdx
@@ -6,6 +6,7 @@ description: Understand why you use the Aspire Azure Queue Storage integrations
import { Image } from 'astro:assets';
import { LinkButton, Steps } from '@astrojs/starlight/components';
import queueIcon from '@assets/icons/azure-storagequeue-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-When you call `AddAzureStorage` (or `addAzureStorage`), it implicitly calls `AddAzureProvisioning`—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](/integrations/cloud/azure/local-provisioning/#configuration).
+When you call
@@ -128,7 +129,7 @@ When you reference the queue resource from the AppHost, Aspire makes several con
## Run as Azurite emulator
-For local development, Aspire can run the [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite) emulator in a container to avoid requiring an Azure subscription. Call `RunAsEmulator` (C#) or `runAsEmulator` (TypeScript) on the storage resource:
+For local development, Aspire can run the [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite) emulator in a container to avoid requiring an Azure subscription. Call
@@ -239,7 +240,7 @@ The resulting port mappings (`container:host`) are:
## Configure Azurite container with persistent lifetime
-To keep the Azurite container alive across AppHost restarts, call `WithLifetime` with `ContainerLifetime.Persistent`:
+To keep the Azurite container alive across AppHost restarts, call
@@ -325,7 +326,7 @@ The data volume is mounted at the `/data` path in the Azurite container. When a
## Configure Azurite container with data bind mount
-To use a bind mount instead of a volume, call `WithDataBindMount`:
+To use a bind mount instead of a volume, call
@@ -373,7 +374,7 @@ Data bind mounts rely on the host machine's filesystem to persist Azurite data a
## Connect to an existing Azure Storage account
-You might have an existing Azure Storage account that you want to connect to. Call `AsExisting` (or `asExisting`) to annotate the resource as already provisioned:
+You might have an existing Azure Storage account that you want to connect to. Call
@@ -420,7 +421,7 @@ await builder.build().run();
-When you call `RunAsExisting`, `PublishAsExisting`, or `AsExisting` to work with resources that are already present in your Azure subscription, you must add certain configuration values to your AppHost so that Aspire can locate them. The necessary configuration values include **SubscriptionId**, **AllowResourceGroupCreation**, **ResourceGroup**, and **Location**. If you don't set them, "Missing configuration" errors appear in the Aspire dashboard. For more information about how to set them, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources).
+When you call
## Connect to storage resources from Azure Storage Explorer
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-connect.mdx
index 75ef9023f..d8672a7c9 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-connect.mdx
@@ -7,6 +7,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import tableIcon from '@assets/icons/azure-table-icon.png';
+import ApiReference from '@components/ApiReference.astro';
- If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using `WithEnvironment`. See the [AppHost reference](/get-started/app-host/) for details.
+ If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started.mdx
index 1e10b5bd6..fb0a2c3da 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started.mdx
@@ -6,6 +6,7 @@ description: Understand why you use the Aspire Azure Table Storage integrations
import { Image } from 'astro:assets';
import { LinkButton, Steps } from '@astrojs/starlight/components';
import tableIcon from '@assets/icons/azure-table-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-When you call `AddAzureStorage` (or `addAzureStorage`), it implicitly calls `AddAzureProvisioning` (or `addAzureProvisioning`) — which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](/integrations/cloud/azure/local-provisioning/#configuration).
+When you call
@@ -133,7 +134,7 @@ When you reference an Azure Table Storage resource from the AppHost, Aspire inje
## Run as emulator (Azurite)
-For local development, configure the storage resource to use the [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite) emulator instead of a real Azure Storage account. Call `RunAsEmulator` (or `runAsEmulator`) on the storage resource:
+For local development, configure the storage resource to use the [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite) emulator instead of a real Azure Storage account. Call
@@ -239,7 +240,7 @@ The preceding code configures the Azurite container ports as follows:
## Configure Azurite container with persistent lifetime
-To configure the Azurite container with a persistent lifetime so it survives app restarts, call `WithLifetime` (or `withLifetime`) with `ContainerLifetime.Persistent`:
+To configure the Azurite container with a persistent lifetime so it survives app restarts, call
@@ -277,7 +278,7 @@ await builder.build().run();
## Configure Azurite container with data volume
-To persist Azurite data across container restarts with a data volume, call `WithDataVolume` (or `withDataVolume`) on the emulator resource:
+To persist Azurite data across container restarts with a data volume, call
@@ -317,7 +318,7 @@ The data volume is mounted at the `/data` path in the Azurite container and when
## Configure Azurite container with data bind mount
-To add a data bind mount to the Azurite container instead of a named volume, call `WithDataBindMount` (or `withDataBindMount`):
+To add a data bind mount to the Azurite container instead of a named volume, call
@@ -389,7 +390,7 @@ For more information on using the Azure Storage Explorer, see [Get started with
## Connect to an existing Azure Storage account
-If you have an existing Azure Storage account, you can connect to it using the `AsExisting` (or `asExisting`) method instead of provisioning a new one:
+If you have an existing Azure Storage account, you can connect to it using the
@@ -435,7 +436,7 @@ await builder.build().run();
:::important
-When you call `RunAsExisting`, `PublishAsExisting`, or `AsExisting` methods to work with resources that are already present in your Azure subscription, you must add certain configuration values to your AppHost to ensure that Aspire can locate them. The necessary configuration values include **SubscriptionId**, **AllowResourceGroupCreation**, **ResourceGroup**, and **Location**. If you don't set them, "Missing configuration" errors appear in the Aspire dashboard. For more information, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources).
+When you call
When you call any of the Azure Virtual Network APIs, it implicitly calls
- `AddAzureProvisioning`—which adds support for generating Azure resources
+
@@ -150,7 +151,7 @@ const vnet = await builder.addAzureVirtualNetwork('vnet', '10.1.0.0/16');
### Add subnets
-Call `AddSubnet` (or `addSubnet`) on the virtual network builder to add a subnet with a name and address prefix:
+Call
@@ -175,7 +176,7 @@ You can add multiple subnets with different address ranges to a single virtual n
### Add NAT gateways
-A [NAT gateway](https://learn.microsoft.com/azure/nat-gateway/) provides deterministic outbound public IP addresses for subnet resources. Call `AddNatGateway` (or `addNatGateway`) to create a NAT gateway, then associate it with a subnet using `WithNatGateway` (or `withNatGateway`):
+A [NAT gateway](https://learn.microsoft.com/azure/nat-gateway/) provides deterministic outbound public IP addresses for subnet resources. Call
@@ -200,7 +201,7 @@ const subnet = vnet.addSubnet("aca-subnet", "10.0.0.0/23")
-By default, a public IP address is automatically created for the NAT gateway. To provide an explicit public IP address for full control, call `AddPublicIPAddress` (or `addPublicIPAddress`) and associate it with `WithPublicIPAddress` (or `withPublicIPAddress`):
+By default, a public IP address is automatically created for the NAT gateway. To provide an explicit public IP address for full control, call
@@ -260,10 +261,10 @@ const subnet = vnet.addSubnet("web", "10.0.1.0/24")
The available shorthand methods are:
-- `AllowInbound` (or `allowInbound`) — Allow inbound traffic.
-- `DenyInbound` (or `denyInbound`) — Deny inbound traffic.
-- `AllowOutbound` (or `allowOutbound`) — Allow outbound traffic.
-- `DenyOutbound` (or `denyOutbound`) — Deny outbound traffic.
+-
@@ -338,7 +339,7 @@ A single NSG can be shared across multiple subnets.
### Delegate subnets to compute environments
-Compute environment integrations that support regional virtual network integration expose a `WithDelegatedSubnet` (or `withDelegatedSubnet` in TypeScript) extension method that assigns a subnet to the environment, enabling subnet delegation so the environment can inject its infrastructure. For example, [Azure Container Apps](/integrations/cloud/azure/configure-container-apps/) and [Azure App Service](/integrations/cloud/azure/azure-app-service/azure-app-service-host/#regional-virtual-network-integration) both support `WithDelegatedSubnet`:
+Compute environment integrations that support regional virtual network integration expose a
@@ -380,7 +381,7 @@ Each compute environment delegates the subnet to its own Azure service (for exam
### Delegate a subnet to an Azure service
-For scenarios that aren't covered by a compute environment's `WithDelegatedSubnet` helper, call `WithServiceDelegation` (or `withServiceDelegation` in TypeScript) directly on the subnet builder to delegate it to a supported Azure service. The delegation `name` defaults to `serviceName` so you don't have to repeat the value:
+For scenarios that aren't covered by a compute environment's `WithDelegatedSubnet` helper, call
@@ -426,7 +427,7 @@ You can also pass another supported Azure resource provider path as `serviceName
### Add private endpoints
-[Private endpoints](https://learn.microsoft.com/azure/private-link/) enable secure connectivity to Azure services over a private network. Call `AddPrivateEndpoint` (or `addPrivateEndpoint`) on a subnet builder and pass the Azure resource to connect to:
+[Private endpoints](https://learn.microsoft.com/azure/private-link/) enable secure connectivity to Azure services over a private network. Call
@@ -462,7 +463,7 @@ When you add a private endpoint, the following resources are automatically creat
3. A **DNS Zone Group** on the private endpoint for automatic DNS registration.
4. The target resource is automatically configured to **deny public network access**.
-The private DNS zone ensures that services within the virtual network automatically resolve the target resource's hostname to its private IP address. Resources that reference the target (for example, via `WithReference`) use the same connection information—DNS resolution handles routing traffic over the private network.
+The private DNS zone ensures that services within the virtual network automatically resolve the target resource's hostname to its private IP address. Resources that reference the target (for example, via
Adding a private endpoint automatically disables public network access on the
@@ -474,7 +475,7 @@ The private DNS zone ensures that services within the virtual network automatica
#### Override public network access
-To keep public access enabled on a resource that has a private endpoint, use `ConfigureInfrastructure` to override the automatic lockdown:
+To keep public access enabled on a resource that has a private endpoint, use
@@ -563,7 +564,7 @@ await builder.build().run();
#### Add access rules
-Access rules control traffic flowing into and out of the perimeter. Call `WithAccessRule` (or `withAccessRule`) and pass an `AzureNspAccessRule` to define a rule:
+Access rules control traffic flowing into and out of the perimeter. Call
@@ -618,7 +619,7 @@ Each property also has a corresponding `*References` variant (for example, `Addr
#### Associate resources with a perimeter
-Call `WithNetworkSecurityPerimeter` (or `withNetworkSecurityPerimeter`) on a PaaS resource builder to associate it with an NSP:
+Call
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-connect.mdx
index 2a3a03638..80bd02d4b 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-connect.mdx
@@ -8,6 +8,7 @@ import { Image } from 'astro:assets';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import InstallDotNetPackage from '@components/InstallDotNetPackage.astro';
import webPubSubIcon from '@assets/icons/azure-webpubsub-icon.png';
+import ApiReference from '@components/ApiReference.astro';
- If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using `WithEnvironment`. See [Customize provisioning infrastructure](../azure-web-pubsub-host/#customize-provisioning-infrastructure) in the Hosting integration reference.
+ If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-host.mdx
index a86f05409..b2b9cd4c6 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-host.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-host.mdx
@@ -7,6 +7,7 @@ import { Image } from 'astro:assets';
import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
import LearnMore from '@components/LearnMore.astro';
import webPubSubIcon from '@assets/icons/azure-webpubsub-icon.png';
+import ApiReference from '@components/ApiReference.astro';
-1. The `AddAzureWebPubSub` (or `addAzureWebPubSub`) call declares an Azure Web PubSub resource named `web-pubsub` in the AppHost.
+1. The
When you call `AddAzureWebPubSub`, it implicitly calls
- `AddAzureProvisioning`—which adds support for generating Azure resources
+
@@ -156,7 +157,7 @@ The preceding code adds a hub resource named `messages` with a hub name of `mess
## Add event handler to a hub
-Event handlers allow your backend services to receive events from Azure Web PubSub. To add an event handler to a hub, chain a call to `AddEventHandler` (or `addEventHandler`):
+Event handlers allow your backend services to receive events from Azure Web PubSub. To add an event handler to a hub, chain a call to
@@ -251,7 +252,7 @@ The available roles for Azure Web PubSub are:
## Connect to an existing Azure Web PubSub instance
-You might have an existing Azure Web PubSub service that you want to connect to. Chain a call to `AsExisting` (or `asExisting`) to annotate that your resource is externally managed:
+You might have an existing Azure Web PubSub service that you want to connect to. Chain a call to
@@ -379,7 +380,7 @@ The generated Bicep is a starting point and is influenced by changes to the prov
## Customize provisioning infrastructure
-All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the `ConfigureInfrastructure` API:
+All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/configure-container-apps.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/configure-container-apps.mdx
index b6ae6a2ee..327a832d8 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/configure-container-apps.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/configure-container-apps.mdx
@@ -6,6 +6,7 @@ description: Learn how to configure Azure Container Apps environment settings, s
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import { Image } from 'astro:assets';
import containerAppsIcon from '@assets/icons/azure-container-apps-environments.svg';
+import ApiReference from '@components/ApiReference.astro';
@@ -233,13 +234,13 @@ When the environment is marked as existing, Aspire generates a thin Bicep module
Some configurations are incompatible with an existing environment and are rejected at publish time:
-- `WithDelegatedSubnet` — VNet integration is a property of the managed environment and can't be reconfigured on an existing one.
-- `WithAzureLogAnalyticsWorkspace` — the existing environment already owns its workspace.
+-
@@ -362,7 +363,7 @@ builder.Build().Run();
## Handle naming conventions
-By default, `AddAzureContainerAppEnvironment` uses a different Azure resource naming scheme than the [Azure Developer CLI (`azd`)](https://learn.microsoft.com/azure/developer/azure-developer-cli/). If you're upgrading an existing deployment that previously used `azd`, you might see duplicate Azure resources. To avoid this issue, call the `WithAzdResourceNaming` method to revert to the naming convention used by `azd`:
+By default, `AddAzureContainerAppEnvironment` uses a different Azure resource naming scheme than the [Azure Developer CLI (`azd`)](https://learn.microsoft.com/azure/developer/azure-developer-cli/). If you're upgrading an existing deployment that previously used `azd`, you might see duplicate Azure resources. To avoid this issue, call the
@@ -397,7 +398,7 @@ Calling this API ensures your existing Azure resources remain consistent and pre
By default, the generated managed environment `name` keeps only lowercase letters from the resource name, so `AddAzureContainerAppEnvironment("cae1")` and `AddAzureContainerAppEnvironment("cae2")` both produce the same Bicep expression once digits are stripped. If you deploy both environments to the *same resource group*, they collapse onto a single physical Azure Container Apps environment and concurrent deployments can fail with `ManagedEnvironmentOperationInProgress`.
-Publish and deploy detect this collision up front and fail with guidance to call `WithUniqueResourceNaming` on the colliding environments:
+Publish and deploy detect this collision up front and fail with guidance to call
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/container-app-jobs.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/container-app-jobs.mdx
index 4e2ea6286..f9970eee9 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/container-app-jobs.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/container-app-jobs.mdx
@@ -6,6 +6,7 @@ description: Learn how to use the Aspire Azure Container App Jobs hosting integr
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import { Image } from 'astro:assets';
import containerAppsIcon from '@assets/icons/azure-container-apps-environments.svg';
+import ApiReference from '@components/ApiReference.astro';
`. |
-| `ContainerResource` | A container image added via `AddContainer`. |
-| `ExecutableResource` | An executable process added via `AddExecutable`. |
+| `ProjectResource` | A .NET project added via