@ViewData["Title"] - BrowserTelemetry

`** Return only the specified section of the page. Provide the section heading to filter the output to that section and its content. * **`--format `** Output format. Choose `Table` for a human-readable table or `Json` for machine-readable JSON output. Defaults to `Table`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Get the full content of the Redis integration page: Aspire CLI ```bash aspire docs get get-started-with-the-redis-integrations ``` * Get only a specific section from a documentation page: Aspire CLI ```bash aspire docs get set-up-redis-in-the-apphost --section "Installation" ``` * Get page content in JSON format: Aspire CLI ```bash aspire docs get build-your-first-aspire-app --format Json ``` ## See also [Section titled “See also”](#see-also) * [aspire docs command](../aspire-docs/) * [aspire docs list command](../aspire-docs-list/) * [aspire docs search command](../aspire-docs-search/) # aspire docs list command > Learn about the aspire docs list command and its usage. This command lists all available Aspire documentation pages from aspire.dev. ## Name [Section titled “Name”](#name) `aspire docs list` - List all available Aspire documentation pages. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire docs list [options] ``` ## Description [Section titled “Description”](#description) The `aspire docs list` command retrieves and displays all available documentation pages from [aspire.dev](https://aspire.dev). The output includes page titles, URL slugs, and brief summaries for each page. Use this command to browse the documentation catalog and discover available topics. The slugs returned can be passed to the [`aspire docs get`](../aspire-docs-get/) command to retrieve the full content of a specific page. ## Options [Section titled “Options”](#options) The following options are available: * **`--format `** Output format. Choose `Table` for a human-readable table or `Json` for machine-readable JSON output. Defaults to `Table`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * List all available documentation pages: Aspire CLI ```bash aspire docs list ``` * List all pages in JSON format: Aspire CLI ```bash aspire docs list --format Json ``` ## See also [Section titled “See also”](#see-also) * [aspire docs command](../aspire-docs/) * [aspire docs search command](../aspire-docs-search/) * [aspire docs get command](../aspire-docs-get/) # aspire docs search command > Learn about the aspire docs search command and its usage. This command searches Aspire documentation using relevance-ranked keyword and phrase queries. ## Name [Section titled “Name”](#name) `aspire docs search` - Search Aspire documentation by keywords. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire docs search [options] ``` ## Description [Section titled “Description”](#description) The `aspire docs search` command performs a relevance-ranked search across the Aspire documentation on [aspire.dev](https://aspire.dev). Results include the page title, slug, matching section, and a relevance score. The ranker rewards exact title, slug, and heading matches and uses inverse document frequency (IDF) weighting so common terms such as `new` or `azure` count less than specific terms. Version separators are normalized so queries like `whats new 13.5`, `what's new 13-5`, and `whats new 135` all match the same pages. Explicit release-note queries (for example, `whats new 13.5` or `changelog`) surface What’s New pages at the top, while incidental mentions in feature docs do not outrank the dedicated pages. The slugs returned in search results can be passed to the [`aspire docs get`](../aspire-docs-get/) command to retrieve the full content of a matching page. ## Arguments [Section titled “Arguments”](#arguments) * **``** The search query. For best results, use multi-word phrases that match the title or heading you are looking for (for example, `"service discovery"` or `"azure container apps environment"`). Specific API names, configuration keys, and feature names work well. Version numbers in the form `13.5`, `13-5`, or `135` are all equivalent and match What’s New pages for that release. ## Options [Section titled “Options”](#options) The following options are available: * **`--format `** Output format. Choose `Table` for a human-readable table or `Json` for machine-readable JSON output. Defaults to `Table`. * **`-n, --limit `** Maximum number of search results to return. Defaults to `5`, with a maximum of `10`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Search for documentation about Redis: Aspire CLI ```bash aspire docs search "redis" ``` * Search for What’s New content for a specific release: Aspire CLI ```bash aspire docs search "whats new 13.5" ``` * Find documentation for a multi-word feature by phrase: Aspire CLI ```bash aspire docs search "service discovery" aspire docs search "azure container apps environment" ``` * Search with a custom result limit: Aspire CLI ```bash aspire docs search "service defaults" --limit 3 ``` * Search and output results in JSON format: Aspire CLI ```bash aspire docs search "deployment" --format Json ``` ## See also [Section titled “See also”](#see-also) * [aspire docs command](../aspire-docs/) * [aspire docs list command](../aspire-docs-list/) * [aspire docs get command](../aspire-docs-get/) # aspire doctor command > Learn about the aspire doctor command and its usage. This command diagnoses Aspire environment issues and verifies setup. ## Name [Section titled “Name”](#name) `aspire doctor` - Check the Aspire development environment for common issues. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire doctor [options] ``` ## Description [Section titled “Description”](#description) The `aspire doctor` command runs a series of diagnostic checks to help you troubleshoot your Aspire development environment. It checks SDKs, container runtimes, and environment settings. Note The `aspire doctor` command replaces the hidden `aspire setup` command. If you previously used `aspire setup` or `aspire setup --force`, use `aspire doctor` instead. The `aspire setup` command is still available for backward compatibility but is hidden from help output. This command is useful for troubleshooting when you encounter issues with Aspire or when setting up a new development environment. The checks are grouped by category: * **Aspire checks**: Reports the current Aspire CLI version and whether a newer CLI version is available, and suggests running `aspire update` when a newer one is available * **AppHost checks**: Reports the AppHost Aspire SDK version when an AppHost project is present in the current directory * **SDK checks**: Reports .NET SDK availability and version * **Container checks**: Validates container runtime (Docker and/or Podman) availability, running status, and version. Reports which runtime is active and why (explicit configuration, auto-detected default, or auto-detected only runtime running) * **Environment checks**: Reports operating system information (type, version, and Linux distro details when available) and validates environment variables and other settings, including the JavaScript toolchain required by TypeScript AppHosts (npm, pnpm, Yarn, or Bun) * **Development tools checks**: When VS Code is detected, reports whether the [Aspire VS Code extension](https://aka.ms/aspire/vscode-extension) is installed Note The development tools check only runs when VS Code is detected, using the same signals the CLI already relies on: the `TERM_PROGRAM=vscode` environment variable (VS Code’s integrated terminal) or `code`/`code-insiders` on `PATH`. If VS Code isn’t detected, the check is skipped and adds no output. When VS Code is detected but the Aspire extension (`microsoft-aspire.aspire-vscode`) isn’t installed, `aspire doctor` reports a warning with a link to install it from the Marketplace. When the extension is already installed, the check passes. Note On Linux, `aspire doctor` reports a warning when `certutil` is unavailable. Aspire uses `certutil` to query and update the NSS certificate databases used by Firefox and Chromium browsers, so without it browser certificate trust may be incomplete. Install `certutil` from your distribution’s NSS tools package, for example `libnss3-tools`, to resolve the warning. Note On Linux, `aspire doctor` also checks the OpenSSL development certificate cache under the dev-certs trust directory. It reports a warning when the cache is missing the current HTTPS development certificate, is missing the subject-hash link OpenSSL uses to look up certificates by directory, or contains certificate files that can’t be read (for example, because they’re corrupt). In each case, `aspire doctor` recommends running `aspire certs clean` followed by `aspire certs trust` to remove stale or corrupt certificates and regenerate trusted development certificates. If the `openssl` command isn’t installed, the fix suggestion also tells you to install it first. Note Environment checks time out after 30 seconds each or two minutes in aggregate, and installation discovery times out after 30 seconds. If a timeout occurs, the `aspire doctor` result includes a warning. The command displays results with clear status indicators: * ✅ (green) - Check passed * ⚠️ (yellow) - Warning (non-blocking issue) * ❌ (red) - Check failed (blocking issue) If any checks fail, the command provides suggestions for how to fix the issues and links to relevant documentation. ## Options [Section titled “Options”](#options) The following options are available: * **`--format `** Output format (Table or Json). Use `Json` for automation scenarios or when you need to parse the results programmatically. Defaults to `Table`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Run diagnostic checks on your development environment: Aspire CLI ```bash aspire doctor ``` * Run diagnostic checks with JSON output: Aspire CLI ```bash aspire doctor --format Json ``` ## Sample output [Section titled “Sample output”](#sample-output) When you run `aspire doctor` from a directory containing an AppHost project, you see output similar to the following: Aspire CLI ```bash Checking Aspire environment... Aspire Environment Check ======================== Aspire ✅ Aspire CLI version 13.6.0 AppHost ✅ AppHost version 13.6.0 (MyApp.AppHost.csproj) .NET SDK ✅ .NET 10.0.203 installed (arm64) Container Runtime ✅ Docker v28.5.1: running (auto-detected (default)) ← active Environment ✅ Operating system: macOS 15.5.0 ✅ HTTPS development certificate is trusted Summary: 6 passed, 0 warnings, 0 failed ``` After the summary, table output also includes an `Aspire CLI Installations` table that lists discovered CLI binaries with their path, version, channel, install route, and PATH status. When the CLI is out of date, the Aspire section shows a warning with the latest available version and a suggestion to run `aspire update`: Aspire CLI ```bash Aspire ⚠️ Aspire CLI version 13.6.0-dev is out of date. Latest version is 13.6.0-preview.1.26479.8 Run 'aspire update' to update Aspire CLI. AppHost ✅ AppHost version 13.6.0 (MyApp.AppHost.csproj) ``` This warning snippet is abbreviated. In complete table output, a summary follows the check results. When any warning or failure is present, Aspire also prints `For detailed prerequisites: https://aka.ms/aspire-prerequisites`. Some CLI and AppHost version messages include an inline `(channel: )` suffix; the same channel data appears in JSON metadata as `identityChannel`, `latestVersionChannel`, or `pinnedChannel` when available. On Linux, when `certutil` is not installed, the Environment section reports a warning instead of failing the check: Aspire CLI ```bash Environment ✅ Operating system: Linux Ubuntu 24.04 ⚠️ certutil is not available; browser certificate trust may be incomplete Install certutil from your distribution's NSS tools package (for example, libnss3-tools). ``` On Linux, when the OpenSSL development certificate cache is stale, missing the current certificate, or contains unreadable certificate files, the Environment section reports a warning with a suggestion to clean and re-trust the certificate: Aspire CLI ```bash Environment ✅ Operating system: Linux Ubuntu 24.04 ⚠️ OpenSSL HTTPS development certificate cache is missing the current certificate Run 'aspire certs clean' and then 'aspire certs trust' to remove stale or corrupt certificates and regenerate trusted development certificates. ``` When only Podman is running: Aspire CLI ```bash Container Runtime ✅ Podman v5.3.0: running (auto-detected (only runtime running)) ← active ❌ Docker is not installed ``` When you set `ASPIRE_CONTAINER_RUNTIME=podman`, Aspire honors the explicit configuration and Podman becomes active even when Docker is also running: Aspire CLI ```bash Container Runtime ✅ Podman v5.3.0: running (explicit configuration) ← active ✅ Docker v27.3.1: running (available) ``` The active runtime is annotated with `← active`. Other detected runtimes are shown with `(available)`. When VS Code is detected but the Aspire extension isn’t installed, the Development tools section reports a warning: Aspire CLI ```bash Development tools ⚠️ VS Code is installed, but the Aspire extension is not installed Install the Aspire extension from the VS Code Marketplace for an integrated Aspire experience. ``` ## Exit codes [Section titled “Exit codes”](#exit-codes) The command returns the following exit codes: | Exit code | Description | | --------- | ---------------------------------------- | | `0` | All checks passed (warnings are allowed) | | `1` | One or more checks failed | ## JSON output format [Section titled “JSON output format”](#json-output-format) When using the `--format Json` option, the output includes a structured response with all check results, a summary, and discovered Aspire CLI installations. The following example is abbreviated to focus on selected checks; actual output includes an entry for every check and can include additional metadata, such as `updateCommand`, `identityChannel`, `latestVersionChannel`, and `pinnedChannel`. JSON output ```json { "checks": [ { "category": "aspire", "name": "cli-version", "status": "pass", "message": "Aspire CLI version 13.6.0", "metadata": { "currentVersion": "13.6.0" } }, { "category": "apphost", "name": "apphost-version", "status": "pass", "message": "AppHost version 13.6.0 (MyApp.AppHost.csproj)", "metadata": { "appHostPath": "MyApp.AppHost.csproj", "version": "13.6.0" } }, { "category": "environment", "name": "operating-system", "status": "pass", "message": "Operating system: Linux Ubuntu 24.04", "metadata": { "osType": "Linux", "displayName": "Linux Ubuntu", "version": "24.04", "description": "Ubuntu 24.04.2 LTS" } }, { "category": "sdk", "name": "dotnet-sdk", "status": "pass", "message": ".NET 10.0.203 installed (arm64)" } ], "summary": { "passed": 6, "warnings": 0, "failed": 0 } } ``` When VS Code is detected, the checks include a `devtools` category entry named `vscode-extension`. It reports `"status": "warning"` when the [Aspire VS Code extension](https://aka.ms/aspire/vscode-extension) isn’t installed, and `"status": "pass"` when it is. Its `metadata` includes `vsCodeInstalled`, `extensionInstalled`, and `extensionId`: JSON output ```json { "category": "devtools", "name": "vscode-extension", "status": "warning", "message": "VS Code is installed, but the Aspire extension is not installed", "fix": "Install the Aspire extension from the VS Code Marketplace for an integrated Aspire experience.", "link": "https://aka.ms/aspire/vscode-extension", "metadata": { "vsCodeInstalled": true, "extensionInstalled": false, "extensionId": "microsoft-aspire.aspire-vscode" } } ``` This check is omitted entirely when VS Code isn’t detected on the machine. When the CLI is out of date, the `cli-version` check has `"status": "warning"` and the `metadata` includes the latest available version: JSON output ```json { "category": "aspire", "name": "cli-version", "status": "warning", "message": "Aspire CLI version 13.6.0-dev is out of date. Latest version is 13.6.0-preview.1.26479.8", "fix": "Run 'aspire update' to update Aspire CLI.", "metadata": { "currentVersion": "13.6.0-dev", "latestVersion": "13.6.0-preview.1.26479.8" } } ``` The `apphost-version` check is only present in the JSON output when an AppHost project is discovered in the current directory. The `operating-system` check is always present and includes the following metadata fields: | Field | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `osType` | The platform family: `Windows`, `macOS`, or `Linux`. | | `displayName` | A human-readable OS name, for example `Windows`, `macOS`, or `Linux Ubuntu`. | | `version` | The OS version string. On Linux this is the `VERSION_ID` from `/etc/os-release` when available; on Windows and macOS it is the value from `Environment.OSVersion`. | | `description` | A longer description of the OS. On Linux this is the `PRETTY_NAME` value from `/etc/os-release` (for example `Ubuntu 24.04.2 LTS`); on other platforms it is the runtime OS description string. | ## See also [Section titled “See also”](#see-also) * [aspire command](../aspire/) * [aspire run command](../aspire-run/) * [Aspire CLI overview](../../overview/) # aspire export command > Learn about the aspire export command and its usage. This command exports telemetry and resource data to a zip file. ## Name [Section titled “Name”](#name) `aspire export` - Export telemetry and resource data to a zip file. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire export [] [options] ``` ## Description [Section titled “Description”](#description) The `aspire export` command packages telemetry and resource data from a running AppHost into a zip file. Use it when you need to collect diagnostics for troubleshooting, share runtime state with a teammate, or preserve data from a running app for later analysis. Hidden resources are excluded from the export by default; use the `--include-hidden` option to include their data. When a resource name is provided, the export is limited to data for that resource. When executed without the `--apphost` option, the command: 1. Scans for all running AppHost processes. 2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to target. 3. If only one AppHost is running in scope, connects to it directly. 4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection. ## Arguments [Section titled “Arguments”](#arguments) * **``** Export data only for the specified resource. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`. * **`-o, --output `** The output file path for the export zip file. * **`--include-hidden`** Includes resources that are marked as hidden. By default, hidden resources are not shown. When a specific resource name is provided, hidden resources are always included regardless of this option. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Zip file contents [Section titled “Zip file contents”](#zip-file-contents) The exported zip archive (default name `aspire-export-.zip`) can contain up to four directories, depending on available data: * **`resources/`** — One JSON file per resource containing resource details such as name, type, state, endpoints, and environment variables. * **`consolelogs/`** — One plain-text `*.txt` file per resource with raw console output lines. * **`structuredlogs/`** — One JSON file per resource with structured log entries serialized in [OTLP format](https://opentelemetry.io/docs/specs/otlp/). * **`traces/`** — One JSON file per resource with distributed traces and spans serialized in [OTLP format](https://opentelemetry.io/docs/specs/otlp/). When a resource name is provided, only data for that resource is included in the archive. When no resource is specified, data for all visible resources is exported. Tip When analyzing an export, start with the `resources/` directory for an overview of resource state, then drill into `consolelogs/`, `structuredlogs/`, and `traces/` for detailed diagnostics. ## Examples [Section titled “Examples”](#examples) * Export diagnostics for the current AppHost: Aspire CLI ```bash aspire export ``` * Export data for a specific resource: Aspire CLI ```bash aspire export webfrontend ``` * Write the export to a specific file: Aspire CLI ```bash aspire export --output './artifacts/aspire-export.zip' ``` * Export data from a specific AppHost project: Aspire CLI ```bash aspire export --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' ``` * Export diagnostics including hidden resources: Aspire CLI ```bash aspire export --include-hidden ``` ## See also [Section titled “See also”](#see-also) * [aspire describe](../aspire-describe/) * [aspire logs](../aspire-logs/) * [aspire otel](../aspire-otel/) # aspire init command > Learn about the aspire init command and how it uses the aspireify agent skill to wire up Aspire support in an existing codebase. ## Name [Section titled “Name”](#name) `aspire init` - Initialize Aspire support in an existing codebase with a C# or TypeScript AppHost. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire init [options] ``` ## Description [Section titled “Description”](#description) The `aspire init` command initializes Aspire support in an existing repo or workspace. It scaffolds a minimal AppHost skeleton together with an `aspire.config.json`, then optionally installs the **`aspireify` agent skill** so your AI coding agent can complete the wiring. This command defaults to **interactive** mode. When executed without any options, the command prompts you for the AppHost language when more than one path is available. Note The `--source` and `--version` options are deprecated and no longer affect `aspire init`. They are accepted for backward compatibility but will be removed in a future release. ### AppHost detection [Section titled “AppHost detection”](#apphost-detection) The command adapts to the repo it finds: * **C# file-based AppHost** (when selected interactively) — creates `apphost.cs` with `#:sdk` and `#:package` directives for a lightweight single-file orchestrator. * **TypeScript AppHost** (when selected interactively) — creates `apphost.mts` with the generated `.aspire/modules/` folder. If the repo already has a root `package.json`, the AppHost is created as a nested `aspire-apphost/` package and the root `aspire.config.json` points to `aspire-apphost/apphost.mts`. Note When a `.sln` or `.slnx` is present, the C# option creates a **project-based AppHost** instead — an `AppHost.csproj` added to the solution with `ProjectReference` items and strongly-typed `AddProject()` calls. In all cases, the AppHost language does not limit what you can orchestrate — C#, JavaScript, Python, Go, Rust, Java, containers, and more can all be modeled in the same application model. ### Skipping solution discovery with —file-based [Section titled “Skipping solution discovery with —file-based”](#skipping-solution-discovery-with-file-based) Repositories can contain incidental `.sln` or `.slnx` files that aren’t meant to back the AppHost — they cause `aspire init` to prompt for a solution or scaffold a project-based AppHost even when you only want a minimal, file-based AppHost at the repository root. Pass `--file-based` to bypass .NET solution discovery entirely and always create the single-file `apphost.cs` scaffold in the current directory, regardless of any `.sln` or `.slnx` files present. `--file-based` requires C#. If another language is selected — explicitly with `--language`, through existing `aspire.config.json` configuration, or at the interactive language prompt — the command fails with an error before scaffolding or persisting the language selection. Omitting `--file-based` (or passing `--file-based false`) preserves normal initialization for all languages. Existing-file protection and agent skill setup are unaffected by this option. Aspire CLI ```bash aspire init --file-based --language csharp ``` ### Channel persistence in aspire.config.json [Section titled “Channel persistence in aspire.config.json”](#channel-persistence-in-aspireconfigjson) When `aspire init` runs with an explicit, non-stable channel (such as `daily` or `staging`), it writes a top-level `channel` key into the generated `aspire.config.json`. This ensures that subsequent commands — `aspire add`, `aspire update`, and others — resolve packages and templates against the same channel the project was initialized with, rather than falling back to the implicit stable default. For example, running a daily CLI build produces: aspire.config.json ```json { "appHost": { "path": "apphost.cs" }, "channel": "daily", "profiles": { "https": { "applicationUrl": "https://localhost:17055;http://localhost:15013", "environmentVariables": { "ASPIRE_DASHBOARD_OTLP_GRPC_ENDPOINT_URL": "https://localhost:16168", "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22043" } }, "http": { "applicationUrl": "http://localhost:15013", "environmentVariables": { "ASPIRE_DASHBOARD_OTLP_GRPC_ENDPOINT_URL": "http://localhost:19147", "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20216", "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true" } } } } ``` If `aspire.config.json` already contains a `channel` value (for example, because you edited it manually or migrated from an older project), the value is preserved and not overwritten. Only channels that are registered as *explicit* in the packaging service are persisted, with one exception: the `stable` channel is treated as the portable default and is intentionally not pinned. ### The aspireify skill [Section titled “The aspireify skill”](#the-aspireify-skill) After the skeleton is dropped, `aspire init` has an option to install the `aspireify` skill into your AI agent’s skill directory (the same directory used by `aspire agent init`). The skill is a Markdown file with instructions that guide your AI coding agent through completing the Aspire wiring for your specific codebase. The skill instructs the agent to: * Scan the repo and discovering existing projects, services, and containers * Ask you clarifying questions before making decisions — for example, which services to orchestrate, whether a hardcoded port is significant, or whether to map an existing env var or switch to Aspire’s service discovery * Wire resources into the AppHost with [`WithReference`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withreference "Injects a connection string as an environment variable from the source resource into the destination resource, using the source resource's name as the...")[`withReference`](/reference/api/typescript/aspire.hosting/withreference/ "Adds a reference to another resource"), [`WaitFor`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#waitfor "Waits for the dependency resource to enter the Running state before starting the resource.")[`waitFor`](/reference/api/typescript/aspire.hosting/waitfor/ "Waits for another resource to be ready"), endpoints, and volumes * Optionally configure OpenTelemetry * Validate the wiring with a smoke-test `aspire start` ## Options [Section titled “Options”](#options) The following options are available: * **`--language`** The AppHost language to scaffold (`csharp`, `typescript`). * **`--file-based`** Create `apphost.cs` in the current directory, skipping .NET solution discovery. Requires C#: fails with an error if another language is selected explicitly, via configuration, or at the language prompt. * **`--skill-locations `** Comma-separated list of skill locations to configure. Use `all` to configure all supported locations or `none` to skip skill location configuration. When not specified, the command prompts interactively. Useful for non-interactive mode in scripts and CI environments. For the list of available locations, see the [`aspire agent init` command reference](../aspire-agent-init/#options). * **`--skills `** Comma-separated list of skills to install. Use `all` to install all available skills or `none` to skip skill installation. When not specified, the command prompts interactively. Useful for non-interactive mode in scripts and CI environments. For the list of available skills, see the [`aspire agent init` command reference](../aspire-agent-init/#options). * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Initialize Aspire support in the current repo interactively: Aspire CLI ```bash aspire init ``` * Initialize Aspire support with a TypeScript AppHost: Aspire CLI ```bash aspire init --language typescript ``` * Initialize an empty C# AppHost at the repository root, ignoring any incidental `.sln` or `.slnx` files: Aspire CLI ```bash aspire init --file-based --language csharp ``` * Initialize Aspire support non-interactively without installing any agent skills: Aspire CLI ```bash aspire init --non-interactive --skills none ``` * Initialize Aspire support non-interactively, installing all skills in the standard location: Aspire CLI ```bash aspire init --non-interactive --language csharp --skill-locations standard --skills all ``` # aspire logs command > Learn about the aspire logs command and its usage. This command displays logs from resources in a running apphost. ## Name [Section titled “Name”](#name) `aspire logs` - Display logs from resources in a running apphost. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire logs [] [options] ``` ## Description [Section titled “Description”](#description) The `aspire logs` command displays console logs from resources in a running AppHost. You can view logs for all resources, filter to a specific resource, follow new log entries in real time, search log content with full-text filtering, and choose table or JSON output for automation. Hidden resources are excluded by default; use the `--include-hidden` option to show their logs. When executed without the `--apphost` option, the command: 1. Scans for all running AppHost processes. 2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to target. 3. If only one AppHost is running in scope, connects to it directly. 4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection. ## Arguments [Section titled “Arguments”](#arguments) * **``** The name of the resource to get logs for. If not specified, logs from all resources are shown. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`. * **`-f, --follow`** Stream logs in real time as they are written. * **`--format `** Output format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. * **`-n, --tail `** Number of lines to show from the end of the logs. * **`-s, --search `** Full-text search to filter log content. Only log lines whose message or resource name contains the specified text are shown. Multiple words are treated as separate fragments that must all match. Use quoted phrases to match exact multi-word text (for example, `--search '"connection timeout"'`). For more information, see [Search and filter](/reference/cli/search-filter/). * **`-t, --timestamps`** Show timestamps for each log line. * **`--include-hidden`** Includes resources that are marked as hidden. By default, hidden resources are not shown. When a specific resource name is provided, hidden resources are always included regardless of this option. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Show logs for all resources: Aspire CLI ```bash aspire logs ``` * Show logs for a specific resource: Aspire CLI ```bash aspire logs webfrontend ``` * Follow logs in real time: Aspire CLI ```bash aspire logs --follow ``` * Show the last 100 log lines with timestamps: Aspire CLI ```bash aspire logs apiservice --tail 100 --timestamps ``` * Output logs as JSON: Aspire CLI ```bash aspire logs --format Json ``` * Show logs including hidden resources: Aspire CLI ```bash aspire logs --include-hidden ``` * Filter logs by search text: Aspire CLI ```bash aspire logs --search "error" ``` * Search with multiple words (all must match): Aspire CLI ```bash aspire logs --search "connection failed" ``` * Search for an exact phrase using quotes: Aspire CLI ```bash aspire logs --search '"connection timeout"' ``` * Search logs for a specific resource and show only the last 75 matching lines: Aspire CLI ```bash aspire logs producer --search needle --tail 75 ``` ## See also [Section titled “See also”](#see-also) * [aspire describe](../aspire-describe/) * [aspire export](../aspire-export/) * [aspire otel](../aspire-otel/) # aspire ls command > Learn about the aspire ls command which discovers and lists AppHost project candidates in the current directory and its subdirectories. ## Name [Section titled “Name”](#name) `aspire ls` - List AppHost project candidates. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire ls [options] ``` ## Description [Section titled “Description”](#description) The `aspire ls` command discovers and lists [AppHost project](/get-started/app-host/) candidates in the current working directory and its subdirectories. It performs parallel discovery and reports results along with each candidate’s programming language and build status. The default output is a human-readable table with the following columns: | Column | Description | | ---------- | ---------------------------------------------------------------------------- | | `PATH` | The file path to the AppHost project | | `LANGUAGE` | The raw AppHost language ID, such as `csharp` or `typescript/nodejs` | | `STATUS` | Build status of the AppHost candidate: `buildable` or `possibly-unbuildable` | The `STATUS` value is `buildable` when the project validates as an AppHost candidate. It is `possibly-unbuildable` when the project looks like an AppHost but may not build in the current environment. ### Discovery and configuration [Section titled “Discovery and configuration”](#discovery-and-configuration) If a configuration file (for example `aspire.config.json` with `appHost.path` or a legacy `.aspire/settings.json` with `appHostPath`) points to an AppHost project, that path is included as a candidate. When a configured AppHost path points to a missing file, `aspire ls` displays a warning. When the configuration file is invalid JSON, has an invalid shape, or the configured AppHost path is empty, contains invalid characters, or isn’t a JSON string, `aspire ls` displays an error. When no configuration file is present, discovery continues silently. ### Output ordering [Section titled “Output ordering”](#output-ordering) **Non-streaming mode** (`--format json` without `--stream`): results are sorted by path before output. **Streaming mode** (`--format json --stream`): results are emitted in arrival order from parallel discovery and are **not sorted**. If you need a deterministic order for streamed output, pipe through a sort step. For example: Aspire CLI ```bash aspire ls --format json --stream | jq -s 'sort_by(.path)' ``` This example uses [jq](https://jqlang.org/), a third-party JSON processor. ## Options [Section titled “Options”](#options) The following options are available: * **`--format `** Output result format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. * **`--stream`** Output discovered AppHosts as newline-delimited JSON (NDJSON), emitting each candidate as soon as it is discovered. Requires `--format json`. * **`--all`** Include all candidate AppHosts by disabling Git filtering and the built-in skip list for common dependency, build-output, and tooling directories such as `bin`, `obj`, `node_modules`, `.venv`, `.git`, and `.vs`. This also includes AppHost snippet files under agent-skill directories, such as `.agents`, `.claude`, `.github/skills`, and `.opencode/skill`, which are excluded from default discovery because they’re code samples rather than runnable AppHosts. The NuGet package cache is still excluded. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * List all discovered AppHost candidates in table format: Aspire CLI ```bash aspire ls ``` Example output: Output ```text PATH LANGUAGE STATUS ./src/MyApp.AppHost/MyApp.AppHost.csproj csharp buildable ./src/OtherApp.AppHost/apphost.ts typescript/nodejs buildable ``` * Output discovered AppHosts as JSON for scripting: Aspire CLI ```bash aspire ls --format json ``` Example output: Output ```json [ { "path": "./src/MyApp.AppHost/MyApp.AppHost.csproj", "language": "csharp", "status": "buildable" }, { "path": "./src/OtherApp.AppHost/apphost.ts", "language": "typescript/nodejs", "status": "buildable" } ] ``` * Stream discovered AppHosts as newline-delimited JSON: Aspire CLI ```bash aspire ls --format json --stream ``` Example output (each line is a JSON object emitted as candidates are discovered; your line order may vary): Output ```text {"path":"./src/OtherApp.AppHost/apphost.ts","language":"typescript/nodejs","status":"buildable"} {"path":"./src/MyApp.AppHost/MyApp.AppHost.csproj","language":"csharp","status":"buildable"} ``` Note: lines are emitted in discovery arrival order and are not sorted. To sort streamed output by path: Aspire CLI ```bash aspire ls --format json --stream | jq -s 'sort_by(.path)' ``` * Include all AppHost candidates, ignoring `.gitignore` and directory filters: Aspire CLI ```bash aspire ls --all ``` ## See also [Section titled “See also”](#see-also) * [aspire run](/reference/cli/commands/aspire-run/) * [aspire ps](/reference/cli/commands/aspire-ps/) # aspire mcp command > Learn about the aspire mcp command and its usage. This command interacts with MCP tools exposed by Aspire resources. ## Name [Section titled “Name”](#name) `aspire mcp` - Interact with MCP tools exposed by Aspire resources. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire mcp [command] [options] ``` ## Description [Section titled “Description”](#description) The `aspire mcp` command lets you discover and call MCP (Model Context Protocol) tools exposed by resources in a running AppHost. Use it to inspect available tools and invoke them from the terminal. Note The `aspire mcp` command interacts with tools exposed by running resources. To start the MCP server used by compatible AI agents, use [`aspire agent mcp`](../aspire-agent-mcp/). ## Options [Section titled “Options”](#options) The following options are available: * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Commands [Section titled “Commands”](#commands) The following commands are available: | Command | Function | | ------------------------------------------ | -------------------------------------------- | | [`aspire mcp tools`](../aspire-mcp-tools/) | List MCP tools exposed by running resources. | | [`aspire mcp call`](../aspire-mcp-call/) | Call an MCP tool on a running resource. | ## Examples [Section titled “Examples”](#examples) * List MCP tools exposed by the current AppHost: Aspire CLI ```bash aspire mcp tools ``` * Call a tool on a running resource: Aspire CLI ```bash aspire mcp call myresource mytool ``` ## See also [Section titled “See also”](#see-also) * [aspire mcp tools](../aspire-mcp-tools/) * [aspire mcp call](../aspire-mcp-call/) * [aspire agent mcp](../aspire-agent-mcp/) # aspire mcp call command > Learn about the aspire mcp call command and its usage. This command calls an MCP tool on a running resource. ## Name [Section titled “Name”](#name) `aspire mcp call` - Call an MCP tool on a running resource. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire mcp call [options] ``` ## Description [Section titled “Description”](#description) The `aspire mcp call` command calls an MCP tool exposed by a resource in a running AppHost. Use `aspire mcp tools` first if you need to discover the available resources and tool names. When executed without the `--apphost` option, the command: 1. Scans for all running AppHost processes. 2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to target. 3. If only one AppHost is running in scope, connects to it directly. 4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection. ## Arguments [Section titled “Arguments”](#arguments) * **``** The name of the resource that exposes the MCP tool. * **``** The name of the MCP tool to call. ## Options [Section titled “Options”](#options) The following options are available: * **`-i, --input `** JSON input to pass to the tool. * **`--apphost `** The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Call a tool on a running resource: Aspire CLI ```bash aspire mcp call myresource mytool ``` * Pass JSON input to the tool call: Aspire CLI ```bash aspire mcp call myresource mytool --input '{"message":"hello"}' ``` * Target a specific AppHost project: Aspire CLI ```bash aspire mcp call myresource mytool --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' ``` ## See also [Section titled “See also”](#see-also) * [aspire mcp](../aspire-mcp/) * [aspire mcp tools](../aspire-mcp-tools/) # aspire mcp tools command > Learn about the aspire mcp tools command and its usage. This command lists MCP tools exposed by running resources. ## Name [Section titled “Name”](#name) `aspire mcp tools` - List MCP tools exposed by running resources. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire mcp tools [options] ``` ## Description [Section titled “Description”](#description) The `aspire mcp tools` command lists the MCP tools exposed by resources in a running AppHost. Use it to discover which resources expose tools and which tool names you can pass to `aspire mcp call`. When executed without the `--apphost` option, the command: 1. Scans for all running AppHost processes. 2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to target. 3. If only one AppHost is running in scope, connects to it directly. 4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`. * **`--format `** Output format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * List MCP tools for the current AppHost: Aspire CLI ```bash aspire mcp tools ``` * Output the tool list as JSON: Aspire CLI ```bash aspire mcp tools --format Json ``` * Target a specific AppHost project: Aspire CLI ```bash aspire mcp tools --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' ``` ## See also [Section titled “See also”](#see-also) * [aspire mcp](../aspire-mcp/) * [aspire mcp call](../aspire-mcp-call/) # aspire new command > Learn about the aspire new command and its usage. This command creates new Aspire projects or solutions. ## Name [Section titled “Name”](#name) `aspire new` - Create a new Aspire project or solution. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire new [command] [options] ``` ## Description [Section titled “Description”](#description) The `aspire new` command is the driver for creating Aspire projects, apps, or solutions, based on the Aspire templates. Each command specifies the template to use, and the options for the driver specify the options for the template. This command defaults to **interactive** mode. When executed without any options, the command prompts you for the project template and version, name, and output folder. When the `--name`, `--output`, and `--version` options are provided, the command runs **non-interactive** and generates files based on the command template. ### Default output directory [Section titled “Default output directory”](#default-output-directory) When you don’t provide `--output`, the default output directory is derived from the **template name**. For example, running `aspire new aspire-starter` without `--output` creates a directory named `./aspire-starter` in the current working directory. If that directory already exists and is non-empty, the command automatically appends a numeric suffix to find a unique name (for example, `./aspire-starter-2`, `./aspire-starter-3`, and so on). ### Output path validation [Section titled “Output path validation”](#output-path-validation) The `--output` option validates the provided path before creating the project: * Paths that contain **invalid characters** (such as null bytes) are rejected with an error. * Paths that point to an **existing non-empty directory** are rejected with a clear error message. Use a different output path or an empty directory. Note The `aspire new` command currently requires an interactive terminal even when all options are provided. The `--non-interactive` flag is not fully supported. In CI/CD pipelines or other non-interactive environments, use `dotnet new` with Aspire templates as an alternative for project creation. ## Interactive prompts [Section titled “Interactive prompts”](#interactive-prompts) When running `aspire new` in interactive mode, the command asks one or more questions before generating the project. The available prompts depend on the template and options you provide. ### Use \*.dev.localhost URLs? [Section titled “Use \*.dev.localhost URLs?”](#use-devlocalhost-urls) During project creation, you may be prompted: > **Use \*.dev.localhost URLs?** This prompt determines whether the generated launch profile configures your Aspire services to be accessible via `*.dev.localhost` wildcard subdomain URLs (for example, `https://myservice.dev.localhost`) instead of standard `http://localhost` with port numbers. #### What are \*.dev.localhost URLs? [Section titled “What are \*.dev.localhost URLs?”](#what-are-devlocalhost-urls) `*.dev.localhost` is a wildcard subdomain pattern that resolves to your local machine (`127.0.0.1` or `::1`) in most modern browsers without additional DNS configuration. This resolution is a browser feature — non-browser HTTP clients (for example, `curl`, `HttpClient`, or other command-line tools) don’t automatically resolve `*.dev.localhost` subdomains and may require **hosts** file entries to reach them. The Aspire developer certificate trusts `*.dev.localhost` subdomains, so browsers accept HTTPS connections to any subdomain when the certificate is trusted. #### Yes — use \*.dev.localhost URLs [Section titled “Yes — use \*.dev.localhost URLs”](#yes--use-devlocalhost-urls) Choosing **Yes** configures the generated project so that each service gets a unique subdomain URL such as `https://myservice.dev.localhost`. This option: * Enables HTTPS for all services from the start, leveraging the Aspire developer certificate. * Gives each service its own origin, which prevents cookie and authentication token collisions between services running on the same machine. * More closely mirrors a production setup where services are hosted on separate domains or subdomains. **Prerequisite:** The Aspire developer certificate must be trusted on your machine. If you haven’t already done so, run: Aspire CLI ```bash aspire certs trust ``` [Command reference: `aspire certs trust`](../aspire-certs-trust/) Note Safari on macOS does not resolve `*.dev.localhost` subdomains to `127.0.0.1` by default. If you use Safari, choose **No** or add entries to your **hosts** file (for example, `127.0.0.1 myservice.dev.localhost`). #### No — use standard localhost URLs (default) [Section titled “No — use standard localhost URLs (default)”](#no--use-standard-localhost-urls-default) Choosing **No** (the default) configures services with standard `http://localhost:` addresses. This option requires no certificate setup and works in all browsers and tools without additional configuration. ## Options [Section titled “Options”](#options) The following options are available: * **`-n, --name`** The name of the project to create. * **`-o, --output`** The output path for the project. * **`-s, --source`** The NuGet source to use for the project templates. * **`-v, --version`** The version of the project templates to use. * **`--channel`** Channel to use for templates (`stable`, `staging`, `daily`). If you don’t specify `--version`, `aspire new` selects a template package from the channel and prefers the version that matches the currently installed CLI/SDK. For explicit pre-release channels, such as `staging` and `daily`, it pins templates to the installed CLI/SDK version when the feed would otherwise select a newer pre-release package. For example, a `13.4` CLI using `--channel daily` won’t pull `13.5` preview templates even if the daily feed contains them. If you specify `--version`, that template version is used with the selected channel. When `--channel` is not specified, `aspire new` automatically uses the running CLI’s *identity channel* — the channel that matches the CLI build you have installed (for example, `daily` for a nightly build, `staging` for a release-candidate build, or a `pr-` channel for a pull-request build). This ensures that the correct package feed is used to resolve `Aspire.ProjectTemplates` without requiring an explicit flag. If the CLI’s identity does not match any registered explicit channel (for example, on a stable release or a locally-built CLI), `aspire new` falls back to ambient NuGet configuration (the implicit nuget.org channel). Requesting `--channel staging` explicitly only resolves on `stable` or `staging` Aspire CLI builds. Daily, local, and per-PR builds don’t have a deterministic staging feed, so they refuse the request with an error naming the running CLI’s identity and pointing at the recovery options: install a staging or stable Aspire CLI, or set [`overrideStagingFeed`](/reference/cli/configuration/#settings-surfaced-by-aspire-config) to point at the staging feed you want to use. * **`--suppress-agent-init`** Suppress the prompt to initialize MCP server configuration for agent environments after project creation. * **`--skill-locations `** Comma-separated list of skill locations to configure. Use `all` to configure all supported locations or `none` to skip skill location configuration. When not specified, the command prompts interactively. Useful for non-interactive mode in scripts and CI environments. For the list of available locations, see the [`aspire agent init` command reference](../aspire-agent-init/#options). * **`--skills `** Comma-separated list of skills to install. Use `all` to install all available skills or `none` to skip skill installation. When not specified, the command prompts interactively. Useful for non-interactive mode in scripts and CI environments. For the list of available skills, see the [`aspire agent init` command reference](../aspire-agent-init/#options). * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Commands [Section titled “Commands”](#commands) Each command represents a template. Pass the `--help` parameter to the template command to print the options available to the template. | Command | Template | | ---------------------- | --------------------------------- | | `aspire-starter` | Starter App (ASP.NET Core/Blazor) | | `aspire-ts-cs-starter` | Starter App (ASP.NET Core/React) | | `aspire-py-starter` | Starter App (FastAPI/React) | | `aspire-ts-starter` | Starter App (Express/React) | | `aspire-empty` | Empty (C# AppHost) | | `aspire-ts-empty` | Empty (TypeScript AppHost) | ### aspire-py-starter options [Section titled “aspire-py-starter options”](#aspire-py-starter-options) The `aspire-py-starter` template accepts the following additional options: * **`--use-redis-cache`** Scaffold the template with an optional Redis cache resource in the TypeScript AppHost. Accepts `true` or `false`. Defaults to prompting interactively. Aspire CLI ```bash aspire new aspire-py-starter --use-redis-cache true ``` ## Examples [Section titled “Examples”](#examples) * Create an Aspire solution from the template. Because the template was selected (`aspire-starter`), you’re prompted for the name, output folder, and template version. Aspire CLI ```bash aspire new aspire-starter ``` * Create an AppHost project named `aspireapp` from the **13.6.0** templates and place the output in a folder named `dev`. Aspire CLI ```bash aspire new aspire-empty --version 13.6.0 --name aspireapp --output ./dev ``` * Create an Aspire starter app using templates from the `daily` channel to get the latest pre-release templates. Aspire CLI ```bash aspire new aspire-starter --channel daily ``` * Create a new project non-interactively without installing any agent skills: Aspire CLI ```bash aspire new aspire-starter --name myapp --skills none --non-interactive ``` * Create a new project non-interactively and install all skills in all supported locations: Aspire CLI ```bash aspire new aspire-starter --name myapp --skill-locations all --skills all --non-interactive ``` ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### Language support not found [Section titled “Language support not found”](#language-support-not-found) When `aspire new` runs a template that requires code generation (for example, a TypeScript or Python AppHost template), it uses language support and code generator assemblies loaded by the apphost server. If those assemblies cannot load their types, the command may fail with an error such as: ```plaintext No language support found for: typescript/nodejs. Available languages: go, java, python, rust. ``` Or, when no language support implementations are discovered at all: ```plaintext No language support found for: typescript/nodejs. No language support implementations were discovered in any loaded assembly. This usually indicates a binary mismatch between the bundled apphost server and the integration assemblies on disk; check the apphost server log for 'LoaderExceptions' Warnings. ``` These errors mean the integration assemblies on disk are not compatible with the bundled apphost server. This typically happens after a partial NuGet cache update, a version skew between the CLI and the integration packages, or an interrupted restore. **To resolve:** 1. Clear the Aspire CLI cache to remove stale cached assemblies: Aspire CLI ```bash aspire cache clear ``` 2. Re-run `aspire new` to trigger a fresh restore of the integration packages. If the error persists, check the apphost server log for `Warning` entries that include `LoaderExceptions` or mention a shared assembly version mismatch (for example, `Aspire.TypeSystem` bundled version vs. the version on disk). These log entries name the offending assembly and describe the mismatch, making it easier to identify which package version is out of sync. Tip Run `aspire new` with `--log-level Debug` (or `--log-level Trace`) to write a detailed log file. Open the log and search for `LoaderExceptions` or `version mismatch` to identify the conflicting assembly. # aspire otel command > Learn about the aspire otel command and its usage. This command is used to view OpenTelemetry data (logs, spans, traces) from a running apphost. ## Name [Section titled “Name”](#name) `aspire otel` - View OpenTelemetry data (logs, spans, traces) from a running apphost. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire otel [command] [options] ``` ## Description [Section titled “Description”](#description) The `aspire otel` command provides subcommands for viewing OpenTelemetry data collected by the Aspire Dashboard from a running AppHost. You can view structured logs, distributed trace spans, and trace summaries directly from the terminal. The data is retrieved from the Dashboard’s telemetry API. By default, the subcommands discover a running AppHost and connect automatically. You can also use `--dashboard-url` to connect to a standalone dashboard directly — paste the full login URL (for example, `http://localhost:18888/login?t=`) and the browser token is automatically exchanged for an API key. ## Options [Section titled “Options”](#options) The following options are available: * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Commands [Section titled “Commands”](#commands) The following commands are available: | Command | Function | | ---------------------------------------------- | ------------------------------------------------------ | | [`aspire otel logs`](../aspire-otel-logs/) | View structured logs from the Dashboard telemetry API. | | [`aspire otel spans`](../aspire-otel-spans/) | View spans from the Dashboard telemetry API. | | [`aspire otel traces`](../aspire-otel-traces/) | View traces from the Dashboard telemetry API. | ## See also [Section titled “See also”](#see-also) * [aspire otel logs command](../aspire-otel-logs/) * [aspire otel spans command](../aspire-otel-spans/) * [aspire otel traces command](../aspire-otel-traces/) # aspire otel logs command > Learn about the aspire otel logs command and its usage. This command views structured logs from the Dashboard telemetry API. ## Name [Section titled “Name”](#name) `aspire otel logs` - View structured logs from the Dashboard telemetry API. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire otel logs [resource] [options] ``` ## Description [Section titled “Description”](#description) The `aspire otel logs` command retrieves and displays structured logs collected by the Aspire Dashboard. You can filter logs by resource name, trace ID, severity level, or a full-text search expression. Use `--follow` to stream logs in real-time as they arrive. ## Arguments [Section titled “Arguments”](#arguments) * **`[resource]`** Filter by resource name. When specified, only logs from the matching resource are shown. Supports both exact instance names and base resource names (which match all replicas). ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost project file. Mutually exclusive with `--dashboard-url`. * **`--dashboard-url `** The URL of a standalone Aspire Dashboard to query instead of discovering one from an AppHost. Accepts a base URL (for example, `http://localhost:18888`) or a full login URL including a browser token (for example, `http://localhost:18888/login?t=`). When a login URL is provided, the token is automatically exchanged for an API key. Mutually exclusive with `--apphost`. * **`--api-key `** The API key used to authenticate with the dashboard’s Telemetry API. Only required when `--dashboard-url` is specified and the dashboard is configured with `ApiKey` authentication and no login URL is provided. * **`-f, --follow`** Stream telemetry in real-time as it arrives. * **`--format `** Output format (Table or Json). * **`-n, --limit `** Maximum number of items to return. * **`--trace-id `** Filter by trace ID. * **`--severity `** Filter logs by minimum severity (Trace, Debug, Information, Warning, Error, Critical). * **`--search `** Full-text search across log text fields, such as log messages, attribute values, scope, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers. For more information, see [Search and filter](/reference/cli/search-filter/). | Syntax | Meaning | | ------------------------------------------------------------------- | --------------------------------------------------- | | `word` | Free-text fragment — matches any searchable field | | `"quoted phrase"` | Single fragment containing spaces | | `field:value` | Field qualifier — value must match the named field | | `-field:value` | Negated qualifier — excludes matches | | `field:>value` / `field:>=value` / `field:`** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * View all structured logs: Aspire CLI ```bash aspire otel logs ``` * View logs for a specific resource: Aspire CLI ```bash aspire otel logs apiservice ``` * Stream logs in real-time: Aspire CLI ```bash aspire otel logs --follow ``` * View only error-level logs in JSON format: Aspire CLI ```bash aspire otel logs --severity Error --format Json ``` * View the last 50 logs for a resource: Aspire CLI ```bash aspire otel logs apiservice --limit 50 ``` * Search logs by message text: Aspire CLI ```bash aspire otel logs --search "connection refused" ``` * Search logs by scope and severity: Aspire CLI ```bash aspire otel logs --search "scope:Microsoft.EntityFrameworkCore severity:Warning" ``` * Filter logs by timestamp: Aspire CLI ```bash aspire otel logs --search "timestamp:>=2026-06-01T12:00:00 severity:error" ``` * View logs from a standalone dashboard using the login URL (token is automatically exchanged for an API key): Aspire CLI ```bash aspire otel logs --dashboard-url "http://localhost:18888/login?t=" ``` * View logs from a secured standalone Aspire Dashboard: Aspire CLI ```bash aspire otel logs --dashboard-url "http://localhost:18888" --api-key "" ``` ## See also [Section titled “See also”](#see-also) * [aspire otel command](../aspire-otel/) * [aspire otel spans command](../aspire-otel-spans/) * [aspire otel traces command](../aspire-otel-traces/) # aspire otel spans command > Learn about the aspire otel spans command and its usage. This command views spans from the Dashboard telemetry API. ## Name [Section titled “Name”](#name) `aspire otel spans` - View spans from the Dashboard telemetry API. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire otel spans [resource] [options] ``` ## Description [Section titled “Description”](#description) The `aspire otel spans` command retrieves and displays distributed trace spans collected by the Aspire Dashboard. Spans represent individual units of work within a distributed trace, such as HTTP requests or database calls. You can filter spans by resource name, trace ID, error status, or a full-text search expression. Use `--follow` to stream spans in real-time as they arrive. ## Arguments [Section titled “Arguments”](#arguments) * **`[resource]`** Filter by resource name. When specified, only spans from the matching resource are shown. Supports both exact instance names and base resource names (which match all replicas). ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost project file. Mutually exclusive with `--dashboard-url`. * **`--dashboard-url `** The URL of a standalone Aspire Dashboard to query instead of discovering one from an AppHost. Accepts a base URL (for example, `http://localhost:18888`) or a full login URL including a browser token (for example, `http://localhost:18888/login?t=`). When a login URL is provided, the token is automatically exchanged for an API key. Mutually exclusive with `--apphost`. * **`--api-key `** The API key used to authenticate with the dashboard’s Telemetry API. Only required when `--dashboard-url` is specified and the dashboard is configured with `ApiKey` authentication and no login URL is provided. * **`-f, --follow`** Stream telemetry in real-time as it arrives. * **`--format `** Output format (Table or Json). * **`-n, --limit `** Maximum number of items to return. * **`--trace-id `** Filter by trace ID. * **`--has-error `** Filter by error status (true to show only errors, false to exclude errors). * **`--search `** Full-text search across span text fields, such as names, attribute values, source, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers. For more information, see [Search and filter](/reference/cli/search-filter/). | Syntax | Meaning | | ------------------------------------------------------------------- | ---------------------------------------------------------- | | `word` | Free-text fragment — matches any searchable field | | `"quoted phrase"` | Single fragment containing spaces | | `field:value` | Field qualifier — value must match the named field | | `-field:value` | Negated qualifier — excludes matches | | `field:>value` / `field:>=value` / `field:`** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * View all spans: Aspire CLI ```bash aspire otel spans ``` * View spans for a specific resource: Aspire CLI ```bash aspire otel spans apiservice ``` * Stream spans in real-time: Aspire CLI ```bash aspire otel spans --follow ``` * View only error spans: Aspire CLI ```bash aspire otel spans --has-error true ``` * View spans for a specific trace in JSON format: Aspire CLI ```bash aspire otel spans --trace-id abc123 --format Json ``` * Search spans by text: Aspire CLI ```bash aspire otel spans --search "/api/orders" ``` * Filter spans by attribute value: Aspire CLI ```bash aspire otel spans --search=@db.system:postgresql ``` * Filter spans by timestamp: Aspire CLI ```bash aspire otel spans --search "timestamp:>=2026-03-01T08:30:00 kind:server" ``` * View spans from a standalone dashboard using the login URL (token is automatically exchanged for an API key): Aspire CLI ```bash aspire otel spans --dashboard-url "http://localhost:18888/login?t=" ``` * View spans from a secured standalone Aspire Dashboard: Aspire CLI ```bash aspire otel spans --dashboard-url "http://localhost:18888" --api-key "" ``` ## See also [Section titled “See also”](#see-also) * [aspire otel command](../aspire-otel/) * [aspire otel logs command](../aspire-otel-logs/) * [aspire otel traces command](../aspire-otel-traces/) # aspire otel traces command > Learn about the aspire otel traces command and its usage. This command views traces from the Dashboard telemetry API. ## Name [Section titled “Name”](#name) `aspire otel traces` - View traces from the Dashboard telemetry API. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire otel traces [resource] [options] ``` ## Description [Section titled “Description”](#description) The `aspire otel traces` command retrieves and displays distributed traces collected by the Aspire Dashboard. A trace represents a complete request as it flows through your distributed application. The command shows trace summaries including timestamp, name, span count, duration, and status. You can view a summary of all traces, or provide a specific trace ID with `--trace-id` to view a detailed span tree for that trace. Use `--search` to filter traces by a full-text search expression. ## Arguments [Section titled “Arguments”](#arguments) * **`[resource]`** Filter by resource name. When specified, only traces involving the matching resource are shown. Supports both exact instance names and base resource names (which match all replicas). ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost project file. Mutually exclusive with `--dashboard-url`. * **`--dashboard-url `** The URL of a standalone Aspire Dashboard to query instead of discovering one from an AppHost. Accepts a base URL (for example, `http://localhost:18888`) or a full login URL including a browser token (for example, `http://localhost:18888/login?t=`). When a login URL is provided, the token is automatically exchanged for an API key. Mutually exclusive with `--apphost`. * **`--api-key `** The API key used to authenticate with the dashboard’s Telemetry API. Only required when `--dashboard-url` is specified and the dashboard is configured with `ApiKey` authentication and no login URL is provided. * **`--format `** Output format (Table or Json). * **`-n, --limit `** Maximum number of items to return. * **`-t, --trace-id `** Filter by trace ID. When specified, displays a detailed span tree for the given trace instead of a summary list. * **`--has-error `** Filter by error status (true to show only errors, false to exclude errors). * **`--search `** Full-text search across trace and span text fields, such as names, attribute values, source, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers. For more information, see [Search and filter](/reference/cli/search-filter/). | Syntax | Meaning | | ------------------------------------------------------------------- | ---------------------------------------------------------- | | `word` | Free-text fragment — matches any searchable field | | `"quoted phrase"` | Single fragment containing spaces | | `field:value` | Field qualifier — value must match the named field | | `-field:value` | Negated qualifier — excludes matches | | `field:>value` / `field:>=value` / `field:`** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * View all traces: Aspire CLI ```bash aspire otel traces ``` * View traces for a specific resource: Aspire CLI ```bash aspire otel traces apiservice ``` * View a specific trace detail: Aspire CLI ```bash aspire otel traces --trace-id abc123 ``` * View only traces with errors: Aspire CLI ```bash aspire otel traces --has-error true ``` * View the last 20 traces in JSON format: Aspire CLI ```bash aspire otel traces --limit 20 --format Json ``` * Search traces by text: Aspire CLI ```bash aspire otel traces --search "checkout" ``` * Filter traces by attribute on any constituent span: Aspire CLI ```bash aspire otel traces --search=@http.status_code:500 ``` * Filter traces by timestamp: Aspire CLI ```bash aspire otel traces --search "timestamp:>2026-01-15T09:30:00 status:error" ``` * View traces from a standalone dashboard using the login URL (token is automatically exchanged for an API key): Aspire CLI ```bash aspire otel traces --dashboard-url "http://localhost:18888/login?t=" ``` * View traces from a secured standalone Aspire Dashboard: Aspire CLI ```bash aspire otel traces --dashboard-url "http://localhost:18888" --api-key "" ``` ## See also [Section titled “See also”](#see-also) * [aspire otel command](../aspire-otel/) * [aspire otel logs command](../aspire-otel-logs/) * [aspire otel spans command](../aspire-otel-spans/) # aspire ps command > Learn about the aspire ps command which lists all running Aspire AppHost processes with their process IDs and dashboard URLs. ## Name [Section titled “Name”](#name) `aspire ps` - List running Aspire AppHosts. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire ps [options] ``` ## Description [Section titled “Description”](#description) The `aspire ps` command lists all running Aspire AppHost processes. The output includes the AppHost project path, process IDs, and dashboard URLs for each running instance. The command scans for running AppHosts by checking the backchannel connections in the `~/.aspire/backchannels/` directory. This approach is fast because it doesn’t need to recursively search for project files. `aspire ps` provides AppHost-level information. Use `--follow` to continuously stream AppHost lifecycle updates. To inspect per-resource details or stream resource state changes within a specific AppHost, use [`aspire describe --follow`](/reference/cli/commands/aspire-describe/). The default output is a human-readable table with the following columns: | Column | Description | | ----------- | -------------------------------------------------- | | `PATH` | The file path to the AppHost project | | `SDK` | The Aspire SDK version used by the AppHost | | `PID` | The process ID of the running AppHost | | `CLI_PID` | The process ID of the CLI that started the AppHost | | `DASHBOARD` | The dashboard URL with login token | Note Log file paths are not shown in the table output. Use `aspire ps --format Json` to retrieve log file paths programmatically. In-scope AppHosts (those within the current directory) are displayed first, followed by out-of-scope AppHosts. Before listing, `aspire ps` also detects and stops any orphaned AppHosts whose launching CLI process has died (for example, after a crash or a hard kill) so the output reflects only AppHosts that are actually running. This cleanup is best effort: if it fails for a given AppHost, `aspire ps` still proceeds with listing the rest. ## Options [Section titled “Options”](#options) The following options are available: * **`-f, --follow`** Continuously stream AppHost lifecycle updates. Requires `--format Json`. Output is emitted as one compact JSON object per line in [Newline Delimited JSON (NDJSON)](https://github.com/ndjson/ndjson-spec) format whenever an AppHost starts, stops, or changes state. Each line follows the same schema as a single AppHost entry from snapshot JSON output, plus a `status` field (`running` or `stopped`). * **`--format `** Output result format. Use `Json` for machine-readable output suitable for scripting and automation. The JSON output includes an array of AppHost objects with `appHostPath`, `appHostPid`, `cliPid`, `logFilePath`, and `dashboardUrl` properties. The `logFilePath` field is `null` when no log path is available. Defaults to `Table`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * List all running AppHosts in table format: Aspire CLI ```bash aspire ps ``` Example output: Output ```text PATH SDK PID CLI_PID DASHBOARD ./src/MyApp.AppHost/MyApp.AppHost.csproj 13.6.0 12345 12340 https://localhost:17244/login?t=abc123 /home/user/other/OtherApp.AppHost.csproj 13.6.0 67890 67885 https://localhost:17250/login?t=def456 ``` * Output running AppHosts as JSON for scripting: Aspire CLI ```bash aspire ps --format Json ``` Example output: Output ```json [ { "appHostPath": "./src/MyApp.AppHost/MyApp.AppHost.csproj", "appHostPid": 12345, "cliPid": 12340, "logFilePath": "~/.aspire/logs/cli_20260516T123456_abc12345.log", "dashboardUrl": "https://localhost:17244/login?t=abc123" } ] ``` The `logFilePath` property is `null` when no log path is available for the AppHost. * Stream AppHost lifecycle updates as NDJSON and pipe to `jq`: Aspire CLI ```bash aspire ps --follow --format Json | jq -c '{ appHostPath, status }' ``` ## See also [Section titled “See also”](#see-also) * [aspire run](/reference/cli/commands/aspire-run/) * [aspire stop](/reference/cli/commands/aspire-stop/) * [aspire describe](/reference/cli/commands/aspire-describe/) # aspire publish command > Learn about the aspire publish command and its usage. This command invokes resource publishers declared by the apphost to serialize resources to disk. ## Name [Section titled “Name”](#name) `aspire publish` - Generates deployment artifacts for an Aspire AppHost project. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire publish [options] [[--] ...] ``` ## Description [Section titled “Description”](#description) The `aspire publish` command publishes resources by serializing them to disk. When this command is run, Aspire executes publishing pipeline steps that have been registered in the app model (for example, by environment resources). These steps serialize resources so that they can be consumed by deployment tools. The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. The command performs the following steps to run an Aspire AppHost: * Creates or updates the rooted `aspire.config.json` file and records the selected AppHost there. Legacy `.aspire/settings.json` files are still read during migration. * Installs or verifies that Aspire’s local hosting certificates are installed and trusted. * Builds the AppHost project and its resources. * Starts the AppHost and its resources. * Executes all publishing pipeline steps registered in the app model. ## Pipeline summary output [Section titled “Pipeline summary output”](#pipeline-summary-output) After the pipeline finishes, `aspire publish` prints a result summary and a step-by-step breakdown. The summary shows how many steps succeeded, the total pipeline duration, and a `Steps Summary:` table. The `Steps Summary:` table lists pipeline steps in their execution hierarchy. Top-level steps appear at the left edge of the step-name column, and child steps are indented under their parent steps. Each row includes the step duration, final status, step name, and, when the terminal is wide enough, a timeline bar that shows when the step started and finished relative to the whole pipeline. Output ```text ------------------------------------------------------------ ✅ 5/5 steps succeeded • Total time: 0.43s Steps Summary: Step timeline: 0s 0.41s │───────┬──────┬─────┬───────│ 0.57ms ✓ validate-compute-environments │╴ │ 0.16ms ✓ before-start │╴ │ 0.41s ✓ pipeline-execution │╶──────────────────────────╴│ 0.41s ✓ custom-publish-prereq │╶──────────────────────────╴│ 0.55ms ✓ publish │ ╴│ ✅ Pipeline succeeded ------------------------------------------------------------ ``` The `Step timeline:` header shows the start and end of the overall pipeline duration. The ruler divides that duration into equal intervals, and each step row uses a bar to show the step’s relative start and end times. Very short steps can appear as a single point marker (`╴`). If the terminal isn’t wide enough to preserve readable step names, Aspire omits the timeline columns and keeps the hierarchical step list. ## Options [Section titled “Options”](#options) The following options are available: * **`--`** Delimits arguments to `aspire publish` from arguments for the AppHost. All arguments after this delimiter are passed to the AppHost. * **`--apphost `** The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`. * **`-o, --output-path`** The output path for the generated artifacts. Defaults to the AppHost directory’s `aspire-output` folder if not specified. * **`--pipeline-log-level`** Set the minimum log level for pipeline logging. Valid values are: `trace`, `debug`, `information`, `warning`, `error`, `critical`. The default is `information`. * **`-e, --environment`** The environment to use for the operation. The default is `Production`. * **`--include-exception-details`** Include exception details (stack traces) in pipeline logs. * **`--list-steps`** List the pipeline steps that would be executed, without running them. Useful for inspecting what a pipeline command will do before invoking it for real. * **`--no-build`** Don’t build or restore the AppHost project before running the command. Use this when you’ve already built the AppHost (for example, in a CI step) and want to skip the implicit build. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Search the current directory structure for AppHost projects to build and publish: Aspire CLI ```bash aspire publish ``` * Publish a specific AppHost project: Aspire CLI ```bash aspire publish --apphost './projects/apphost/orchestration.AppHost.csproj' ``` * Publish a specific AppHost project with arguments: Aspire CLI ```bash aspire publish --apphost './projects/apphost/orchestration.AppHost.csproj' -- -fast ``` # aspire resource command > Learn about the aspire resource command and its usage. This command executes a command on a resource in a running apphost. ## Name [Section titled “Name”](#name) `aspire resource` - Execute a command on a resource. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire resource [command-options] [options] aspire resource -- [command-options] ``` ## Description [Section titled “Description”](#description) The `aspire resource` command executes a command exposed by a resource in a running AppHost. Use it to trigger actions such as `start`, `stop`, or `restart` without opening the dashboard. The available command names depend on the selected resource. If a resource doesn’t expose the command you specify, Aspire returns an error. Note `aspire resource` doesn’t expose a fixed set of CLI subcommands in `--help`. Instead, `` is a positional argument whose valid values come from the selected resource at runtime. This is why the CLI reference documents `aspire resource` as a single command page instead of separate pages such as `aspire resource start`. ### Command arguments as named options [Section titled “Command arguments as named options”](#command-arguments-as-named-options) When a resource command defines arguments, those arguments are passed as **named options** on the command line. Named options make it easier to supply only the arguments you need, skip optional ones, and pass values in any order. To see what arguments a specific command accepts, use the command-specific `--help` flag: Aspire CLI ```bash aspire resource --help ``` The help output lists each argument with its type, whether it’s required, its default value (if any), and the set of allowed values for choice arguments. For example: ```console Echo a message with text, number, boolean, choice, and secret command arguments. Usage: aspire resource [command-options] [options] aspire resource -- [command-options] Command options: --message Text value to echo. Required. --repeat How many times to echo the message. Default: 1. --shout Uppercase the echoed message. Default: false. --flavor The message flavor. Allowed values: vanilla, chocolate, strawberry. Default: vanilla. --secret Secret text command argument. The command only returns its length. Options: --apphost The path to the Aspire AppHost file or a directory to search -?, -h, --help Show help and usage information ``` #### Handling option name collisions [Section titled “Handling option name collisions”](#handling-option-name-collisions) If a command argument name conflicts with an Aspire CLI option (such as `--apphost`), use `--` to separate Aspire CLI options from command-specific options: Aspire CLI ```bash aspire resource --apphost './MyApp.AppHost.cs' -- --apphost myvalue ``` Everything after `--` is treated as command argument options and is not parsed as Aspire CLI flags. ### Discovering available resource commands [Section titled “Discovering available resource commands”](#discovering-available-resource-commands) Running `aspire resource --help` with a specific resource name queries the running AppHost and appends an **Available resource commands** section to the help output. This lets you discover what commands a resource supports without opening the dashboard. Example output ```text Available resource commands: restart Restart the resource. start Start the resource. stop Stop the resource. ``` If no single in-scope AppHost can be determined without an explicit `--apphost`, the resource-scoped help is shown without the commands section rather than prompting for AppHost selection. To pass `--help` as an argument to the resource command itself (rather than as a CLI help flag), separate it with `--`: Aspire CLI ```bash aspire resource myresource mycommand -- --help ``` ### AppHost selection [Section titled “AppHost selection”](#apphost-selection) When executed without the `--apphost` option, the command: 1. Scans for all running AppHost processes. 2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to target. 3. If only one AppHost is running in scope, connects to it directly. 4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection. ## Arguments [Section titled “Arguments”](#arguments) * **``** The name of the resource to execute the command on. * **``** The name of the resource command to execute, such as `start`, `stop`, `restart`, `set-parameter`, or `delete-parameter`. ## Built-in parameter commands [Section titled “Built-in parameter commands”](#built-in-parameter-commands) Aspire provides two built-in resource commands for managing parameter resources at runtime. These commands accept named options and can be used non-interactively (for example, in scripts or automation). The examples in this section assume an AppHost parameter resource named `mydb-password`; for details on defining parameter resources, see [External parameters](/fundamentals/external-parameters/). Boolean options for these commands require an explicit `true` or `false` value. For example, `--save-to-user-secrets true` requests saving the value to user secrets. * **`set-parameter`** — Set the value of a parameter resource. The legacy name `parameter-set` is also accepted. | Option | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `--value ` | Required. The value to assign to the parameter. | | `--save-to-user-secrets [true\|false]` | Optional. Save the value to the .NET user secrets store in addition to the running AppHost. Defaults to preserving any existing saved state. | Aspire CLI ```bash aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword" aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword" --save-to-user-secrets true ``` * **`delete-parameter`** — Delete the current value of a parameter resource. The legacy name `parameter-delete` is also accepted. | Option | Description | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `--delete-from-user-secrets [true\|false]` | Optional. Also remove the value from the .NET user secrets store. The value is removed only when this option is supplied with `true`. | Aspire CLI ```bash aspire resource mydb-password delete-parameter aspire resource mydb-password delete-parameter --delete-from-user-secrets true ``` To see the current options for a parameter command, use command-specific help: Aspire CLI ```bash aspire resource mydb-password set-parameter --help ``` Note The canonical command names changed in Aspire 13.4. `parameter-set` was renamed to `set-parameter` and `parameter-delete` was renamed to `delete-parameter`. The old names are accepted as aliases and continue to work. ### Azure resource location command [Section titled “Azure resource location command”](#azure-resource-location-command) Locally provisioned Azure resources also expose a `change-location` command for moving an existing resource to a different Azure region. Some Azure resource types are location-immutable, so changing their location requires Aspire to delete and recreate the live resource — which can permanently lose any data it holds. Pass `--confirm-delete true` to acknowledge this before Aspire proceeds: Aspire CLI ```bash aspire resource my-storage change-location --location westus2 --confirm-delete true ``` Without `--confirm-delete true`, the command fails before any deletion, override persistence, reset, or reprovisioning occurs. For details, see [Change a resource’s Azure location](/integrations/cloud/azure/local-provisioning/#change-a-resources-azure-location). ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost file or a directory to search. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`--include-hidden`** Includes resource commands that are marked as hidden. By default, hidden commands are not shown in help output or executed. Use this option to expose and run commands that are intentionally hidden from the default command listing. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Restart a resource in the current AppHost: Aspire CLI ```bash aspire resource cache restart ``` * Stop a specific resource: Aspire CLI ```bash aspire resource worker stop ``` * Target a specific AppHost file: Aspire CLI ```bash # C# AppHost aspire resource api restart --apphost './apphost.cs' # TypeScript AppHost aspire resource api restart --apphost './apphost.mts' ``` * List available commands for a specific resource: Aspire CLI ```bash # C# AppHost aspire resource myapi --help --apphost './apphost.cs' # TypeScript AppHost aspire resource myapi --help --apphost './apphost.mts' ``` * Include hidden commands when listing available commands: Aspire CLI ```bash # C# AppHost aspire resource myapi --help --include-hidden --apphost './apphost.cs' # TypeScript AppHost aspire resource myapi --help --include-hidden --apphost './apphost.mts' ``` * Show command-specific help for a resource command with arguments: Aspire CLI ```bash aspire resource my-resource echo-message --help ``` * Execute a resource command with named arguments: Aspire CLI ```bash aspire resource my-resource echo-message --message "hello" --repeat 3 --shout true ``` * Supply only some optional command arguments (skipping others): Aspire CLI ```bash aspire resource my-resource echo-message --message "hello" --flavor chocolate ``` * Use `--` to avoid conflict with an Aspire CLI option named `--apphost`: Aspire CLI ```bash aspire resource my-resource custom-cmd --apphost './apphost.mts' -- --apphost myvalue ``` ## See also [Section titled “See also”](#see-also) * [aspire describe](../aspire-describe/) * [aspire logs](../aspire-logs/) * [aspire wait](../aspire-wait/) # aspire resources command > Learn about the aspire resources command alias and migrate to the primary aspire describe command. ## Name [Section titled “Name”](#name) `aspire resources` - Alias for `aspire describe`. ## Description [Section titled “Description”](#description) Command renamed `aspire resources` is a backward-compatible alias. Use [`aspire describe`](/reference/cli/commands/aspire-describe/) as the primary command name. The `aspire resources` command was renamed to `aspire describe`. Existing scripts that use `aspire resources` continue to work. The `--watch` flag was also renamed to `--follow` (`-f`). Use `aspire describe --follow` for continuous updates. ## See also [Section titled “See also”](#see-also) * [aspire describe command](/reference/cli/commands/aspire-describe/) # aspire restore command > Learn about the aspire restore command and its usage. This command restores dependencies and generates SDK code for an apphost. ## Name [Section titled “Name”](#name) `aspire restore` - Restore dependencies and generate SDK code for an apphost. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire restore [options] ``` ## Description [Section titled “Description”](#description) The `aspire restore` command restores the AppHost and generates the SDK code that Aspire uses for resources, integrations, and tooling. Use it when you want to make restore an explicit step in automation or validate that the AppHost can restore cleanly without starting it. For TypeScript AppHosts, restore reads the `packages` section in `aspire.config.json`, restores those hosting integration packages, and regenerates the `.aspire/modules/` TypeScript SDK imported by `apphost.mts`. This is useful after running `aspire add`, switching branches, updating pinned package versions, or restoring dependencies in CI before `aspire run`, `aspire publish`, or deployment workflows. The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. This command is useful in CI/CD pipelines, after adding or updating integrations, or before running build, publish, and deployment workflows. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Restore the AppHost discovered from the current directory: Aspire CLI ```bash aspire restore ``` * Restore a specific AppHost project: Aspire CLI ```bash aspire restore --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' ``` * Restore a specific TypeScript AppHost and regenerate `.aspire/modules/`: Aspire CLI ```bash aspire restore --apphost './apphost.mts' ``` ## See also [Section titled “See also”](#see-also) * [aspire run](../aspire-run/) * [aspire start](../aspire-start/) * [aspire publish](../aspire-publish/) # aspire run command > Learn about the aspire run command, which builds and runs an Aspire AppHost project locally and streams logs and telemetry to your terminal. ## Name [Section titled “Name”](#name) `aspire run` - Run an Aspire AppHost in development mode. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire run [options] [[--] ...] ``` ## Description [Section titled “Description”](#description) The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the AppHost, launches the web dashboard, and prints a list of endpoints. The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. The command performs the following steps to run an Aspire AppHost: * Creates or updates the rooted `aspire.config.json` file and records the selected AppHost there. Legacy `.aspire/settings.json` files are still read during migration. * Installs or verifies that Aspire’s local hosting certificates are installed and trusted. * Builds the AppHost project and its resources. * Starts the AppHost and its resources. * Starts the dashboard. ## Stopping the AppHost [Section titled “Stopping the AppHost”](#stopping-the-apphost) To stop the running AppHost and exit, press ⌃+C`⌃+C`Control + C`CtrlC`Control + C`CtrlC` (or send `SIGTERM` on Linux/macOS). The shutdown follows a three-step sequence. If shutdown takes longer than a moment, a `🛑 Stopping Aspire.` message is displayed shortly after you press ⌃+C`⌃+C`Control + C`CtrlC`Control + C`CtrlC` to confirm that shutdown is in progress. 1. **Cooperative cancellation** — The CLI requests that the AppHost stop gracefully. 2. **Graceful wait** — The CLI waits for the AppHost process to exit cleanly on its own. 3. **Automatic force-kill** — If the AppHost does not exit within the graceful timeout, the CLI terminates the process automatically. If graceful shutdown is taking too long and you need to exit immediately, press ⌃+C`⌃+C`Control + C`CtrlC`Control + C`CtrlC` a second time. This collapses the graceful window and starts the force-kill sequence immediately. Note On Windows, TypeScript/JavaScript AppHosts started with `tsx` or `npm` run in an isolated console session so that the Ctrl+C signal is delivered correctly to the Node.js process rather than to an unrelated foreground window. ## Configuring the startup timeout [Section titled “Configuring the startup timeout”](#configuring-the-startup-timeout) `aspire run` uses a default timeout of 120 seconds when connecting to the AppHost after preparation completes. If this connection takes longer—for example on a slow machine or in a CI environment—set the `ASPIRE_CLI_START_TIMEOUT` environment variable to a higher number of seconds: Aspire CLI ```bash export ASPIRE_CLI_START_TIMEOUT=300 aspire run ``` If `ASPIRE_CLI_START_TIMEOUT` is set to a value that isn’t a positive whole number of seconds, `aspire run` displays an error and exits without starting the AppHost. This behavior also applies to `aspire run --detach` and to `aspire start`. `ASPIRE_CLI_START_TIMEOUT` excludes AppHost preparation, including restore and build, guest dependency installation and pre-execution checks, and extension-owned builds. For file-based C# AppHosts, the required safety build performed even with `--no-build` is also excluded. Once preparation completes, the CLI has the full configured timeout to connect to the AppHost. `ASPIRE_CLI_START_TIMEOUT` controls how long `aspire run` and `aspire start` wait for the AppHost to start. It’s separate from `aspire wait --timeout`, which controls how long `aspire wait` waits for an individual *resource* inside an already-running AppHost to reach a target status. ## Hot Reload and watch behavior [Section titled “Hot Reload and watch behavior”](#hot-reload-and-watch-behavior) By default, `aspire run` starts the distributed application once. It doesn’t watch the AppHost or resource source files. After you change AppHost code, stop the running AppHost with ⌃+C`⌃+C`Control + C`CtrlC`Control + C`CtrlC`, and then run `aspire run` again. For individual resource changes, keep the AppHost running and restart or rebuild the resource from the Aspire CLI or dashboard when needed. Aspire also has an opt-in `defaultWatchEnabled` feature flag. When enabled, Aspire uses watch mode by default and automatically restarts the Aspire application after file changes: Aspire CLI ```bash aspire config set features.defaultWatchEnabled true ``` Use Aspire watch mode when you want Aspire to restart the AppHost-managed application for you after AppHost changes. It supports both C# and TypeScript AppHosts; C# project resources are also controlled by this setting today. Other resource hot reload behavior depends on the framework or runtime backing the resource. For more information, see [Hot Reload and watch](/app-host/hot-reload-and-watch/). The following snippet is an example of the output displayed by the `aspire run` command: Aspire CLI ```bash Dashboard: https://localhost:17244/login?t=9db79f2885dae24ee06c6ef10290b8b2 Logs: /home/vscode/.aspire/cli/logs/apphost-5932-2025-08-25-18-37-31.log Press CTRL+C to stop the apphost and exit. ``` ## Options [Section titled “Options”](#options) The following options are available: * **`--`** Delimits arguments to `aspire run` from arguments for the AppHost being run. All arguments after this delimiter are passed to the AppHost run. * **`--detach`** Run the AppHost in the background and exit after it starts. The AppHost continues running as a background process. Use `aspire ps` to list running AppHosts and `aspire stop` to stop them. * **`--format `** Output result format. Only valid when used with `--detach`. Use `Json` for machine-readable output suitable for scripting and automation. * **`--isolated`** Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously. This is useful for parallel testing or comparing different configurations side-by-side. * **`--no-build`** Do not build or restore the project before running. Use this option when you have already built the project and want to skip the build step for faster startup. * **`--apphost `** The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Search the current directory structure for AppHost projects to build and run: Aspire CLI ```bash aspire run ``` * Run a specific AppHost project: Aspire CLI ```bash aspire run --apphost './projects/apphost/orchestration.AppHost.csproj' ``` * Run a specific AppHost project with arguments: Aspire CLI ```bash aspire run --apphost './projects/apphost/orchestration.AppHost.csproj' -- -fast ``` * Run the AppHost in the background: Aspire CLI ```bash aspire run --detach ``` * Run the AppHost in the background with JSON output: Aspire CLI ```bash aspire run --detach --format Json ``` * Run in isolated mode for parallel testing: Aspire CLI ```bash aspire run --isolated ``` * Skip building and run immediately: Aspire CLI ```bash aspire run --no-build ``` # aspire secret command > Learn about the aspire secret command and its usage. This command is used to manage user secrets for an Aspire AppHost. ## Name [Section titled “Name”](#name) `aspire secret` - Manage AppHost user secrets. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire secret [command] [options] ``` ## Description [Section titled “Description”](#description) The `aspire secret` command manages user secrets for an Aspire AppHost project. User secrets provide a safe way to store sensitive configuration values—such as passwords, API keys, and connection strings—outside of your project files during local development. Aspire uses user secrets to persist values that resources need across restarts, such as auto-generated passwords for database containers. When you add a persistent resource that requires a password, Aspire automatically initializes user secrets for the AppHost and saves the generated password. On subsequent runs, the saved password is reused so that the resource retains its state. The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost project file. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Commands [Section titled “Commands”](#commands) The following commands are available: | Command | Function | | ---------------------------------------------------------- | --------------------------- | | [`aspire secret set `](../aspire-secret-set/) | Set a secret value. | | [`aspire secret get `](../aspire-secret-get/) | Get a secret value. | | [`aspire secret list`](../aspire-secret-list/) | List all secrets. | | [`aspire secret delete `](../aspire-secret-delete/) | Delete a secret. | | [`aspire secret path`](../aspire-secret-path/) | Show the secrets file path. | ## Examples [Section titled “Examples”](#examples) * Set a secret value for the current AppHost: Aspire CLI ```bash aspire secret set Parameters:postgres-password MySecretPassword123 ``` * List all secrets for a specific AppHost: Aspire CLI ```bash aspire secret list --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj ``` * Get the value of a specific secret: Aspire CLI ```bash aspire secret get Parameters:postgres-password ``` * Show the path to the secrets file: Aspire CLI ```bash aspire secret path ``` # aspire secret delete command > Learn about the aspire secret delete command and its usage. This command deletes a user secret for an Aspire AppHost. ## Name [Section titled “Name”](#name) `aspire secret delete` - Delete a secret. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire secret delete [options] ``` ## Description [Section titled “Description”](#description) The `aspire secret delete` command deletes a user secret from the secrets store for an Aspire AppHost. The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. The command returns the following exit codes: * `0`—The command succeeded. * `3`—Failed to find the AppHost project. * `4`—The specified secret key was not found. ## Arguments [Section titled “Arguments”](#arguments) The following arguments are available: * **`key`** The secret key to delete. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost project file. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Delete a secret: Aspire CLI ```bash aspire secret delete Parameters:postgres-password ``` * Delete a secret for a specific AppHost: Aspire CLI ```bash aspire secret delete Parameters:rabbitmq-password --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj ``` # aspire secret get command > Learn about the aspire secret get command and its usage. This command retrieves a user secret value for an Aspire AppHost. ## Name [Section titled “Name”](#name) `aspire secret get` - Get a secret value. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire secret get [options] ``` ## Description [Section titled “Description”](#description) The `aspire secret get` command retrieves a user secret value for an Aspire AppHost. The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. The command returns the following exit codes: * `0`—The command succeeded. * `3`—Failed to find the AppHost project. * `4`—The specified secret key was not found. ## Arguments [Section titled “Arguments”](#arguments) The following arguments are available: * **`key`** The secret key to retrieve. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost project file. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Get the value of a password parameter: Aspire CLI ```bash aspire secret get Parameters:postgres-password ``` * Get a secret for a specific AppHost: Aspire CLI ```bash aspire secret get Parameters:rabbitmq-password --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj ``` # aspire secret list command > Learn about the aspire secret list command and its usage. This command lists all user secrets for an Aspire AppHost. ## Name [Section titled “Name”](#name) `aspire secret list` - List all secrets. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire secret list [options] ``` ## Description [Section titled “Description”](#description) The `aspire secret list` command lists all user secrets stored for an Aspire AppHost. By default, secrets are displayed in a table format sorted alphabetically by key. If no secrets are configured, the command displays “No secrets configured.” The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. ## Options [Section titled “Options”](#options) The following options are available: * **`--format `** Output format. Use `Json` for machine-readable output suitable for scripting and automation. Defaults to `Table`. * **`--apphost `** The path to the Aspire AppHost project file. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * List all secrets for the current AppHost: Aspire CLI ```bash aspire secret list ``` * List secrets in JSON format: Aspire CLI ```bash aspire secret list --format json ``` * List secrets for a specific AppHost: Aspire CLI ```bash aspire secret list --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj ``` # aspire secret path command > Learn about the aspire secret path command and its usage. This command shows the file path where user secrets are stored for an Aspire AppHost. ## Name [Section titled “Name”](#name) `aspire secret path` - Show the secrets file path. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire secret path [options] ``` ## Description [Section titled “Description”](#description) The `aspire secret path` command displays the full file path to the user secrets file for an Aspire AppHost. This is useful when you need to directly inspect or edit the secrets file, or when troubleshooting secrets resolution. The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost project file. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Show the secrets file path for the current AppHost: Aspire CLI ```bash aspire secret path ``` * Show the secrets file path for a specific AppHost: Aspire CLI ```bash aspire secret path --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj ``` # aspire secret set command > Learn about the aspire secret set command and its usage. This command sets a user secret value for an Aspire AppHost. ## Name [Section titled “Name”](#name) `aspire secret set` - Set a secret value. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire secret set [options] ``` ## Description [Section titled “Description”](#description) The `aspire secret set` command sets a user secret value for an Aspire AppHost. If user secrets haven’t been initialized for the AppHost yet, this command automatically initializes them before setting the value. The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. ## Arguments [Section titled “Arguments”](#arguments) The following arguments are available: * **`key`** The secret key to set. Use a colon (`:`) as a separator for hierarchical keys, such as `Parameters:postgres-password`. * **`value`** The secret value to set. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost project file. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Set a password parameter: Aspire CLI ```bash aspire secret set Parameters:postgres-password MySecretPassword123 ``` * Set a secret for a specific AppHost: Aspire CLI ```bash aspire secret set Parameters:rabbitmq-password Pass123 --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj ``` # aspire start command > Learn about the aspire start command and its usage. This command starts an AppHost in the background. ## Name [Section titled “Name”](#name) `aspire start` - Start an AppHost in the background. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire start [options] [[--] ...] ``` ## Description [Section titled “Description”](#description) The `aspire start` command starts an AppHost in the background and exits after the AppHost reaches a stable running state. Use it when you want a detached AppHost that you can inspect later with commands such as `aspire ps`, `aspire describe`, `aspire logs`, and `aspire stop`. The Aspire CLI uses the following logic, in order, to determine which AppHost project to process: * The `--apphost` option. This option specifies the path to the Aspire AppHost project file to process. * The rooted `aspire.config.json` file. If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration. * Searches the current directory and subdirectories. Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects. Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it. You can output detached startup details as a table or JSON, and you can pass additional arguments through to the AppHost by using the `--` delimiter. ### Startup readiness and failure diagnostics [Section titled “Startup readiness and failure diagnostics”](#startup-readiness-and-failure-diagnostics) `aspire start` waits for the AppHost to report that it has reached a stable running state before detaching. This means that early startup failures — such as TypeScript syntax errors in a non-C# AppHost or C# compile errors in a .NET AppHost — are surfaced in the parent terminal instead of being silently lost in the background. When the AppHost fails to start, `aspire start` displays a curated excerpt of the startup output that filters out noise such as package install logs and highlights the relevant error messages: Aspire CLI ```bash Starting Aspire AppHost in the background... ❌ Failed to start the AppHost. ℹ️ Recent AppHost startup output: apphost.ts(1,15): error TS1109: Expression expected. ❌ AppHost process exited with code 2. 📄 See logs at ``` For a .NET AppHost with a compile error, the output includes the relevant build diagnostics: Aspire CLI ```bash Starting Aspire AppHost in the background... ❌ Failed to start the AppHost. ℹ️ Recent AppHost startup output: Determining projects to restore... All projects are up-to-date for restore. /work/MyAppHost/Program.cs(3,41): error CS1002: ; expected [/work/MyAppHost/MyAppHost.csproj] Build FAILED. 0 Warning(s) 1 Error(s) ❌ AppHost failed to build. 📄 See logs at ``` The parent log also captures the replayed child output under `DetachedAppHost/...` log categories so the log file is self-contained. Pressing ⌃+C`⌃+C`Control + C`CtrlC`Control + C`CtrlC` while `aspire start` is waiting for the AppHost to start will terminate the startup process. ### Configuring the startup timeout [Section titled “Configuring the startup timeout”](#configuring-the-startup-timeout) `ASPIRE_CLI_START_TIMEOUT` configures the startup waits used by `aspire start`. The default is 120 seconds. To allow more time for startup after preparation completes, set the environment variable to a higher number of seconds: Aspire CLI ```powershell $env:ASPIRE_CLI_START_TIMEOUT = "300" aspire start ``` If `ASPIRE_CLI_START_TIMEOUT` is set to a value that isn’t a positive whole number of seconds, `aspire start` displays an error and exits without starting the AppHost. This behavior also applies to `aspire run`, including `aspire run --detach`. `ASPIRE_CLI_START_TIMEOUT` excludes AppHost preparation, including restore and build, guest dependency installation and pre-execution checks, and extension-owned builds. This also excludes the safety build required for file-based C# AppHosts even with `--no-build`. The child process starts its connection timeout after preparation completes; the detached launcher starts its separate readiness timeout when the AppHost’s backchannel connection appears. ## Hot Reload and watch behavior [Section titled “Hot Reload and watch behavior”](#hot-reload-and-watch-behavior) By default, `aspire start` starts the AppHost as a detached background process. It doesn’t watch the AppHost or resource source files. After you change AppHost code, restart the detached AppHost by running `aspire start` again. For individual resource changes, keep the AppHost running and restart or rebuild the resource from the Aspire CLI or dashboard when needed. Aspire also has an opt-in `defaultWatchEnabled` feature flag. When enabled, Aspire uses watch mode by default and automatically restarts the Aspire application after file changes: Aspire CLI ```bash aspire config set features.defaultWatchEnabled true ``` Use Aspire watch mode when you want Aspire to restart the AppHost-managed application for you after AppHost changes. It supports both C# and TypeScript AppHosts; C# project resources are also controlled by this setting today. Other resource hot reload behavior depends on the framework or runtime backing the resource. For more information, see [Hot Reload and watch](/app-host/hot-reload-and-watch/). ## Options [Section titled “Options”](#options) The following options are available: * **`--`** Delimits arguments to `aspire start` from arguments for the AppHost being run. All arguments after this delimiter are passed to the application. * **`--no-build`** Do not build or restore the project before running. Use this option when you have already built the project and want to skip the restore and build step. * **`--apphost `** The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`. * **`--format `** Output format for detached AppHost results. Use `Json` for machine-readable output suitable for scripting and automation. * **`--isolated`** Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Start the AppHost discovered from the current directory: Aspire CLI ```bash aspire start ``` * Start a specific AppHost in the background: Aspire CLI ```bash aspire start --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' ``` * Output detached startup details as JSON: Aspire CLI ```bash aspire start --format Json ``` * Start the AppHost in isolated mode: Aspire CLI ```bash aspire start --isolated ``` * Start the AppHost with a specific environment: Aspire CLI ```bash aspire start --environment Development ``` ## See also [Section titled “See also”](#see-also) * [aspire run](../aspire-run/) * [aspire ps](../aspire-ps/) * [aspire logs](../aspire-logs/) * [aspire stop](../aspire-stop/) # aspire stop command > Learn about the aspire stop command, which gracefully stops a running Aspire AppHost process so resources are torn down in the correct order. ## Name [Section titled “Name”](#name) `aspire stop` - Stop a running Aspire AppHost. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire stop [options] ``` ## Description [Section titled “Description”](#description) The `aspire stop` command stops a running Aspire AppHost process. When no options are provided, the command scans for running AppHosts and stops the in-scope AppHost directly, or prompts you to choose one when multiple AppHosts are available. When executed without the `--apphost` option, the command: 1. Scans for all running AppHost processes. 2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to stop. 3. If only one AppHost is running in scope, stops it directly. 4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection. The command requests a graceful shutdown of the selected AppHost process (and its process tree), coordinating a clean shutdown of the AppHost, dashboard, and non-persistent containers and processes. Resources configured with a [persistent lifetime](/app-host/resource-lifetimes/#persistent-lifetime) remain available for later runs. ### Stopping a detached AppHost [Section titled “Stopping a detached AppHost”](#stopping-a-detached-apphost) When stopping an AppHost that was started with [`aspire run --detach`](/reference/cli/commands/aspire-run/#options), the `aspire stop` command waits for the AppHost process to terminate before removing its backchannel socket file. Removing the socket prevents subsequent CLI commands, such as `aspire add` or `aspire describe`, from attempting to connect to the stopped process. ### Clean up persistent resources [Section titled “Clean up persistent resources”](#clean-up-persistent-resources) Use `--force` to stop the selected AppHost and then remove the persistent resources associated with it: Aspire CLI ```bash aspire stop --force ``` The command performs the normal stop flow first, then removes persistent resources associated with the AppHost. The command attempts to clean up persistent resources whether or not an instance of the AppHost is running. Persistent resources started using a version of the Aspire CLI released before `--force` support was added can’t be cleaned up using `--force`. By default, `--force` preserves persistent volumes so that data survives cleanup. Caution The `--force` option permanently removes the selected AppHost’s persistent resource instances without an additional confirmation prompt. Data stored only in those resources can be lost. For container resources, use a [volume or bind mount](/fundamentals/persist-data-volumes/) to persist data independently of a specific resource’s lifetime. Additional notes and limitations: * You can’t combine `--force` with `--all`; cleaning up persistent resources is only supported when stopping instances of a specific AppHost. * AppHost instances and associated persistent resources are resolved based on the AppHost path. If you remove or rename an AppHost after it creates persistent resources, the command won’t associate previously created persistent resources with the AppHost at its new path. In that case, either run `aspire stop --force` before renaming the AppHost or manually clean up the associated persistent resources. * For a .NET AppHost that doesn’t use the Aspire CLI bundle, cleanup requires Aspire.Hosting 13.5 or later. If the AppHost uses an older version, its version can’t be determined, or its project can’t be inspected, the command displays a warning and still attempts cleanup. Resources created without the required workload metadata might remain. * If the AppHost stops successfully, but persistent resource cleanup fails, the command exits with an error but leaves the AppHost stopped. You can resolve any errors and run `aspire stop --force` again or manually clean up any remaining persistent resources if necessary. ### Also remove persistent volumes [Section titled “Also remove persistent volumes”](#also-remove-persistent-volumes) By default, `aspire stop --force` preserves any [persistent volumes](/fundamentals/persist-data-volumes/) created for the AppHost, so their data survives cleanup. Pass `--volumes` together with `--force` to also remove those volumes: Aspire CLI ```bash aspire stop --force --volumes ``` `--volumes` requires `--force`; using `--volumes` without `--force` fails with an error. Only named volumes that Aspire created and tracks ownership of are removed. Anonymous volumes and bind mounts aren’t targeted by `--volumes`, but anonymous volumes associated with a persistent container may be removed when `--force` removes that container. A volume that existed before the AppHost started is adopted for mounting but isn’t recorded as Aspire-owned, so cleanup leaves it intact. Caution Removing persistent volumes permanently deletes their data. There’s no additional confirmation prompt before deletion. For a non-bundle .NET AppHost older than Aspire.Hosting 13.6, the CLI can’t determine whether the AppHost created the volume-ownership records required for cleanup and displays a compatibility warning before still attempting cleanup. Before scanning for AppHosts to stop, `aspire stop` also detects and cleans up any orphaned AppHosts whose launching CLI process has died, so leaked processes are removed even if a normal stop can’t reach one of them. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost project file. When specified, the command stops only the AppHost running from that AppHost project without prompting for selection. * **`--all`** Stop all running AppHosts without prompting for selection. You can’t combine this option with `--force`. * **`--force`** Perform the normal attempt to stop all instances of a specific AppHost, then attempt to clean up persistent resources associated with that AppHost, preserving persistent volumes by default. You can combine this option with `--apphost` to specify an AppHost to stop, but not with `--all`. * **`--volumes`** Also remove persistent volumes created by Aspire during persistent resource cleanup. Requires `--force`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Stop the AppHost running in the current directory scope: Aspire CLI ```bash aspire stop ``` * Stop a specific AppHost project: Aspire CLI ```bash aspire stop --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' ``` * Stop all running AppHosts: Aspire CLI ```bash aspire stop --all ``` * Stop the AppHost and clean up its persistent resources, preserving volumes: Aspire CLI ```bash aspire stop --force ``` * Stop the AppHost and remove its persistent resources, including persistent volumes: Aspire CLI ```bash aspire stop --force --volumes ``` * Stop any running instances and clean up persistent resources for a specific AppHost when the target AppHost might be ambiguous: Aspire CLI ```bash aspire stop --force --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj' ``` ## See also [Section titled “See also”](#see-also) * [aspire run](/reference/cli/commands/aspire-run/) * [aspire ps](/reference/cli/commands/aspire-ps/) # aspire terminal command > Use aspire terminal to list and attach to interactive resource terminals, or play tape files to automate shell and REPL checks. ## Name [Section titled “Name”](#name) `aspire terminal` - Manage interactive terminal sessions for resources. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire terminal [command] [options] ``` ## Description [Section titled “Description”](#description) The `aspire terminal` command provides subcommands for working with interactive terminal sessions exposed by resources that were registered using [`WithTerminal()`](/app-host/with-terminal/) in the AppHost. You can list which resources have a terminal, attach your local terminal to a running session, or automate input and output checks with a tape file. The connected AppHost must advertise the `terminals.v1` capability (Aspire.Hosting 13.4 or later). Against an older AppHost the subcommands report that terminals are not supported. Experimental tape playback in Aspire 13.6 The `tape play` subcommand requires Aspire CLI 13.6 or later. This requirement doesn’t apply to the existing `ps` and `attach` commands. ## Options [Section titled “Options”](#options) The following options are available: * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Commands [Section titled “Commands”](#commands) The following commands are available: | Command | Function | | ------------------------------------------------------ | -------------------------------------------------------------- | | [`aspire terminal attach`](../aspire-terminal-attach/) | Attach the local terminal to a resource’s interactive session. | | [`aspire terminal ps`](../aspire-terminal-ps/) | List interactive terminal sessions in the connected AppHost. | | [`aspire terminal tape`](../aspire-terminal-tape/) | Automate an existing resource terminal with a tape file. | ## See also [Section titled “See also”](#see-also) * [Test TUI and shell apps using WithTerminal](/app-host/with-terminal/) * [aspire terminal attach command](../aspire-terminal-attach/) * [aspire terminal ps command](../aspire-terminal-ps/) * [aspire terminal tape play command](../aspire-terminal-tape-play/) * [Automate resource terminals with tape files](/dashboard/terminal-tape-playback/) * [Dashboard terminals](/dashboard/terminals/) # aspire terminal attach command > Learn about the aspire terminal attach command, which connects your local terminal to a resource's interactive PTY session exposed using WithTerminal. ## Name [Section titled “Name”](#name) `aspire terminal attach` - Attach the local terminal to an interactive PTY session for a resource. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire terminal attach [options] ``` ## Description [Section titled “Description”](#description) The `aspire terminal attach` command connects your local terminal to the interactive pseudo-terminal (PTY) session of a resource that was registered with [`WithTerminal()`](/app-host/with-terminal/). Once attached, you interact with the resource’s terminal, as if it were running directly in your console. For example, you can drive its TUI or type into its shell. The command discovers the running AppHost, verifies it supports the `terminals.v1` capability, looks up the resource, and connects to one of its terminal replicas. When the resource has a single replica, that replica is selected automatically. When it has more than one, you’re prompted to choose one—or you can pass `--replica`. Multiple peers can attach to the same session at once. By default, `attach` takes the **primary** role and drives the terminal’s dimensions. Pass `--viewer` to join as a passive **viewer** instead. This technique is useful when another peer, such as the dashboard, is currently driving the session. While attached, the following hotkeys are available: | Hotkey | Action | | ---------- | ----------------------------------------- | | `Ctrl+B D` | Detach from the session and exit cleanly. | | `Ctrl+B T` | Take control (request the primary role). | If the selected replica has already exited, the command attaches to the historical output buffer; no live input is sent. ## Arguments [Section titled “Arguments”](#arguments) The following arguments are available: * **``** The name of the resource to attach a terminal to. The resource must have been registered with `.WithTerminal()`. ## Options [Section titled “Options”](#options) The following options are available: * **`--apphost `** The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`. * **`-r, --replica `** The 0-based replica index to attach to. Required when the resource has more than one replica and the CLI is not running interactively. * **`--viewer`** Connect as a viewer (secondary) instead of taking primary control. Viewers see the terminal output but do not drive its dimensions. This option is useful when another peer (for example, the dashboard) is currently driving the session. Take control later with `Ctrl+B T`. * **`-?, -h, --help`** Prints help and usage documentation for the available commands and options. * **`-l, --log-level `** Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs. * **`--non-interactive`** Run the command in non-interactive mode, disabling all interactive prompts and spinners. * **`--nologo`** Suppress the startup banner and telemetry notice. * **`--banner`** Display the animated Aspire CLI welcome banner. * **`--wait-for-debugger`** Wait for a debugger to attach before running a command. ## Examples [Section titled “Examples”](#examples) * Attach to a resource’s terminal: Aspire CLI ```bash aspire terminal attach agent ``` * Attach to a specific replica of a multi-replica resource: Aspire CLI ```bash aspire terminal attach agent --replica 1 ``` * Join an existing session as a passive viewer: Aspire CLI ```bash aspire terminal attach agent --viewer ``` ## See also [Section titled “See also”](#see-also) * [Test TUI and shell apps using WithTerminal](/app-host/with-terminal/) * [aspire terminal command](../aspire-terminal/) * [aspire terminal ps command](../aspire-terminal-ps/) * [aspire terminal tape play command](../aspire-terminal-tape-play/) * [Automate resource terminals with tape files](/dashboard/terminal-tape-playback/) * [Dashboard terminals](/dashboard/terminals/) # aspire terminal ps command > Learn about the aspire terminal ps command, which lists every WithTerminal-enabled resource in the connected AppHost with grid size, attached peers, and per-replica health. ## Name [Section titled “Name”](#name) `aspire terminal ps` - List interactive terminal sessions in the connected AppHost. ## Synopsis [Section titled “Synopsis”](#synopsis) Aspire CLI ```bash aspire terminal ps [options] ``` ## Description [Section titled “Description”](#description) The `aspire terminal ps` command lists every resource in the connected AppHost that was registered using [`WithTerminal()`](/app-host/with-terminal/). For each terminal it reports the current grid size, the number of attached peers, and per-replica health so you can see what’s available before running [`aspire terminal attach`](/reference/cli/commands/aspire-terminal-attach/). Resources whose terminal host isn’t reachable are still listed with a status that indicates they’re unavailable, rather than being silently dropped. The connected AppHost must advertise the `terminals.v1` capability (Aspire.Hosting 13.4 or later). The default output is a human-readable table with the following columns: | Column | Description | | ---------- | ------------------------------------------------------------------------- | | `Resource` | The display name of the terminal-enabled resource. | | `Replica` | The 0-based replica index (one row per replica). | | `Status` | Whether the replica is `alive`, `exited (

)`, or `host unreachable`. |
| `Size`     | The current terminal grid size (`columns`x`rows`).                        |
| `Peers`    | The number of peers currently attached to the replica.                    |
| `Restarts` | The number of times the replica’s terminal host has restarted.            |

## Options

[Section titled “Options”](#options)

The following options are available:

* **`--apphost `**

  The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`.

* **`--format `**

  Output format. `text` (default) renders a table; `json` emits structured output for scripting. The JSON output is an array of terminal entries with `resourceName`, `displayName`, `configuredColumns`, `configuredRows`, `isHostReachable`, and a `replicas` array. Each replica includes `replicaIndex`, `isAlive`, `exitCode`, `producerConnected`, `restartCount`, `currentColumns`, `currentRows`, and `attachedPeerCount`. When `--verbose` is set, each replica also includes a `peers` array of `{ peerId, displayName }`.

* **`-v, --verbose`**

  Include per-peer details for every attached viewer (peer id and display name).

* **`-?, -h, --help`**

  Prints help and usage documentation for the available commands and options.

* **`-l, --log-level `**

  Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.

* **`--non-interactive`**

  Run the command in non-interactive mode, disabling all interactive prompts and spinners.

* **`--nologo`**

  Suppress the startup banner and telemetry notice.

* **`--banner`**

  Display the animated Aspire CLI welcome banner.

* **`--wait-for-debugger`**

  Wait for a debugger to attach before running a command.

## Examples

[Section titled “Examples”](#examples)

* List terminal sessions in the running AppHost:

  Aspire CLI

  ```bash
  aspire terminal ps
  ```

  Example output:

  Output

  ```text
  Resource  Replica  Status  Size    Peers  Restarts
  agent     0        alive   120x30  1      0
  ```

* Include per-peer details:

  Aspire CLI

  ```bash
  aspire terminal ps --verbose
  ```

* Emit JSON for scripting and pipe to `jq`:

  Aspire CLI

  ```bash
  aspire terminal ps --format json | jq -c '.[] | { resourceName, isHostReachable }'
  ```

## See also

[Section titled “See also”](#see-also)

* [Test TUI and shell apps using WithTerminal](/app-host/with-terminal/)
* [aspire terminal command](/reference/cli/commands/aspire-terminal/)
* [aspire terminal attach command](/reference/cli/commands/aspire-terminal-attach/)
* [aspire terminal tape play command](/reference/cli/commands/aspire-terminal-tape-play/)
* [Automate resource terminals with tape files](/dashboard/terminal-tape-playback/)
* [Dashboard terminals](/dashboard/terminals/)

# aspire terminal tape command

> Use the aspire terminal tape command group to play tape files against existing resource terminals and automate repeatable shell or REPL checks.

## Name

[Section titled “Name”](#name)

`aspire terminal tape` - Automate existing resource terminal sessions with tape files.

## Synopsis

[Section titled “Synopsis”](#synopsis)

Aspire CLI

```bash
aspire terminal tape [command] [options]
```

## Description

[Section titled “Description”](#description)

The `aspire terminal tape` command group runs scripted terminal interactions against resources registered with [`WithTerminal()`](/app-host/with-terminal/). Its `play` subcommand sends input, waits for output, and can record text screens without launching a new shell or owning the resource lifecycle.

Experimental in Aspire 13.6

Tape playback requires Aspire CLI 13.6 or later and an AppHost with terminal support. No feature flag is required.

For a runnable shell example and the supported [Tape file syntax](/dashboard/terminal-tape-playback/#tape-file-syntax), see [Automate resource terminals with tape files](/dashboard/terminal-tape-playback/).

## Options

[Section titled “Options”](#options)

* **`-?, -h, --help`**

  Prints help and usage documentation for the available commands and options.

* **`-l, --log-level `**

  Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.

* **`--non-interactive`**

  Run the command in non-interactive mode, disabling all interactive prompts and spinners.

* **`--nologo`**

  Suppress the startup banner and telemetry notice.

* **`--banner`**

  Display the animated Aspire CLI welcome banner.

* **`--wait-for-debugger`**

  Wait for a debugger to attach before running a command.

## Commands

[Section titled “Commands”](#commands)

| Command                                                      | Function                                         |
| ------------------------------------------------------------ | ------------------------------------------------ |
| [`aspire terminal tape play`](../aspire-terminal-tape-play/) | Play a tape against a running resource terminal. |

## See also

[Section titled “See also”](#see-also)

* [Automate resource terminals with tape files](/dashboard/terminal-tape-playback/)
* [aspire terminal command](../aspire-terminal/)
* [aspire terminal tape play command](../aspire-terminal-tape-play/)

# aspire terminal tape play command

> Play a tape against a running Aspire resource terminal, select a replica, configure a timeout, and capture final or per-command text screens.

## Name

[Section titled “Name”](#name)

`aspire terminal tape play` - Play a tape file against an existing resource terminal.

## Synopsis

[Section titled “Synopsis”](#synopsis)

Aspire CLI

```bash
aspire terminal tape play  --tape-file  [options]
```

## Description

[Section titled “Description”](#description)

The command parses a `.tape` file, discovers a running AppHost, selects a live terminal replica, validates the tape, and plays it against that terminal. The resource must be registered with [`WithTerminal()`](/app-host/with-terminal/), and the AppHost must advertise the `terminals.v1` capability.

Experimental in Aspire 13.6

Tape playback requires Aspire CLI 13.6 or later and an AppHost with terminal support. No feature flag is required.

Playback connects as a secondary peer. It doesn’t request primary ownership, resize the terminal, start a new shell, or stop the resource on completion or failure. Input remains shared with other connected peers; coordinate playback with dashboard and CLI users.

An empty or comment-only tape reads the current screen. If the selected replica has no live terminal producer yet, playback waits for one within `--timeout`, including during startup or recycling. The command doesn’t start or restart the resource. AppHost-owned dock and interaction terminals, including clients opened by `WithRepl()`, aren’t resource targets for this command.

See [Tape file syntax](/dashboard/terminal-tape-playback/#tape-file-syntax) for supported commands and compatibility limits. Unsupported media, clipboard, scrolling, sizing, and shell-launch settings fail preflight before any tape input is sent.

## Arguments

[Section titled “Arguments”](#arguments)

* **``**

  The name of the terminal-enabled resource to automate.

## Options

[Section titled “Options”](#options)

* **`--tape-file `** (required)

  Path to the tape on the CLI machine. Relative paths resolve from the CLI’s working directory.

* **`-r, --replica `**

  The zero-based terminal replica index. A single replica is selected automatically. With multiple replicas, the CLI prompts for a choice unless you supply this option; non-interactive playback requires an explicit selection.

* **`--apphost `**

  Path to the AppHost used to select a running application. `--project` is a legacy alias. This option doesn’t start the AppHost.

* **`--timeout `**

  Overall timeout for waiting for a live terminal producer, connecting, and playing the tape. Defaults to `120` seconds; accepts integers from `1` through `4294967`. The deadline starts after resource selection, so it doesn’t bound initial AppHost discovery. Recording finalization and cleanup may continue after cancellation. Individual tape waits can have shorter timeouts.

* **`-?, -h, --help`**

  Prints help and usage documentation for the available commands and options.

* **`-l, --log-level `**

  Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.

* **`--non-interactive`**

  Run the command in non-interactive mode, disabling all interactive prompts and spinners.

* **`--nologo`**

  Suppress the startup banner and telemetry notice.

* **`--banner`**

  Display the animated Aspire CLI welcome banner.

* **`--wait-for-debugger`**

  Wait for a debugger to attach before running a command.

## Output and exit codes

[Section titled “Output and exit codes”](#output-and-exit-codes)

The final plain-text screen is written to **stdout**. Discovery messages, warnings, and diagnostics are written to **stderr**. A failed tape command also prints its failure screen to stdout, with the source location and command context on stderr.

| Exit code | Meaning                                                                                      |
| --------- | -------------------------------------------------------------------------------------------- |
| `0`       | The tape completed. This doesn’t assert that every program invoked inside a shell succeeded. |
| `1`       | Invalid input, tape syntax, preflight validation, or resource selection.                     |
| `16`      | Tape command failure, including a wait failure, or a terminal connection failure.            |
| `17`      | The overall `--timeout` deadline expired.                                                    |
| `130`     | User cancellation.                                                                           |

AppHost discovery and compatibility errors use their corresponding CLI exit codes. A disconnected terminal fails playback instead of retrying potentially non-idempotent input.

Use `Output recording.txt` or `Output recording.ascii` in the root tape to record **per-command** text screens. This differs from stdout’s final screen. `Output` and `Source` paths resolve relative to the root tape file’s directory, including directives in nested sources. Included sources require the exact `.tape` extension; their `Output` directives are ignored. Output parent directories must exist, and existing recording files aren’t overwritten.

## Examples

[Section titled “Examples”](#examples)

Use the [complete shell smoke test and resource setup](/dashboard/terminal-tape-playback/#run-a-shell-smoke-test) to create `shell-smoke.tape` and start the `shell` resource:

Play a shell smoke test

```bash
aspire terminal tape play shell --tape-file shell-smoke.tape
```

To select an AppHost explicitly and bound playback to 30 seconds, use your AppHost’s path:

Select a replica and AppHost

```bash
aspire terminal tape play shell --replica 0 --tape-file shell-smoke.tape --apphost ./apphost.cs --timeout 30
```

Save the final screen and diagnostics separately:

Redirect the playback result

```bash
aspire terminal tape play shell --tape-file shell-smoke.tape > final-screen.txt 2> tape-diagnostics.txt
```

Shell redirection can overwrite files independently of tape `Output` protections. For a multi-screen recording, follow [Record screens as text](/dashboard/terminal-tape-playback/#record-screens-as-text).

## See also

[Section titled “See also”](#see-also)

* [Automate resource terminals with tape files](/dashboard/terminal-tape-playback/)
* [Tape file syntax](/dashboard/terminal-tape-playback/#tape-file-syntax)
* [aspire terminal tape command](../aspire-terminal-tape/)
* [aspire terminal ps command](../aspire-terminal-ps/)
* [aspire terminal attach command](../aspire-terminal-attach/)

# aspire update command

> Learn about the aspire update command and its usage. This command helps you keep your Aspire projects current by automatically detecting and updating outdated packages and templates.

## Name

[Section titled “Name”](#name)

`aspire update` - Update Aspire packages and templates in your project.

## Synopsis

[Section titled “Synopsis”](#synopsis)

Aspire CLI

```bash
aspire update [options]
```

## Description

[Section titled “Description”](#description)

The `aspire update` command helps you keep your Aspire projects current by automatically detecting and updating outdated packages, templates, and repository CLI references. It finds outdated Aspire NuGet packages while respecting channel configurations and intelligently handles complex dependency graphs.

The Aspire CLI uses the following logic, in order, to determine which AppHost project to process:

* The `--apphost` option.

  This option specifies the path to the Aspire AppHost project file to process.

* The rooted `aspire.config.json` file.

  If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration.

* Searches the current directory and subdirectories.

  Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects.

  Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it.

The command performs the following:

* Detects outdated Aspire NuGet packages in your project
* Respects your configured Aspire channel (preview, stable, etc.)
* Resolves diamond dependencies to avoid duplicate updates
* Applies all package version edits before running a single final `dotnet restore`, so channel switches that add NuGet source mappings don’t cause restore failures mid-update
* Provides colorized output with detailed summary of changes

### Non-interactive usage

[Section titled “Non-interactive usage”](#non-interactive-usage)

When you use `--non-interactive`, also pass `--yes` to explicitly confirm the update operation. Omitting `--yes` when using `--non-interactive` is an error:

Aspire CLI

```bash
aspire update --yes --non-interactive
```

If you specify `--non-interactive` without `--yes`, the command exits with an error:

Output

```text
The update command requires --yes when the --non-interactive option is specified.
```

### Updating repository Aspire CLI references

[Section titled “Updating repository Aspire CLI references”](#updating-repository-aspire-cli-references)

A repository can pin the Aspire CLI independently of the executable you’re currently running, using an `Aspire.Cli` entry in `.config/dotnet-tools.json` or `dotnet-tools.json`, or an `@microsoft/aspire-cli` entry in `package.json` (`dependencies`, `devDependencies`, or `optionalDependencies`). `aspire update` updates these existing pins alongside AppHost integrations, or without an AppHost.

Discovery starts in the selected AppHost’s directory, or the current directory without an AppHost, and searches ancestor directories for the nearest CLI references. At each level, it checks `.config/dotnet-tools.json` before `dotnet-tools.json`. The .NET search stops after finding an Aspire entry or checking a manifest marked `isRoot: true`; npm independently searches for the nearest `package.json` with a CLI reference.

Updates preserve unrelated manifest entries and npm version-specifier forms: exact versions or full-version `^`/`~` ranges. Unsupported specifiers, such as file, workspace, or alias references and compound ranges, are skipped with a warning.

.NET pins resolve through the selected package channel, the same as project package updates. npm uses the `latest` dist-tag for the stable/default channel; requesting an explicit non-stable channel (for example, `daily`) requires that exact CLI version to already be published on npm.

Updating repository CLI references changes only the manifests; this step does not install the updated CLI, replace the running executable, or refresh lockfiles. Guest AppHost dependency installation can still change lockfiles during a project update. Follow the printed restore or install instructions afterward: run `dotnet tool restore` with the selected channel’s NuGet feed available, or your package manager’s install command, such as `npm install`.

### Updating guest AppHost projects

[Section titled “Updating guest AppHost projects”](#updating-guest-apphost-projects)

When updating a guest AppHost project, such as a TypeScript AppHost, `aspire update` checks the selected Aspire SDK version before modifying files. If the selected SDK is newer than the running Aspire CLI:

* **With repository CLI references**: The command offers to update the pins instead of replacing the running executable. After updating the pins, or if they’re already current, it skips the project update and asks you to restore or install the CLI, then re-run `aspire update`.
* **Without repository CLI references**: The command offers to update the CLI itself. If you confirm, it skips the project update and follows the [installation-specific update behavior](#updating-the-cli-based-on-how-it-was-installed), either downloading the binary or printing package-manager commands to run manually.

After updating the CLI, re-run `aspire update` to complete the project update. This check helps prevent a guest AppHost project from being left in a broken state when the CLI’s bundled code generator doesn’t support the selected SDK version.

Tip

If your repository doesn’t pin the CLI, you can run `aspire update --self` before updating a guest AppHost project. Follow any package-manager instructions it prints to complete the CLI update. For repositories with CLI pins, use plain `aspire update` and follow the restore or install guidance instead; `--self` doesn’t update those pins.

### Updating the CLI based on how it was installed

[Section titled “Updating the CLI based on how it was installed”](#updating-the-cli-based-on-how-it-was-installed)

`aspire update --self` (and the update notice shown when a newer version is available) adapts to how the CLI was installed so it doesn’t overwrite files owned by a package manager:

* When the CLI was installed from **npm** (the `@microsoft/aspire-cli` package), the command prints the npm update command to run instead of downloading a new binary:

  Output

  ```text
  To update the Aspire CLI when installed from npm, run:
    npm install -g @microsoft/aspire-cli@latest
  ```

* When the CLI was installed with the **install script** or another **binary install**, `aspire update --self` downloads and installs the latest CLI binary directly.

* When the CLI was installed as a **.NET tool**, the command prints the `dotnet tool update` command to run.

* When the CLI was installed via **Nix** (profile or flake), the command prints the Nix update commands to run instead of downloading a new binary. Because the Nix store is read-only, in-place binary updates are not possible:

  Output

  ```text
  To update the Aspire CLI when installed from Nix, update the profile package or flake input:
    nix profile upgrade aspire-cli
    nix flake update 
  ```

  Run `nix profile upgrade aspire-cli` for a profile install, or `nix flake update ` for a project flake.

## Options

[Section titled “Options”](#options)

The following options are available:

* **`--apphost `**

  The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`.

* **`--self`**

  Update the Aspire CLI itself to the latest version. The CLI adapts to how it was installed: npm and .NET tool installs print the matching package-manager command to run, while install-script and other binary installs download the latest binary directly. See [Updating the CLI based on how it was installed](#updating-the-cli-based-on-how-it-was-installed).

* **`--channel`**

  Channel to update to (`stable`, `staging`, `daily`). When switching channels, `aspire update` applies all package version edits to your project first and then runs a single `dotnet restore`, ensuring that NuGet source mappings added for the target channel are in place before any restore is attempted.

  For non-stable channels (`staging`, `daily`), `aspire update` creates or updates a project-level `nuget.config` with the source mappings needed to resolve packages from that channel’s feed. For the `stable` channel, no `nuget.config` is created because nuget.org is already the default NuGet source. If an existing `nuget.config` is present and the project has package or channel updates to apply when switching to or using `stable`, those changes are applied as part of that update to remove any stale channel-specific feed entries. If the project is already up to date, `aspire update` reports this and exits before touching `nuget.config`, so a stale channel-specific feed entry from a previous `staging` or `daily` switch can remain until the next update that actually applies changes.

  When you switch to a persistable channel, such as `daily`, `aspire update` also rewrites the top-level `channel` key in `aspire.config.json` when the file already exists. Only channels registered as *explicit* channels are persisted, with one exception: the `stable` channel is treated as the portable default and is intentionally not pinned. The persisted channel keeps subsequent `aspire add` and `aspire update` runs resolving packages against the channel you just switched to.

  The `staging` channel can only be resolved from a `stable` or `staging` Aspire CLI build. Daily, local, and per-PR CLI builds don’t have a deterministic staging feed, so requesting `--channel staging` from one of them fails with an error naming the running CLI’s identity and pointing at the recovery options: install a staging or stable Aspire CLI, or set the `overrideStagingFeed` configuration value (for example, `aspire config set -g overrideStagingFeed `) to point at the staging feed you want to use. See [`overrideStagingFeed`](/reference/cli/configuration/#settings-surfaced-by-aspire-config) in the CLI configuration reference.

* **`-y, --yes`**

  Automatically confirm all prompts without user input. Use this option in CI/CD pipelines or other non-interactive environments to skip confirmation dialogs.

* **`--nuget-config-dir`**

  Path to the directory containing the `NuGet.Config` file to use when searching for packages. When not specified, the command searches for a `NuGet.Config` file in the current directory and its parents.

* **`-?, -h, --help`**

  Prints help and usage documentation for the available commands and options.

* **`-l, --log-level `**

  Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.

* **`--non-interactive`**

  Run the command in non-interactive mode, disabling all interactive prompts and spinners.

* **`--nologo`**

  Suppress the startup banner and telemetry notice.

* **`--banner`**

  Display the animated Aspire CLI welcome banner.

* **`--wait-for-debugger`**

  Wait for a debugger to attach before running a command.

## Examples

[Section titled “Examples”](#examples)

* Analyze and update out-of-date Aspire packages and templates:

  Aspire CLI

  ```bash
  aspire update
  ```

* Update a specific AppHost project:

  Aspire CLI

  ```bash
  aspire update --apphost './projects/apphost/orchestration.AppHost.csproj'
  ```

* Update packages in a CI/CD pipeline without interactive prompts:

  Aspire CLI

  ```bash
  aspire update --yes --non-interactive
  ```

* Update packages using a specific NuGet configuration file:

  Aspire CLI

  ```bash
  aspire update --nuget-config-dir './config'
  ```

* Update packages to the daily preview channel:

  Aspire CLI

  ```bash
  aspire update --channel daily
  ```

# aspire wait command

> Learn about the aspire wait command which blocks until a named resource reaches a target status, with a configurable timeout.

## Name

[Section titled “Name”](#name)

`aspire wait` - Wait for a resource to reach a target status.

## Synopsis

[Section titled “Synopsis”](#synopsis)

Aspire CLI

```bash
aspire wait  [options]
```

## Description

[Section titled “Description”](#description)

The `aspire wait` command blocks until a named resource within a running AppHost reaches a target status. This is useful for CI/CD pipelines and automation workflows where you need to wait for resources to be ready after starting an AppHost with `aspire run --detach`.

The `--timeout` option here controls how long to wait for a *resource* to reach its target status. It’s separate from the `ASPIRE_CLI_START_TIMEOUT` environment variable, which controls how long `aspire run` and `aspire start` wait for the *AppHost itself* to finish starting up. See [aspire run](/reference/cli/commands/aspire-run/#configuring-the-startup-timeout) for details.

The command connects to a running AppHost via the backchannel and streams resource state changes in real-time. It validates that the specified resource exists before entering the wait loop, so typos in resource names are caught immediately rather than causing a silent timeout. If the resource enters the `FailedToStart` state, the wait fails immediately with exit code 18, even when the target status is `down` — a resource that failed to start is never treated as a successful “down” outcome.

When executed without the `--apphost` option, the command:

1. Scans for all running AppHost processes.
2. If multiple AppHosts are running within the current directory scope, prompts you to select which one to target.
3. If only one AppHost is running in scope, connects to it directly.
4. If no in-scope AppHosts are found but out-of-scope AppHosts exist, displays all running AppHosts for selection.

## Arguments

[Section titled “Arguments”](#arguments)

* **``**

  The name of the resource to wait for. This must match the name of a resource defined in the running AppHost.

## Options

[Section titled “Options”](#options)

The following options are available:

* **`--status `**

  The target status to wait for. Defaults to `healthy`. The following values are supported:

  | Value     | Condition                                                                    |
  | --------- | ---------------------------------------------------------------------------- |
  | `healthy` | Resource is running and healthy, or running with no health checks configured |
  | `up`      | Resource is running, regardless of health status                             |
  | `down`    | Resource has finished, exited, or failed to start                            |

  Values are case-insensitive.

* **`--timeout `**

  The maximum number of seconds to wait for the resource to reach the target status. Defaults to `120`. Must be a positive integer.

* **`--apphost `**

  The path to the Aspire AppHost project file. When specified, the command connects to the AppHost running from that apphost without prompting for selection.

* **`-?, -h, --help`**

  Prints help and usage documentation for the available commands and options.

* **`-l, --log-level `**

  Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.

* **`--non-interactive`**

  Run the command in non-interactive mode, disabling all interactive prompts and spinners.

* **`--nologo`**

  Suppress the startup banner and telemetry notice.

* **`--banner`**

  Display the animated Aspire CLI welcome banner.

* **`--wait-for-debugger`**

  Wait for a debugger to attach before running a command.

## Exit codes

[Section titled “Exit codes”](#exit-codes)

| Code | Meaning                                                                     |
| ---- | --------------------------------------------------------------------------- |
| 0    | Resource reached the target status                                          |
| 7    | No running AppHost found                                                    |
| 17   | Timeout exceeded before the resource reached the target status              |
| 18   | Resource entered the `FailedToStart` state, regardless of the target status |

## Examples

[Section titled “Examples”](#examples)

* Wait for a resource to be healthy (default):

  Aspire CLI

  ```bash
  aspire wait webfrontend
  ```

* Wait for a resource to be running:

  Aspire CLI

  ```bash
  aspire wait mydb --status up
  ```

* Wait for a resource to stop:

  Aspire CLI

  ```bash
  aspire wait worker --status down
  ```

* Wait with a custom timeout of 60 seconds:

  Aspire CLI

  ```bash
  aspire wait webfrontend --timeout 60
  ```

* Target a specific AppHost project:

  Aspire CLI

  ```bash
  aspire wait mydb --apphost './src/MyApp.AppHost/MyApp.AppHost.csproj'
  ```

* Use with `aspire run --detach` in a CI/CD pipeline:

  Aspire CLI

  ```bash
  aspire run --detach
  aspire wait webfrontend
  aspire wait mydb --status healthy
  ```

## See also

[Section titled “See also”](#see-also)

* [aspire run](/reference/cli/commands/aspire-run/)
* [aspire ps](/reference/cli/commands/aspire-ps/)
* [aspire stop](/reference/cli/commands/aspire-stop/)

# Configuration settings

> Learn about Aspire CLI configuration, the aspire.config.json settings and their default values, and the JSON Schema for editor completions and validation.

Aspire configuration is a rooted `aspire.config.json` file for project-scoped CLI configuration. Use the `aspire config` command family to inspect and update those settings, and use `aspire config list --all` to see the feature flags surfaced by your installed CLI.

## Configuration file model

[Section titled “Configuration file model”](#configuration-file-model)

Starting in Aspire 13.2, Aspire prefers a rooted `aspire.config.json` file for project-scoped configuration. The CLI can also read and write user-scoped global defaults.

* **Project-scoped configuration**

  Project-scoped settings live in a rooted `aspire.config.json` file. This replaces the older `.aspire/settings.json` model.

* **Global configuration**

  User-scoped defaults can be set with `aspire config set --global ...`. Project-scoped settings override global values when both are present. Project-specific values such as `appHost.path` must be configured locally in `aspire.config.json`.

The consolidated `aspire.config.json` file also stores other rooted Aspire configuration, such as the SDK version, launch profiles, and integration packages. The [settings table](#settings-surfaced-by-aspire-config) lists the settings you can configure in the file and their default values.

## Example `aspire.config.json`

[Section titled “Example aspire.config.json”](#example-aspireconfigjson)

aspire.config.json

```json
{
  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
  "appHost": {
    "path": "./apphost.mts"
  },
  "channel": "staging",
  "features": {
    "defaultWatchEnabled": true,
    "showAllTemplates": true,
    "updateNotificationsEnabled": true
  }
}
```

The highlighted `$schema` property is additive

By default, the configuration files do not include the `$schema` property. You can add it manually to enable editor support for JSON Schema.

## JSON Schema support

[Section titled “JSON Schema support”](#json-schema-support)

Aspire publishes a JSON Schema for `aspire.config.json` so editors can provide completions, validation, and hover documentation while you edit the file.

Two URLs are available:

* The **latest** URL always points to the newest published schema:

  Latest schema URL

  ```text
  https://aspire.dev/reference/cli/configuration/schema.json
  ```

  [`schema.json`](/reference/cli/configuration/schema.json)

* A **versioned** URL pins to a specific Aspire release, such as `13.6.0`:

  Versioned schema URL

  ```text
  https://aspire.dev/reference/cli/configuration/schema/13.6.0.json
  ```

  Every stable Aspire release starting with 13.2.0 has a versioned schema, and that schema never changes after the release ships.

### Reference the schema from `aspire.config.json`

[Section titled “Reference the schema from aspire.config.json”](#reference-the-schema-from-aspireconfigjson)

Most editors automatically pick up a schema when the JSON file declares a top-level `$schema` property:

aspire.config.json

```diff
{
  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
  "appHost": {
    "path": "./apphost.mts"
  }
}
```

Note

Use a versioned URL, such as `.../schema/13.6.0.json`, when you want schema behavior to stay stable alongside a pinned Aspire CLI version. Use the unversioned `schema.json` when you want to always validate against the latest release.

### Associate the schema in Visual Studio Code

[Section titled “Associate the schema in Visual Studio Code”](#associate-the-schema-in-visual-studio-code)

With the [Aspire VS Code extension](/get-started/aspire-vscode-extension/) installed, the schema is registered for `aspire.config.json` automatically. Without the extension, add a `$schema` property to the top of `aspire.config.json` (see above) or map the schema manually in `.vscode/settings.json` under `json.schemas`.

### Other editors

[Section titled “Other editors”](#other-editors)

Any editor or tool that understands JSON Schema draft-07 can consume the hosted schema — including JetBrains IDEs (**Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings**), Neovim with [`jsonls`](https://github.com/microsoft/vscode-json-languageservice), and command-line validators such as [`ajv`](https://ajv.js.org/) or [`check-jsonschema`](https://github.com/python-jsonschema/check-jsonschema). Point the tool at either the latest or versioned URL above.

## Settings surfaced by `aspire config`

[Section titled “Settings surfaced by aspire config”](#settings-surfaced-by-aspire-config)

Use `aspire config list` to see the values that are currently set, and use `aspire config list --all` to enumerate the feature flags your installed CLI can configure. The following table lists the settings, their default values, and what they control.

| Key                                          | Default                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appHost.language`                           | —                                  | Language of the AppHost, such as `typescript/nodejs` or `python`. The CLI uses it to choose the runtime that runs the AppHost.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `appHost.path`                               | —                                  | Path to the default AppHost entry point, such as `apphost.mts`, `Program.cs`, or an AppHost project file, relative to the directory that contains `aspire.config.json`. Set it in the local `aspire.config.json` file; the CLI ignores it in global configuration.                                                                                                                                                                                                                                                                                                                  |
| `certificates.nssDbPaths`                    | —                                  | NSS database paths used for browser certificate trust on Linux. Separate paths with the platform path separator. Prefix a path with `firefox=` or `chromium=` to apply the trust settings expected by that browser family. Takes precedence over the upstream `DOTNET_DEV_CERTS_NSSDB_PATHS` environment variable.                                                                                                                                                                                                                                                                  |
| `channel`                                    | —                                  | Aspire channel used to resolve Aspire packages, such as `stable`, `staging`, or `daily`. `aspire new`, `aspire init`, and `aspire update` can record it, `aspire add` reads it for non-C# AppHosts, and `aspire update` uses it when you don’t pass `--channel`.                                                                                                                                                                                                                                                                                                                    |
| `docs.api.sitemapUrl`                        | `https://aspire.dev/sitemap-0.xml` | API reference sitemap used by `aspire docs api`. Leave it unset to use the built-in aspire.dev source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `docs.llmsTxtUrl`                            | `https://aspire.dev/llms-full.txt` | `llms.txt` documentation source used by `aspire docs`. Leave it unset to use the built-in aspire.dev source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `features.defaultWatchEnabled`               | `false`                            | Enable or disable watch mode by default when running Aspire applications for automatic restarts on file changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `features.experimentalPolyglot:go`           | `false`                            | Enable or disable experimental Go AppHost support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `features.experimentalPolyglot:java`         | `false`                            | Enable or disable experimental Java AppHost support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `features.experimentalPolyglot:python`       | `false`                            | Enable or disable experimental Python AppHost support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `features.experimentalPolyglot:rust`         | `false`                            | Enable or disable experimental Rust AppHost support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `features.nugetSignatureVerificationEnabled` | `true`                             | Enable or disable defaulting the `DOTNET_NUGET_SIGNATURE_VERIFICATION` environment variable for NuGet operations. When enabled on Linux, the CLI sets the variable to `true` unless you’ve set it to `false`.                                                                                                                                                                                                                                                                                                                                                                       |
| `features.polyglotIntegrationFilterEnabled`  | `false`                            | Enable or disable an experimental filter that restricts `aspire add`, `aspire integration list`, and `aspire integration search` in non-C# AppHosts to integrations with the `polyglot` NuGet tag. The filter fails closed, so enabling it against a remote feed hides every integration. Azure DevOps Artifacts feeds ignore `tags:` query scoping, and nuget.org returns no first-party integrations for the tag. Enable it only against a local package source or hive, where the CLI reads the tag from the package’s `.nuspec` file.                                           |
| `features.showAllTemplates`                  | `false`                            | Show all available templates, including experimental ones, in `aspire new` and `aspire init`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `features.showDeprecatedPackages`            | `false`                            | Show or hide deprecated packages in `aspire add` search results.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `features.stagingChannelEnabled`             | `false`                            | Enable or disable access to the `staging` channel for early access to preview features and packages. When enabled, daily, local, and per-PR CLI builds can also resolve the `staging` channel.                                                                                                                                                                                                                                                                                                                                                                                      |
| `features.updateNotificationsEnabled`        | `true`                             | Enable or disable Aspire CLI update notifications.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `overrideStagingFeed`                        | —                                  | Feed URL for the `staging` channel. Any non-empty value lets every CLI build resolve the `staging` channel, and a valid `http` or `https` URL replaces the default staging feed. To set it, run `aspire config set -g overrideStagingFeed `. Without this setting or `features.stagingChannelEnabled`, `--channel staging` only resolves on `stable` or `staging` Aspire CLI builds. Daily, local, and per-PR builds refuse it and report the recovery options. This key isn’t part of the published JSON Schema, so schema-aware editors flag it as an unknown property. |
| `packages.`                       | —                                  | Version of a hosting integration package for a non-C# AppHost, keyed by package ID. A value that ends in `.csproj` is treated as a project reference. `aspire add` adds entries, and `aspire update` updates their versions. For more information, see [Add and restore integrations](/app-host/typescript-apphost/#add-and-restore-integrations).                                                                                                                                                                                                                                  |
| `profiles..applicationUrl`             | —                                  | Application URLs for the launch profile, such as `https://localhost:17000;http://localhost:15000`. To learn where each kind of AppHost stores launch profiles, see [AppHost configuration](/app-host/configuration/).                                                                                                                                                                                                                                                                                                                                                               |
| `profiles..environmentVariables`       | —                                  | Environment variables for the launch profile.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `sdk.version`                                | Installed CLI version              | Aspire SDK version for a non-C# AppHost, which determines the version of the `Aspire.Hosting` packages to use. `aspire update` updates this value.                                                                                                                                                                                                                                                                                                                                                                                                                                  |

Each `.` in a key maps to a nested object in `aspire.config.json`. For example, `aspire config set appHost.path ./apphost.mts` writes `"appHost": { "path": "./apphost.mts" }`. Replace placeholders such as `` and `` with your own values.

Caution

`aspire config set` treats every `.` and `:` in a key as a nesting separator, so it can’t write keys whose names contain those characters:

* In `features.experimentalPolyglot:`, `experimentalPolyglot:` is a single feature name. Without `--global`, the CLI writes a nested `experimentalPolyglot` object to the local `aspire.config.json` file, and later commands fail to load the file. Set these flags with `--global`, or add them to the local file by hand, for example `"experimentalPolyglot:go": true` in the `features` object.
* Package IDs such as `Aspire.Hosting.Redis` contain dots. Use `aspire add` to add packages, or edit the `packages` object by hand.

### Configure the AppHost path

[Section titled “Configure the AppHost path”](#configure-the-apphost-path)

Use `appHost.path` to set the default AppHost entry point for the current configuration root:

Set the local AppHost path

```bash
aspire config set appHost.path ./apphost.mts
```

The CLI writes this value to the local `aspire.config.json` file:

aspire.config.json

```json
{
  "appHost": {
    "path": "./apphost.mts"
  }
}
```

The AppHost path can point to the entry point used by your AppHost language, such as `apphost.mts`, `Program.cs`, or an AppHost project file. The path is project-specific and can’t be configured globally. If a global settings file contains `appHost.path` or the legacy `appHostPath` key, the CLI ignores that value and warns that AppHost paths must be configured locally. The legacy `appHostPath` key is also blocked by `aspire config set`; use `appHost.path` instead.

### Configure browser certificate trust on Linux

[Section titled “Configure browser certificate trust on Linux”](#configure-browser-certificate-trust-on-linux)

On Linux, the NSS databases used to trust the Aspire HTTPS development certificate can be configured through `certificates.nssDbPaths`, including user-level configuration:

Set the NSS database paths globally

```bash
aspire config set --global certificates.nssDbPaths "firefox=/path/to/firefox/profile:chromium=/path/to/chromium/nssdb"
```

Prefix a path with `firefox=` or `chromium=` to apply the trust settings expected by that browser family, and separate multiple paths with the platform path separator.

If `certificates.nssDbPaths` is unset, `aspire certs trust` will also honor the `DOTNET_DEV_CERTS_NSSDB_PATHS` environment variable, but Aspire configuration will take precedence when present. When no specific configuration is supplied, Aspire applies certificate trust to NSS databases in well-known browser specific paths for Firefox and Chrome/Chromium. Run [`aspire certs trust`](../commands/aspire-certs-trust/) to apply the configured trust settings.

## Toggle preview feature experiences

[Section titled “Toggle preview feature experiences”](#toggle-preview-feature-experiences)

Use feature flags to opt in to preview experiences that your installed Aspire CLI supports.

Tip

The available feature flags depend on your installed CLI version. Treat the output of `aspire config list --all` as the authoritative list of feature flags and their default values.

1. Run `aspire config list --all` to discover available `features.*` keys.

2. Enable a feature flag for the current project with `aspire config set`:

   Enable a project-scoped preview feature

   ```bash
   aspire config set features. true
   ```

3. Use `--global` (or `-g`) when you want the feature enabled by default across projects. Copy the key name exactly from `aspire config list --all` because some language-specific flags use a `:` suffix:

   Enable a user-scoped preview feature default

   ```bash
   aspire config set features. true --global
   ```

   For example, consider the following that enables global support for Go:

   Enable global Go support

   ```bash
   aspire config set features.experimentalPolyglot:go true --global
   ```

   Always set `experimentalPolyglot:` flags with `--global`, or add them to the local `aspire.config.json` file by hand. For details, see the caution under [Settings surfaced by `aspire config`](#settings-surfaced-by-aspire-config).

4. Turn a feature off by setting it to `false`, or remove the override with `aspire config delete `.

## Working with configuration

[Section titled “Working with configuration”](#working-with-configuration)

* Use `aspire config list` to show currently set project-scoped and global values.

* Use `aspire config list --all` to include the feature flags that your installed CLI can configure.

* Use `aspire config get ` to inspect a specific setting such as `channel` or `appHost.path`.

* Use `aspire config set  ` to update a setting, and `aspire config set --global ...` when you want a user-scoped default.

## CLI commands

[Section titled “CLI commands”](#cli-commands)

| Command                                                                         | Status | Function                                                                       |
| ------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------ |
| [`aspire config`](/reference/cli/commands/aspire-config/)                       | Stable | Command driver for managing Aspire configuration.                              |
| [`aspire config list`](/reference/cli/commands/aspire-config-list/)             | Stable | List currently configured values, or all available feature flags with `--all`. |
| [`aspire config get `](/reference/cli/commands/aspire-config-get/)         | Stable | Get a configuration value.                                                     |
| [`aspire config set  `](/reference/cli/commands/aspire-config-set/) | Stable | Set a configuration value.                                                     |
| [`aspire config delete `](/reference/cli/commands/aspire-config-delete/)   | Stable | Delete a configuration value.                                                  |

For command-level details, see the [`aspire config` command reference](/reference/cli/commands/aspire-config/).

# Config File Description

Starting in Aspire 13.2, Aspire prefers a rooted `aspire.config.json` file for project-scoped configuration. The CLI can also read and write user-scoped global defaults.

* **Project-scoped configuration**

  Project-scoped settings live in a rooted `aspire.config.json` file. This replaces the older `.aspire/settings.json` model.

* **Global configuration**

  User-scoped defaults can be set with `aspire config set --global ...`. Project-scoped settings override global values when both are present. Project-specific values such as `appHost.path` must be configured locally in `aspire.config.json`.

# Config Settings Table

| Key                                          | Default                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appHost.language`                           | —                                  | Language of the AppHost, such as `typescript/nodejs` or `python`. The CLI uses it to choose the runtime that runs the AppHost.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `appHost.path`                               | —                                  | Path to the default AppHost entry point, such as `apphost.mts`, `Program.cs`, or an AppHost project file, relative to the directory that contains `aspire.config.json`. Set it in the local `aspire.config.json` file; the CLI ignores it in global configuration.                                                                                                                                                                                                                                                                                                                  |
| `certificates.nssDbPaths`                    | —                                  | NSS database paths used for browser certificate trust on Linux. Separate paths with the platform path separator. Prefix a path with `firefox=` or `chromium=` to apply the trust settings expected by that browser family. Takes precedence over the upstream `DOTNET_DEV_CERTS_NSSDB_PATHS` environment variable.                                                                                                                                                                                                                                                                  |
| `channel`                                    | —                                  | Aspire channel used to resolve Aspire packages, such as `stable`, `staging`, or `daily`. `aspire new`, `aspire init`, and `aspire update` can record it, `aspire add` reads it for non-C# AppHosts, and `aspire update` uses it when you don’t pass `--channel`.                                                                                                                                                                                                                                                                                                                    |
| `docs.api.sitemapUrl`                        | `https://aspire.dev/sitemap-0.xml` | API reference sitemap used by `aspire docs api`. Leave it unset to use the built-in aspire.dev source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `docs.llmsTxtUrl`                            | `https://aspire.dev/llms-full.txt` | `llms.txt` documentation source used by `aspire docs`. Leave it unset to use the built-in aspire.dev source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `features.defaultWatchEnabled`               | `false`                            | Enable or disable watch mode by default when running Aspire applications for automatic restarts on file changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `features.experimentalPolyglot:go`           | `false`                            | Enable or disable experimental Go AppHost support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `features.experimentalPolyglot:java`         | `false`                            | Enable or disable experimental Java AppHost support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `features.experimentalPolyglot:python`       | `false`                            | Enable or disable experimental Python AppHost support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `features.experimentalPolyglot:rust`         | `false`                            | Enable or disable experimental Rust AppHost support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `features.nugetSignatureVerificationEnabled` | `true`                             | Enable or disable defaulting the `DOTNET_NUGET_SIGNATURE_VERIFICATION` environment variable for NuGet operations. When enabled on Linux, the CLI sets the variable to `true` unless you’ve set it to `false`.                                                                                                                                                                                                                                                                                                                                                                       |
| `features.polyglotIntegrationFilterEnabled`  | `false`                            | Enable or disable an experimental filter that restricts `aspire add`, `aspire integration list`, and `aspire integration search` in non-C# AppHosts to integrations with the `polyglot` NuGet tag. The filter fails closed, so enabling it against a remote feed hides every integration. Azure DevOps Artifacts feeds ignore `tags:` query scoping, and nuget.org returns no first-party integrations for the tag. Enable it only against a local package source or hive, where the CLI reads the tag from the package’s `.nuspec` file.                                           |
| `features.showAllTemplates`                  | `false`                            | Show all available templates, including experimental ones, in `aspire new` and `aspire init`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `features.showDeprecatedPackages`            | `false`                            | Show or hide deprecated packages in `aspire add` search results.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `features.stagingChannelEnabled`             | `false`                            | Enable or disable access to the `staging` channel for early access to preview features and packages. When enabled, daily, local, and per-PR CLI builds can also resolve the `staging` channel.                                                                                                                                                                                                                                                                                                                                                                                      |
| `features.updateNotificationsEnabled`        | `true`                             | Enable or disable Aspire CLI update notifications.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `overrideStagingFeed`                        | —                                  | Feed URL for the `staging` channel. Any non-empty value lets every CLI build resolve the `staging` channel, and a valid `http` or `https` URL replaces the default staging feed. To set it, run `aspire config set -g overrideStagingFeed `. Without this setting or `features.stagingChannelEnabled`, `--channel staging` only resolves on `stable` or `staging` Aspire CLI builds. Daily, local, and per-PR builds refuse it and report the recovery options. This key isn’t part of the published JSON Schema, so schema-aware editors flag it as an unknown property. |
| `packages.`                       | —                                  | Version of a hosting integration package for a non-C# AppHost, keyed by package ID. A value that ends in `.csproj` is treated as a project reference. `aspire add` adds entries, and `aspire update` updates their versions. For more information, see [Add and restore integrations](/app-host/typescript-apphost/#add-and-restore-integrations).                                                                                                                                                                                                                                  |
| `profiles..applicationUrl`             | —                                  | Application URLs for the launch profile, such as `https://localhost:17000;http://localhost:15000`. To learn where each kind of AppHost stores launch profiles, see [AppHost configuration](/app-host/configuration/).                                                                                                                                                                                                                                                                                                                                                               |
| `profiles..environmentVariables`       | —                                  | Environment variables for the launch profile.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `sdk.version`                                | Installed CLI version              | Aspire SDK version for a non-C# AppHost, which determines the version of the `Aspire.Hosting` packages to use. `aspire update` updates this value.                                                                                                                                                                                                                                                                                                                                                                                                                                  |

Each `.` in a key maps to a nested object in `aspire.config.json`. For example, `aspire config set appHost.path ./apphost.mts` writes `"appHost": { "path": "./apphost.mts" }`. Replace placeholders such as `` and `` with your own values.

Caution

`aspire config set` treats every `.` and `:` in a key as a nesting separator, so it can’t write keys whose names contain those characters:

* In `features.experimentalPolyglot:`, `experimentalPolyglot:` is a single feature name. Without `--global`, the CLI writes a nested `experimentalPolyglot` object to the local `aspire.config.json` file, and later commands fail to load the file. Set these flags with `--global`, or add them to the local file by hand, for example `"experimentalPolyglot:go": true` in the `features` object.
* Package IDs such as `Aspire.Hosting.Redis` contain dots. Use `aspire add` to add packages, or edit the `packages` object by hand.

# Banner Option

**`--banner`**

Display the animated Aspire CLI welcome banner.

# Help Option

**`-?, -h, --help`**

Prints help and usage documentation for the available commands and options.

# Include Hidden Option

**`--include-hidden`**

Includes resources that are marked as hidden. By default, hidden resources are not shown. When a specific resource name is provided, hidden resources are always included regardless of this option.

# Option List Steps

**`--list-steps`**

List the pipeline steps that would be executed, without running them. Useful for inspecting what a pipeline command will do before invoking it for real.

# Log Level Option

**`-l, --log-level `**

Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.

# Option No Build

**`--no-build`**

Don’t build or restore the AppHost project before running the command. Use this when you’ve already built the AppHost (for example, in a CI step) and want to skip the implicit build.

# No Logo Option

**`--nologo`**

Suppress the startup banner and telemetry notice.

# Non-Interactive Option

**`--non-interactive`**

Run the command in non-interactive mode, disabling all interactive prompts and spinners.

# Option AppHost

**`--apphost `**

The path to the Aspire AppHost file or project file, such as `apphost.mts`, `apphost.cs`, or an AppHost `.csproj`.

# Option Version

**`-v, --version`**

Prints the version of the Aspire CLI tool.

# Option Wait

**`--wait-for-debugger`**

Wait for a debugger to attach before running a command.

# Project Search Logic

The Aspire CLI uses the following logic, in order, to determine which AppHost project to process:

* The `--apphost` option.

  This option specifies the path to the Aspire AppHost project file to process.

* The rooted `aspire.config.json` file.

  If the rooted config exists in the current directory, it’s used. If not, the CLI walks up the directory structure looking for it. If Aspire finds the rooted config, it uses the recorded AppHost information to determine which project to process. Legacy `.aspire/settings.json` files are still read during migration.

* Searches the current directory and subdirectories.

  Starting in the current directory, the CLI gathers all AppHost projects from that directory and below. If a single project is discovered, it’s automatically selected. If multiple projects are discovered, they’re printed to the terminal for the user to manually select one of the projects.

  Once a project is selected, either automatically or manually, Aspire records that selection in the rooted configuration so later commands can reuse it.

# Install script

> Learn about the aspire-install scripts to install the Aspire CLI. Use the Aspire CLI to create, run, and manage Aspire solutions.

This article describes the syntax for the Aspire installation scripts, available in both Bash and PowerShell versions. To download and use these scripts, see [Install the Aspire CLI](/get-started/install-cli/).

## Name

[Section titled “Name”](#name)

`aspire-install.ps1` | `aspire-install.sh` - Scripts used to install the Aspire CLI.

## Synopsis

[Section titled “Synopsis”](#synopsis)

* Bash

  Bash

  ```bash
  aspire-install.sh
    [--install-path ]
    [--version ]
    [--quality ]
    [--os ]
    [--arch ]
    [--skip-path]
    [--keep-archive]
    [--verbose]
    [--help]
  ```

* PowerShell

  PowerShell

  ```powershell
  aspire-install.ps1
    [-InstallPath ]
    [-Version ]
    [-Quality ]
    [-OS ]
    [-Architecture ]
    [-SkipPath]
    [-KeepArchive]
    [-Help]"
  ```

## Description

[Section titled “Description”](#description)

The `aspire-install` scripts perform a nonadmin installation of the Aspire CLI.

### Script behavior

[Section titled “Script behavior”](#script-behavior)

Both scripts behave the same way. They download the Aspire CLI for the target platform, install it to the specified location, and add it to your PATH environment variable.

By default, the installation scripts download and install the latest stable release of the Aspire CLI. Specify a different version with the `-Version|--version` argument or a different quality level with the `-Quality|--quality` argument.

Unless changed with the `-InstallPath|--install-path` argument, the script installs to a user-specific location: `%USERPROFILE%\.aspire\bin` on Windows or `$HOME/.aspire/bin` on Linux/macOS.

## Options

[Section titled “Options”](#options)

* **`-InstallPath|--install-path `**

  Specifies the installation path. The directory is created if it doesn’t exist. The default value is *%USERPROFILE%.aspire\bin* on Windows and *$HOME/.aspire/bin* on Linux/macOS. The Aspire CLI executable is placed directly in this directory.

* **`-Version|--version `**

  Represents a specific version to install. For example: `13.6`. If not specified, the latest stable version is installed.

* **`-Quality|--quality `**

  Downloads the specified quality build. The possible values are:

  * `release`: The latest stable release (default).
  * `staging`: Builds from the current release branch (prerelease builds).
  * `dev`: Latest builds from the `main` branch (development builds).

  The different quality values signal different stages of the release process:

  * `release`: The final stable releases of the Aspire CLI. Intended for production use.
  * `staging`: Prerelease builds intended for testing upcoming releases. Not recommended for production use.
  * `dev`: The latest builds from the main development branch. They’re built frequently and aren’t fully tested. Not recommended for production use but can be used to test specific features or fixes immediately after they’re merged.

* **`-OS|--os `**

  Specifies the operating system for which the CLI is being installed. Possible values are: `win`, `linux`, `linux-musl`, `osx`.

  The parameter is optional and should only be used when it’s required to override the operating system that is detected by the script.

* **`-Architecture|--arch `**

  Architecture of the Aspire CLI binaries to install. Possible values are `x64`, `x86`, `arm64`. The default behavior is to autodetect the current system architecture.

* **`-SkipPath|--skip-path`**

  If you set this option, the script installs the CLI without modifying your `PATH` environment variable. Use this when you want to manually manage your PATH or when installing in environments where automatic `PATH` modification isn’t desired.

* **`-KeepArchive|--keep-archive`**

  If you set this option, the script keeps the downloaded archive files and temporary directory after installation. By default, the script deletes the archive after extraction and cleans up the temporary directory.

* **`--verbose`**

  Displays diagnostics information. (Linux/macOS only)

* **`-Help|--help`**

  Prints help information for the script.

## Examples

[Section titled “Examples”](#examples)

* Install the latest stable version to the default location:

  * Bash

    ```bash
    ./aspire-install.sh
    ```

  * PowerShell

    ```powershell
    .\aspire-install.ps1
    ```

* Install to a custom directory:

  * Bash

    ```bash
    ./aspire-install.sh --install-path "/usr/local/bin"
    ```

  * PowerShell

    ```powershell
    .\aspire-install.ps1 -InstallPath 'C:\Tools\Aspire'
    ```

* Install a specific version:

  * Bash

    ```bash
    ./aspire-install.sh --version "13.6"
    ```

  * PowerShell

    ```powershell
    .\aspire-install.ps1 -Version '13.6'
    ```

* Install development builds:

  * Bash

    ```bash
    ./aspire-install.sh --quality "dev"
    ```

  * PowerShell

    ```powershell
    .\aspire-install.ps1 -Quality 'dev'
    ```

* Download and install development builds in one command:

  * Bash

    ```bash
    curl -sSL https://aspire.dev/install.sh | bash -s -- --quality "dev"
    ```

  * PowerShell

    ```powershell
    Invoke-Expression "& { $(Invoke-RestMethod 'https://aspire.dev/install.ps1') } -Quality 'dev'"
    ```

* Install with verbose output (Linux/macOS only):

  * Bash

    ```bash
    ./aspire-install.sh --verbose
    ```

  * PowerShell

    ```powershell
    # The --verbose option is not available in the PowerShell script.
    ```

* Install without modifying `PATH`:

  * Bash

    ```bash
    ./aspire-install.sh --skip-path
    ```

  * PowerShell

    ```powershell
    .\aspire-install.ps1 -SkipPath
    ```

  Or download and install in one command:

  * Bash

    ```bash
    curl -fsSL https://aspire.dev/install.sh | bash -s -- --skip-path
    ```

  * PowerShell

    ```powershell
    irm https://aspire.dev/install.ps1 | iex -SkipPath
    ```

## Uninstall

[Section titled “Uninstall”](#uninstall)

There’s no uninstall script. Delete the installation directory, such as `%USERPROFILE%\.aspire\bin` on Windows or `$HOME/.aspire/bin` on Linux/macOS.

To delete the installation directory, run the following command from your terminal:

* Bash

  ```bash
  rm -rf $HOME/.aspire/bin
  ```

* PowerShell

  ```powershell
  Remove-Item -Recurse -Force "$HOME\.aspire\bin"
  ```

Reminder

After deleting the installation directory, don’t forget to remove it from your `PATH` environment variable.

## See also

[Section titled “See also”](#see-also)

* [Install Aspire CLI](/get-started/install-cli/)
* [`aspire` command reference](/reference/cli/commands/aspire/)

# Microsoft-collected CLI telemetry

> Learn what telemetry the Aspire CLI collects, how the data is used to improve the product, and how to opt out using environment variables or CLI configuration.

The Aspire CLI collects usage telemetry to help Microsoft improve the product. This data helps the Aspire team understand how the CLI is used and identify areas for improvement.

## Scope

[Section titled “Scope”](#scope)

Aspire CLI telemetry is collected when using the CLI to run commands. Telemetry is gathered during normal CLI usage, unless you have [opted out](#how-to-opt-out) of telemetry collection.

### AI agent skill usage

[Section titled “AI agent skill usage”](#ai-agent-skill-usage)

When you run `aspire agent init`, Aspire installs Aspire’s AI skills and a `PostToolUse` hook into each detected agent client’s user-level configuration (for example, GitHub Copilot CLI and Claude Code). The hook lets Aspire understand which of its AI skills and tools are actually used so the team can invest in the most valuable ones.

After each agent tool use, the hook checks if an **Aspire** skill, Aspire MCP tool, or Aspire skill reference file was involved. If so, the hook inspects the event and forwards a low-cardinality usage event to the hidden `aspire agent telemetry` command. The command records the event through the same CLI telemetry pipeline. Tool uses that don’t involve Aspire skills or tools are ignored. See [AI agent skill usage data](#ai-agent-skill-usage-data) for exactly what’s recorded.

## How to opt-out

[Section titled “How to opt-out”](#how-to-opt-out)

To opt-out of telemetry collection, set the `ASPIRE_CLI_TELEMETRY_OPTOUT` environment variable to `true`. This will disable telemetry collection for all CLI commands:

* Bash

  ```bash
  export ASPIRE_CLI_TELEMETRY_OPTOUT=true
  ```

* PowerShell

  ```powershell
  $env:ASPIRE_CLI_TELEMETRY_OPTOUT="true"
  ```

## Disclosure

[Section titled “Disclosure”](#disclosure)

The first time you run an Aspire CLI command, you’ll see a disclosure message informing you that telemetry is being collected and how to opt out.

## Data points

[Section titled “Data points”](#data-points)

Aspire CLI telemetry doesn’t collect personal data, such as usernames or email addresses. It doesn’t scan your code and doesn’t extract source code, paths containing usernames, or environment-specific information. The data is sent securely to Microsoft.

Protecting your privacy is important to Microsoft. If you suspect that telemetry is collecting sensitive data or the data is being insecurely or inappropriately handled, file an issue in the [GitHub microsoft/aspire](https://github.com/microsoft/aspire) repository for investigation.

Aspire CLI collects the following data:

| Aspire CLI versions | Data                                        | Notes                                                                                                                                                                                                                                                                                                                                          |
| ------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 13.2                | CLI launch.                                 | Includes command name and exit code. Option and argument values are not sent to Microsoft.                                                                                                                                                                                                                                                     |
| 13.2                | Ensure .NET SDK install.                    | Includes .NET SDK version installed.                                                                                                                                                                                                                                                                                                           |
| 13.2                | CLI-related unhandled exceptions.           | —                                                                                                                                                                                                                                                                                                                                              |
| 13.5                | Coding agent detection.                     | When the CLI is invoked from a known coding agent environment (such as GitHub Copilot, Claude, Cursor, or others), the detected agent name is recorded. Only the known agent name is sent — no environment variable values or other identifying data are included. This data point is omitted entirely when no known coding agent is detected. |
| 13.6                | Coding agent detection: GitHub Copilot app. | The detector now separately identifies the GitHub Copilot app (the desktop GitHub application acting as an AI agent) as `copilot-app`, in addition to `copilot-cli` when the underlying Copilot CLI environment variables are also present.                                                                                                    |
| 13.5                | AI agent skill usage.                       | Recorded only for Aspire’s own skills and tools. See [AI agent skill usage data](#ai-agent-skill-usage-data).                                                                                                                                                                                                                                  |

### AI agent skill usage data

[Section titled “AI agent skill usage data”](#ai-agent-skill-usage-data)

The agent telemetry hook installed by `aspire agent init` reports a single event each time one of Aspire’s own AI skills or tools is used. Three event types are reported:

* `skill_invocation` — an Aspire skill was invoked, or its `SKILL.md` was read.
* `tool_invocation` — an Aspire MCP tool was called.
* `reference_file_read` — a reference file bundled alongside an Aspire skill was read.

Each event records only a subset of the following low-cardinality, Aspire-owned values (depending on the event type):

| Field           | Description                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| Event type      | One of `skill_invocation`, `tool_invocation`, or `reference_file_read`.                                         |
| Client name     | The agent client that produced the event, for example `copilot-cli`, `claude-code`, or `vscode`.                |
| Session ID      | The agent session identifier (an opaque GUID), used to group events from one session.                           |
| Skill name      | The Aspire skill name, matched against the fixed list of skills Aspire ships (for example `aspire-deployment`). |
| Tool name       | The Aspire MCP tool name (for example `aspire-list_resources`).                                                 |
| File reference  | The skill-relative path of a reference file, for example `aspire/references/deploy.md`.                         |
| Event timestamp | The UTC time the event occurred.                                                                                |

To protect your privacy, the hook only forwards an event when the skill or tool name matches the fixed set Aspire ships, and a file reference is reported only as the path **after** the skill folder. Absolute paths, repository names, user names, file contents, and tool arguments are never recorded. Before sending, the `aspire agent telemetry` command validates each value, discards anything it doesn’t recognize, and honors the same `ASPIRE_CLI_TELEMETRY_OPTOUT` opt-out.

## See also

[Section titled “See also”](#see-also)

* [Aspire CLI overview](/reference/cli/overview/)

# Aspire CLI overview

> Overview of the Aspire CLI, the cross-platform terminal tool for creating, running, and deploying Aspire AppHost projects from your shell.

The Aspire CLI (`aspire` command) is a cross-platform tool that provides command-line functionality to create, manage, run, and publish multi-language Aspire projects. Use the Aspire CLI to streamline development workflows and coordinate services for distributed applications.

Use trusted repositories

Only run Aspire CLI commands from repositories and directories that you trust.

The Aspire CLI is an interactive-first experience.

[Install the Aspire CLI](/get-started/install-cli/)Get started by installing the Aspire CLI on your machine.

[Review install script reference](../install-script/)Explore the details of the install script with reference.

## Use templates

[Section titled “Use templates”](#use-templates)

The `aspire new` command is an interactive-first CLI experience, and is used to create one or more Aspire projects. As part of creating a project, Aspire CLI ensures that the latest Aspire project templates are installed into the `dotnet` system.

Use the `aspire new` command to create an Aspire project from a list of templates. Once a template is selected, the name of the project is set, and the output folder is chosen, `aspire` downloads the latest templates and generates one or more projects.

[Command reference: `aspire new`](../commands/aspire-new/)

While command-line parameters can be used to automate the creation of an Aspire project, the Aspire CLI is an interactive-first experience.

## Initialize existing repos and workspaces

[Section titled “Initialize existing repos and workspaces”](#initialize-existing-repos-and-workspaces)

The `aspire init` command adds Aspire support to an existing repo or workspace. It can scaffold a C# or TypeScript AppHost, making it easy to adopt Aspire incrementally without creating an entirely new project structure.

The command analyzes your existing repo or workspace and creates the AppHost and initial configuration needed for the path you choose.

[Command reference: `aspire init`](../commands/aspire-init/)

## Start the Aspire AppHost

[Section titled “Start the Aspire AppHost”](#start-the-aspire-apphost)

The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the AppHost, launches the web dashboard, and prints a list of endpoints.

When `aspire run` starts, it searches the current directory for an AppHost project. If a project isn’t found, the subdirectories are searched until one is found. If no AppHost project is found, Aspire stops. Once a project is found, Aspire CLI takes the following steps:

1. Installs or verifies that Aspire’s local hosting certificates are installed and trusted.
2. Builds the AppHost project and its resources.
3. Starts the AppHost and its resources.
4. Starts the dashboard.

The following snippet is an example of the output displayed by the `aspire run` command:

Aspire CLI

```bash
Dashboard:  https://localhost:17244/login?t=9db79f2885dae24ee06c6ef10290b8b2


    Logs:  /home/vscode/.aspire/cli/logs/apphost-5932-2025-08-25-18-37-31.log


        Press CTRL+C to stop the apphost and exit.
```

[Command reference: `aspire run`](../commands/aspire-run/)

## Add integrations

[Section titled “Add integrations”](#add-integrations)

The `aspire add` command is an easy way to add official integration packages to your AppHost project. Use this as an alternative to a NuGet search through your IDE. You can run `aspire add ` if you know the name or NuGet ID of the integration package. If you omit a name or ID, the tool provides a list of packages to choose from. If you provide a partial name or ID, the tool filters the list of packages with items that match the provided value.

[Command reference: `aspire add`](../commands/aspire-add/)

## Update Aspire packages

[Section titled “Update Aspire packages”](#update-aspire-packages)

The `aspire update` command helps you keep your Aspire projects current by automatically detecting and updating outdated packages and templates. It finds outdated Aspire NuGet packages while respecting channel configurations and intelligently handles complex dependency graphs.

The command validates package compatibility before applying changes and provides detailed output showing which packages were updated.

[Command reference: `aspire update`](../commands/aspire-update/)

## Publish Aspire applications

[Section titled “Publish Aspire applications”](#publish-aspire-applications)

The `aspire publish` command publishes resources by serializing them to disk. When this command is run, Aspire executes the publish pipeline step, and any dependent steps, registered in the app model. These steps serialize resources so that they can be consumed by deployment tools.

Some integrations automatically register publishing pipeline steps for you, for example:

* `AzureEnvironmentResource` generates Bicep assets
* `DockerComposeEnvironmentResource` generates docker-compose YAML
* `KubernetesEnvironmentResource` generates Kubernetes Helm charts

[Command reference: `aspire publish`](../commands/aspire-publish/)

## Deploy Aspire solutions

[Section titled “Deploy Aspire solutions”](#deploy-aspire-solutions)

The `aspire deploy` command invokes the `deploy` pipeline step and any dependent steps (such as the `publish` step) registered in the app model.

Tip

Consider this a good way to deploy your Aspire solution to a staging or testing environment.

[Command reference: `aspire deploy`](../commands/aspire-deploy/)

## Destroy deployed environments

[Section titled “Destroy deployed environments”](#destroy-deployed-environments)

The `aspire destroy` command tears down an environment that was previously deployed with `aspire deploy`. It completes the deployment lifecycle: `aspire publish` → `aspire deploy` → `aspire destroy`.

Each compute environment implements its own destroy step with contextual confirmation before removing resources. Pass `--yes` to skip the confirmation prompt in automated environments.

[Command reference: `aspire destroy`](../commands/aspire-destroy/)

## Execute pipeline steps

[Section titled “Execute pipeline steps”](#execute-pipeline-steps)

The `aspire do` command executes a specific pipeline step and its dependencies in your Aspire AppHost. This provides fine-grained control over the orchestration pipeline, allowing you to run individual steps of the deployment or build process without executing the entire pipeline.

Use this command to test individual pipeline stages during development or to execute only the dependencies needed for a particular step.

[Command reference: `aspire do`](../commands/aspire-do/)

## Restore AppHost dependencies

[Section titled “Restore AppHost dependencies”](#restore-apphost-dependencies)

The `aspire restore` command restores dependencies and generates the SDK code your AppHost needs before you build, run, or automate the application. Use it as an explicit restore step in CI/CD pipelines or after changing integrations and resources.

[Command reference: `aspire restore`](../commands/aspire-restore/)

## Start the AppHost in the background

[Section titled “Start the AppHost in the background”](#start-the-apphost-in-the-background)

The `aspire start` command starts an AppHost in the background and returns once it is running. Use it when you want a detached apphost without staying attached to the interactive `aspire run` session.

[Command reference: `aspire start`](../commands/aspire-start/)

## Stop a running AppHost

[Section titled “Stop a running AppHost”](#stop-a-running-apphost)

The `aspire stop` command stops a running Aspire AppHost process. When multiple AppHosts are running, the command prompts you to select which one to stop, or you can use `--all` to stop them all at once.

[Command reference: `aspire stop`](../commands/aspire-stop/)

## List running AppHosts

[Section titled “List running AppHosts”](#list-running-apphosts)

The `aspire ps` command lists all running Aspire AppHost processes. The output includes the AppHost project path, process IDs, and dashboard URLs for each running instance. Use `--format Json` for machine-readable output suitable for scripting and automation.

[Command reference: `aspire ps`](../commands/aspire-ps/)

## Wait for resource readiness

[Section titled “Wait for resource readiness”](#wait-for-resource-readiness)

The `aspire wait` command blocks until a named resource within a running AppHost reaches a target status such as `healthy`, `up`, or `down`. This is useful for CI/CD pipelines and automation workflows where you need to wait for resources to be ready after starting an AppHost in the background.

[Command reference: `aspire wait`](../commands/aspire-wait/)

## Run resource commands

[Section titled “Run resource commands”](#run-resource-commands)

The `aspire resource` command executes a command exposed by a resource in a running AppHost, such as `start`, `stop`, or `restart`. Use it when you need to manage an individual resource directly from the terminal.

[Command reference: `aspire resource`](../commands/aspire-resource/)

## Inspect runtime data

[Section titled “Inspect runtime data”](#inspect-runtime-data)

Use `aspire describe`, `aspire logs`, and `aspire export` to inspect resources, stream logs, and package telemetry and resource data from a running AppHost. Use `aspire otel` to view OpenTelemetry data—structured logs, distributed trace spans, and trace summaries—collected by the Aspire Dashboard directly from the terminal. Together, these commands give you a CLI-first workflow for monitoring and collecting diagnostics.

[Command reference: `aspire describe`](../commands/aspire-describe/), [Command reference: `aspire logs`](../commands/aspire-logs/), [Command reference: `aspire export`](../commands/aspire-export/), and [Command reference: `aspire otel`](../commands/aspire-otel/)

Use the `--search` option with `aspire logs` and `aspire otel` commands to filter output by matching text against log content and trace/span fields. Search supports free-text fragments, structured `field:value` qualifiers, negation, and comparison operators.

[Search and filter](../search-filter/)

## Diagnose and prepare the environment

[Section titled “Diagnose and prepare the environment”](#diagnose-and-prepare-the-environment)

Use `aspire doctor` to verify that your environment is ready for Aspire development, and `aspire certs` to manage the HTTPS development certificates used by local resources and dashboards.

[Command reference: `aspire doctor`](../commands/aspire-doctor/) and [Command reference: `aspire certs`](../commands/aspire-certs/)

## Work with MCP tools

[Section titled “Work with MCP tools”](#work-with-mcp-tools)

The `aspire mcp` command lets you list and call MCP tools exposed by running resources. If you need to start the MCP server used by compatible AI agents, use `aspire agent mcp`.

[Command reference: `aspire mcp`](../commands/aspire-mcp/) and [Command reference: `aspire agent mcp`](../commands/aspire-agent-mcp/)

## Manage CLI configuration

[Section titled “Manage CLI configuration”](#manage-cli-configuration)

The `aspire config` command lets you manage Aspire CLI configuration settings. Use it to `list`, `get`, `set`, or `delete` configuration values that control CLI behavior. This command is also used to toggle features on or off.

[Command reference: `aspire config`](../commands/aspire-config/)

## Manage secrets

[Section titled “Manage secrets”](#manage-secrets)

The `aspire secret` command manages user secrets for an Aspire AppHost project. User secrets provide a safe way to store sensitive configuration values—such as passwords, API keys, and connection strings—outside of your project files during local development.

Aspire uses user secrets to persist values that resources need across restarts, such as auto-generated passwords for database containers.

[Command reference: `aspire secret`](../commands/aspire-secret/)

## Browse documentation

[Section titled “Browse documentation”](#browse-documentation)

The `aspire docs` command lets you browse and search the official Aspire documentation directly from the terminal. You can list all available pages, search for specific topics by keyword, or retrieve the full content of a page by its slug—all without leaving your development workflow.

[Command reference: `aspire docs`](../commands/aspire-docs/)

## Manage CLI cache

[Section titled “Manage CLI cache”](#manage-cli-cache)

The `aspire cache` command manages the disk cache used by the Aspire CLI. The CLI caches data such as downloaded templates, NuGet package information, and other temporary files to improve performance and reduce network requests.

Use `aspire cache clear` to remove all cached data. This is useful when troubleshooting CLI issues, freeing up disk space, or ensuring fresh data after updating the CLI.

[Command reference: `aspire cache`](../commands/aspire-cache/)

# Search and filter telemetry data in the Aspire CLI

> Learn how to use the --search option to filter logs, traces, and spans in the Aspire CLI.

The `--search` option filters output by matching against text and attributes on returned data. Search is supported by these commands:

* [`aspire logs`](../commands/aspire-logs/)
* [`aspire otel logs`](../commands/aspire-otel-logs/)
* [`aspire otel spans`](../commands/aspire-otel-spans/)
* [`aspire otel traces`](../commands/aspire-otel-traces/)

For example, to filter console logs for a specific resource by text:

Aspire CLI

```bash
aspire logs redis --search "timeout"
```

## Search syntax

[Section titled “Search syntax”](#search-syntax)

Search queries support free-text fragments, field qualifiers, attribute qualifiers, negation, and comparison operators.

| Syntax                                                              | Meaning                                                           | Example                       |
| ------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------- |
| `word`                                                              | Free-text fragment — must appear in at least one searchable field | `timeout`                     |
| `"quoted phrase"`                                                   | Single fragment containing spaces                                 | `"connection refused"`        |
| `field:value`                                                       | Field qualifier — value must match the named field                | `severity:error`              |
| `field:"value with spaces"`                                         | Quoted field qualifier value                                      | `message:"connection failed"` |
| `@attr:value`                                                       | Attribute qualifier — matches custom span/log attributes          | `@http.method:GET`            |
| `-field:value` / `-@attr:value`                                     | Negated qualifier — excludes matches                              | `-severity:debug`             |
| `field:>value` / `field:>=value` / `field:100`               |

All terms are AND’d: every fragment and qualifier must independently match.

## Timestamp qualifier

[Section titled “Timestamp qualifier”](#timestamp-qualifier)

Use the `timestamp` field qualifier to narrow structured logs, traces, and spans to a specific date/time range. The qualifier accepts ISO 8601 date or date/time strings together with a comparison operator:

Aspire CLI

```bash
aspire otel logs --search "timestamp:>2026-01-15T09:30:00"
aspire otel traces --search "timestamp:<=2026-06-01T12:00:00Z"
aspire otel spans --search "timestamp:>=2026-01-01 timestamp:<2027-01-01"
```

The supported comparison operators are `>`, `>=`, `<`, and `<=`.

Timestamp values are internally stored in UTC. The `timestamp` value is converted to UTC using these timezone rules:

* A value with no timezone suffix (for example `2026-01-15` or `2026-01-15T09:30:00`) is treated as local time on the dashboard server and adjusted to UTC before comparison.
* A value with a UTC offset (for example `2026-06-01T12:00:00+05:00`) is adjusted to UTC before comparison.
* A value with the `Z` suffix is treated as UTC directly.

## Console logs

[Section titled “Console logs”](#console-logs)

Matches against log line text content and resource name. Only free-text is supported (no structured qualifiers).

Aspire CLI

```bash
aspire logs redis --search "timeout"
aspire logs --follow --search "\"connection error\""
```

## Structured logs

[Section titled “Structured logs”](#structured-logs)

Supports free-text and structured qualifiers. Free-text matches against message, resource name, scope, trace/span IDs, severity, and all attribute keys/values.

Available field qualifiers: `severity`, `resource`, `scope`, `message`, `trace-id`, `span-id`, `event`, `timestamp`.

Aspire CLI

```bash
aspire otel logs --search "severity:error \"connection failed\""
aspire otel logs --search "resource:api -severity:debug"
aspire otel logs --search "scope:Microsoft.EntityFrameworkCore"
aspire otel logs --search "timestamp:>=2026-06-01T12:00:00 severity:error"
```

## Traces

[Section titled “Traces”](#traces)

Supports free-text and structured qualifiers. Free-text matches against trace name, resource name, and all span fields within the trace.

Available field qualifiers: `name`, `resource`, `trace-id`, `status`, `duration`, `timestamp`.

Aspire CLI

```bash
aspire otel traces --search "checkout"
aspire otel traces --search "status:error duration:>500"
aspire otel traces --search "@http.status_code:500"
aspire otel traces --search "timestamp:>2026-01-15T09:30:00 status:error"
```

## Spans

[Section titled “Spans”](#spans)

Supports free-text and structured qualifiers. Free-text matches against span name, resource name, scope, trace/span IDs, status, kind, and all attribute keys/values.

Available field qualifiers: `name`, `resource`, `scope`, `status`, `kind`, `trace-id`, `span-id`, `duration`, `timestamp`.

Aspire CLI

```bash
aspire otel spans --search "@http.method:GET duration:>100 status:error"
aspire otel spans --search "@db.system:postgresql"
aspire otel spans --search "-kind:internal"
aspire otel spans --search "timestamp:>=2026-03-01T08:30:00 kind:server"
```

## See also

[Section titled “See also”](#see-also)

* [Command reference: `aspire logs`](../commands/aspire-logs/)
* [Command reference: `aspire otel logs`](../commands/aspire-otel-logs/)
* [Command reference: `aspire otel spans`](../commands/aspire-otel-spans/)
* [Command reference: `aspire otel traces`](../commands/aspire-otel-traces/)

# Container images

> A complete reference of every container image used by Aspire hosting integrations — grouped by category, with registry, tag, and the AppHost API that introduces each.

Every Aspire hosting integration that runs a container declares its default image, tag, and registry in source. This page catalogs all of them in one place — grouped by integration category — so you can see exactly what Aspire pulls, from which registry, and which AppHost API introduces each image.

**34** container images across **24** hosting integrations and **5** registries.

## Databases13

* Milvus

  `docker.io/milvusdb/milvus:v2.5.27`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/milvusdb/milvus)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Milvus/MilvusContainerImageTags.cs)

  [Integration docs](/integrations/databases/milvus/milvus-get-started/)

* AttuCompanion · Milvus

  `docker.io/zilliz/attu:v2.5`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/zilliz/attu)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Milvus/MilvusContainerImageTags.cs)

  [Integration docs](/integrations/databases/milvus/milvus-get-started/)

* MongoDB

  `docker.io/library/mongo:8.3`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/_/mongo)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.MongoDB/MongoDBContainerImageTags.cs)

  [Integration docs](/integrations/databases/mongodb/mongodb-get-started/)

* Mongo ExpressCompanion · MongoDB

  `docker.io/library/mongo-express:1.0`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/_/mongo-express)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.MongoDB/MongoDBContainerImageTags.cs)

  [Integration docs](/integrations/databases/mongodb/mongodb-get-started/)

* MySQL

  `docker.io/library/mysql:9.7`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/_/mysql)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.MySql/MySqlContainerImageTags.cs)

  [Integration docs](/integrations/databases/mysql/mysql-get-started/)

* phpMyAdminCompanion · MySQL

  `docker.io/library/phpmyadmin:5.2`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/_/phpmyadmin)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.MySql/MySqlContainerImageTags.cs)

  [Integration docs](/integrations/databases/mysql/mysql-get-started/)

* Oracle Database

  `container-registry.oracle.com/database/free:23.26.1.0`

  [Oracle Container Registry](https://container-registry.oracle.com/ords/ocr/ba/database/free)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Oracle/OracleContainerImageTags.cs)

  [Integration docs](/integrations/databases/efcore/oracle/oracle-get-started/)

* PostgreSQL

  `docker.io/library/postgres:18.3`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/_/postgres)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.PostgreSQL/PostgresContainerImageTags.cs)

  [Integration docs](/integrations/databases/postgres/postgres-get-started/)

* Postgres MCPCompanion · PostgreSQL

  `docker.io/crystaldba/postgres-mcp:0.3.0`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/crystaldba/postgres-mcp)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.PostgreSQL/PostgresContainerImageTags.cs)

  [Integration docs](/integrations/databases/postgres/postgres-get-started/)

* pgAdminCompanion · PostgreSQL

  `docker.io/dpage/pgadmin4:9.15.0`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/dpage/pgadmin4)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.PostgreSQL/PostgresContainerImageTags.cs)

  [Integration docs](/integrations/databases/postgres/postgres-get-started/)

* pgwebCompanion · PostgreSQL

  `docker.io/sosedoff/pgweb:0.17.0`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/sosedoff/pgweb)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.PostgreSQL/PostgresContainerImageTags.cs)

  [Integration docs](/integrations/databases/postgres/postgres-get-started/)

* Qdrant

  `docker.io/qdrant/qdrant:v1.18.0`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/qdrant/qdrant)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Qdrant/QdrantContainerImageTags.cs)

  [Integration docs](/integrations/databases/qdrant/qdrant-get-started/)

* SQL Server

  `mcr.microsoft.com/mssql/server:2022-latest`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/mssql/server/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.SqlServer/SqlServerContainerImageTags.cs)

  [Integration docs](/integrations/databases/sql-server/sql-server-get-started/)

## Caching5

* Garnet

  `ghcr.io/microsoft/garnet:1.0`

  [GitHub Container Registry](https://github.com/microsoft/garnet/pkgs/container/garnet)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Garnet/GarnetContainerImageTags.cs)

  [Integration docs](/integrations/caching/garnet/garnet-get-started/)

* Redis

  `docker.io/library/redis:8.6`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/_/redis)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Redis/RedisContainerImageTags.cs)

  [Integration docs](/integrations/caching/redis/redis-get-started/)

* Redis CommanderCompanion · Redis

  `ghcr.io/joeferner/redis-commander:latest`

  [GitHub Container Registry](https://github.com/joeferner/redis-commander/pkgs/container/redis-commander)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Redis/RedisContainerImageTags.cs)

  [Integration docs](/integrations/caching/redis/redis-get-started/)

* RedisInsightCompanion · Redis

  `docker.io/redis/redisinsight:3.4`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/redis/redisinsight)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Redis/RedisContainerImageTags.cs)

  [Integration docs](/integrations/caching/redis/redis-get-started/)

* Valkey

  `docker.io/valkey/valkey:9.1`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/valkey/valkey)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Valkey/ValkeyContainerImageTags.cs)

  [Integration docs](/integrations/caching/valkey/valkey-get-started/)

## Messaging4

* Kafka

  `docker.io/confluentinc/confluent-local:8.2.0`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/confluentinc/confluent-local)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Kafka/KafkaContainerImageTags.cs)

  [Integration docs](/integrations/messaging/apache-kafka/apache-kafka-get-started/)

* Kafka UICompanion · Kafka

  `docker.io/kafbat/kafka-ui:v1.5.0`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/kafbat/kafka-ui)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Kafka/KafkaContainerImageTags.cs)

  [Integration docs](/integrations/messaging/apache-kafka/apache-kafka-get-started/)

* NATS

  `docker.io/library/nats:2.14`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/_/nats)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Nats/NatsContainerImageTags.cs)

  [Integration docs](/integrations/messaging/nats/nats-get-started/)

* RabbitMQ

  `docker.io/library/rabbitmq:4.3`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/_/rabbitmq)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.RabbitMQ/RabbitMQContainerImageTags.cs)

  Also:`4.3-management`

  [Integration docs](/integrations/messaging/rabbitmq/rabbitmq-get-started/)

## Observability1

* Seq

  `docker.io/datalust/seq:2025.2`

  [![](/_astro/docker.CnL-arqo_BXovm.svg)Docker Hub](https://hub.docker.com/r/datalust/seq)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Seq/SeqContainerImageTags.cs)

  [Integration docs](/integrations/observability/seq/seq-get-started/)

## Security1

* Keycloak

  `quay.io/keycloak/keycloak:26.6`

  [Quay.io](https://quay.io/repository/keycloak/keycloak)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Keycloak/KeycloakContainerImageTags.cs)

  [Integration docs](/integrations/security/keycloak/)

## Reverse proxies1

* YARP

  `mcr.microsoft.com/dotnet/nightly/yarp:2.3-preview`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/dotnet/nightly/yarp/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Yarp/YarpContainerImageTags.cs)

  [Integration docs](/integrations/reverse-proxies/yarp/)

## Azure emulators9

* App Configuration Emulator

  `mcr.microsoft.com/azure-app-configuration/app-configuration-emulator:1.2.0`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/azure-app-configuration/app-configuration-emulator/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Azure.AppConfiguration/AppConfigurationEmulatorContainerImageTags.cs)

  [Integration docs](/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started/)

* CosmosDB Emulator

  `mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/cosmosdb/linux/azure-cosmos-emulator/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Azure.CosmosDB/CosmosDBEmulatorContainerImageTags.cs)

  Also:`stable`

  [Integration docs](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started/)

* Event Hubs Emulator

  `mcr.microsoft.com/azure-messaging/eventhubs-emulator:2.2.0`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/azure-messaging/eventhubs-emulator/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Azure.EventHubs/EventHubsEmulatorContainerImageTags.cs)

  [Integration docs](/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/)

* Durable Task Scheduler Emulator

  `mcr.microsoft.com/dts/dts-emulator:latest`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/dts/dts-emulator/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Azure.Functions/DurableTask/DurableTaskSchedulerEmulatorContainerImageTags.cs)

  [Integration docs](/integrations/cloud/azure/azure-functions/azure-functions-get-started/)

* Azure Kusto Emulator

  `mcr.microsoft.com/azuredataexplorer/kustainer-linux:2026.03.16.1116-2611-994a3c9-master`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/azuredataexplorer/kustainer-linux/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Azure.Kusto/AzureKustoEmulatorContainerImageTags.cs)

  [Integration docs](/integrations/cloud/azure/azure-data-explorer/)

* Service Bus Emulator

  `mcr.microsoft.com/azure-messaging/servicebus-emulator:2.0.0`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/azure-messaging/servicebus-emulator/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Azure.ServiceBus/ServiceBusEmulatorContainerImageTags.cs)

  [Integration docs](/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/)

* SQL ServerCompanion · Service Bus Emulator

  `mcr.microsoft.com/mssql/server:2022-latest`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/mssql/server/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Azure.ServiceBus/ServiceBusEmulatorContainerImageTags.cs)

  [Integration docs](/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/)

* SignalR Emulator

  `mcr.microsoft.com/signalr/signalr-emulator:latest`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/signalr/signalr-emulator/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Azure.SignalR/SignalREmulatorContainerImageTags.cs)

  [Integration docs](/integrations/cloud/azure/azure-signalr/azure-signalr-get-started/)

* Storage Emulator

  `mcr.microsoft.com/azure-storage/azurite:3.35.0`

  [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/azure-storage/azurite/about)[Source](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Azure.Storage/StorageEmulatorContainerImageTags.cs)

  [Integration docs](/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started/)

Tags reflect the latest defaults on the microsoft/aspire **main** branch, and may be newer than the version pinned by the package you install. Companion images (management UIs, emulator dependencies) are listed under the integration that ships them.

# Aspire Reference

> Comprehensive reference documentation for Aspire — CLI tools, APIs, and command-line reference materials.

The tools you need, at your fingertips.

From the interactive CLI to the full API surface — everything you need to build, run, and deploy Aspire applications is documented here.

[CLI overview](/reference/cli/overview/)[Browse samples](/reference/samples/)

## The Aspire CLI

[Section titled “The Aspire CLI”](#the-aspire-cli)

The `aspire` CLI is a cross-platform, interactive-first tool that manages the full lifecycle of your distributed applications — from scaffolding to deployment.

## Create, run, and deploy from one tool.

The aspire CLI scaffolds projects from templates, orchestrates multi-service apps, publishes deployment artifacts, and deploys to cloud environments — all with a single, intuitive command-line experience.

[View full CLI reference](/reference/cli/overview/)

Terminal

## Core commands

[Section titled “Core commands”](#core-commands)

Every `aspire` command is designed to be discoverable and interactive. Pass `--help` to any command for inline documentation.

### [aspire new](/reference/cli/commands/aspire-new/)

[Scaffold a new Aspire project from a rich library of templates. Interactive prompts guide you through every option.](/reference/cli/commands/aspire-new/)

[Learn more ](/reference/cli/commands/aspire-new/)

### [aspire run](/reference/cli/commands/aspire-run/)

[Start your entire distributed application locally. The dashboard launches automatically for real-time monitoring.](/reference/cli/commands/aspire-run/)

[Learn more ](/reference/cli/commands/aspire-run/)

### [aspire publish](/reference/cli/commands/aspire-publish/)

[Generate deployment artifacts — Docker Compose, Kubernetes manifests, Bicep, and more — with parameterized secrets.](/reference/cli/commands/aspire-publish/)

[Learn more ](/reference/cli/commands/aspire-publish/)

### [aspire deploy](/reference/cli/commands/aspire-deploy/)

[Resolve parameters and execute a deployment to your target environment. Works with Azure, Docker, and custom integrations.](/reference/cli/commands/aspire-deploy/)

[Learn more ](/reference/cli/commands/aspire-deploy/)

### [aspire init](/reference/cli/commands/aspire-init/)

[Add Aspire orchestration to an existing repo with a C# or TypeScript AppHost. Creates the AppHost and wires up the initial configuration.](/reference/cli/commands/aspire-init/)

[Learn more ](/reference/cli/commands/aspire-init/)

### [aspire doctor](/reference/cli/commands/aspire-doctor/)

[Diagnose your development environment. Checks SDKs, container runtimes, and environment settings.](/reference/cli/commands/aspire-doctor/)

[Learn more ](/reference/cli/commands/aspire-doctor/)

## More commands

[Section titled “More commands”](#more-commands)

### [aspire add](/reference/cli/commands/aspire-add/)

[Add integrations and resources to your AppHost project interactively.](/reference/cli/commands/aspire-add/)

[Learn more ](/reference/cli/commands/aspire-add/)

### [aspire ps](/reference/cli/commands/aspire-ps/)

[List all running Aspire processes and their status.](/reference/cli/commands/aspire-ps/)

[Learn more ](/reference/cli/commands/aspire-ps/)

### [aspire stop](/reference/cli/commands/aspire-stop/)

[Gracefully stop a running Aspire application.](/reference/cli/commands/aspire-stop/)

[Learn more ](/reference/cli/commands/aspire-stop/)

### [aspire resource](/reference/cli/commands/aspire-resource/)

[Execute a command exposed by a resource in a running Aspire apphost.](/reference/cli/commands/aspire-resource/)

[Learn more ](/reference/cli/commands/aspire-resource/)

### [aspire config](/reference/cli/commands/aspire-config/)

[Get, set, list, and manage CLI configuration values.](/reference/cli/commands/aspire-config/)

[Learn more ](/reference/cli/commands/aspire-config/)

### [aspire agent](/reference/cli/commands/aspire-agent/)

[Initialize and configure AI agent support, including the MCP server.](/reference/cli/commands/aspire-agent/)

[Learn more ](/reference/cli/commands/aspire-agent/)

## Docs and API reference commands

[Section titled “Docs and API reference commands”](#docs-and-api-reference-commands)

Use the `aspire docs` and `aspire docs api` command groups to browse, search, and retrieve Aspire documentation and API reference content without leaving the terminal.

### [aspire docs](/reference/cli/commands/aspire-docs/)

[Browse and search Aspire documentation from aspire.dev, right from your terminal.](/reference/cli/commands/aspire-docs/)

[Learn more ](/reference/cli/commands/aspire-docs/)

### [aspire docs search](/reference/cli/commands/aspire-docs-search/)

[Search Aspire documentation pages by keyword and get ranked, relevant results.](/reference/cli/commands/aspire-docs-search/)

[Learn more ](/reference/cli/commands/aspire-docs-search/)

### [aspire docs get](/reference/cli/commands/aspire-docs-get/)

[Retrieve the full content of a documentation page by its slug.](/reference/cli/commands/aspire-docs-get/)

[Learn more ](/reference/cli/commands/aspire-docs-get/)

### [aspire docs api](/reference/cli/commands/aspire-docs-api/)

[Browse, search, and retrieve Aspire API reference documentation from aspire.dev.](/reference/cli/commands/aspire-docs-api/)

[Learn more ](/reference/cli/commands/aspire-docs-api/)

### [aspire docs api search](/reference/cli/commands/aspire-docs-api-search/)

[Search Aspire API reference entries, including types, methods, and members, by keyword.](/reference/cli/commands/aspire-docs-api-search/)

[Learn more ](/reference/cli/commands/aspire-docs-api-search/)

### [aspire docs api get](/reference/cli/commands/aspire-docs-api-get/)

[Get the full content of a specific API reference entry by identifier.](/reference/cli/commands/aspire-docs-api-get/)

[Learn more ](/reference/cli/commands/aspire-docs-api-get/)

Give AI coding agents current Aspire context

The `aspire docs` commands give AI coding agents current guidance from aspire.dev. The `aspire docs api` commands provide package, type, and member reference content. Install [Aspire skills](/get-started/aspire-skills/) and follow [Use AI coding agents](/get-started/ai-coding-agents/) to help agents choose the right commands and verify changes with application evidence.

## API reference

[Section titled “API reference”](#api-reference)

### [Search C# APIs](/reference/api/csharp/)

[A searchable interface to explore all Aspire C# APIs, types, and members across every Aspire package. Find exactly the type or method you need.](/reference/api/csharp/)

[Search C# APIs](/reference/api/csharp/)

### [Search TypeScript APIs](/reference/api/typescript/)

[Explore the full TypeScript API surface for Aspire — from core SDK types to CLI configuration interfaces. Searchable and cross-referenced for easy discovery.](/reference/api/typescript/)

[Search TypeScript APIs](/reference/api/typescript/)

### [CLI configuration](/reference/cli/configuration/)

[Customize CLI behavior, default templates, telemetry, and more with per-user and per-project configuration.](/reference/cli/configuration/)

[View config options](/reference/cli/configuration/)

### [Install script reference](/reference/cli/install-script/)

[Detailed reference for the cross-platform Aspire CLI install script — options, parameters, and automation scenarios.](/reference/cli/install-script/)

[Script reference](/reference/cli/install-script/)

## Samples

[Section titled “Samples”](#samples)

Explore fully functional sample projects that demonstrate real-world patterns and best practices with Aspire — from e-commerce apps with databases and caching, to multi-language integrations with JavaScript and Python, to cloud deployments with Azure Functions.

### [Browse all samples](/reference/samples/)

[Filter by technology, language, or feature to find the perfect starting point for your next project. Each sample links directly to its GitHub repository for easy cloning.](/reference/samples/)

[View samples](/reference/samples/)

## Diagnostics

[Section titled “Diagnostics”](#diagnostics)

Every diagnostic Aspire emits falls into one of two categories. Both help you catch issues early — before they become runtime problems.

### [Warnings](/diagnostics/overview/)

[Non-blocking issues that flag potential problems — unsupported languages, experimental APIs, and configuration suggestions that keep your project on the right track.](/diagnostics/overview/)

[Learn more ](/diagnostics/overview/)

### [Errors](/diagnostics/overview/)

[Blocking issues that must be resolved — missing SDK references, invalid resource names, and API usage violations that prevent your app from building correctly.](/diagnostics/overview/)

[Learn more ](/diagnostics/overview/)

## Ready to get hands-on?

Install the CLI and start building your first distributed application in minutes.

[Install the Aspire CLI](/get-started/install-cli/)[Build your first app](/get-started/first-app/)

# Samples

> Explore Aspire sample projects — fully functional apps demonstrating real-world patterns, integrations, and best practices.

Explore a curated collection of official Aspire sample projects. Each sample is a fully functional application you can clone and run to learn patterns for databases, messaging, cloud services, and more.

Search samplesSearch samples…

Azure4Azure Functions1Azure Storage2Blazor3Containers1C#19Dashboard17Databases11Docker16EF Core4Go2Grafana1gRPC2Health Checks7Java1JavaScript8Metrics9Migrations3MySQL1Node.js12Orleans1PostgreSQL7Prometheus1Python7RabbitMQ1Redis5SQL Server4TypeScript16Volumes2

Show all 29 tags

29samplesClear filtersReset all

![Screenshot of the Aspire Shop sample](/_astro/aspireshop-frontend-dark.CODo7EHP_1Szq62.webp)

## [Aspire Shop](/reference/samples/aspire-shop/)

Browse a product catalog served by the Catalog service and add items to a cart held by the Basket service. Built with Aspire.

The app consists of four .NET services: AspireShop.Frontend: This is an ASP.NET Core Blazor app that displays a paginated catalog of products and allows users to add products to a shopping cart. AspireShop.CatalogService: This is an HTTP API that provides access to the catalog of products stored in a PostgreSQL database. AspireShop.CatalogDbManager: This is an HTTP API that manages the initialization and updating of the catalog database. AspireShop.BasketService: This is a gRPC service that provides access to the shopping cart stored in Redis. The app also includes a .NET class library project, AspireShop.ServiceDefaults, that contains the code-based defaults used by the .NET service projects.

Read more…

BlazorC#DatabasesgRPCPostgreSQL+1

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/aspire-shop)

![Screenshot of the Image Gallery sample](/_astro/aspire-with-functions.C_ro9zlf_ZJCOBi.webp)

## [Image Gallery](/reference/samples/aspire-with-azure-functions/)

The app consists of two services: ImageGallery.Frontend: This is a Blazor app that displays a for uploading of images, showing thumbnails of images in a grid. ImageGallery.Functions: This is an Azure Function triggered by the arrival of a new blob using a Functions Blob Trigger.

The app also includes a class library project, ImageGallery.ServiceDefaults, that contains the service defaults used by the service projects, and the ImageGallery.AppHost Aspire AppHost project.

Read more…

AzureAzure FunctionsBlazorC#

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/aspire-with-azure-functions)

![Screenshot of the Integrating Angular, React, and Vue with Aspire sample](/_astro/aspire-dashboard-dark.-t972p3u_Z2cqWwY.webp)

## [Integrating Angular, React, and Vue with Aspire](/reference/samples/aspire-with-javascript/)

This sample demonstrates using the Aspire JavaScript hosting integration to configure and run client-side applications.

The app consists of five services: AspireJavaScript.MinimalApi: This is an HTTP API that returns randomly generated weather forecast data. AspireJavaScript.Angular: An Angular app that consumes the weather forecast API and displays it with a featured-day hero and supporting day cards. AspireJavaScript.React: A React app (Webpack) that consumes the weather forecast API and displays the forecast. AspireJavaScript.Vue: A Vue app that consumes the weather forecast API and presents the forecast as a swipeable, keyboard-navigable day-by-day carousel. AspireJavaScript.Vite: A React + Vite + TypeScript app that consumes the weather forecast API and displays the forecast. The four front ends all render the same weather data, but each one wears a completely different design identity — the point of the sample is to compare the frameworks side by side, so we lean into that contrast: Every front end is keyboard operable, ships a skip link, announces async state with aria-live, honors prefers-reduced-motion and prefers-color-scheme, and passes an automated axe-core accessibility scan in both light and dark themes.

Read more…

C#DashboardJavaScriptNode.jsTypeScript

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/aspire-with-javascript)

![Screenshot of the Node.js weather explorer with Aspire sample](/_astro/aspire-with-node-primary-page-dark.DNZr_Q_V_Bx4KU.webp)

## [Node.js weather explorer with Aspire](/reference/samples/aspire-with-node/)

An interactive weather map backed by an Express + OpenTelemetry API that reads live data from the Open-Meteo external service, all orchestrated by a TypeScript AppHost (apphost.mts).

The sample consists of two apps: api: A TypeScript Express API run directly with tsx. It returns on-demand forecasts and place names by calling Open-Meteo (modeled as an Aspire external service) plus keyless reverse/forward geocoding, and serves an interactive Scalar API reference. OpenTelemetry instrumentation streams traces, metrics, and logs to the Aspire dashboard. frontend: A React 19 + Vite app rendering a full-screen Leaflet map. Click or search any point to load real current conditions, an hourly strip, and a 5-day forecast, with an animated RainViewer radar overlay, switchable basemaps, geolocation, and a °F/°C toggle.

Read more…

DashboardDatabasesHealth ChecksJavaScriptMetrics+2

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/aspire-with-node)

![Screenshot of the Integrating a FastAPI (Python) app within an Aspire application sample](/_astro/aspire-with-python-primary-page-dark.l6yWF_xv_Rt2AS.webp)

## [Integrating a FastAPI (Python) app within an Aspire application](/reference/samples/aspire-with-python/)

This sample demonstrates integrating a FastAPI (Python) app and a JavaScript frontend using Aspire.

The sample consists of two apps: app: This is a simple FastAPI-based Python app that returns randomly generated weather forecast data. frontend: This is a Vite-based React app that renders the weather forecast data.

Read more…

C#JavaScriptNode.jsPython

File-based AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/aspire-with-python)

![Screenshot of the Working with client apps in an Aspire application sample](/_astro/skyline-winforms-dawn.Cg6kT3TF_1I0vmz.webp)

## [Working with client apps in an Aspire application](/reference/samples/client-apps-integration/)

This sample demonstrates working with client apps such as WinForms, WPF, etc., in an Aspire app, such that the client app is launched along with the AppHost project, can resolve services via service discovery, and logs, traces, and metrics are sent via OpenTelemetry to the dashboard.

Both client apps share one Skyline weather-companion identity rendered two ways: the WinForms client in a light Dawn palette and the WPF client in a dark Dusk palette. Each calls the backend weather API, renders the forecast as accessible cards, and streams its logs, traces, and metrics to the Aspire dashboard via OpenTelemetry. The app is based on the Aspire Starter App template, with the following additional elements: ClientAppsIntegration.WinForms: This is a WinForms application that displays the results of calling the weather API service application. ClientAppsIntegration.WPF: This is a WPF application that displays the results of calling the weather API service application. ClientAppsIntegration.AppDefaults: This is a class library that defines the default configuration for orchestrated apps. It's a more general version of the typical ServiceDefaults class library that's included in Aspire apps. The ClientAppsIntegration.WinForms and ClientAppsIntegration.WPF projects reference this project and calls its AddAppDefaults() method. ClientAppsIntegration.ServiceDefaults: This has been modified from the default ServiceDefaults template to be based on and extend the ClientAppsIntegration.AppDefaults class library. The ClientAppsIntegration.ApiService project references this project and calls its AddServiceDefaults() method.

Read more…

C#DashboardMetrics

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/client-apps-integration)

![Screenshot of the Working with container-built resources in an Aspire application sample](/_astro/aspire-dashboard-container-build-dark.DBaDYR4z_Z21SPDf.webp)

## [Working with container-built resources in an Aspire application](/reference/samples/container-build/)

This sample demonstrates integrating applications into an Aspire app via Dockerfiles and container-based builds. This is especially helpful to integrate applications written in languages that Aspire does not have a native integration for, or to reduce the prerequisites required to run the application.

The sample integrates a simple app written using Go and the Gin Web Framework by using a Dockerfile: ginapp: This is a simple "Hello, World" HTTP API that returns a JSON object like { "message": "Hello, World!" } from / and sends OpenTelemetry instrumentation to the Aspire dashboard.

Read more…

C#DashboardDockerGoMetrics

File-based AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/container-build)

## [Writing custom resources for Aspire hosting integrations](/reference/samples/custom-resources/)

This sample demonstrates how to write custom resources for Aspire hosting integrations. This is useful when you want to integrate something into the Aspire development experience as a resource that isn't an executable or container. Custom resources can particpate in the Aspire development experience, including the dashboard, and can be used to integrate with other tools or services. Custom resources are defined using C# and generally consist of a class that implements the IResource interface and some extension methods to enable adding them to an IDistributedApplicationBuilder. Custom resources can publish and respond to events to give them "life" and allow them to interact with the rest of the Aspire application. In this sample, we define a TalkingClock custom resource that spawns child ClockHand resources that tick on and off every second. We also define a TestResource custom resource that simply cycles through a set of states. Read more about the Aspire resource model here.

C#Dashboard

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/custom-resources)

![Screenshot of the Working with database containers in an Aspire application sample](/_astro/database-containers-api-reference.B2KRT6y0_ZcTzJt.webp)

## [Working with database containers in an Aspire application](/reference/samples/database-containers/)

This sample demonstrates working with database containers in an Aspire app, using the features of the underlying container image to modify the default database created during container startup. This is especially helpful when not using an ORM like Entity Framework Core that can run migrations on application startup (e.g., as in the Aspire Shop sample) and handle cases when the database configured in the AppHost is not yet created.

The app uses the following database container types: Microsoft SQL Server MySQL PostgreSQL The app consists of an API service: ContainerDatabases.ApiService: This is an HTTP API that returns data from each of the configured databases.

Read more…

C#DashboardDatabasesDockerEF Core+4

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/database-containers)

## [Database migrations with Entity Framework Core sample app](/reference/samples/database-migrations/)

This sample demonstrates how to use Entity Framework Core's migrations feature with Aspire. The sample has three important projects: DatabaseMigrations.ApiService - A web app that uses the database. DatabaseMigrations.MigrationService - A background worker app that applies migrations when it starts up. DatabaseMigrations.ApiModel - The EF Core context and entity types. This project is used by both the API and migration service. DatabaseMigrations.ApiService and DatabaseMigrations.MigrationService reference a SQL Server resource. During local development the SQL Server resource is launched in a container.

C#DatabasesEF CoreMigrationsPostgreSQL+1

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/database-migrations)

![Screenshot of the Go API with In-Memory Storage sample](/_astro/golang-api.Cq0bp0Vg_Z2i6BXD.webp)

## [Go API with In-Memory Storage](/reference/samples/golang-api/)

REST API built with Go and chi router, using in-memory storage with thread-safe operations. Opening the running app in a browser lands on a themed Scalar API reference\—a polished, Go-cyan developer portal generated from the service's OpenAPI 3.1 document\—while API clients keep receiving JSON.

This sample demonstrates a TypeScript AppHost that runs the Go API directly during local development and switches to a checked-in Dockerfile for Docker Compose publishing.

Read more…

DockerGoHealth ChecksTypeScript

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/golang-api)

![Screenshot of the Configuring health checks & running the ASP.NET Core HealthChecksUI container with Aspire sample](/_astro/healthchecksui.Sk118vSD_1sXiH2.webp)

## [Configuring health checks & running the ASP.NET Core HealthChecksUI container with Aspire](/reference/samples/health-checks-ui/)

This sample demonstrates configuring ASP.NET Core Health Checks and running the ASP.NET Core HealthChecksUI container with Aspire.

The sample is based on the Aspire Starter App project template and thus consists of a frontend web app that communicates with a backend ASP.NET Core API service and a Redis cache. The frontend web app shows the health of the sample's services: a status overview, per-service uptime and latency tiles, a page that runs an on-demand health probe, and a live forecast streamed from the API service. It supports both light and dark themes:

Read more…

AzureC#DashboardDatabasesDocker+2

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/health-checks-ui)

![Screenshot of the Image Gallery with Event-Triggered Azure Container Apps Jobs sample](/_astro/image-gallery-primary-page-dark.BRQre6MB_vATtX.webp)

## [Image Gallery with Event-Triggered Azure Container Apps Jobs](/reference/samples/image-gallery/)

Lumina media library, light theme Lumina media library, dark theme

Upload images to Azure Blob Storage with queue-triggered thumbnail generation. Demonstrates event-driven Container Apps Jobs with queue-based autoscaling, managed identity authentication, and Azure SQL free tier - can run entirely within Azure free tier limits. The Lumina front end is a productized media library built with React, TypeScript, CSS Modules and Heroicons. It ships light and dark themes (honoring prefers-color-scheme), an accessible drag-and-drop upload flow, live thumbnail polling and a keyboard-operable lightbox.

Read more…

AzureAzure StorageC#MetricsNode.js+2

File-based AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/image-gallery)

## [MailDev and MailKit custom integrations](/reference/samples/maildev-mailkit/)

This sample demonstrates how to build custom Aspire hosting and client integrations with Aspire 13.6. The runnable AppHost is written in TypeScript and consumes the C# hosting integration through the Aspire Type System (ATS).

C#DashboardDockerHealth ChecksJavaScript+3

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/maildev-mailkit)

![Screenshot of the Aspire metrics sample app sample](/_astro/dashboard-screenshot.BcH8Y3Qb_NdN7u.webp)

## [Aspire metrics sample app](/reference/samples/metrics/)

This is a simple .NET app that shows off collecting metrics with OpenTelemetry and exporting them to Prometheus and Grafana for reporting.

The instrumented app is a small web UI that emits OpenTelemetry metrics. Click around it — the Weather feed and the Auth Required flow — to generate the request traffic that shows up on the Grafana dashboard above. It supports both light and dark themes:

Read more…

C#DashboardGrafanaMetricsPrometheus

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/Metrics)

![Screenshot of the Node.js Express + Redis + Vite Frontend sample](/_astro/node-express-redis-primary-page-dark.CxY_K2XL_ZFQycr.webp)

## [Node.js Express + Redis + Vite Frontend](/reference/samples/node-express-redis/)

Visit counter with Express backend, Redis caching, and React TypeScript frontend using YARP.

DockerJavaScriptNode.jsRedisTypeScript

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/node-express-redis)

![Screenshot of the Aspire Orleans sample app sample](/_astro/grainpoll-results-dark.BQ_fmCDx_hwxvk.webp)

## [Aspire Orleans sample app](/reference/samples/orleans-voting/)

This is a simple .NET app that shows how to use Orleans with Aspire orchestration.

The voting frontend lets you create a poll, share its link, and vote on it. Vote totals are tracked by an Orleans grain and update in real time across every connected viewer. It supports both light and dark themes. Create a poll, share the link, and watch the votes roll in:

Read more…

C#Orleans

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/orleans-voting)

![Screenshot of the Polyglot Task Queue sample](/_astro/polyglot-task-queue-primary-page-dark.BJetckN2_Z99PS7.webp)

## [Polyglot Task Queue](/reference/samples/polyglot-task-queue/)

Distributed task processing with Python, C#, and Node.js workers using RabbitMQ and end-to-end OpenTelemetry tracing.

DashboardDockerJavaScriptMetricsNode.js+3

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/polyglot-task-queue)

![Screenshot of the Python FastAPI + PostgreSQL Sample sample](/_astro/python-fastapi-postgres.BLzg4yt8_1jFerw.webp)

## [Python FastAPI + PostgreSQL Sample](/reference/samples/python-fastapi-postgres/)

FastAPI REST API with PostgreSQL database using Aspire Python support.

This sample demonstrates Aspire 13's polyglot platform support for Python applications, showcasing a simple CRUD API built with FastAPI and PostgreSQL. It also ships a bespoke, on-brand Scalar API reference as its developer-facing UX — a themed FastAPI/Python developer portal served at /scalar, with the classic Swagger UI still available at /docs.

Read more…

ContainersC#DatabasesDockerHealth Checks+3

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/python-fastapi-postgres)

![Screenshot of the Python OpenAI Agent Sample sample](/_astro/python-openai-agent-primary-page-dark.UC35Nr0X_Z11G7Ta.webp)

## [Python OpenAI Agent Sample](/reference/samples/python-openai-agent/)

\[!NOTE] The screenshots above show a deterministic, stubbed conversation captured for documentation. Live OpenAI responses require your own API key (see below) and were not exercised when these images were generated.

Python FastAPI AI agent with OpenAI integration demonstrating AI workloads with Aspire. This sample demonstrates Aspire 13's Python support combined with AI workloads, showcasing a Python-based AI chat agent powered by OpenAI.

Read more…

DashboardDockerHealth ChecksPythonTypeScript

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/python-openai-agent)

## [Python Script Sample](/reference/samples/python-script/)

Simple Python script demonstrating Aspire's Python integration with automatic virtual environment management. This sample shows how Aspire 13's Python support automatically manages Python applications, including virtual environment creation and dependency installation.

DashboardPythonTypeScript

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/python-script)

![Screenshot of the RAG Document Q\&A with Svelte sample](/_astro/rag-document-qa-svelte-primary-page-dark.rfO08z-L_1mFb0L.webp)

## [RAG Document Q\&A with Svelte](/reference/samples/rag-document-qa-svelte/)

The uploaded document list, answer, and cited passages shown above are illustrative — an OpenAI API key is required for live embeddings and answers. The empty-document and upload error states are captured against the real backend.

Upload documents and ask questions using Retrieval Augmented Generation with vector search.

Read more…

DatabasesDockerNode.jsPythonTypeScript

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/rag-document-qa-svelte)

![Screenshot of the Spring Petclinic with Angular, Spring Boot, and PostgreSQL sample](/_astro/spring-petclinic.CC0kmQSJ_11ivQv.webp)

## [Spring Petclinic with Angular, Spring Boot, and PostgreSQL](/reference/samples/spring-petclinic/)

A compact Petclinic-style application demonstrating the official Aspire Java hosting integration from a TypeScript AppHost.

DashboardDatabasesDockerHealth ChecksJava+6

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/spring-petclinic)

![Screenshot of the Standalone Aspire dashboard sample app sample](/_astro/aspire-dashboard-screenshot-dark.BFx2HEi6_AEv29.webp)

## [Standalone Aspire dashboard sample app](/reference/samples/standalone-dashboard/)

View telemetry from any app in the Aspire dashboard. The dashboard supports running standalone, and apps configured with an OpenTelemetry SDK can send it data.

This sample is a .NET console app that downloads data from NuGet. The app sends telemetry to the Aspire dashboard which is viewed in the dashboard telemetry UI.

Read more…

C#DashboardDockergRPCMetrics

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/standalone-dashboard)

## [Aspire terminals](/reference/samples/terminals/)

Use interactive tools alongside your application without installing them on the host, copying connection strings, or leaving the Aspire dashboard. Each basic sample is standalone: its own API, Redis database, Dockerfile, and saved request collection. Both demonstrate the same round trip: create a note in a REST terminal UI, edit its underlying Redis value in a REPL, then read the changed value through the API. The automation sample reuses the C# basic sample's API and Slumber image source, but launches its own resources and supplies a separate request collection. The custom REPL sample is independent and uses rqlite's official image and SQL shell. Each sample has its own AppHost and can run separately.

C#DashboardDatabasesRedisTypeScript

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/terminals)

![Screenshot of the ASP.NET Core Minimal API + PostgreSQL + Vite sample](/_astro/vite-csharp-postgres-primary-page-dark.DFRnO3nh_Z2ttIIF.webp)

## [ASP.NET Core Minimal API + PostgreSQL + Vite](/reference/samples/vite-csharp-postgres/)

Todo app with C# Minimal APIs, Entity Framework Core, PostgreSQL, and React TypeScript frontend.

C#DashboardDatabasesDockerEF Core+3

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/vite-csharp-postgres)

![Screenshot of the Vite React + FastAPI sample](/_astro/vite-react-fastapi-primary-page-dark.t0MbuP2h_Z1zcRoJ.webp)

## [Vite React + FastAPI](/reference/samples/vite-react-fastapi/)

Todo app with React frontend and Python FastAPI backend using YARP for unified routing.

DockerJavaScriptNode.jsPythonTypeScript

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/vite-react-fastapi)

![Screenshot of the YARP Serving Static Files sample](/_astro/vite-yarp-static-primary-page-dark.BRDSPo_5_4lthm.webp)

## [YARP Serving Static Files](/reference/samples/vite-yarp-static/)

YARP reverse proxy serving a Vite frontend with dual-mode operation (dev HMR + production static files).

DockerNode.jsTypeScript

TypeScript AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/vite-yarp-static)

![Screenshot of the Persistent Volume sample](/_astro/volume-mount-frontend-login-dark.DEDHbpz1_ZNibc1.webp)

## [Persistent Volume](/reference/samples/volume-mount/)

This sample demonstrates how to configure a SQL Server container to use a persistent volume in Aspire, so that the data is persisted across app launches. This method can be used to persist data across instances of other container types configured in Aspire apps too, e.g. PostgreSQL, Redis, etc.

The app consists of a single service, VolumeMount.BlazorWeb, that is configured with a SQL Server container instance via the AppHost project. PostgreSQL and Azure Storage data services are also configured in the AppHost and Blazor projects for demonstration and experimentation purposes. This Blazor Web app has been setup to use ASP.NET Core Identity for local user account registration and authentication, including Blazor identity UI. Using a persistent volume means that user accounts created when running locally are persisted across launches of the app. \[!NOTE] The web front end wears a bespoke "Vault" identity — a split-screen authentication experience, a custom design-token system, distinct iconography, and full light/dark theming — tuned to meet WCAG 2.2 AA (with AAA contrast on body text). The app also includes a class library project, VolumeMount.Data, that contains the Entity Framework Core data model and migrations, a worker service project, VolumeMount.MigrationService, that applies any pending database migrations on startup before the web front end starts, and a standard class library project, VolumeMount.ServiceDefaults, that contains the service defaults used by the service projects.

Read more…

AzureAzure StorageBlazorC#Dashboard+8

C# (csproj) AppHost

[View on GitHub](https://github.com/microsoft/aspire-samples/tree/main/samples/volume-mount)

No matching samples

Try another search or clear the active filters.

Reset all

# Aspire support policy and lifecycle

> Review the official Aspire support policy: release cadence, lifecycle dates, and Microsoft Modern Lifecycle guidance for production deployments and upgrades.

📆 Last updated: October 20, 2026

## Microsoft support for Aspire

[Section titled “Microsoft support for Aspire”](#microsoft-support-for-aspire)

Every Microsoft product has a lifecycle, including Aspire. The lifecycle begins when a product is released and ends when it is no longer supported. Knowing key dates in this lifecycle helps you make informed decisions about when to upgrade or make other changes to your software. This product is governed by the [Microsoft Modern Lifecycle](https://support.microsoft.com/lifecycle) policy.

The Aspire support policy follows the Microsoft Modern Lifecycle with unique versioning and support policies specific to Aspire releases.

## Release cadence

[Section titled “Release cadence”](#release-cadence)

Aspire ships roughly a new major release every year with various minor releases throughout the year.

### Supported versions

[Section titled “Supported versions”](#supported-versions)

The following table lists Aspire versions that are actively supported:

| Version     | Original release date | Latest patch version | Patch release date | End of support                                |
| ----------- | --------------------- | -------------------- | ------------------ | --------------------------------------------- |
| Aspire 13.6 | September 29, 2026    | 13.6.2               | October 20, 2026   | When next major or minor version is released. |

### Out of support versions

[Section titled “Out of support versions”](#out-of-support-versions)

The following table lists Aspire versions no longer supported:

| Version     | Original release date | Latest patch version | Patch release date | End of support     |
| ----------- | --------------------- | -------------------- | ------------------ | ------------------ |
| Aspire 13.5 | August 18, 2026       | 13.5.4               | September 15, 2026 | September 29, 2026 |
| Aspire 13.4 | June 1, 2026          | 13.4.6               | June 20, 2026      | August 18, 2026    |
| Aspire 13.3 | May 7, 2026           | 13.3.5               | May 21, 2026       | June 1, 2026       |
| Aspire 13.2 | March 23, 2026        | 13.2.4               | April 24, 2026     | May 7, 2026        |
| Aspire 13.1 | December 17, 2025     | 13.1.3               | March 19, 2026     | March 23, 2026     |
| Aspire 13.0 | November 11, 2025     | 13.0.2               | December 3, 2025   | December 17, 2025  |
| Aspire 9.5  | September 25, 2025    | 9.5.2                | October 23, 2025   | November 11, 2025  |
| Aspire 9.4  | July 29, 2025         | 9.4.2                | September 2, 2025  | September 25, 2025 |
| Aspire 9.3  | May 19, 2025          | 9.3.2                | June 20, 2025      | July 29, 2025      |
| Aspire 9.2  | April 10, 2025        | 9.2.1                | April 24, 2025     | May 19, 2025       |
| Aspire 9.1  | February 25, 2025     | 9.1.0                | February 25, 2025  | April 10, 2025     |
| Aspire 9.0  | November 12, 2024     | 9.0.0                | November 12, 2024  | February 25, 2025  |
| Aspire 8.2  | August 29, 2024       | 8.2.2                | October 24, 2024   | November 12, 2024  |
| Aspire 8.1  | July 23, 2024         | 8.1.0                | July 23, 2024      | August 29, 2024    |
| Aspire 8.0  | May 21, 2024          | 8.0.2                | June 28, 2024      | July 23, 2024      |

## Versioning and support

[Section titled “Versioning and support”](#versioning-and-support)

At any time, only the latest release of Aspire is supported by Microsoft. For example: support for Aspire 8.0 ended when Aspire 8.1 was released.

To receive technical support from Microsoft, you need to be on the latest servicing level (update) for the latest Aspire release.

## Servicing updates

[Section titled “Servicing updates”](#servicing-updates)

Servicing updates may be made available for supported versions of Aspire. Aspire updates may include a mix of security and non-security fixes in a single patch update. In months without a patch update, a release might not occur.

## Support of containers used by Aspire

[Section titled “Support of containers used by Aspire”](#support-of-containers-used-by-aspire)

Aspire enables the use of third-party containers through resources and integrations. The Aspire team cannot evaluate the underlying third-party containers for which we have API support for suitability for specific customer requirements.

You should evaluate whichever containers you choose to compose and automate with Aspire to ensure they meet your, your employer’s, or your government’s requirements on security and safety as well as cryptographic regulations and any other regulatory or corporate standards that may apply to your use of the container.

Updates to Aspire will from time to time bring updates to third-party containers.

# Access resources in tests

> Resolve and inspect Aspire AppHost resources from your tests — connection strings, endpoints, HTTP clients, and service discovery URIs for integration scenarios.

In this article, you learn how to access the resources from the Aspire AppHost in your tests. The AppHost represents the full application environment and contains all the resources that are available to the application. When writing functional or integration tests with Aspire, you might need to access these resources to verify the behavior of your application.

## Access HTTP resources

[Section titled “Access HTTP resources”](#access-http-resources)

To access an HTTP resource, use the `HttpClient` to request and receive responses. The `DistributedApplication` and the `DistributedApplicationFactory` both provide a `CreateHttpClient` method that’s used to create an `HttpClient` instance for a specific resource, based on the resource name from the AppHost. This method also takes an optional `endpointName` parameter, so if the resource has multiple endpoints, you can specify which one to use.

## Access other resources

[Section titled “Access other resources”](#access-other-resources)

In a test, you might want to access other resources by the connection information they provide, for example, querying a database to verify the state of the data. For this, you use the `GetConnectionString` method to retrieve the connection string for a resource, and then provide that to a client library within the test to interact with the resource.

## Ensure resources are available

[Section titled “Ensure resources are available”](#ensure-resources-are-available)

Starting with Aspire 9, there’s support for waiting on dependent resources to be available (via the [health check](/fundamentals/health-checks/) mechanism). This is useful in tests that ensure a resource is available before attempting to access it. The `ResourceNotificationService` class provides a `WaitForResourceAsync` method that’s used to wait for a named resource to be available. This method takes the resource name and the desired state of the resource as parameters and returns a `Task` that yields back when the resource is available. You can access the `ResourceNotificationService` via `app.ResourceNotifications`, as in the following example.

Note

It’s recommended to provide a time-out when waiting for resources, to prevent the test from hanging indefinitely in situations where a resource never becomes available.

```csharp
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
await app.ResourceNotifications.WaitForResourceAsync(
    "webfrontend",
    KnownResourceStates.Running,
    cts.Token);
```

A resource enters the `KnownResourceStates.Running` state as soon as it starts executing, but this doesn’t mean that it’s ready to serve requests. If you want to wait for the resource to be ready to serve requests, and your resource has health checks, you can wait for the resource to become healthy by using the `WaitForResourceHealthyAsync` method.

```csharp
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));


await app.ResourceNotifications.WaitForResourceHealthyAsync(
    "webfrontend",
    cts.Token);
```

This resource-notification pattern ensures that the resources are available before running the tests, avoiding potential issues with the tests failing due to the resources not being ready.

Tip

If a resource fails during startup (for example, a container exits immediately or an executable can’t be found), Aspire flushes any captured resource logs before it publishes the terminal (`Exited` or `FailedToStart`) state notification. That means test code awaiting `WaitForResourceAsync` with a terminal state can rely on the resource’s stdout/stderr output being present in the captured host logs at the point the wait completes, which makes fast-failing resources easier to diagnose.

## Start & Stop

[Section titled “Start & Stop”](#start--stop)

In some cases, you may want to manually start a resource when it is not initially started, for when the resource was created [`WithExplicitStart`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withexplicitstart "Adds a Aspire.Hosting.ApplicationModel.ExplicitStartupAnnotation annotation to the resource so it doesn't automatically start with the AppHost startup.")[`withExplicitStart`](/reference/api/typescript/aspire.hosting/withexplicitstart/ "Prevents resource from starting automatically") for example.

```csharp
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
await app.ResourceCommands.ExecuteCommandAsync(
    "webfrontend",
    KnownResourceCommands.StartCommand,
    cts.Token);
```

You could also want to stop a resource manually to see if your application is resilient when a particular resource shuts down.

```csharp
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
await app.ResourceCommands.ExecuteCommandAsync(
    "webfrontend",
    KnownResourceCommands.StopCommand,
    cts.Token);
```

# Advanced testing scenarios

> Advanced patterns for DistributedApplicationTestingBuilder — selectively disabling resources, overriding configuration, and authoring resilient Aspire integration tests.

This article covers advanced patterns for testing Aspire applications, including selectively disabling resources during tests, overriding environment variables, and customizing the AppHost for specific test scenarios.

## Selectively disable resources in tests

[Section titled “Selectively disable resources in tests”](#selectively-disable-resources-in-tests)

When running integration tests, you might want to exclude certain resources to reduce test complexity or cost—for example, disabling a monitoring dashboard or skipping a sidecar resource that isn’t relevant to a particular test.

### Use `WithExplicitStart` to control resource startup

[Section titled “Use WithExplicitStart to control resource startup”](#use-withexplicitstart-to-control-resource-startup)

The recommended way to make a resource optional is to use [`WithExplicitStart`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withexplicitstart "Adds a Aspire.Hosting.ApplicationModel.ExplicitStartupAnnotation annotation to the resource so it doesn't automatically start with the AppHost startup.")[`withExplicitStart`](/reference/api/typescript/aspire.hosting/withexplicitstart/ "Prevents resource from starting automatically") in the AppHost, and then let tests choose whether to start that resource. Resources marked with `WithExplicitStart` are created but don’t start automatically with the rest of the application.

In your AppHost, mark the resource as explicitly started:

AppHost.cs

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var api = builder.AddProject("api");


// This resource is optional and won't start automatically
builder.AddContainer("monitoring", "grafana/grafana")
    .WithExplicitStart();


builder.Build().Run();
```

In your test, you can start the resource manually if needed, or leave it stopped:

IntegrationTest.cs

```csharp
[Fact]
public async Task ApiWorksWithoutMonitoring()
{
    var appHost = await DistributedApplicationTestingBuilder
        .CreateAsync();


    await using var app = await appHost.BuildAsync();
    await app.StartAsync();


    // The "monitoring" resource is not started—only "api" is running
    using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
    await app.ResourceNotifications.WaitForResourceHealthyAsync("api", cts.Token);


    using var httpClient = app.CreateHttpClient("api");
    using var response = await httpClient.GetAsync("/health");
    Assert.Equal(HttpStatusCode.OK, response.StatusCode);
}
```

### Conditionally add resources based on configuration

[Section titled “Conditionally add resources based on configuration”](#conditionally-add-resources-based-on-configuration)

Another approach is to use configuration in your AppHost to conditionally add resources. This gives tests control over which resources are included:

AppHost.cs

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var api = builder.AddProject("api");


// Only add the database resource if not explicitly disabled
if (builder.Configuration.GetValue("AddDatabase", true))
{
    var db = builder.AddPostgres("postgres").AddDatabase("mydb");
    api.WithReference(db);
}


builder.Build().Run();
```

In tests, pass the configuration argument to skip the database:

IntegrationTest.cs

```csharp
[Fact]
public async Task ApiStartsWithoutDatabase()
{
    var appHost = await DistributedApplicationTestingBuilder
        .CreateAsync(["AddDatabase=false"]);


    // Assert that the "postgres" resource doesn't exist
    Assert.DoesNotContain(appHost.Resources, r => r.Name == "postgres");


    await using var app = await appHost.BuildAsync();
    await app.StartAsync();


    using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
    await app.ResourceNotifications.WaitForResourceAsync(
        "api", KnownResourceStates.Running, cts.Token);
}
```

### Remove wait annotations in tests

[Section titled “Remove wait annotations in tests”](#remove-wait-annotations-in-tests)

Resources in Aspire can have wait dependencies (via [`WaitFor`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#waitfor "Waits for the dependency resource to enter the Running state before starting the resource.")[`waitFor`](/reference/api/typescript/aspire.hosting/waitfor/ "Waits for another resource to be ready") or [`WaitForCompletion`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#waitforcompletion "Waits for the dependency resource to enter the Exited or Finished state before starting the resource.")[`waitForCompletion`](/reference/api/typescript/aspire.hosting/waitforcompletion/ "Waits for the dependency resource to enter the Exited or Finished state before starting the resource.")). In some tests, you may want to remove these wait annotations to speed up test startup or to test behavior when dependent resources are unavailable.

You can remove `WaitAnnotation` instances after building the testing builder, before calling `BuildAsync`:

IntegrationTest.cs

```csharp
using Aspire.Hosting.ApplicationModel;


[Fact]
public async Task ApiStartsWithoutWaitingForDatabase()
{
    var appHost = await DistributedApplicationTestingBuilder
        .CreateAsync();


    // Remove wait annotations from all resources so they start immediately
    foreach (var resource in appHost.Resources)
    {
        var waitAnnotations = resource.Annotations.OfType().ToList();
        foreach (var annotation in waitAnnotations)
        {
            resource.Annotations.Remove(annotation);
        }
    }


    await using var app = await appHost.BuildAsync();
    await app.StartAsync();


    // Resources start without waiting for dependencies
}
```

Note

Removing wait annotations means resources start immediately, even if their dependencies aren’t ready. Use this technique carefully—only when you intentionally want to test behavior in the absence of proper startup ordering.

## Override environment variables in tests

[Section titled “Override environment variables in tests”](#override-environment-variables-in-tests)

Because Aspire tests run services in separate processes, you can’t inject services directly through dependency injection. However, you can influence application behavior through environment variables or configuration.

### Override environment variables via the AppHost builder

[Section titled “Override environment variables via the AppHost builder”](#override-environment-variables-via-the-apphost-builder)

Use [`WithEnvironment`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withenvironment "Adds an environment variable to the resource.")[`withEnvironment`](/reference/api/typescript/aspire.hosting/withenvironment/ "Sets an environment variable") on the resource builder after creating the testing builder to set environment variables for specific resources. You access the resource builder through the `CreateResourceBuilder` method:

IntegrationTest.cs

```csharp
[Fact]
public async Task ApiUsesTestFeatureFlag()
{
    var appHost = await DistributedApplicationTestingBuilder
        .CreateAsync();


    // Override an environment variable for the "api" resource
    appHost.CreateResourceBuilder("api")
        .WithEnvironment("FeatureFlags__NewCheckout", "true");


    await using var app = await appHost.BuildAsync();
    await app.StartAsync();


    // The "api" service now runs with the overridden feature flag
}
```

### Override configuration with AppHost arguments

[Section titled “Override configuration with AppHost arguments”](#override-configuration-with-apphost-arguments)

You can also pass arguments to the AppHost to override configuration values. Arguments are passed to the .NET configuration system, so they can override values from `appsettings.json`. For more information, see [Pass arguments to your AppHost](/testing/manage-app-host/#pass-arguments-to-your-apphost).

### Override AppHost configuration before resources are created

[Section titled “Override AppHost configuration before resources are created”](#override-apphost-configuration-before-resources-are-created)

For more control over the AppHost configuration before any resources are created, use the `DistributedApplicationFactory` class and override the `OnBuilderCreating` lifecycle method. For more information, see [Use the `DistributedApplicationFactory` class](/testing/manage-app-host/#use-the-distributedapplicationfactory-class).

For full documentation on argument passing and the `DistributedApplicationFactory` lifecycle, see [Manage the AppHost in tests](/testing/manage-app-host/).

## File-based AppHost limitations

[Section titled “File-based AppHost limitations”](#file-based-apphost-limitations)

The Aspire CLI supports **file-based AppHosts** — a lightweight `apphost.cs` file with no `.csproj` project file. These are created with `aspire init` or the `aspire-apphost-singlefile` template and are run directly with `aspire run`.

Caution

File-based AppHosts (`apphost.cs` without a `.csproj`) **cannot** be tested with `DistributedApplicationTestingBuilder`. Because they don’t have a project file, they don’t appear in the auto-generated `Projects` namespace, and there’s no project reference to pass to `CreateAsync()`.

The `DistributedApplicationTestingBuilder.CreateAsync()` method requires a type from the `Projects` namespace:

IntegrationTest.cs

```csharp
// This requires Projects.MyAppHost to exist — only available via ProjectReference
var appHost = await DistributedApplicationTestingBuilder
    .CreateAsync();
```

The `Projects` namespace entries are only generated for `` entries in your test project. A file-based `apphost.cs` produces no such entry.

## See also

[Section titled “See also”](#see-also)

* [Manage the AppHost in tests](/testing/manage-app-host/)
* [Access resources in tests](/testing/accessing-resources/)
* [Testing overview](/testing/overview/)

# Manage the AppHost in tests

> Manage the Aspire AppHost lifecycle in your tests — start, dispose, and configure DistributedApplicationTestingBuilder for fast, repeatable integration runs.

Select your testing framework

xUnit.netMSTestNUnit

When writing functional or integration tests with Aspire, managing the [AppHost](/get-started/app-host/) instance efficiently is crucial. The AppHost represents the full application environment and can be costly to create and tear down. This article explains how to manage the AppHost instance in your Aspire tests.

For writing tests with Aspire, you use the [Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package which contains some helper classes to manage the AppHost instance in your tests.

## Use the `DistributedApplicationTestingBuilder` class

[Section titled “Use the DistributedApplicationTestingBuilder class”](#use-the-distributedapplicationtestingbuilder-class)

In the [tutorial on writing your first test](/testing/write-your-first-test/), you were introduced to the `DistributedApplicationTestingBuilder` class which can be used to create the AppHost instance:

```csharp
var appHost = await DistributedApplicationTestingBuilder
    .CreateAsync();
```

The `DistributedApplicationTestingBuilder.CreateAsync` method takes the AppHost project type as a generic parameter to create the AppHost instance. While this method is executed at the start of each test, it’s more efficient to create the AppHost instance once and share it across tests as the test suite grows.

With xUnit, you implement the [IAsyncLifetime](https://github.com/xunit/xunit/blob/master/src/xunit.core/IAsyncLifetime.cs) interface on the test class to support asynchronous initialization and disposal of the AppHost instance. The `InitializeAsync` method is used to create the AppHost instance before the tests are run and the `DisposeAsync` method disposes the AppHost once the tests are completed.

```csharp
public class WebTests : IAsyncLifetime
{
    private DistributedApplication _app;


    public async Task InitializeAsync()
    {
        var appHost = await DistributedApplicationTestingBuilder
            .CreateAsync();


        _app = await appHost.BuildAsync();
    }


    public async Task DisposeAsync() => await _app.DisposeAsync();


    [Fact]
    public async Task GetWebResourceRootReturnsOkStatusCode()
    {
        // test code here
    }
}
```

With MSTest, you use the `ClassInitializeAttribute` and `ClassCleanupAttribute` on static methods of the test class to provide the initialization and cleanup of the AppHost instance. The `ClassInitialize` method is used to create the AppHost instance before the tests are run and the `ClassCleanup` method disposes the AppHost instance once the tests are completed.

```csharp
[TestClass]
public class WebTests
{
    private static DistributedApplication _app;


    [ClassInitialize]
    public static async Task ClassInitialize(TestContext context)
    {
       var appHost = await DistributedApplicationTestingBuilder
            .CreateAsync();


        _app = await appHost.BuildAsync();
    }


    [ClassCleanup]
    public static async Task ClassCleanup() => await _app.DisposeAsync();


    [TestMethod]
    public async Task GetWebResourceRootReturnsOkStatusCode()
    {
        // test code here
    }
}
```

With NUnit, you use the [OneTimeSetUp](https://docs.nunit.org/articles/nunit/writing-tests/attributes/onetimesetup.html) and [OneTimeTearDown](https://docs.nunit.org/articles/nunit/writing-tests/attributes/onetimeteardown.html) attributes on methods of the test class to provide the setup and teardown of the AppHost instance. The `OneTimeSetUp` method is used to create the AppHost instance before the tests are run and the `OneTimeTearDown` method disposes the AppHost instance once the tests are completed.

```csharp
public class WebTests
{
    private DistributedApplication _app;


    [OneTimeSetUp]
    public async Task OneTimeSetup()
    {
       var appHost = await DistributedApplicationTestingBuilder
            .CreateAsync();


        _app = await appHost.BuildAsync();
    }


    [OneTimeTearDown]
    public async Task OneTimeTearDown() => await _app.DisposeAsync();


    [Test]
    public async Task GetWebResourceRootReturnsOkStatusCode()
    {
        // test code here
    }
}
```

By capturing the AppHost in a field when the test run is started, you can access it in each test without the need to recreate it, decreasing the time it takes to run the tests. Then, when the test run completes, the AppHost is disposed, which cleans up any resources that were created during the test run, such as containers.

## Pass arguments to your AppHost

[Section titled “Pass arguments to your AppHost”](#pass-arguments-to-your-apphost)

You can access the arguments from your AppHost with the `args` parameter. Arguments are also passed to [.NET’s configuration system](https://learn.microsoft.com/dotnet/core/extensions/configuration), so you can override many configuration settings this way. In the following example, you override the [environment](https://learn.microsoft.com/aspnet/core/fundamentals/environments) by specifying it as a command line option:

```csharp
var builder = await DistributedApplicationTestingBuilder
    .CreateAsync(
    [
        "--environment=Testing"
    ]);
```

Other arguments can be passed to your AppHost `Program` and made available in your AppHost. In the next example, you pass an argument to the AppHost and use it to control whether you add data volumes to a Postgres instance.

In the AppHost `Program`, you use configuration to support enabling or disabling volumes:

```csharp
var postgres = builder.AddPostgres("postgres1");
if (builder.Configuration.GetValue("UseVolumes", true))
{
    postgres.WithDataVolume();
}
```

In test code, you pass `"UseVolumes=false"` in the `args` to the AppHost:

```csharp
public async Task DisableVolumesFromTest()
{
    // Disable volumes in the test builder via arguments:
    using var builder = await DistributedApplicationTestingBuilder
        .CreateAsync(
        [
            "UseVolumes=false"
        ]);


    // The container will have no volume annotation since we disabled volumes by passing UseVolumes=false
    var postgres = builder.Resources.Single(r => r.Name == "postgres1");


    Assert.Empty(postgres.Annotations.OfType());
}
```

## Use the `DistributedApplicationFactory` class

[Section titled “Use the DistributedApplicationFactory class”](#use-the-distributedapplicationfactory-class)

While the `DistributedApplicationTestingBuilder` class is useful for many scenarios, there might be situations where you want more control over starting the AppHost, such as executing code before the builder is created or after the AppHost is built. In these cases, you implement your own version of the `DistributedApplicationFactory` class. This is what the `DistributedApplicationTestingBuilder` uses internally.

```csharp
public class TestingAspireAppHost()
    : DistributedApplicationFactory(typeof(Projects.AspireApp_AppHost))
{
    // override methods here
}
```

The constructor requires the type of the AppHost project reference as a parameter. Optionally, you can provide arguments to the underlying host application builder. These arguments control how the AppHost starts and provide values to the args variable used by the *AppHost.cs* file to start the AppHost instance.

## Lifecycle methods

[Section titled “Lifecycle methods”](#lifecycle-methods)

The `DistributionApplicationFactory` class provides several lifecycle methods that can be overridden to provide custom behavior throughout the preparation and creation of the AppHost. The available methods are `OnBuilderCreating`, `OnBuilderCreated`, `OnBuilding`, and `OnBuilt`.

For example, we can use the `OnBuilderCreating` method to set configuration, such as the subscription and resource group information for Azure, before the AppHost is created and any dependent Azure resources are provisioned, resulting in our tests using the correct Azure environment.

```csharp
public class TestingAspireAppHost()
    : DistributedApplicationFactory(typeof(Projects.AspireApp_AppHost))
{
    protected override void OnBuilderCreating(
        DistributedApplicationOptions applicationOptions,
        HostApplicationBuilderSettings hostOptions)
    {
        hostOptions.Configuration ??= new();
        hostOptions.Configuration["environment"] = "Development";
        hostOptions.Configuration["AZURE_SUBSCRIPTION_ID"] = "00000000-0000-0000-0000-000000000000";
        hostOptions.Configuration["AZURE_RESOURCE_GROUP"] = "my-resource-group";
    }
}
```

Because of the order of precedence in the .NET configuration system, the environment variables will be used over anything in the *appsettings.json* or *secrets.json* file.

Another scenario you might want to use in the lifecycle is to configure the services used by the AppHost. In the following example, consider a scenario where you override the `OnBuilderCreated` API to add resilience to the `HttpClient`:

```csharp
protected override void OnBuilderCreated(
    DistributedApplicationBuilder applicationBuilder)
{
    applicationBuilder.Services.ConfigureHttpClientDefaults(clientBuilder =>
    {
        clientBuilder.AddStandardResilienceHandler();
    });
}
```

# Testing overview

> Write integration tests for your Aspire applications using the Aspire.Hosting.Testing package — spin up the AppHost, resolve resources, and verify end-to-end behavior.

Aspire supports automated testing of your distributed applications through the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package. This package provides the `DistributedApplicationTestingBuilder` class, which creates a test host for your application. The testing builder launches your AppHost project in a background thread and manages its lifecycle, allowing you to control and manipulate the application and its resources.

By default, the testing builder disables the dashboard and randomizes the ports of proxied resources to enable multiple instances of your application to run concurrently. Once your test completes, disposing of the application or testing builder cleans up your app resources.

## Understanding Aspire testing

[Section titled “Understanding Aspire testing”](#understanding-aspire-testing)

Aspire’s testing capabilities are designed specifically for closed-box integration testing of your entire distributed application. Unlike unit tests or open-box integration tests, which typically run individual components in isolation, Aspire tests launch your complete solution—the AppHost and all its resources—as separate processes, closely simulating real-world scenarios.

The following diagram shows how the Aspire testing project starts the AppHost, which then starts the application and its resources:

![Aspire testing diagram showing how a test project starts the AppHost, which orchestrates the Database, API, and Frontend applications. The test project sends an HTTP request to the Frontend application.](/_astro/testing-diagram.CUK_51bY_gGVoA.svg)

1. The **test project** starts the AppHost.
2. The **AppHost** process starts.
3. The **AppHost** runs the `Database`, `API`, and `Frontend` applications.
4. The **test project** sends an HTTP request to the `Frontend` application.

The test project starts the AppHost, which then orchestrates all dependent app resources—regardless of their type. The test project can send an HTTP request to the `Frontend` app, which depends on an `API` app, and the `API` app depends on a `Database`. A successful request confirms that the `Frontend` app can communicate with the `API` app, and that the `API` app can successfully get data from the `Database`.

Caution

Aspire testing doesn’t enable scenarios for mocking, substituting, or replacing services in dependency injection—as the tests run in a separate process.

### When to use Aspire testing

[Section titled “When to use Aspire testing”](#when-to-use-aspire-testing)

Use Aspire testing when you want to:

* Verify end-to-end functionality of your distributed application.
* Ensure interactions between multiple services and resources (such as databases) behave correctly in realistic conditions.
* Confirm data persistence and integration with real external dependencies, like a PostgreSQL database.

If your goal is to test a single project in isolation, run components in-memory, or mock external dependencies, consider using `WebApplicationFactory` instead.

Note

Aspire tests run your application as separate processes, meaning you don’t have direct access to internal services or components from your test code. You can influence application behavior through environment variables or configuration settings, but internal state and services remain encapsulated within their respective processes.

## Configuration options

[Section titled “Configuration options”](#configuration-options)

The `DistributedApplicationTestingBuilder` provides several configuration options to customize how your tests run. You can control port assignment, enable the dashboard, and adjust other settings through the builder’s options.

### Disable port randomization

[Section titled “Disable port randomization”](#disable-port-randomization)

By default, Aspire uses random ports to allow multiple instances of your application to run concurrently without interference. It uses Aspire’s service discovery to ensure applications can locate each other’s endpoints. To disable port randomization, pass `"DcpPublisher:RandomizePorts=false"` when constructing your testing builder:

```csharp
var builder = await DistributedApplicationTestingBuilder
    .CreateAsync(
        [
            "DcpPublisher:RandomizePorts=false"
        ]);
```

### Enable the dashboard

[Section titled “Enable the dashboard”](#enable-the-dashboard)

The testing builder disables the Aspire dashboard by default. To enable it, set the `DisableDashboard` property to `false` when creating your testing builder:

```csharp
var builder = await DistributedApplicationTestingBuilder
    .CreateAsync(
        args: [],
        configureBuilder: (appOptions, hostSettings) =>
        {
            appOptions.DisableDashboard = false;
        });
```

# Testing in CI/CD pipelines

> Run Aspire integration tests reliably in CI/CD — GitHub Actions, Azure DevOps, container runtimes, port allocation, and managing flaky distributed application tests.

This article covers how to run Aspire integration tests reliably in continuous integration (CI) and continuous deployment (CD) environments, addressing common challenges such as test timeouts, Azure authentication, and container requirements.

## Container requirements

[Section titled “Container requirements”](#container-requirements)

Aspire integration tests typically start containers, such as databases, caches, and other services, as part of the test run. Your CI environment must have a container runtime available.

* **GitHub Actions**: For Linux-based Aspire test containers, use `ubuntu-*` runners, which have Docker available by default. GitHub-hosted `windows-*` and `macos-*` runners do not provide a Docker engine suitable for running Linux containers; use self-hosted runners with a configured container runtime if you need to target those operating systems.
* **Azure DevOps**: Docker is available on Microsoft-hosted agents (`ubuntu-latest`, `windows-latest`). Ensure the agent pool supports Docker.
* **Self-hosted runners**: Install and start Docker or another compatible container runtime, such as Podman, before running tests.

Caution

Some CI environments restrict container networking, privileged containers, or certain Docker features. If you encounter container startup failures in CI, check your runner’s Docker capabilities and network configuration.

## Configure timeouts to prevent hanging tests

[Section titled “Configure timeouts to prevent hanging tests”](#configure-timeouts-to-prevent-hanging-tests)

One of the most common issues experienced when running Aspire tests in CI is a test that hangs indefinitely because resources never reach their expected state. Always configure explicit timeouts for resource waiting and test execution.

### Set timeouts on resource waiting

[Section titled “Set timeouts on resource waiting”](#set-timeouts-on-resource-waiting)

The `WaitForResourceAsync` and `WaitForResourceHealthyAsync` methods accept a `CancellationToken`. Always pass a token with a timeout to avoid indefinite waits:

IntegrationTest.cs

```csharp
using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));


await app.ResourceNotifications.WaitForResourceHealthyAsync(
    "webfrontend",
    cts.Token);
```

### Set timeouts on `BuildAsync` and `StartAsync`

[Section titled “Set timeouts on BuildAsync and StartAsync”](#set-timeouts-on-buildasync-and-startasync)

Use `WaitAsync` to apply a timeout to the `BuildAsync` and `StartAsync` operations:

IntegrationTest.cs

```csharp
var timeout = TimeSpan.FromMinutes(5);
var cancellationToken = CancellationToken.None;


await using var app = await appHost.BuildAsync(cancellationToken)
    .WaitAsync(timeout, cancellationToken);


await app.StartAsync(cancellationToken)
    .WaitAsync(timeout, cancellationToken);
```

### Use longer timeouts in CI

[Section titled “Use longer timeouts in CI”](#use-longer-timeouts-in-ci)

CI environments are often slower than local development machines due to network latency when pulling container images, limited CPU and memory, and parallel test execution. Consider using environment-aware timeouts:

IntegrationTest.cs

```csharp
private static readonly TimeSpan DefaultTimeout =
    Environment.GetEnvironmentVariable("CI") is not null
        ? TimeSpan.FromMinutes(5)   // Longer timeout in CI
        : TimeSpan.FromSeconds(30); // Shorter timeout locally


[Fact]
public async Task GetWebResourceRootReturnsOkStatusCode()
{
    var appHost = await DistributedApplicationTestingBuilder
        .CreateAsync();


    await using var app = await appHost.BuildAsync()
        .WaitAsync(DefaultTimeout);
    await app.StartAsync().WaitAsync(DefaultTimeout);


    using var cts = new CancellationTokenSource(DefaultTimeout);
    await app.ResourceNotifications.WaitForResourceHealthyAsync(
        "webfrontend", cts.Token);


    using var httpClient = app.CreateHttpClient("webfrontend");
    using var response = await httpClient.GetAsync("/");
    Assert.Equal(HttpStatusCode.OK, response.StatusCode);
}
```

## Configure Azure authentication in CI

[Section titled “Configure Azure authentication in CI”](#configure-azure-authentication-in-ci)

When running tests that involve Azure resources, such as Azure Cosmos DB, Azure Service Bus, or Azure Storage, you must configure Azure authentication appropriately for your CI environment.

### Local versus CI authentication

[Section titled “Local versus CI authentication”](#local-versus-ci-authentication)

In local development, Aspire uses your developer identity via `DefaultAzureCredential`, which tries Visual Studio, Azure CLI, and other sources. In CI, no developer identity is available, so you must configure a **service principal** or **managed identity**.

A common symptom of misconfigured CI authentication is an error like:

```plaintext
The principal type 'User' is not allowed. Expected 'ServicePrincipal'.
```

This occurs when a role assignment in your Aspire AppHost is configured with `principalType: "User"` but the CI pipeline is running as a service principal.

### Use `DefaultAzureCredential` with environment variables

[Section titled “Use DefaultAzureCredential with environment variables”](#use-defaultazurecredential-with-environment-variables)

The recommended approach is to configure a service principal and set the standard Azure SDK environment variables in your CI pipeline. `DefaultAzureCredential` automatically picks up these environment variables:

| Environment variable  | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `AZURE_CLIENT_ID`     | The application (client) ID of your service principal |
| `AZURE_TENANT_ID`     | Your Azure Active Directory tenant ID                 |
| `AZURE_CLIENT_SECRET` | The client secret of your service principal           |

Note

When deploying to Azure Container Apps or Azure App Service, Aspire 13.0 automatically sets `AZURE_TOKEN_CREDENTIALS=managedidentity` so that `DefaultAzureCredential` uses only `ManagedIdentityCredential`. This doesn’t affect test environments, but is important to understand if your tests also exercise deployment paths. For more information, see [DefaultAzureCredential behavior in Azure deployments](/whats-new/aspire-13/#defaultazurecredential-behavior-in-azure-deployments).

* GitHub Actions

  .github/workflows/tests.yml

  ```yaml
  - name: Run Aspire integration tests
    env:
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
      AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    run: dotnet test --no-build
  ```

* Azure DevOps

  azure-pipelines.yml

  ```yaml
  - task: DotNetCoreCLI@2
    displayName: Run Aspire integration tests
    inputs:
      command: test
      projects: '**/*.Tests.csproj'
    env:
      AZURE_CLIENT_ID: $(AZURE_CLIENT_ID)
      AZURE_TENANT_ID: $(AZURE_TENANT_ID)
      AZURE_CLIENT_SECRET: $(AZURE_CLIENT_SECRET)
      AZURE_SUBSCRIPTION_ID: $(AZURE_SUBSCRIPTION_ID)
  ```

### Configure Azure credentials in the AppHost factory

[Section titled “Configure Azure credentials in the AppHost factory”](#configure-azure-credentials-in-the-apphost-factory)

You can also set Azure credentials programmatically in your test setup using the `DistributedApplicationFactory`:

CiAppHostFactory.cs

```csharp
public class CiAppHostFactory()
    : DistributedApplicationFactory(typeof(Projects.MyAppHost))
{
    protected override void OnBuilderCreating(
        DistributedApplicationOptions applicationOptions,
        HostApplicationBuilderSettings hostOptions)
    {
        hostOptions.Configuration ??= new();


        // Read credentials from environment and forward to AppHost configuration
        if (Environment.GetEnvironmentVariable("AZURE_CLIENT_ID") is { } clientId)
        {
            hostOptions.Configuration["AZURE_CLIENT_ID"] = clientId;
        }


        if (Environment.GetEnvironmentVariable("AZURE_TENANT_ID") is { } tenantId)
        {
            hostOptions.Configuration["AZURE_TENANT_ID"] = tenantId;
        }


        if (Environment.GetEnvironmentVariable("AZURE_CLIENT_SECRET") is { } clientSecret)
        {
            hostOptions.Configuration["AZURE_CLIENT_SECRET"] = clientSecret;
        }


        if (Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID") is { } subscriptionId)
        {
            hostOptions.Configuration["AZURE_SUBSCRIPTION_ID"] = subscriptionId;
        }
    }
}
```

### Skip Azure tests when credentials are unavailable

[Section titled “Skip Azure tests when credentials are unavailable”](#skip-azure-tests-when-credentials-are-unavailable)

When Azure credentials aren’t configured, you may want to skip tests that require Azure resources rather than fail them. Use a guard at the start of your test or in a base class:

IntegrationTest.cs

```csharp
[Fact]
public async Task TestWithAzureCosmosDb()
{
    if (Environment.GetEnvironmentVariable("AZURE_CLIENT_ID") is null
        || Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID") is null)
    {
        // Skip when Azure credentials are not available
        throw new Xunit.Sdk.SkipException("""
            Azure credentials not configured; skipping test.
            """);
    }


    var appHost = await DistributedApplicationTestingBuilder
        .CreateAsync();


    // ... rest of test
}
```

Tip

Consider using test categories or traits to separate tests that require Azure credentials from tests that run entirely on local containers. This lets CI pipelines choose which tests to run based on available credentials.

## Run tests in parallel

[Section titled “Run tests in parallel”](#run-tests-in-parallel)

Aspire tests use random port assignment by default, which allows multiple test instances to run concurrently without port conflicts. This is controlled by the `DcpPublisher:RandomizePorts` setting, which is enabled by default in the testing builder.

For CI environments running multiple test classes in parallel, random ports help prevent failures caused by port collisions. If you’ve disabled random ports, for example to match a specific port in a health check URL, re-enable them for CI:

IntegrationTest.cs

```csharp
var appHost = await DistributedApplicationTestingBuilder
    .CreateAsync(
    [
        "DcpPublisher:RandomizePorts=true"
    ]);
```

For information about disabling port randomization, see [Testing overview: Disable port randomization](/testing/overview/#disable-port-randomization).

## Example CI workflow

[Section titled “Example CI workflow”](#example-ci-workflow)

The following is a complete GitHub Actions workflow for running Aspire integration tests:

Note

GitHub Actions automatically sets the `CI` environment variable to `true` for all workflow runs. The test code from the earlier [Use longer timeouts in CI](#use-longer-timeouts-in-ci) section checks for this variable to apply extended timeouts. Other CI platforms such as Azure DevOps, CircleCI, and others, also set `CI=true` by default.

.github/workflows/integration-tests.yml

```yaml
name: Integration Tests


on:
  push:
    branches: [main]
  pull_request:
    branches: [main]


jobs:
  test:
    runs-on: ubuntu-latest


    steps:
      - uses: actions/checkout@v4


      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.x'


      - name: Restore dependencies
        run: dotnet restore


      - name: Build
        run: dotnet build --no-restore


      - name: Run integration tests
        env:
          # Azure credentials (optional—skip Azure tests if not set)
          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
          AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
        run: dotnet test --no-build --verbosity normal
        timeout-minutes: 30
```

Tip

Always set a `timeout-minutes` on your test job to prevent stuck tests from consuming CI minutes indefinitely.

## Troubleshooting common CI failures

[Section titled “Troubleshooting common CI failures”](#troubleshooting-common-ci-failures)

### Tests hang or time out

[Section titled “Tests hang or time out”](#tests-hang-or-time-out)

**Cause**: Resources fail to start or become healthy within the expected time.

**Solutions**:

* Increase the timeout values in your tests.
* Add logging to capture resource startup output.
* Check that Docker is available and running on the CI agent.
* Verify that container images can be pulled (network access, image name, and tags).

### Container pull failures

[Section titled “Container pull failures”](#container-pull-failures)

**Cause**: The CI environment can’t pull required container images.

**Solutions**:

* Check that the CI runner has internet access to Docker Hub or your container registry.
* Pre-pull commonly used images as a build step.
* Use a private registry mirror if Docker Hub rate limits are an issue.

### Azure authentication errors

[Section titled “Azure authentication errors”](#azure-authentication-errors)

**Cause**: Missing or incorrect Azure service principal credentials.

**Solutions**:

* Ensure `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_CLIENT_SECRET` are set as CI secrets.
* Verify the service principal has the required role assignments in Azure.
* Check that `AZURE_SUBSCRIPTION_ID` is set when provisioning Azure resources.

### Port conflicts

[Section titled “Port conflicts”](#port-conflicts)

**Cause**: Multiple test instances using the same fixed ports.

**Solution**: Ensure `DcpPublisher:RandomizePorts` isn’t explicitly set to `false` when running tests in parallel.

## See also

[Section titled “See also”](#see-also)

* [Testing overview](/testing/overview/)
* [Manage the AppHost in tests](/testing/manage-app-host/)
* [Advanced testing scenarios](/testing/advanced-scenarios/)

# Write your first test

> Test your Aspire solutions using xUnit.net, NUnit, or MSTest — wire up DistributedApplicationTestingBuilder, start the AppHost, and assert on resources from your tests.

Select your testing framework

xUnit.netMSTestNUnit

In this article, you’ll learn how to create a test project, write C# tests, and run them for your Aspire solutions. These aren’t unit tests—they’re functional and integration tests that validate how your distributed application components work together. Aspire provides testing project templates for xUnit.net, MSTest, and NUnit frameworks, each including a sample test to help you get started quickly.

## Conceptualizing distributed app testing

[Section titled “Conceptualizing distributed app testing”](#conceptualizing-distributed-app-testing)

Before you start testing your Aspire solutions, you’ll need the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package. This powerful package provides the `DistributedApplicationTestingBuilder` class—your gateway to creating a test host for distributed applications.

Think of the `DistributedApplicationTestingBuilder` as a test harness that launches your AppHost project with built-in instrumentation. This gives you precise control to access and manipulate the host throughout its lifecycle. You’ll work with familiar Aspire types like `IDistributedApplicationBuilder` and `DistributedApplication` to build and start your [AppHost](/get-started/app-host/), making your tests feel natural and intuitive.

## Create a test project

[Section titled “Create a test project”](#create-a-test-project)

To create an Aspire test project, use the testing project template. When starting a new Aspire project, both IDE and CLI tooling prompts you to create a test project for some templates. To add a test project to an existing Aspire solution, use the [`dotnet new`](https://learn.microsoft.com/dotnet/core/tools/dotnet-new) command:

```bash
dotnet new aspire-xunit -o xUnit.Tests
```

```bash
dotnet new aspire-mstest -o MSTest.Tests
```

```bash
dotnet new aspire-nunit -o NUnit.Tests
```

Change directory to the newly created test project:

```bash
cd xUnit.Tests
```

```bash
cd MSTest.Tests
```

```bash
cd NUnit.Tests
```

After adding the test project to your Aspire solution, add a project reference to the target AppHost. For example, if your Aspire solution contains an AppHost project named `AspireApp.AppHost`, add a project reference to it from the test project:

```bash
dotnet reference add ../AspireApp.AppHost/AspireApp.AppHost.csproj --project xUnit.Tests.csproj
```

```bash
dotnet reference add ../AspireApp.AppHost/AspireApp.AppHost.csproj --project MSTest.Tests.csproj
```

```bash
dotnet reference add ../AspireApp.AppHost/AspireApp.AppHost.csproj --project NUnit.Tests.csproj
```

Finally, you can uncomment out the `IntegrationTest1.cs` file in the test project to explore the sample test.

## Explore the test project

[Section titled “Explore the test project”](#explore-the-test-project)

The following example test project was created as part of the **Blazor & Minimal API starter** template. If you’re unfamiliar with it, see [Build your first app—C#](/get-started/first-app/?lang=csharp). The Aspire test project takes a project reference dependency on the target AppHost. Consider the template project:

xUnit.Tests.csproj

```xml



  
    net10.0
    enable
    enable
    false
    true
  


  
    
    
    
    
    
  


  
    
  


  
    
    
    
    
    
  



```

MSTest.Tests.csproj

```xml



  
    net10.0
    enable
    enable
    false
    true
    true
    Exe
  


  
    
    
  


  
    
  


  
    
    
    
    
    
  



```

NUnit.Tests.csproj

```xml



  
    net10.0
    enable
    enable
    false
    true
  


  
    
    
    
    
    
    
  


  
    
  


  
    
    
    
    
    
  



```

The preceding project file is fairly standard. There’s a `PackageReference` to the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package, which includes the required types to write tests for Aspire projects.

The template test project includes an `IntegrationTest1` class with a single test. The test verifies the following scenario:

* The AppHost is successfully created and started.
* The `webfrontend` resource is available and running.
* An HTTP request can be made to the `webfrontend` resource and returns a successful response (HTTP 200 OK).

Consider the following test class:

IntegrationTest1.cs

```csharp
using Microsoft.Extensions.Logging;


namespace xUnit.Tests.Tests;


public class IntegrationTest1
{
    private static readonly TimeSpan DefaultTimeout = TimeSpan.FromSeconds(30);


    [Fact]
    public async Task GetWebResourceRootReturnsOkStatusCode()
    {
        // Arrange
        var cancellationToken = CancellationToken.None;
        var appHost = await DistributedApplicationTestingBuilder
            .CreateAsync(cancellationToken);
        appHost.Services.AddLogging(logging =>
        {
            logging.SetMinimumLevel(LogLevel.Debug);
            // Override the logging filters from the app's configuration
            logging.AddFilter(appHost.Environment.ApplicationName, LogLevel.Debug);
            logging.AddFilter("Aspire.", LogLevel.Debug);
        });
        appHost.Services.ConfigureHttpClientDefaults(clientBuilder =>
        {
            clientBuilder.AddStandardResilienceHandler();
        });


        await using var app = await appHost.BuildAsync(cancellationToken)
            .WaitAsync(DefaultTimeout, cancellationToken);
        await app.StartAsync(cancellationToken)
            .WaitAsync(DefaultTimeout, cancellationToken);


        // Act
        using var httpClient = app.CreateHttpClient("webfrontend");
        await app.ResourceNotifications.WaitForResourceHealthyAsync(
            "webfrontend", cancellationToken)
            .WaitAsync(DefaultTimeout, cancellationToken);
        using var response = await httpClient.GetAsync("/", cancellationToken);


        // Assert
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
    }
}
```

IntegrationTest1.cs

```csharp
using Microsoft.Extensions.Logging;


namespace MSTest.Tests;


[TestClass]
public class IntegrationTest1
{
    public TestContext TestContext { get; set; }


    private static readonly TimeSpan DefaultTimeout = TimeSpan.FromSeconds(30);


    [TestMethod]
    public async Task GetWebResourceRootReturnsOkStatusCode()
    {
        // Arrange
        var cancellationToken = TestContext.CancellationTokenSource.Token;
        var appHost = await DistributedApplicationTestingBuilder
            .CreateAsync();
        appHost.Services.AddLogging(logging =>
        {
            logging.SetMinimumLevel(LogLevel.Debug);
            // Override the logging filters from the app's configuration
            logging.AddFilter(appHost.Environment.ApplicationName, LogLevel.Debug);
            logging.AddFilter("Aspire.", LogLevel.Debug);
        });
        appHost.Services.ConfigureHttpClientDefaults(clientBuilder =>
        {
            clientBuilder.AddStandardResilienceHandler();
        });


        await using var app = await appHost.BuildAsync(cancellationToken)
            .WaitAsync(DefaultTimeout, cancellationToken);
        await app.StartAsync(cancellationToken)
            .WaitAsync(DefaultTimeout, cancellationToken);


        // Act
        using var httpClient = app.CreateHttpClient("webfrontend");
        await app.ResourceNotifications.WaitForResourceHealthyAsync(
            "webfrontend", cancellationToken)
            .WaitAsync(DefaultTimeout, cancellationToken);
        using var response = await httpClient.GetAsync("/", cancellationToken);


        // Assert
        Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);
    }
}
```

IntegrationTest1.cs

```csharp
using Microsoft.Extensions.Logging;


namespace NUnit.Tests;


public class IntegrationTest1
{
    private static readonly TimeSpan DefaultTimeout = TimeSpan.FromSeconds(30);


    [Test]
    public async Task GetWebResourceRootReturnsOkStatusCode()
    {
        // Arrange
        using var cts = new CancellationTokenSource(DefaultTimeout);
        var cancellationToken = cts.Token;
        var appHost = await DistributedApplicationTestingBuilder
            .CreateAsync();
        appHost.Services.AddLogging(logging =>
        {
            logging.SetMinimumLevel(LogLevel.Debug);
            // Override the logging filters from the app's configuration
            logging.AddFilter(appHost.Environment.ApplicationName, LogLevel.Debug);
            logging.AddFilter("Aspire.", LogLevel.Debug);
        });
        appHost.Services.ConfigureHttpClientDefaults(clientBuilder =>
        {
            clientBuilder.AddStandardResilienceHandler();
        });


        await using var app = await appHost.BuildAsync(cancellationToken)
            .WaitAsync(DefaultTimeout, cancellationToken);
        await app.StartAsync(cancellationToken)
            .WaitAsync(DefaultTimeout, cancellationToken);


        // Act
        using var httpClient = app.CreateHttpClient("webfrontend");
        await app.ResourceNotifications.WaitForResourceHealthyAsync(
            "webfrontend", cancellationToken)
            .WaitAsync(DefaultTimeout, cancellationToken);
        using var response = await httpClient.GetAsync("/", cancellationToken);


        // Assert
        Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));
    }
}
```

The preceding code:

* Relies on the `DistributedApplicationTestingBuilder.CreateAsync` API to asynchronously create the AppHost.
* The `appHost` is an instance of `IDistributedApplicationTestingBuilder` that represents the AppHost.
* The `appHost` instance has its service collection configured with logging and the standard HTTP resilience handler. For more information, see [Build resilient HTTP apps: Key development patterns](https://learn.microsoft.com/dotnet/core/resilience/http-resilience).
* The `appHost` has its `BuildAsync` method invoked, which returns the `DistributedApplication` instance as the `app`.
* The `app` is started asynchronously.
* An `HttpClient` is created for the `webfrontend` resource by calling `app.CreateHttpClient`.
* The `app.ResourceNotifications` is used to wait for the `webfrontend` resource to be healthy.
* A simple HTTP GET request is made to the root of the `webfrontend` resource.
* The test asserts that the response status code is `OK`.

## Test resource environment variables

[Section titled “Test resource environment variables”](#test-resource-environment-variables)

To further test resources and their expressed dependencies in your Aspire solution, you can assert that environment variables are injected correctly. The following example demonstrates how to test that the `webfrontend` resource has an HTTPS environment variable that resolves to the `apiservice` resource:

EnvVarTests.cs

```csharp
using Aspire.Hosting;
using Microsoft.Extensions.Logging.Abstractions;


namespace Tests;


public class EnvVarTests
{
    [Fact]
    public async Task WebResourceEnvVarsResolveToApiService()
    {
        // Arrange
        var builder = await DistributedApplicationTestingBuilder
            .CreateAsync();


        var frontend = builder.CreateResourceBuilder("webfrontend");


        // Act
        var executionConfiguration = await ExecutionConfigurationBuilder.Create(frontend.Resource)
            .WithEnvironmentVariablesConfig()
            .BuildAsync(new(DistributedApplicationOperation.Publish), NullLogger.Instance, CancellationToken.None)
            .ConfigureAwait(true);


        var envVars = executionConfiguration.EnvironmentVariables.ToDictionary();


        // Assert
        Assert.Contains(envVars, static (kvp) =>
        {
            var (key, value) = kvp;


            return key is "APISERVICE_HTTPS"
                && value is "{apiservice.bindings.https.url}";
        });
    }
}
```

EnvVarTests.cs

```csharp
using Aspire.Hosting;
using Microsoft.Extensions.Logging.Abstractions;


namespace Tests;


[TestClass]
public class EnvVarTests
{
    [TestMethod]
    public async Task WebResourceEnvVarsResolveToApiService()
    {
        // Arrange
        var builder = await DistributedApplicationTestingBuilder
            .CreateAsync();


        var frontend = builder.CreateResourceBuilder("webfrontend");


        // Act
        var executionConfiguration = await ExecutionConfigurationBuilder.Create(frontend.Resource)
            .WithEnvironmentVariablesConfig()
            .BuildAsync(new(DistributedApplicationOperation.Publish), NullLogger.Instance, CancellationToken.None)
            .ConfigureAwait(true);


        var envVars = executionConfiguration.EnvironmentVariables.ToDictionary();


        // Assert
        CollectionAssert.Contains(envVars,
            new KeyValuePair(
                key: "APISERVICE_HTTPS",
                value: "{apiservice.bindings.https.url}"));
    }
}
```

EnvVarTests.cs

```csharp
using Aspire.Hosting;
using Microsoft.Extensions.Logging.Abstractions;


namespace Tests;


public class EnvVarTests
{
    [Test]
    public async Task WebResourceEnvVarsResolveToApiService()
    {
        // Arrange
        var builder = await DistributedApplicationTestingBuilder
            .CreateAsync();


        var frontend = builder.CreateResourceBuilder("webfrontend");


        // Act
        var executionConfiguration = await ExecutionConfigurationBuilder.Create(frontend.Resource)
            .WithEnvironmentVariablesConfig()
            .BuildAsync(new(DistributedApplicationOperation.Publish), NullLogger.Instance, CancellationToken.None)
            .ConfigureAwait(true);


        var envVars = executionConfiguration.EnvironmentVariables.ToDictionary();


        // Assert
        Assert.That(envVars, Does.Contain(
            new KeyValuePair(
                key: "APISERVICE_HTTPS",
                value: "{apiservice.bindings.https.url}")));
    }
}
```

The preceding code:

* Relies on the `DistributedApplicationTestingBuilder.CreateAsync` API to asynchronously create the AppHost.
* The `builder` instance is used to retrieve an `IResourceWithEnvironment` instance named “webfrontend” from the `Resources` property.
* Builds an `ExecutionConfiguration` for the `webfrontend` resource using `ExecutionConfigurationBuilder`, explicitly enabling environment variable configuration via [`WithEnvironmentVariablesConfig`](/reference/api/csharp/aspire.hosting/executionconfigurationbuilderextensions/methods/#withenvironmentvariablesconfig "Adds an environment variables configuration gatherer to the builder.")[`withEnvironmentVariablesConfig`](/reference/api/typescript/aspire.hosting/withenvironmentvariablesconfig/ "Adds an environment variables configuration gatherer to the builder.").
* Calls `BuildAsync` with `DistributedApplicationOperation.Publish` to generate the environment variables that will be published for the resource, including unresolved binding expressions.
* With the returned environment variables, the test asserts that the `webfrontend` resource has an HTTPS environment variable that resolves to the `apiservice` resource.

## Capture logs from tests

[Section titled “Capture logs from tests”](#capture-logs-from-tests)

When writing tests for your Aspire solutions, you might want to capture and view logs to help with debugging and monitoring test execution. The `DistributedApplicationTestingBuilder` provides access to the service collection, allowing you to configure logging for your test scenarios.

### Configure logging providers

[Section titled “Configure logging providers”](#configure-logging-providers)

To capture logs from your tests, use the `AddLogging` method on the `builder.Services` to configure logging providers specific to your testing framework:

LoggingTest.cs

```csharp
using Microsoft.Extensions.Logging;


namespace Tests;


public class LoggingTest
{
    [Fact]
    public async Task GetWebResourceRootReturnsOkStatusCodeWithLogging()
    {
        // Arrange
        var builder = await DistributedApplicationTestingBuilder
            .CreateAsync();


        builder.Services.ConfigureHttpClientDefaults(clientBuilder =>
        {
            clientBuilder.AddStandardResilienceHandler();
        });


        // Configure logging to capture test execution logs
        builder.Services.AddLogging(logging => logging
            .AddConsole() // Outputs logs to console
            .AddFilter("Default", LogLevel.Information)
            .AddFilter("Microsoft.AspNetCore", LogLevel.Warning)
            .AddFilter("Aspire.Hosting.Dcp", LogLevel.Warning));


        await using var app = await builder.BuildAsync();


        await app.StartAsync();


        // Act
        var httpClient = app.CreateHttpClient("webfrontend");


        using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
        await app.ResourceNotifications.WaitForResourceHealthyAsync(
            "webfrontend",
            cts.Token);


        var response = await httpClient.GetAsync("/");


        // Assert
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
    }
}
```

LoggingTest.cs

```csharp
using Microsoft.Extensions.Logging;


namespace Tests;


[TestClass]
public class LoggingTest
{
    [TestMethod]
    public async Task GetWebResourceRootReturnsOkStatusCodeWithLogging()
    {
        // Arrange
        var builder = await DistributedApplicationTestingBuilder
            .CreateAsync();


        builder.Services.ConfigureHttpClientDefaults(clientBuilder =>
        {
            clientBuilder.AddStandardResilienceHandler();
        });


        // Configure logging to capture test execution logs
        builder.Services.AddLogging(logging => logging
            .AddConsole() // Outputs logs to console
            .AddFilter("Default", LogLevel.Information)
            .AddFilter("Microsoft.AspNetCore", LogLevel.Warning)
            .AddFilter("Aspire.Hosting.Dcp", LogLevel.Warning));


        await using var app = await builder.BuildAsync();


        await app.StartAsync();


        // Act
        var httpClient = app.CreateHttpClient("webfrontend");


        using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
        await app.ResourceNotifications.WaitForResourceHealthyAsync(
            "webfrontend",
            cts.Token);


        var response = await httpClient.GetAsync("/");


        // Assert
        Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);
    }
}
```

LoggingTest.cs

```csharp
using Microsoft.Extensions.Logging;


namespace Tests;


public class LoggingTest
{
    [Test]
    public async Task GetWebResourceRootReturnsOkStatusCodeWithLogging()
    {
        // Arrange
        var builder = await DistributedApplicationTestingBuilder
            .CreateAsync();


        builder.Services.ConfigureHttpClientDefaults(clientBuilder =>
        {
            clientBuilder.AddStandardResilienceHandler();
        });


        // Configure logging to capture test execution logs
        builder.Services.AddLogging(logging => logging
            .AddConsole() // Outputs logs to console
            .AddFilter("Default", LogLevel.Information)
            .AddFilter("Microsoft.AspNetCore", LogLevel.Warning)
            .AddFilter("Aspire.Hosting.Dcp", LogLevel.Warning));


        await using var app = await builder.BuildAsync();


        await app.StartAsync();


        // Act
        var httpClient = app.CreateHttpClient("webfrontend");


        using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
        await app.ResourceNotifications.WaitForResourceHealthyAsync(
                "webfrontend",
                cts.Token);


        var response = await httpClient.GetAsync("/");


        // Assert
        Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));
    }
}
```

### Configure log filters

[Section titled “Configure log filters”](#configure-log-filters)

Since the *appsettings.json* configuration from your application isn’t automatically replicated in test projects, you need to explicitly configure log filters. This is important to avoid excessive logging from infrastructure components that might overwhelm your test output. The following snippet explicitly configures log filters:

```csharp
builder.Services.AddLogging(logging => logging
    .AddFilter("Default", LogLevel.Information)
    .AddFilter("Microsoft.AspNetCore", LogLevel.Warning)
    .AddFilter("Aspire.Hosting.Dcp", LogLevel.Warning));
```

The preceding configuration:

* Sets the default log level to `Information` for most application logs.
* Reduces noise from ASP.NET Core infrastructure by setting it to `Warning` level.
* Limits Aspire hosting infrastructure logs to `Warning` level to focus on application-specific logs.

### Popular logging packages

[Section titled “Popular logging packages”](#popular-logging-packages)

Different testing frameworks have different logging provider packages available to assist with managing logging during test execution:

xUnit.net doesn’t capture log output from tests as test output. Tests must [use the `ITestOutputHelper` interface](https://xunit.net/docs/capturing-output) to achieve this.

For xUnit.net, consider using one of these logging packages:

* [📦 MartinCostello.Logging.XUnit](https://www.nuget.org/packages/MartinCostello.Logging.XUnit) - Outputs `ILogger` logs to `ITestOutputHelper` output.
* [📦 Xunit.DependencyInjection.Logging](https://www.nuget.org/packages/Xunit.DependencyInjection.Logging) - Integrates with xUnit.net’s dependency injection.
* [📦 Serilog.Extensions.Logging.File](https://www.nuget.org/packages/Serilog.Extensions.Logging.File) - Writes logs to files.
* [📦 Microsoft.Extensions.Logging.Console](https://www.nuget.org/packages/Microsoft.Extensions.Logging.Console) - Outputs logs to console.

For MSTest, consider using one of these logging packages:

* [📦 Serilog.Extensions.Logging.File](https://www.nuget.org/packages/Serilog.Extensions.Logging.File) - Writes logs to files.
* [📦 Microsoft.Extensions.Logging.Console](https://www.nuget.org/packages/Microsoft.Extensions.Logging.Console) - Outputs logs to console.

For NUnit, consider using one of these logging packages:

* [📦 Extensions.Logging.NUnit](https://www.nuget.org/packages/Extensions.Logging.NUnit) - Integrates with NUnit framework.
* [📦 Serilog.Extensions.Logging.File](https://www.nuget.org/packages/Serilog.Extensions.Logging.File) - Writes logs to files.
* [📦 Microsoft.Extensions.Logging.Console](https://www.nuget.org/packages/Microsoft.Extensions.Logging.Console) - Outputs logs to console.

## Summary

[Section titled “Summary”](#summary)

The Aspire testing project template makes it easier to create test projects for Aspire solutions. The template project includes a sample test that you can use as a starting point for your tests. The `DistributedApplicationTestingBuilder` follows a familiar pattern to the `WebApplicationFactory` in ASP.NET Core. It allows you to create a test host for your distributed application and run tests against it.

Finally, when using the `DistributedApplicationTestingBuilder` all resource logs are redirected to the `DistributedApplication` by default. The redirection of resource logs enables scenarios where you want to assert that a resource is logging correctly.

# What's new in Aspire 13

> Explore Aspire 13.0: multi-language app development with first-class Python and JavaScript support, container-based builds, aspire do pipelines, and VS Code extension.

📢 Aspire 13 represents a major milestone in the Aspire product line.

The product is now called Aspire, dropping its previous .NET prefix. Aspire is a multi-language application platform that continues to provide best-in-class support for .NET applications while making Python and JavaScript first-class citizens, with comprehensive support for running, debugging, and deploying applications.

This release introduces:

* Python support includes modules, Uvicorn deployment, flexible package management with uv, pip, or venv, and automatic production Dockerfile generation.
* JavaScript support includes Vite and npm-based apps, package manager auto-detection, debugging, and container-based build pipelines.
* Multi-language infrastructure provides URI, JDBC, and individual connection properties, plus certificate trust across languages and containers.
* Container files can serve as build artifacts, so build outputs are containers rather than folders for reproducible, isolated, and portable builds.
* `aspire do` provides build, publish, and deployment pipelines with parallel execution, dependency tracking, and extensible workflows.
* The modern CLI adds `aspire init` for existing apps and deployment state management that remembers configuration across runs.
* The VS Code extension streamlines project creation, integration management, multi-language debugging, and deployment.

Along with the rebranding, Aspire now has a new home at [aspire.dev](https://aspire.dev), the central hub for documentation, getting started guides, and community resources.

Aspire 13 requires the .NET 10 SDK or later.

If you have feedback, questions, or want to contribute to Aspire, collaborate with us on [ GitHub](https://github.com/microsoft/aspire) or join us on our new [ Discord](https://aka.ms/aspire-discord) to chat with the team and other community members.

## 🆙 Upgrade to Aspire 13.0

[Section titled “🆙 Upgrade to Aspire 13.0”](#-upgrade-to-aspire-130)

Caution

Aspire 13.0 is a major version release with breaking changes. Please review the [Breaking changes](#-breaking-changes) section before upgrading.

The easiest way to upgrade to Aspire 13.0 is using the `aspire update` command:

1. Update the Aspire CLI to the latest version:

   * Bash

     ```bash
     curl -sSL https://aspire.dev/install.sh | bash
     ```

   * PowerShell

     ```powershell
     irm https://aspire.dev/install.ps1 | iex
     ```

2. Update your Aspire project using the [`aspire update` command](/reference/cli/commands/aspire-update/):

   Aspire CLI — Update all Aspire packages

   ```bash
   aspire update
   ```

   This command will:

   * Update the `Aspire.AppHost.Sdk` version in your AppHost project.
   * Update all Aspire NuGet packages to version 13.0.
   * Handle dependency resolution automatically.
   * Support both regular projects and Central Package Management (CPM).

3. Update your Aspire templates:

   ```bash
   dotnet new install Aspire.ProjectTemplates
   ```

Note

If you’re upgrading from Aspire 8.x, follow [the upgrade guide](/whats-new/upgrade-aspire/) first to upgrade to 9.x, then upgrade to 13.0.

## 🧩 AppHost template updates

[Section titled “🧩 AppHost template updates”](#-apphost-template-updates)

Aspire 13.0 introduces a simplified AppHost project template structure. The SDK now encapsulates the `Aspire.Hosting.AppHost` package, resulting in cleaner project files.

**Before (9.x):**

```xml



  


  
    Exe
    net9.0
    enable
    enable
    1bf2ca25-7be4-4963-8782-c53a74e10ad9
  


  
    
    
  


  
    
    
  



```

**After (13.0):**

```xml



  
    Exe
    net10.0
    enable
    enable
    1bf2ca25-7be4-4963-8782-c53a74e10ad9
  


  
    
    
  


  
    
  



```

Key changes include:

* The SDK is specified directly in the `` tag with its version: `Sdk="Aspire.AppHost.Sdk/13.0.0"`.
* The SDK automatically includes `Aspire.Hosting.AppHost`, so an explicit package reference is no longer needed.
* The separate `` element and the `Microsoft.NET.Sdk` base SDK are removed.
* The target framework is updated from `net9.0` to `net10.0`.

The `aspire update` command automatically handles this migration when upgrading from 9.x to 13.0.

Tip

For an even simpler setup, Aspire 13.0 also supports [single-file AppHosts](#single-file-apphost-support) that don’t require a project file at all. Single-file AppHosts are perfect for quick prototypes and learning scenarios.

The same project as a file-based AppHost:

apphost.cs

```csharp
#:sdk Aspire.AppHost.Sdk@13.0.0
#:package Aspire.Hosting.Redis@13.0.0


var builder = DistributedApplication.CreateBuilder(args);


var cache = builder.AddRedis("cache");
var api = builder.AddProject("apiservice", "../MyApi")
                 .WithReference(cache);


builder.Build().Run();
```

No project file needed - just a single `.cs` file with package references declared using `#:package` directives.

## 🌐 Aspire as a multi-language platform

[Section titled “🌐 Aspire as a multi-language platform”](#-aspire-as-a-multi-language-platform)

Aspire 13.0 marks a shift from a .NET-centric orchestration tool to a multi-language application platform. Python and JavaScript are now first-class citizens alongside .NET, with comprehensive support for development, debugging, and deployment workflows.

### Python as a first-class citizen

[Section titled “Python as a first-class citizen”](#python-as-a-first-class-citizen)

Aspire 13.0 introduces comprehensive Python support, making it effortless to build, debug, and deploy Python applications alongside your other services.

#### Flexible Python application models

[Section titled “Flexible Python application models”](#flexible-python-application-models)

Aspire provides three ways to run Python code, each suited to different use cases:

Flexible Python application models

```csharp
var builder = DistributedApplication.CreateBuilder(args);


// Run a Python script directly
var etl = builder.AddPythonApp("etl-job", "../etl", "process_data.py");


// Run a Python module (python -m celery)
var worker = builder.AddPythonModule("celery-worker", "../worker", "celery")
    .WithArgs("worker", "-A", "tasks", "--loglevel=info");


// Run an executable from the virtual environment (e.g., gunicorn)
var api = builder.AddPythonExecutable("api", "../api", "gunicorn")
    .WithArgs("app:app", "--bind", "0.0.0.0:8000");
```

#### Uvicorn integration for ASGI applications

[Section titled “Uvicorn integration for ASGI applications”](#uvicorn-integration-for-asgi-applications)

For Python web applications using ASGI frameworks like FastAPI, Starlette, or Quart, Aspire provides dedicated [`AddUvicornApp`](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods/#adduvicornapp "Adds a Uvicorn-based Python application to the distributed application builder with HTTP endpoint configuration.")[`addUvicornApp`](/reference/api/typescript/aspire.hosting.python/adduvicornapp/ "Adds a Uvicorn-based Python application to the distributed application builder with HTTP endpoint configuration.") support:

Uvicorn integration

```csharp
var api = builder.AddUvicornApp("api", "./api", "main:app")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health");
```

The `AddUvicornApp` method automatically:

* Configures HTTP endpoints.
* Sets up appropriate Uvicorn command-line arguments.
* Supports hot-reload during development.
* Integrates with Aspire’s health check system.

#### Python package management

[Section titled “Python package management”](#python-package-management)

Aspire 13.0 provides flexible Python package management with automatic detection.

When you add a Python app, Aspire automatically detects and configures package management:

Automatic package detection

```csharp
// If pyproject.toml or requirements.txt exists → automatically uses pip
// If neither exists → creates a virtual environment (.venv)
var api = builder.AddUvicornApp("api", "./api", "main:app");
```

In most cases, you don’t need to configure package management explicitly because Aspire detects it automatically.

For modern Python projects using [uv](https://github.com/astral-sh/uv), explicitly opt in with [`WithUv`](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods/#withuv "Adds a UV environment setup task to ensure the virtual environment exists before running the Python application.")[`withUv`](/reference/api/typescript/aspire.hosting.python/withuv/ "Adds a UV environment setup task to ensure the virtual environment exists before running the Python application."):

Using uv for package management

```csharp
builder.AddUvicornApp("api", "./api", "main:app")
    .WithUv();  // Use uv for package management
```

When using `WithUv()`, Aspire:

* Automatically runs `uv sync` to install dependencies from `pyproject.toml`.
* Creates isolated virtual environments per project.
* Leverages uv’s performance benefits (10-100x faster than pip).
* Auto-detects Python version from project configuration.

To configure pip behavior explicitly, use [`WithPip`](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods/#withpip "Configures the Python resource to use pip as the package manager and optionally installs packages before the application starts.")[`withPip`](/reference/api/typescript/aspire.hosting.python/withpip/ "Configures the Python resource to use pip as the package manager and optionally installs packages before the application starts."):

Using pip for package management

```csharp
builder.AddUvicornApp("api", "./api", "main:app")
    .WithPip();  // Explicitly use pip for package management
```

When using `WithPip()`, Aspire:

* Automatically installs dependencies from `requirements.txt` or `pyproject.toml` (pip supports both).
* Detects virtual environments (`.venv`) by walking up parent directories.
* Creates a virtual environment if one doesn’t exist.

By default, Aspire uses `.venv` in the app directory as the virtual environment path. Use [`WithVirtualEnvironment`](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods/#withvirtualenvironment "Configures a custom virtual environment path for the Python application.")[`withVirtualEnvironment`](/reference/api/typescript/aspire.hosting.python/withvirtualenvironment/ "Configures a custom virtual environment path for the Python application.") to specify a custom path or control automatic creation:

Configuring virtual environment path

```csharp
// Use a custom venv path
builder.AddPythonApp("api", "./api", "main.py")
    .WithVirtualEnvironment("myenv");


// Use existing venv without auto-creation
builder.AddPythonApp("worker", "./worker", "worker.py")
    .WithVirtualEnvironment(".venv", createIfNotExists: false);
```

By default, `createIfNotExists` is `true`, so Aspire will create the virtual environment if it doesn’t exist. Set it to `false` to require the virtual environment to already exist.

#### VS Code debugging support

[Section titled “VS Code debugging support”](#vs-code-debugging-support)

Python applications can be debugged directly in VS Code with full breakpoint support. Aspire 13.0 automatically enables debugging infrastructure for all Python resources - no additional configuration required. See [Visual Studio Code extension](#visual-studio-code-extension) for more.

Supported debugging scenarios include:

* Debug Python scripts added with [`AddPythonApp`](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods/#addpythonapp "Adds a Python application to the application model.")[`addPythonApp`](/reference/api/typescript/aspire.hosting.python/addpythonapp/ "Adds a Python application to the application model."), including breakpoints and variable inspection.
* Debug Python modules added with [`AddPythonModule`](/reference/api/csharp/aspire.hosting.python/pythonappresourcebuilderextensions/methods/#addpythonmodule "Adds a Python module to the application model.")[`addPythonModule`](/reference/api/typescript/aspire.hosting.python/addpythonmodule/ "Adds a Python module to the application model."), including module resolution.
* Debug Flask apps with auto-reload.
* Debug Uvicorn and FastAPI ASGI applications with async and await support.

Debugging is automatically enabled for Python resources, and the Aspire VS Code extension generates VS Code launch configurations automatically.

#### Automatic Dockerfile generation

[Section titled “Automatic Dockerfile generation”](#automatic-dockerfile-generation)

Aspire automatically generates production-ready Dockerfiles for Python applications when publishing:

Automatic Dockerfile generation

```csharp
// With uv (recommended)
builder.AddUvicornApp("api", "./api", "main:app")
    .WithUv();


// Or with pip
builder.AddUvicornApp("api", "./api", "main:app")
    .WithPip();
```

The generated Dockerfile automatically adapts based on your package manager choice:

* With uv, the Dockerfile uses uv for fast dependency installation from `pyproject.toml`.
* With pip, it installs dependencies from `requirements.txt`.

Both approaches use appropriate Python base images and follow container best practices.

#### Python version detection

[Section titled “Python version detection”](#python-version-detection)

Aspire automatically detects the Python version for Dockerfile generation from multiple sources (in priority order):

1. A `.python-version` file has the highest priority.
2. The `requires-python` field in `pyproject.toml` is next.
3. The virtual environment’s `python --version` provides the fallback.

The detected version selects the appropriate Python base image for Docker publishing.

#### Starter template: Vite + FastAPI

[Section titled “Starter template: Vite + FastAPI”](#starter-template-vite--fastapi)

Aspire 13.0 includes a new `aspire-py-starter` template that demonstrates a full-stack Python application:

Create Python starter template

```bash
aspire new aspire-py-starter
```

This template includes:

* A FastAPI backend runs as a Python ASGI application using Uvicorn.
* A Vite and React frontend uses TypeScript.
* OpenTelemetry integration provides distributed tracing, logs, and metrics.
* Optional Redis caching provides a distributed cache across requests.
* Container files let the Python backend serve the frontend’s static files.

Build a full-stack multi-language app—Python backend + JavaScript frontend—fast. Use `aspire new aspire-py-starter` to generate it, then explore the [Python integration](/integrations/frameworks/python/) and [JavaScript integration](/integrations/frameworks/javascript/) guides.

The React frontend communicates with the FastAPI backend via HTTP endpoints, demonstrating seamless integration between the two languages within a single Aspire application. The new template has a modern UX:

![Deployed Python/React application running in Docker Compose](/_astro/python-starter-dark.C71FfuaJ_uxMQg.webp)

### JavaScript as a first-class citizen

[Section titled “JavaScript as a first-class citizen”](#javascript-as-a-first-class-citizen)

Aspire 13.0 refactors and expands JavaScript support. In earlier versions, the `Aspire.Hosting.NodeJs` integration enabled JavaScript applications. In Aspire 13.0, the integration was renamed to `Aspire.Hosting.JavaScript` and it introduces [`AddJavaScriptApp`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#addjavascriptapp "Adds a JavaScript application resource to the distributed application using the specified app directory and run script.")[`addJavaScriptApp`](/reference/api/typescript/aspire.hosting.javascript/addjavascriptapp/ "Adds a JavaScript application resource to the distributed application using the specified app directory and run script.") as the foundational method for all JavaScript applications.

#### Unified JavaScript application model

[Section titled “Unified JavaScript application model”](#unified-javascript-application-model)

The new `AddJavaScriptApp` method replaces the older `AddNpmApp` (removed) and provides a consistent way to add JavaScript applications:

Unified JavaScript application model

```csharp
var builder = DistributedApplication.CreateBuilder(args);


// Add a JavaScript application - runs "npm run dev" by default
var frontend = builder.AddJavaScriptApp("frontend", "./frontend");


// Use a different package manager
var admin = builder.AddJavaScriptApp("admin", "./admin")
    .WithYarn();
```

By default, `AddJavaScriptApp`:

* Automatically detects npm from `package.json`.
* Runs the “dev” script during local development.
* Runs the “build” script when publishing to create production assets.
* Automatically generates Dockerfiles to build production assets.

#### Package manager flexibility

[Section titled “Package manager flexibility”](#package-manager-flexibility)

Aspire automatically detects and supports multiple JavaScript package managers with intelligent defaults for both development and production scenarios.

Starting in Aspire 13.0, package managers install dependencies by default (`install = true`). This keeps dependencies up to date during development and publishing.

When publishing (production mode), Aspire automatically uses deterministic install commands based on the presence of lockfiles:

* npm uses `npm ci` if `package-lock.json` exists; otherwise, it uses `npm install`.
* Yarn uses `yarn install --immutable` when `yarn.lock` exists and Yarn 2 or later is detected. Otherwise, it uses `yarn install --frozen-lockfile` when `yarn.lock` exists or `yarn install` when no lockfile exists.
* pnpm uses `pnpm install --frozen-lockfile` if `pnpm-lock.yaml` exists; otherwise, it uses `pnpm install`.

This ensures reproducible builds in CI/CD and production environments while remaining flexible during development.

You can also customize package manager behavior:

Customizing package managers

```csharp
// Customize npm with additional flags
var app = builder.AddJavaScriptApp("app", "./app")
    .WithNpm(installCommand: "ci", installArgs: ["--legacy-peer-deps"]);


// Or use different package managers
var yarnApp = builder.AddJavaScriptApp("yarn-app", "./yarn-app")
    .WithYarn(installArgs: ["--immutable"]);
```

#### Customizing scripts

[Section titled “Customizing scripts”](#customizing-scripts)

You can customize which scripts run during development and build:

Customizing scripts

```csharp
// Use different script names
var app = builder.AddJavaScriptApp("app", "./app")
    .WithRunScript("start")      // Run "npm run start" during development instead of "dev"
    .WithBuildScript("prod");     // Run "npm run prod" during publish instead of "build"
```

#### Passing arguments to scripts

[Section titled “Passing arguments to scripts”](#passing-arguments-to-scripts)

Unlike the deprecated `AddNpmApp` API, `AddJavaScriptApp` does not support an `args` constructor parameter for passing command-line arguments directly to scripts. You have two options to pass arguments:

Option 1 uses [`WithArgs`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withargs "Adds arguments to be passed to a resource that supports arguments when it is launched.")[`withArgs`](/reference/api/typescript/aspire.hosting/withargs/ "Adds arguments to be passed to a resource that supports arguments when it is launched.") to pass arguments directly:

Pass arguments using WithArgs

```csharp
// Before (Aspire 9.x with AddNpmApp)
// builder.AddNpmApp("hasura-console", "../Web/ClientApp",
//     scriptName: "hasura:console",
//     args: ["--no-browser"])


// After (Aspire 13.0 with AddJavaScriptApp)
builder.AddJavaScriptApp("hasura-console", "../Web/ClientApp")
    .WithRunScript("hasura:console")
    .WithArgs("--no-browser");
```

Option 2 defines custom scripts with arguments in `package.json`:

package.json — Define custom scripts with arguments

```json
{
  "scripts": {
    "dev": "vite",
    "hasura:console": "hasura console --no-browser"
  }
}
```

Reference custom script

```csharp
// Before (Aspire 9.x with AddNpmApp)
// builder.AddNpmApp("hasura-console", "../Web/ClientApp",
//     scriptName: "hasura:console",
//     args: ["--no-browser"])


// After (Aspire 13.0 with AddJavaScriptApp)
builder.AddJavaScriptApp("hasura-console", "../Web/ClientApp")
    .WithRunScript("hasura:console");
```

Option 2 keeps all script configuration in `package.json`, making your scripts more discoverable and easier to run outside of Aspire (e.g., `npm run hasura:console`).

#### Vite support

[Section titled “Vite support”](#vite-support)

[`AddViteApp`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#addviteapp "Adds a Vite app to the distributed application builder.")[`addViteApp`](/reference/api/typescript/aspire.hosting.javascript/addviteapp/ "Adds a Vite app to the distributed application builder.") is now a specialization of `AddJavaScriptApp` with Vite-specific optimizations:

Vite support

```csharp
var frontend = builder.AddViteApp("frontend", "./frontend")
    .WithReference(api);
```

Vite applications get:

* Automatic port binding configuration.
* Hot module replacement (HMR) support.
* Optimized build scripts for production.
* Automatic Dockerfile generation.

#### Dynamic Dockerfile generation

[Section titled “Dynamic Dockerfile generation”](#dynamic-dockerfile-generation)

JavaScript applications automatically generate Dockerfiles when published, with intelligent defaults based on your package manager:

Dynamic Dockerfile generation

```csharp
var app = builder.AddJavaScriptApp("app", "./app");
```

The generated Dockerfile:

* Detects Node.js version from `.nvmrc`, `.node-version`, `package.json`, or `.tool-versions`.
* Uses multi-stage builds for smaller images.
* Installs dependencies in a separate layer for better caching.
* Runs your build script to create production assets.
* Defaults to `node:22-slim` if no version is specified.

For information about using JavaScript build artifacts in other containers, see [Container files as build artifacts](#container-files-as-build-artifacts).

#### Node support

[Section titled “Node support”](#node-support)

[`AddNodeApp`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#addnodeapp "Adds a node application to the application model. Node should be available on the PATH.")[`addNodeApp`](/reference/api/typescript/aspire.hosting.javascript/addnodeapp/ "Adds a node application to the application model. Node should be available on the PATH.") has now been refactored to align with other language integrations.

Node support

```csharp
var app = builder.AddNodeApp("frontend", "./frontend", "app.js")
    .WithReference(api);
```

Node.js applications get:

* Defaults to npm when `package.json` exists.
* Allows for customizing package manager and build/run scripts.
* Automatic Dockerfile generation with multi-stage builds for smaller images (defaults to `node:22-alpine` if no version is specified).

### Multi-language infrastructure

[Section titled “Multi-language infrastructure”](#multi-language-infrastructure)

Beyond language-specific support, Aspire 13.0 introduces infrastructure features that work across all languages.

#### Multi-language connection properties

[Section titled “Multi-language connection properties”](#multi-language-connection-properties)

Database resources now expose multiple connection string formats automatically, making it easy to connect from any language:

Multi-language connection properties

```csharp
var postgres = builder.AddPostgres("db").AddDatabase("mydb");


// .NET app uses the "ConnectionStrings" configuration section
var dotnetApi = builder.AddProject()
    .WithReference(postgres);


// Python app can use URI format
var pythonWorker = builder.AddPythonModule("worker", "./worker", "worker.main")
    .WithEnvironment("DATABASE_URL", postgres.Resource.UriExpression);


// Java app can use JDBC format
var javaApp = builder.AddExecutable("java-app", "java", "./app", ["-jar", "app.jar"])
    .WithEnvironment("DB_JDBC", postgres.Resource.JdbcConnectionStringExpression);
```

When you reference a database resource with [`WithReference`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withreference "Injects a connection string as an environment variable from the source resource into the destination resource, using the source resource's name as the...")[`withReference`](/reference/api/typescript/aspire.hosting/withreference/ "Adds a reference to another resource"), Aspire automatically exposes multiple connection properties as environment variables. For example, a PostgreSQL resource named `db` exposes:

* `DB_URI` - PostgreSQL URI format: `postgresql://user:pass@host:port/dbname`.
* `DB_JDBCCONNECTIONSTRING` - JDBC format: `jdbc:postgresql://host:port/dbname`.
* `DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD`, `DB_DATABASENAME` - Individual properties.

The JDBC connection string does not include credentials for security best practices. Use the separate `DB_USERNAME` and `DB_PASSWORD` environment variables to authenticate, or configure your JDBC driver to use these properties.

This pattern works for all supported databases (PostgreSQL, SQL Server, Oracle, MySQL, MongoDB, etc.) with appropriate URI and JDBC formats for each.

Note

These new connection property conventions are available in the built-in Aspire database integrations (PostgreSQL, SQL Server, Oracle, MySQL, MongoDB, etc.). If you have custom or community integrations, they may need to be updated to expose these properties. See the [connection properties agent documentation](https://github.com/microsoft/aspire/blob/main/.github/agents/connectionproperties.agent.md) for guidance on implementing these conventions in your own integrations.

#### Certificate trust across languages

[Section titled “Certificate trust across languages”](#certificate-trust-across-languages)

Aspire 13.0 automatically configures ASP.NET Development Certificate trust for Python, Node.js, and containerized applications without any additional configuration:

Certificate trust across languages

```csharp
// Python applications automatically trust development certificates
var pythonApi = builder.AddUvicornApp("api", "./api", "main:app");


// Node.js applications automatically trust development certificates
var nodeApi = builder.AddJavaScriptApp("frontend", "./frontend");


// Containerized applications automatically trust development certificates
var container = builder.AddContainer("service", "myimage");
```

Aspire automatically:

* Python resources receive the `SSL_CERT_FILE` and `REQUESTS_CA_BUNDLE` environment variables.
* Node.js resources receive the `NODE_EXTRA_CA_CERTS` environment variable.
* Containers mount certificate bundles and receive the appropriate environment variables.
* Aspire generates and manages development certificates without manual intervention on all platforms.

This enables secure HTTPS communication during local development across all languages and containerized services.

#### Simplified service URL environment variables

[Section titled “Simplified service URL environment variables”](#simplified-service-url-environment-variables)

Aspire 13.0 introduces multi-language-friendly environment variables that make service discovery easier for apps that consume environment variables directly.

Simplified service URL environment variables

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var api = builder.AddProject("api");


// Python app gets simple environment variables
var pythonApp = builder.AddPythonModule("worker", "./worker", "worker.main")
    .WithReference(api); // Sets API and API_HTTPS env vars


await builder.Build().RunAsync();
```

Instead of complex service discovery formats, these apps receive simple environment variables:

* `API_HTTP=http://localhost:5000`—HTTP endpoint.
* `API_HTTPS=https://localhost:5001`—HTTPS endpoint.

This feature makes Aspire’s service discovery mechanism accessible to any programming language, not just .NET applications with service discovery libraries.

## 🛠️ CLI and tooling

[Section titled “🛠️ CLI and tooling”](#️-cli-and-tooling)

### aspire init command

[Section titled “aspire init command”](#aspire-init-command)

The new `aspire init` command provides a streamlined, interactive experience for initializing Aspire solutions with comprehensive project setup and configuration.

Find out more about the `aspire init` command in the [aspire init documentation](/reference/cli/commands/aspire-init/).

Initialize new Aspire solution

```bash
# Initialize a new Aspire solution - interactive prompts guide you through setup
aspire init
```

When you run `aspire init`, the CLI will:

* Find and update existing solution files in the current directory.
* Create a single-file AppHost for quick starts when no solution exists.
* Prompt you to add projects to your AppHost.
* Configure references to service defaults automatically.
* Create package source mappings for Aspire packages in `NuGet.config`.
* Prompt you to select the appropriate template version.

The init command simplifies the initial project setup through an interactive workflow that ensures consistent configuration across team members.

Note

The `aspire init` command sets up the Aspire project structure and configuration, but does not automatically add resources (databases, caches, message queues, etc.) to your AppHost. You’ll need to manually add resource definitions to your AppHost code using methods like [`AddPostgres`](/reference/api/csharp/aspire.hosting.postgresql/postgresbuilderextensions/methods/#addpostgres "Adds a PostgreSQL resource to the application model. A container is used for local development.")[`addPostgres`](/reference/api/typescript/aspire.hosting.postgresql/addpostgres/ "Adds a PostgreSQL resource to the application model. A container is used for local development."), [`AddRedis`](/reference/api/csharp/aspire.hosting.redis/redisbuilderextensions/methods/#addredis "Adds a Redis container to the application model.")[`addRedis`](/reference/api/typescript/aspire.hosting.redis/addredis/ "Adds a Redis container to the application model."), [`AddRabbitMQ`](/reference/api/csharp/aspire.hosting.rabbitmq/rabbitmqbuilderextensions/methods/#addrabbitmq "Adds a RabbitMQ container to the application model.")[`addRabbitMQ`](/reference/api/typescript/aspire.hosting.rabbitmq/addrabbitmq/ "Adds a RabbitMQ container to the application model."), etc.

### aspire new: Curated starter templates

[Section titled “aspire new: Curated starter templates”](#aspire-new-curated-starter-templates)

Aspire 13.0 refocuses `aspire new` around curated starter templates that demonstrate different application patterns. The command now provides an interactive experience designed to help you get started quickly with ready-to-run examples.

```bash
aspire new
```

When you run the command, you’ll see an interactive menu to select a starter template:

```plaintext
Select a template:


> Blazor & Minimal API starter
  React (Vite) & FastAPI starter
  Empty AppHost


(Type to search)
```

Available starter templates include:

* The [Blazor and Minimal API starter](/get-started/first-app/?lang=csharp) is a full-stack .NET application with a Blazor frontend and ASP.NET Core API.
* The [React (Vite) and FastAPI starter](#starter-template-vite--fastapi) demonstrates Python and JavaScript integration.
* The Empty AppHost is a minimal single-file AppHost for custom applications.

The starter template collection is designed to be extensible and will grow over time to showcase different architectural patterns and technology combinations. This approach makes it easier to explore Aspire’s capabilities and learn from working examples.

For command reference material, see the [aspire new documentation](/reference/cli/commands/aspire-new/).

### Aspire update improvements

[Section titled “Aspire update improvements”](#aspire-update-improvements)

The `aspire update` command has received significant improvements in Aspire 13.0, including the new `--self` flag to update the CLI itself:

Aspire update commands

```bash
# Update all Aspire packages in the current project
aspire update


# Update the Aspire CLI itself (new in 13.0)
aspire update --self


# Update a specific project
aspire update --project ./src/MyApp.AppHost
```

Aspire 13.0 adds:

* A `--self` flag that updates the Aspire CLI without reinstalling it.
* Reliability fixes for edge cases in dependency resolution.
* Clearer error messages when updates fail.
* Faster package detection and update operations.

The `aspire update` command continues to support:

* Central package management (CPM) solutions.
* Diamond dependency resolution.
* Single-file app hosts.
* XML fallback parsing for unresolvable AppHost SDKs.
* Enhanced visual presentation with colorized output.
* Channel awareness (stable, preview, staging).

For detailed command reference, see [aspire update](/reference/cli/commands/aspire-update/).

### Visual Studio Code extension

[Section titled “Visual Studio Code extension”](#visual-studio-code-extension)

Aspire 13.0 includes a new Aspire VS Code extension which brings Aspire CLI features to VS Code. It provides commands to create and debug projects, add integrations, configure launch settings, and manage deployments directly from the Command Palette.

Note

To use most extension features, the Aspire 13.0 CLI must be installed and available on the user `PATH`. You can verify this by running `aspire --version` in a VS Code terminal. For installation steps, see [Upgrade to Aspire 13.0](#-upgrade-to-aspire-130).

Key features include:

* Launch and debug Python and C# resources in VS Code with the Aspire debugger.
* Use `Aspire: New Aspire project` to create projects from templates.
* Use `Aspire: Add an integration` to add Aspire integrations to your AppHost.
* Use `Aspire: Configure launch.json` to set up a VS Code launch configuration automatically.
* Use `Aspire: Manage configuration settings` to configure Aspire CLI settings.
* Use the preview `Aspire: Publish deployment artifacts` and `Aspire: Deploy app` commands for publishing and deployment.

To get started:

1. Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=microsoft-aspire.aspire-vscode).
2. Open the Command Palette (Command + Shift + P`CommandShiftP`Control + Shift + P`CtrlShiftP`Control + Shift + P`CtrlShiftP`).
3. Type “Aspire” to see all available commands.
4. Use `Aspire: Configure launch.json` to set up debugging for your AppHost.

The extension requires the Aspire CLI to be installed and available on your PATH. All commands are grouped under the Aspire category in the Command Palette for easy discovery.

### Single-file AppHost support

[Section titled “Single-file AppHost support”](#single-file-apphost-support)

Aspire 13.0 introduces comprehensive support for single-file app hosts, allowing you to define your entire distributed application in a single `.cs` file without a project file.

Single-file AppHost

```csharp
// apphost.cs
#:sdk Aspire.AppHost.Sdk@13.0.0
#:package Aspire.Hosting.PostgreSQL@13.0.0


var builder = DistributedApplication.CreateBuilder(args);


var database = builder.AddPostgres("postgres");


builder.AddProject("api")
    .WithReference(database);


await builder.Build().RunAsync();
```

Single-file app host support includes:

* The `aspire-apphost-singlefile` template, available through `aspire new`.
* Integration with `aspire run`, `aspire deploy`, `aspire publish`, `aspire add`, and `aspire update`.
* Full debugging and launch configuration support.

Note

Single-file app hosts require .NET 10.0 SDK or later.

### Automatic .NET SDK installation (Preview)

[Section titled “Automatic .NET SDK installation (Preview)”](#automatic-net-sdk-installation-preview)

The Aspire CLI includes a preview feature for automatically installing required .NET SDK versions when they’re missing.

Caution

This is a preview feature that is **not enabled by default**. To use automatic SDK installation, enable it with:

```bash
aspire config set features.dotnetSdkInstallationEnabled true
```

Once enabled, the CLI will automatically install missing SDKs:

```bash
# With the feature enabled, the CLI will automatically install the required SDK
aspire run


# Installing .NET SDK 10.0.100...
# ✅ SDK installation complete
# Running app host...
```

The automatic SDK installation feature provides:

* Support for Windows, macOS, and Linux.
* Automatic detection of required SDK versions.
* Alternative installation options if automatic installation fails.

When enabled, this preview feature can improve the onboarding experience for new team members and CI/CD environments.

### Non-interactive mode for CI/CD

[Section titled “Non-interactive mode for CI/CD”](#non-interactive-mode-for-cicd)

The `--non-interactive` flag disables prompts and interactive progress indicators for CI/CD scenarios. The CLI automatically detects common CI environments and enables this mode. You can also set `ASPIRE_NON_INTERACTIVE=true` or use `--non-interactive` explicitly.

Note

Not all commands support non-interactive mode. Commands that require user input will fail if the `--non-interactive` flag is set and required values are not provided through other means.

***

For advanced deployment workflows, see [aspire do](#aspire-do), which introduces a comprehensive pipeline system for coordinating build, deployment, and publishing operations.

## ⭐ Major new features

[Section titled “⭐ Major new features”](#-major-new-features)

### aspire do

[Section titled “aspire do”](#aspire-do)

Aspire 13.0 introduces `aspire do` - a comprehensive system for coordinating build, deployment, and publishing operations. This new architecture provides a foundation for orchestrating complex deployment workflows with built-in support for step dependencies, parallel execution, and detailed progress reporting.

The `aspire do` system replaces the previous publishing infrastructure with a more flexible, extensible model that allows resource-specific deployment logic to be decentralized and composed into larger workflows.

Caution

🧪 **Early Preview**: The pipeline APIs are in early preview and marked as experimental. See [aspire do command reference](/reference/cli/commands/aspire-do/) for more information.

For basic CLI commands and tooling, see [CLI and tooling](#cli-and-tooling), which covers [aspire init](#aspire-init-command), [aspire update](#aspire-update-improvements), and [non-interactive mode](#non-interactive-mode-for-cicd).

The following example adds a custom pipeline step:

The Aspire AppHost defines a global `DistributedApplicationPipeline` instance on the `DistributedApplicationBuilder` that can be used to register steps in the pipeline at the top-level.

Custom pipeline step

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.Pipeline.AddStep("validate", (context) =>
{
    context.Logger.LogInformation("Running validation checks...");
    // Your custom validation logic
    return Task.CompletedTask;
}, requiredBy: WellKnownPipelineSteps.Build);
```

Steps registered in the pipeline can be run via the CLI:

Run custom pipeline step

```bash
aspire do validate
```

The pipeline system supports global steps, resource-specific steps, dependency configuration, parallel execution, and built-in logging. Resources can contribute their own steps via [`WithPipelineStepFactory`](/reference/api/csharp/aspire.hosting/pipelinestepfactoryextensions/methods/#withpipelinestepfactory "Adds a pipeline step to the resource that will be executed during deployment.")[`withPipelineStepFactory`](/reference/api/typescript/aspire.hosting/withpipelinestepfactory/ "Adds a pipeline step to the resource that will be executed during deployment.") and control ordering with [`WithPipelineConfiguration`](/reference/api/csharp/aspire.hosting/pipelinestepfactoryextensions/methods/#withpipelineconfiguration "Registers a callback to be executed during the pipeline configuration phase, allowing modification of step dependencies and relationships.")[`withPipelineConfiguration`](/reference/api/typescript/aspire.hosting/withpipelineconfiguration/ "Registers a callback to be executed during the pipeline configuration phase, allowing modification of step dependencies and relationships.").

#### Running pipeline steps

[Section titled “Running pipeline steps”](#running-pipeline-steps)

Use `aspire do` to execute pipeline steps. The command automatically resolves dependencies and executes steps in the correct order:

Running pipeline steps

```bash
aspire do deploy                              # Runs all steps necessary to deploy the app
aspire do publish --output-path ./artifacts   # Custom output path
aspire do deploy --environment Production     # Target specific environment
aspire do deploy --pipeline-log-level debug            # Verbose logging for troubleshooting
```

### Container files as build artifacts

[Section titled “Container files as build artifacts”](#container-files-as-build-artifacts)

Aspire 13.0 can extract files from one resource’s container and copy them into another resource’s container during the build process. This enables patterns such as building a frontend in one container and serving it from a backend in another.

Container files as build artifacts

```csharp
var frontend = builder.AddViteApp("frontend", "./frontend");
var api = builder.AddUvicornApp("api", "./api", "main:app");


// Extract files FROM the frontend container and copy TO the 'static' folder
// in the api container
api.PublishWithContainerFiles(frontend, "./static");
```

The process has four steps:

1. The `frontend` resource builds inside its container, producing output files.
2. Aspire extracts those files from the `frontend` container.
3. The files are copied into the `api` container at `./static`.
4. The final `api` container contains both the API code and the frontend static files.

For example, the FastAPI app can serve the static files:

Serving frontend from backend

```python
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles


app = FastAPI()


# API endpoints
@app.get("/api/data")
def get_data():
    return {"message": "Hello from API"}


# Serve the frontend static files
app.mount("/", StaticFiles(directory="static", html=True), name="static")
```

This pattern works with any resource types (C#, Python, JavaScript) and integrates seamlessly with `aspire do` for dependency tracking, parallel execution, and incremental builds.

### Dockerfile builder API (experimental)

[Section titled “Dockerfile builder API (experimental)”](#dockerfile-builder-api-experimental)

Aspire 13.0 introduces an experimental programmatic Dockerfile generation API that allows you to define Dockerfiles using C# code with a composable, type-safe API.

Caution

🧪 **Experimental Feature**: The Dockerfile Builder API is experimental and may change before general availability.

```csharp
var app = builder.AddContainer("app", "app")
    .PublishAsDockerFile(publish =>
    {
        publish.WithDockerfileBuilder("/path/to/app", context =>
        {
            var buildStage = context.Builder
                .From("golang:1.23", "builder")
                .WorkDir("/build")
                .Copy(".", "./")
                .Run("go build -o /app/server .");


            context.Builder
                .From("alpine:latest")
                .CopyFrom(buildStage.StageName!, "/app/server", "/app/server")
                .Entrypoint(["/app/server"]);
        });
    });
```

The API provides multi-stage builds, fluent method chaining (`WorkDir`, `Copy`, `Run`, `Env`, `User`, `Entrypoint`), comments/formatting, and BuildKit features.

### Certificate management

[Section titled “Certificate management”](#certificate-management)

Aspire 13.0 introduces certificate management for custom certificate authorities and developer certificate trust:

```csharp
// Add custom certificate collections
var certs = builder.AddCertificateAuthorityCollection("custom-certs")
    .WithCertificatesFromFile("./certs/my-ca.pem")
    .WithCertificatesFromStore(StoreName.CertificateAuthority, StoreLocation.LocalMachine);


var gateway = builder.AddYarp("gateway")
    .WithCertificateAuthorityCollection(certs)
    .WithDeveloperCertificateTrust(trust: true);
```

Features include loading from PEM files or certificate stores, flexible trust scoping, customizable container paths, and automatic dev certificate trust configuration.

## 📦 Integrations

[Section titled “📦 Integrations”](#-integrations)

Aspire 13.0 introduces new integration packages that expand platform support.

### .NET MAUI integration

[Section titled “.NET MAUI integration”](#net-maui-integration)

Aspire 13.0 introduces a new `Aspire.Hosting.Maui` package that enables orchestrating .NET MAUI mobile applications alongside your cloud services.

AppHost.cs

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var api = builder.AddProject("api");


// To easily reach your local API project from the
// emulator/Simulator/physical device, you can use the Dev Tunnels integration
var publicDevTunnel = builder.AddDevTunnel("devtunnel-public")
    .WithAnonymousAccess()
    .WithReference(api.GetEndpoint("https"));


// Add the .NET MAUI project resource
var mauiapp = builder.AddMauiProject("myapp", @"../MyApp/MyApp.csproj");


// Add MAUI app for Windows
mauiapp.AddWindowsDevice()
    .WithReference(api);


// Add MAUI app for Mac Catalyst
mauiapp.AddMacCatalystDevice()
    .WithReference(api);


// Add MAUI app for iOS running on the iOS Simulator (starts
// a random one, or uses the currently started one)
mauiapp.AddiOSSimulator()
    .WithOtlpDevTunnel() // Needed to get the OpenTelemetry data to "localhost"
    .WithReference(api, publicDevTunnel); // Needs a dev tunnel to reach "localhost"


// Add MAUI app for Android running on the emulator with
// default emulator (uses running or default emulator, needs to be started)
mauiapp.AddAndroidEmulator()
    .WithOtlpDevTunnel() // Needed to get the OpenTelemetry data to "localhost"
    .WithReference(api, publicDevTunnel); // Needs a dev tunnel to reach "localhost"


builder.Build().Run();
```

MAUI integration features:

* The integration supports Windows, Mac Catalyst, Android, and iOS.
* You can register multiple device instances for testing.
* Aspire detects host OS compatibility and marks resources as unsupported when needed.
* MAUI apps participate in service discovery and can reference backend services.

This enables a complete mobile + cloud development experience where you can run and debug your mobile app alongside your backend services in a single Aspire project.

## 📊 Dashboard enhancements

[Section titled “📊 Dashboard enhancements”](#-dashboard-enhancements)

### Aspire MCP server

[Section titled “Aspire MCP server”](#aspire-mcp-server)

[The Dashboard now includes an MCP server](/get-started/aspire-mcp-server/) that integrates Aspire into your AI development ecosystem. The MCP server enables AI assistants to query resources, access telemetry data, and execute commands directly from your development environment.

To get started:

1. Run your Aspire app and open the dashboard.
2. Click the MCP button in the top right corner.
3. Follow the instructions to configure your AI assistant (Claude Code, GitHub Copilot CLI, Cursor, VS Code, etc.).

The MCP server uses streamable HTTP with API key authentication for secure access. Configuration requires:

* `url`: The Aspire MCP endpoint address.
* `type`: Set to “http” for the streamable-HTTP MCP server.
* `x-mcp-api-key`: HTTP header for authentication.

Available tools include:

* `list_resources`—Retrieve all resources with state, endpoints, environment variables, and metadata.
* `list_console_logs`—Access resource console output.
* `list_structured_logs`—Retrieve telemetry data, optionally filtered by resource.
* `list_traces`—Access distributed trace information.
* `list_trace_structured_logs`—View logs associated with specific traces.
* `execute_resource_command`—Execute commands on resources.

This enables AI assistants to directly interact with your Aspire applications, analyze telemetry in real-time, and provide intelligent insights during development.

![MCP dialog](/_astro/mcp-dialog.DJhOAzMI_ZNCrSS.webp "MCP dialog")

### Interaction services dynamic inputs and comboboxes

[Section titled “Interaction services dynamic inputs and comboboxes”](#interaction-services-dynamic-inputs-and-comboboxes)

The interaction service just got a major upgrade:

* 💫 Dropdowns can now accept text—in other words, ComboBox inputs. For more information, see [interaction service custom choice](#interaction-service-custom-choices).
* 🔄 Supports dynamic data loading for cascading dropdowns. For more information, see [interaction service dynamic inputs](#interaction-service-dynamic-inputs).

You can see an example of the new interaction service features in the dashboard with the Azure provisioning dialog. 🚀

![New interaction service feature in the Azure provisioning dialog](/_astro/interaction-service.DyDhNPwb_1Fr5Pm.webp "New interaction service feature in the Azure provisioning dialog")

### Multi-language icons

[Section titled “Multi-language icons”](#multi-language-icons)

Aspire is going multi-language with strong support for JavaScript ☕ and Python 🐍 apps. The dashboard features new programming language icons for app resources. This includes .NET projects (C#, F#, VB.NET) and JavaScript and Python apps.

![Multi-language icons](/_astro/language-icons.BEudrxhN_ZtkNc.webp "Multi-language icons")

### Improved accent colors

[Section titled “Improved accent colors”](#improved-accent-colors)

Resources in the dashboard have accent colors, which is used to color their icon and telemetry. Accent colors are now more FluentUI-ish (saturation++) with custom tweaks for light and dark themes.

The dark blue accent color is no longer almost invisible on a dark background!

![Accent color tweaks](/_astro/color-tweaks.vuk9FmkC_ZpotwQ.webp "Accent color tweaks")

### Health checks last run time

[Section titled “Health checks last run time”](#health-checks-last-run-time)

The dashboard makes it easy to see resource health statuses. New in Aspire 13, the last run time is now displayed next to each resource’s current state. This helps you tell whether an unhealthy resource is still being checked and progressing toward a healthy state.

![Health checks last run time](/_astro/health-checks-last-run.BNWR06oy_uB0fF.webp "Health checks last run time")

## 🖥️ App model enhancements

[Section titled “🖥️ App model enhancements”](#️-app-model-enhancements)

### C# file-based app support

[Section titled “C# file-based app support”](#c-file-based-app-support)

Aspire 13.0 adds first-class support for C# file-based applications, enabling you to add C# apps without full project files to your distributed application.

apphost.cs

```csharp
#:sdk Aspire.AppHost.Sdk@13.0.0
#:package Aspire.Hosting.Redis@13.0.0


// Type is for evaluation purposes only and is subject to change or
// removal in future updates. Suppress this diagnostic to proceed.
#pragma warning disable ASPIRECSHARPAPPS001


var builder = DistributedApplication.CreateBuilder(args);


var cache = builder.AddRedis("cache");


builder.AddCSharpApp("worker", "../worker/Program.cs")
    .WithReference(cache);


builder.Build().Run();
```

This works seamlessly with .NET 10 SDK’s file-based application support. The C# file-based app can use service discovery, access referenced resources, and be debugged in VS Code just like regular projects.

### Network identifiers

[Section titled “Network identifiers”](#network-identifiers)

Aspire 13.0 introduces `NetworkIdentifier` for better network context awareness in endpoint resolution.

AppHost.cs

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var api = builder.AddProject("api");


// Get endpoint with specific network context
var localhostEndpoint = api.GetEndpoint("http", KnownNetworkIdentifiers.LocalhostNetwork);
var containerEndpoint = api.GetEndpoint("http", KnownNetworkIdentifiers.DefaultAspireContainerNetwork);


await builder.Build().RunAsync();
```

Network identifier features:

* Resolve endpoints based on the network context, such as the host or container network.
* Use predefined identifiers for common scenarios: `LocalhostNetwork`, `DefaultAspireContainerNetwork`, and `PublicInternet`.
* Endpoints now include their `NetworkID` instead of a container host address.
* Container-to-container communication is improved.

### Interaction service dynamic inputs

[Section titled “Interaction service dynamic inputs”](#interaction-service-dynamic-inputs)

The interaction service has been improved with support for dynamic inputs. This feature allows inputs to load options based on other input values, enabling cascading dropdowns and dependent parameter prompting.

Note

This is an experimental feature marked with `[Experimental("ASPIREINTERACTION001")]`.

```csharp
var inputs = new List
{
    // First input - static options
    new InteractionInput
    {
        Name = "DatabaseType",
        InputType = InputType.Choice,
        Label = "Database Type",
        Required = true,
        Options =
        [
            KeyValuePair.Create("postgres", "PostgreSQL"),
            KeyValuePair.Create("mysql", "MySQL"),
            KeyValuePair.Create("sqlserver", "SQL Server")
        ]
    },


    // Second input - loads dynamically based on DatabaseType
    new InteractionInput
    {
        Name = "DatabaseVersion",
        InputType = InputType.Choice,
        Label = "Database Version",
        Required = true,
        DynamicLoading = new InputLoadOptions
        {
            LoadCallback = async (context) =>
            {
                var dbType = context.AllInputs["DatabaseType"].Value;
                context.Input.Options = await GetAvailableVersionsAsync(dbType);
            },
            DependsOnInputs = ["DatabaseType"]
        }
    }
};
```

Features include callback-based loading (`LoadCallback`), dependency tracking (`DependsOnInputs`), access to other input values (`context.AllInputs`), and async support for loading from APIs or databases.

### Interaction service custom choices

[Section titled “Interaction service custom choices”](#interaction-service-custom-choices)

Choice inputs can be configured to accept custom choices by setting `AllowCustomChoice` to `true`. In the dashboard, these inputs are [displayed as a combobox](https://wikipedia.org/wiki/Combo_box).

```csharp
var input = new InteractionInput
{
    Name = "AllowCustomInput",
    Label = "Favorite food?",
    InputType = InputType.Choice,
    Options = [KeyValuePair.Create("pizza", "Pizza"), KeyValuePair.Create("burger", "Burger")],
    AllowCustomChoice = true
};


var result = await interactionService.PromptInputAsync("What is your favorite food?", "Select your favorite food.", input);
```

### Reference and connection improvements

[Section titled “Reference and connection improvements”](#reference-and-connection-improvements)

#### Named references

[Section titled “Named references”](#named-references)

Reference resources with explicit names to control the environment variable prefix:

AppHost.cs

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var primaryDb = builder.AddPostgres("postgres-primary")
    .AddDatabase("customers");


var replicaDb = builder.AddPostgres("postgres-replica")
    .AddDatabase("customers");


var api = builder.AddProject("api")
    .WithReference(primaryDb, "primary")
    .WithReference(replicaDb, "replica");
```

The following environment variables are injected into `api`:

```bash
# From primaryDb with "primary" name
ConnectionStrings__primary=Host=postgres-primary;...


# From replicaDb with "replica" name
ConnectionStrings__replica=Host=postgres-replica;...
```

This allows the application to distinguish between multiple database connections using the custom names.

#### Connection properties

[Section titled “Connection properties”](#connection-properties)

Access individual connection string components to build custom connection strings or configuration:

AppHost.cs

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var postgres = builder.AddPostgres("postgres").AddDatabase("mydb");
var redis = builder.AddRedis("cache");


var worker = builder.AddProject("worker")
    .WithEnvironment("DB_HOST", postgres.Resource.GetConnectionProperty("Host"))
    .WithEnvironment("DB_PORT", postgres.Resource.GetConnectionProperty("Port"))
    .WithEnvironment("DB_NAME", postgres.Resource.DatabaseName)
    .WithEnvironment("CACHE_HOST", redis.Resource.GetConnectionProperty("Host"))
    .WithEnvironment("CACHE_PORT", redis.Resource.GetConnectionProperty("Port"));
```

The following environment variables are injected into `worker`:

```bash
DB_HOST=postgres
DB_PORT=5432
DB_NAME=mydb
CACHE_HOST=cache
CACHE_PORT=6379
```

This is useful when your application needs individual connection components rather than a full connection string, or when building connection strings in formats Aspire doesn’t provide natively.

#### Endpoint reference enhancements

[Section titled “Endpoint reference enhancements”](#endpoint-reference-enhancements)

Control how service URLs are resolved and injected with network-aware endpoint references:

AppHost.cs

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var api = builder.AddProject("api")
    .WithExternalHttpEndpoints();


var frontend = builder.AddJavaScriptApp("frontend", "./frontend")
    .WithEnvironment("API_URL", api.GetEndpoint("https"));
```

The following environment variables are injected into `frontend`:

```bash
# Default behavior - uses the external endpoint URL
API_URL=https://localhost:7123
```

For advanced scenarios, you can specify the network context:

```csharp
var worker = builder.AddProject("worker")
    .WithEnvironment("API_URL",
        api.GetEndpoint("http",
            KnownNetworkIdentifiers.DefaultAspireContainerNetwork));
```

The following environment variables are injected into `worker`:

```bash
# Container network context - uses internal container address
API_URL=http://api:8080
```

This enables proper service-to-service communication whether the consumer is running on the host or in a container.

### Other app model improvements

[Section titled “Other app model improvements”](#other-app-model-improvements)

* The [`WithComputeEnvironment`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withcomputeenvironment "Configures the compute environment for the compute resource.")[`withComputeEnvironment`](/reference/api/typescript/aspire.hosting/withcomputeenvironment/ "Configures the compute environment for the compute resource.") API is now **stable**, so you can deploy resources to specific compute environments without experimental warnings.
* The [`ExcludeFromMcp`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#excludefrommcp "Exclude the resource from MCP operations using the Aspire MCP server. The resource is excluded from results that return resources, console logs and telemetry.")[`excludeFromMcp`](/reference/api/typescript/aspire.hosting/excludefrommcp/ "Exclude the resource from MCP operations using the Aspire MCP server. The resource is excluded from results that return resources, console logs and telemetry.") extension controls which resources are visible to AI assistants and MCP clients.
* [`WithReferenceEnvironment`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withreferenceenvironment "Configures how information is injected into environment variables when the resource references other resources.")[`withReferenceEnvironment`](/reference/api/typescript/aspire.hosting/withreferenceenvironment/ "Configures how information is injected into environment variables when the resource references other resources.") and `ReferenceEnvironmentInjectionFlags` provide fine-grained control over how references inject environment variables.
* `TryCreateResourceBuilder` safely attempts resource builder creation and returns `false` instead of throwing when creation fails.

## 🚀 Deployment improvements

[Section titled “🚀 Deployment improvements”](#-deployment-improvements)

### Deployment pipeline reimplementation

[Section titled “Deployment pipeline reimplementation”](#deployment-pipeline-reimplementation)

Aspire 13.0 completely reimplements the deployment workflow on top of [aspire do](#aspire-do). This architectural change transforms deployment from a monolithic operation into a composable set of discrete, parallelizable steps.

The new deployment pipeline automatically parallelizes independent operations, dramatically reducing deployment time. Steps like prerequisites, builds, and provisioning run concurrently when dependencies allow.

Use `aspire do` to execute individual deployment phases:

```bash
aspire do build                           # Build all containers
aspire deploy                             # Complete deployment
aspire do deploy --pipeline-log-level debug        # Deploy with verbose logging
```

This enables incremental deployments, debugging specific steps, and CI/CD pipeline splitting. Use `--pipeline-log-level debug` for detailed troubleshooting output.

Use the `--list-steps` flag (available on `aspire deploy`, `aspire publish`, `aspire destroy`, and `aspire do`) to inspect the pipeline that would run for a given command — including step order, dependencies, and the resources each step targets — without actually executing it.

The pipeline-based deployment provides dependency tracking, real-time progress reporting, failure isolation, selective execution, extensibility, and built-in diagnostics.

For more details, see [aspire do](#aspire-do).

### Deployment state management

[Section titled “Deployment state management”](#deployment-state-management)

Aspire 13.0 introduces deployment state management that automatically persists deployment information locally across runs. When you deploy to Azure, Aspire now remembers your choices and deployment state between sessions.

Aspire stores the following information locally:

* Azure subscription, resource group, location, and tenant selections.
* Parameter values from previous deployments.
* Records of deployed resources and their locations.

```bash
# First deployment - you're prompted for configuration, assumes "Production" environment
aspire deploy
# Select Azure subscription, resource group, location, tenant...


# Subsequent deployments - no prompts, uses saved state
aspire deploy
# Uses previous selections automatically


# First deployment to a different environment -- prompted again
aspire deploy --environment staging
```

This eliminates repetitive prompts and makes iterative deployments faster. Your deployment configuration is stored locally (not in source control), so each developer can have their own Azure configuration without conflicts.

For example:

1. First time: Select subscription “My Subscription”, resource group “my-rg”, location “eastus”
2. Deploy completes, state saved locally
3. Make code changes
4. Run `aspire deploy` again - automatically uses “My Subscription”, “my-rg”, “eastus”
5. No need to re-enter configuration

The state is stored in your local user profile at:

* On Windows: `%USERPROFILE%\.aspire\deployments\\.json`
* On macOS and Linux: `$HOME/.aspire/deployments//.json`

The `` is a SHA256 hash of your AppHost project path, allowing different projects to maintain separate state. The `` corresponds to the deployment environment (e.g., `production`, `development`).

This location is excluded from source control by design, so each developer can have their own Azure configuration without conflicts.

If you need to reset your deployment state (for example, to change subscriptions or start fresh), use the `--clear-cache` flag:

```bash
aspire deploy --clear-cache
# Clears saved state and prompts for configuration again
```

This removes all saved deployment state, including Azure configuration, parameter values, and deployment context. The next deployment will prompt you for all configuration values as if it were the first deployment.

## ☁️ Azure

[Section titled “☁️ Azure”](#️-azure)

### Azure tenant selection

[Section titled “Azure tenant selection”](#azure-tenant-selection)

Aspire 13.0 introduces interactive tenant selection during Azure provisioning, fixing issues with multi-tenant scenarios (work and personal accounts).

When provisioning Azure resources, if multiple tenants are available, the CLI will prompt you to select the appropriate tenant. The tenant selection is stored alongside your subscription, location, and resource group choices for consistent deployments.

```bash
aspire deploy


# If you have multiple tenants, you'll be prompted:
# Select Azure tenant:
#   > work@company.com (Default Directory)
#     personal@outlook.com (Personal Account)
```

### Azure App Service enhancements

[Section titled “Azure App Service enhancements”](#azure-app-service-enhancements)

Aspire 13.0 brings significant improvements to Azure App Service deployment, making it easier to deploy and monitor your applications in production.

#### Aspire dashboard in App Service

[Section titled “Aspire dashboard in App Service”](#aspire-dashboard-in-app-service)

The Aspire Dashboard is now included by default when deploying to Azure App Service, giving you visibility into your deployed applications:

```csharp
builder.AddAzureAppServiceEnvironment("env");
// Dashboard is included by default at https://[prefix]-aspiredashboard-[unique string].azurewebsites.net
```

The deployed dashboard provides the same experience as local development: view logs, traces, metrics, and application topology for your production environment.

To disable the dashboard:

```csharp
builder.AddAzureAppServiceEnvironment("env")
    .WithDashboard(enable: false);
```

#### Application Insights integration

[Section titled “Application Insights integration”](#application-insights-integration)

Enable Azure Application Insights for comprehensive monitoring and telemetry:

```csharp
builder.AddAzureAppServiceEnvironment("env")
    .WithAzureApplicationInsights();
```

When enabled, Aspire automatically:

* Creates a Log Analytics workspace.
* Creates an Application Insights resource.
* Configures all App Service Web Apps with the connection string.
* Injects `APPLICATIONINSIGHTS_CONNECTION_STRING` into your applications.

You can also reference an existing Application Insights resource:

```csharp
var insights = builder.AddAzureApplicationInsights("insights");


builder.AddAzureAppServiceEnvironment("env")
    .WithAzureApplicationInsights(insights);
```

## ⚠️ Breaking changes

[Section titled “⚠️ Breaking changes”](#️-breaking-changes)

### Package renames

[Section titled “Package renames”](#package-renames)

The `Aspire.Hosting.NodeJs` package has been renamed to `Aspire.Hosting.JavaScript` to reflect its broader support for JavaScript applications such as Node.js and Vite.

Update your package references:

```xml






```

Or use the CLI:

```bash
# Before (9.x)
aspire add nodejs


# After (13.0)
aspire add javaScript
```

### Removed APIs

[Section titled “Removed APIs”](#removed-apis)

The following APIs have been removed in Aspire 13.0:

Removed publishing infrastructure, replaced by `aspire do`, includes:

* `PublishingContext` and `PublishingCallbackAnnotation`
* `DeployingContext` and `DeployingCallbackAnnotation`
* `WithPublishingCallback` extension method
* `IDistributedApplicationPublisher` interface
* `IPublishingActivityReporter`, `IPublishingStep`, `IPublishingTask` interfaces
* `NullPublishingActivityReporter` class
* `PublishingExtensions` class (all extension methods)
* `PublishingOptions` class
* `CompletionState` enum

Removed debugging APIs, replaced with the new flexible API, include:

* Old `WithDebugSupport` overload with `debugAdapterId` and `requiredExtensionId` parameters
* `SupportsDebuggingAnnotation` (replaced with new debug support annotation)

Removed or renamed diagnostic codes include:

* `ASPIRECOMPUTE001` diagnostics (removed - API graduated from experimental)
* `ASPIREPUBLISHERS001` (renamed to `ASPIREPIPELINES001-003`)

The removed CLI option is:

* `--watch` flag removed from `aspire run` (replaced by `features.defaultWatchEnabled` feature flag)

### Obsolete APIs

[Section titled “Obsolete APIs”](#obsolete-apis)

The following APIs are marked as obsolete in Aspire 13.0 and will be removed in a future release:

Obsolete lifecycle hooks include:

* `IDistributedApplicationLifecycleHook` interface - Use `IDistributedApplicationEventingSubscriber` instead

Use eventing subscriber extensions instead of these obsolete lifecycle hook extension methods:

* `AddLifecycleHook()` - Use `AddEventingSubscriber()` instead
* `AddLifecycleHook(Func)` - Use `AddEventingSubscriber(Func)` instead
* `TryAddLifecycleHook()` - Use `TryAddEventingSubscriber()` instead
* `TryAddLifecycleHook(Func)` - Use `TryAddEventingSubscriber(Func)` instead

Use `aspire do` instead of these obsolete publishing interfaces:

* `IDistributedApplicationPublisher` - Use `PipelineStep` instead
* `PublishingOptions` - Use `PipelineOptions` instead

Use the new JavaScript hosting APIs instead of:

* `AddNpmApp()` - Use `AddJavaScriptApp()` instead for general npm-based apps, or `AddViteApp()` for Vite projects

Migrating from AddNpmApp

The `AddNpmApp` API supported an `args` parameter for passing command-line arguments to scripts. `AddJavaScriptApp` does not have this parameter. Instead, define custom scripts in your `package.json` with the required arguments. See [Passing arguments to scripts](#passing-arguments-to-scripts) for details and examples.

While the obsoleted APIs still work in 13.0, they will be removed in the next major version. Update your code to use the recommended replacements.

### Changed signatures

[Section titled “Changed signatures”](#changed-signatures)

The `AllocatedEndpoint` constructor changed:

```csharp
// Before (9.x)
var endpoint = new AllocatedEndpoint(
    "http",
    8080,
    containerHostAddress: "localhost");


// After (13.0)
var endpoint = new AllocatedEndpoint(
    endpointAnnotation,
    "http",
    8080,
    networkIdentifier: KnownNetworkIdentifiers.LocalhostNetwork);
```

The `ParameterProcessor` constructor changed:

```csharp
// Before (9.x)
var processor = new ParameterProcessor(
    notificationService,
    loggerService,
    interactionService,
    logger,
    executionContext,
    distributedApplicationOptions);


// After (13.0)
var processor = new ParameterProcessor(
    notificationService,
    loggerService,
    interactionService,
    logger,
    executionContext,
    deploymentStateManager);
```

The `InteractionInput` properties changed:

* `MaxLength`: Changed from settable to init-only.
* `Options`: Changed from init-only to settable.
* `Placeholder`: Changed from settable to init-only.

`WithReference` for `IResourceWithServiceDiscovery` changed:

* Added new overload with `name` parameter for named references.
* Existing overload still available for compatibility.

`ProcessArgumentValuesAsync` and `ProcessEnvironmentVariableValuesAsync` changed:

```csharp
// Before (9.x)
await resource.ProcessArgumentValuesAsync(
    executionContext, processValue, logger,
    containerHostName: "localhost", cancellationToken);


// After (13.0)
await resource.ProcessArgumentValuesAsync(
    executionContext, processValue, logger, cancellationToken);
```

The `containerHostName` parameter has been removed. Network context is now handled through `NetworkIdentifier`.

[`GetValueAsync`](/reference/api/csharp/aspire.hosting/endpointreference/methods/#getvalueasync "Gets the URL of the endpoint asynchronously. Waits for the endpoint to be allocated if necessary.")[`getValueAsync`](/reference/api/typescript/aspire.hosting/endpointreference/getvalueasync/ "Gets the URL of the endpoint asynchronously. Waits for the endpoint to be allocated if necessary.") behavior changed:

```csharp
// Before (9.x) - would throw immediately if not allocated
var value = await endpointRef.GetValueAsync(cancellationToken);


// After (13.0) - waits for allocation, check IsAllocated if you need immediate failure
if (!endpointRef.IsAllocated)
{
    throw new InvalidOperationException("Endpoint not allocated");
}
var value = await endpointRef.GetValueAsync(cancellationToken);
```

### Major architectural changes

[Section titled “Major architectural changes”](#major-architectural-changes)

#### Universal container-to-host communication

[Section titled “Universal container-to-host communication”](#universal-container-to-host-communication)

Aspire 13.0 introduces a major architectural change to enable universal container-to-host communication, independent of container orchestrator support.

The architecture now:

* Leverages DCP’s container tunnel capability for container-to-host connectivity.
* `EndpointReference` resolution is now context-aware (uses `NetworkIdentifier`).
* Endpoint references are tracked by their `EndpointAnnotation`.
* `AllocatedEndpoint` constructor signature changed.

As a result:

* Enables containers to communicate with host-based services reliably across all deployment scenarios.
* Code that directly constructs `AllocatedEndpoint` objects will need updates.
* Extension methods that process endpoint references may need Network Identifier context.

To migrate, enable the currently experimental universal container-to-host communication feature by setting `ASPIRE_ENABLE_CONTAINER_TUNNEL` to `true`.

This change fixes long-standing issues with container-to-host communication (issue #6547).

#### Refactored AddNodeApp API

[Section titled “Refactored AddNodeApp API”](#refactored-addnodeapp-api)

The `AddNodeApp` API has been refactored with breaking changes to how Node.js applications are configured.

The signature changed:

```csharp
// Before (9.x) - absolute scriptPath with optional workingDirectory
builder.AddNodeApp(
    name: "frontend",
    scriptPath: "/absolute/path/to/app.js",
    workingDirectory: "/absolute/path/to",
    args: ["--port", "3000"]);


// After (13.0) - appDirectory with relative scriptPath
builder.AddNodeApp(
    name: "frontend",
    appDirectory: "../frontend",
    scriptPath: "app.js");
```

Behavior also changed:

1. If `package.json` exists in `appDirectory`, npm is configured automatically with auto-install enabled.
2. Docker publishing support generates multi-stage builds by default.
3. Use `WithNpm()`, [`WithYarn`](/reference/api/csharp/communitytoolkit.aspire.hosting.mcpinspector/mcpinspectorresourcebuilderextensions/methods/#withyarn "Configures the MCP Inspector to use yarn as the package manager.")[`withYarn`](/reference/api/typescript/communitytoolkit.aspire.hosting.mcpinspector/withyarn/ "Configures the MCP Inspector to use yarn as the package manager."), or [`WithPnpm`](/reference/api/csharp/communitytoolkit.aspire.hosting.mcpinspector/mcpinspectorresourcebuilderextensions/methods/#withpnpm "Configures the MCP Inspector to use pnpm as the package manager.")[`withPnpm`](/reference/api/typescript/communitytoolkit.aspire.hosting.mcpinspector/withpnpm/ "Configures the MCP Inspector to use pnpm as the package manager.") with [`WithRunScript`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#withrunscript "Adds a run script annotation to the specified JavaScript application resource builder, specifying the script to execute and its arguments during run mode.")[`withRunScript`](/reference/api/typescript/aspire.hosting.javascript/withrunscript/ "Adds a run script annotation to the specified JavaScript application resource builder, specifying the script to execute and its arguments during run mode.") to execute `package.json` scripts.

To migrate:

```csharp
// Before (9.x)
var app = builder.AddNodeApp("frontend", "../frontend/server.js", "../frontend");


// After (13.0)
var app = builder.AddNodeApp("frontend", "../frontend", "server.js");


// Or use package.json script
var app = builder.AddNodeApp("frontend", "../frontend", "server.js")
    .WithNpm()
    .WithRunScript("dev");
```

#### DefaultAzureCredential behavior in Azure deployments

[Section titled “DefaultAzureCredential behavior in Azure deployments”](#defaultazurecredential-behavior-in-azure-deployments)

Aspire 13.0 changes the default behavior of `DefaultAzureCredential` when deploying to Azure Container Apps and Azure App Service to use only `ManagedIdentityCredential`.

When you deploy to Azure Container Apps or Azure App Service, Aspire now automatically sets the `AZURE_TOKEN_CREDENTIALS` environment variable to `ManagedIdentityCredential`. This configures `DefaultAzureCredential` to behave deterministically by only using `ManagedIdentityCredential`, instead of attempting other credential types like `EnvironmentCredential` or `WorkloadIdentityCredential` first.

This change ensures `DefaultAzureCredential` always uses `ManagedIdentityCredential` in production, enables retry logic, disables probe requests for improved performance, and aligns with [Azure SDK authentication best practices](https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices?tabs=aspdotnet#use-deterministic-credentials-in-production-environments).

**Previous behavior (9.x):**

`DefaultAzureCredential` used the full chain of credential types, attempting `EnvironmentCredential` and `WorkloadIdentityCredential` before `ManagedIdentityCredential`.

**New behavior (13.0):**

`DefaultAzureCredential` only uses `ManagedIdentityCredential` when the `AZURE_TOKEN_CREDENTIALS` environment variable is set to `ManagedIdentityCredential`.

The affected APIs are:

* [`AddAzureContainerAppEnvironment`](/reference/api/csharp/aspire.hosting.azure.appcontainers/azurecontainerappextensions/methods/#addazurecontainerappenvironment "Adds a container app environment resource to the distributed application builder.")[`addAzureContainerAppEnvironment`](/reference/api/typescript/aspire.hosting.azure.appcontainers/addazurecontainerappenvironment/ "Adds a container app environment resource to the distributed application builder.")
* [`AddAzureAppServiceEnvironment`](/reference/api/csharp/aspire.hosting.azure.appservice/azureappserviceenvironmentextensions/methods/#addazureappserviceenvironment "Adds a azure app service environment resource to the distributed application builder.")[`addAzureAppServiceEnvironment`](/reference/api/typescript/aspire.hosting.azure.appservice/addazureappserviceenvironment/ "Adds a azure app service environment resource to the distributed application builder.")

If you were relying on `EnvironmentCredential` or `WorkloadIdentityCredential` in your application, choose one of the following options:

1. Use explicit credentials instead of `DefaultAzureCredential` in your application, such as `EnvironmentCredential` or `WorkloadIdentityCredential`.

2. Remove the environment variable by implementing a callback that removes `AZURE_TOKEN_CREDENTIALS` from the deployment:

   ```csharp
   // For Azure Container Apps
   builder.AddProject("frontend")
       .PublishAsAzureContainerApp((infra, app) =>
       {
           var containerAppContainer = app.Template.Containers[0].Value!;
           var azureTokenCredentialEnv = containerAppContainer.Env
               .Single(v => v.Value!.Name.Value == "AZURE_TOKEN_CREDENTIALS");
           containerAppContainer.Env.Remove(azureTokenCredentialEnv);
       });


   // For Azure App Service
   builder.AddProject("frontend")
       .PublishAsAzureAppServiceWebsite((infra, website) =>
       {
           var azureTokenCredentialSetting = website.AppSettings
               .Single(v => v.Value!.Name.Value == "AZURE_TOKEN_CREDENTIALS");
           website.AppSettings.Remove(azureTokenCredentialSetting);
       });
   ```

### Migration guide

[Section titled “Migration guide”](#migration-guide)

#### Migrating from publishing callbacks to pipeline steps

[Section titled “Migrating from publishing callbacks to pipeline steps”](#migrating-from-publishing-callbacks-to-pipeline-steps)

**Before (9.x)**:

```csharp
var api = builder.AddProject("api")
    .WithPublishingCallback(async (context, cancellationToken) =>
    {
        await CustomDeployAsync(context, cancellationToken);
    });
```

**After (13.0)**:

```csharp
var api = builder.AddProject("api")
    .WithPipelineStepFactory(context =>
    {
        return new PipelineStep()
        {
            Name = "CustomDeployStep",
            Action = CustomDeployAsync,
            RequiredBySteps = [WellKnownPipelineSteps.Publish]
        };
    });
```

For more details, see [Deployment pipeline documentation](/deployment/pipelines/).

#### Migrating from lifecycle hooks to events

[Section titled “Migrating from lifecycle hooks to events”](#migrating-from-lifecycle-hooks-to-events)

**Before (9.x)**:

```csharp
public class MyLifecycleHook : IDistributedApplicationLifecycleHook
{
    public async Task BeforeStartAsync(
        DistributedApplicationModel model,
        CancellationToken cancellationToken)
    {
        // Logic before start
    }
}


builder.Services.TryAddLifecycleHook();
```

**After (13.0)**:

```csharp
public class MyEventSubscriber : IDistributedApplicationEventingSubscriber
{
    public Task SubscribeAsync(
        IDistributedApplicationEventing eventing,
        DistributedApplicationExecutionContext executionContext,
        CancellationToken cancellationToken)
    {
        eventing.Subscribe((@event, ct) =>
        {
            // Access model and services via event
            var model = @event.Model;
            var services = @event.Services;


            // Logic before start


            return Task.CompletedTask;
        });


        return Task.CompletedTask;
    }
}


builder.Services.TryAddEventingSubscriber();
```

### Experimental features

[Section titled “Experimental features”](#experimental-features)

The following features are marked as `[Experimental]` and may change in future releases:

* The Dockerfile builder APIs: [`WithDockerfileBuilder`](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods/#withdockerfilebuilder "Builds the specified container image from a Dockerfile generated by a callback using the Aspire.Hosting.ApplicationModel.Docker.DockerfileBuilder API.")[`withDockerfileBuilder`](/reference/api/typescript/aspire.hosting/withdockerfilebuilder/ "Configures the resource to use a programmatically generated Dockerfile"), [`AddDockerfileBuilder`](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods/#adddockerfilebuilder "Adds a Dockerfile to the application model that can be treated like a container resource, with the Dockerfile generated programmatically using the...")[`addDockerfileBuilder`](/reference/api/typescript/aspire.hosting/adddockerfilebuilder/ "Adds a container resource built from a programmatically generated Dockerfile"), and [`WithDockerfileBaseImage`](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods/#withdockerfilebaseimage "Configures custom base images for generated Dockerfiles.")[`withDockerfileBaseImage`](/reference/api/typescript/aspire.hosting/withdockerfilebaseimage/ "Configures custom base images for generated Dockerfiles.").
* C# file-based app support through [`AddCSharpApp`](/reference/api/csharp/aspire.hosting/projectresourcebuilderextensions/methods/#addcsharpapp "Adds a C# project or file-based app to the application model.")[`addCSharpApp`](/reference/api/typescript/aspire.hosting/addcsharpapp/ "Adds a C# application resource").
* Dynamic inputs through `InputLoadOptions` and dynamic input loading.
* Pipeline features through `IDistributedApplicationPipeline` and related APIs.

To use experimental features, you must enable them explicitly and acknowledge they may change:

```csharp
#pragma warning disable ASPIREXXX // Experimental feature
var app = builder.AddCSharpApp("myapp", "./app.cs");
#pragma warning restore ASPIREXXX
```

***

We’d love to hear about your experience with Aspire 13.0. Share feedback on [GitHub](https://github.com/microsoft/aspire/issues) or join the conversation on [Discord](https://aka.ms/aspire-discord).

## 🙏 Community

[Section titled “🙏 Community”](#-community)

Aspire is built in the open, and this release wouldn’t be what it is without you. A huge thank you to everyone who helped make Aspire 13.0 possible.

### The Aspire core team is

* [![Adam Ratzman](https://github.com/adamint.png?size=96)Adam Ratzman](https://github.com/adamint)
* [![Ankit Jain](https://github.com/radical.png?size=96)Ankit Jain](https://github.com/radical)
* [![Damian Edwards](https://github.com/DamianEdwards.png?size=96)Damian Edwards](https://github.com/DamianEdwards)
* [![David Fowler](https://github.com/davidfowl.png?size=96)David Fowler](https://github.com/davidfowl)
* [![David Negstad](https://github.com/danegsta.png?size=96)David Negstad](https://github.com/danegsta)
* [![David Pine](https://github.com/IEvangelist.png?size=96)David Pine](https://github.com/IEvangelist)
* [![Ella Hathaway](https://github.com/ellahathaway.png?size=96)Ella Hathaway](https://github.com/ellahathaway)
* [![Eric Erhardt](https://github.com/eerhardt.png?size=96)Eric Erhardt](https://github.com/eerhardt)
* [![James Newton-King](https://github.com/JamesNK.png?size=96)James Newton-King](https://github.com/JamesNK)
* [![José Pérez](https://github.com/joperezr.png?size=96)José Pérez](https://github.com/joperezr)
* [![Karol Zadora-Przylecki](https://github.com/karolz-ms.png?size=96)Karol Zadora-Przylecki](https://github.com/karolz-ms)
* [![Maddy Montaquila](https://github.com/maddymontaquila.png?size=96)Maddy Montaquila](https://github.com/maddymontaquila)
* [![Mitch Denny](https://github.com/mitchdenny.png?size=96)Mitch Denny](https://github.com/mitchdenny)
* [![Sébastien Ros](https://github.com/sebastienros.png?size=96)Sébastien Ros](https://github.com/sebastienros)

Special thanks to everyone whose pull requests shipped in Aspire 13.0, including:

[@bart-vmware](https://github.com/bart-vmware), [@captainsafia](https://github.com/captainsafia), [@foxminchan](https://github.com/foxminchan), [@hewe-saxo](https://github.com/hewe-saxo), [@jfversluis](https://github.com/jfversluis), [@jguadagno](https://github.com/jguadagno), [@jomaxso](https://github.com/jomaxso), [@MattKotsenas](https://github.com/MattKotsenas), [@Meir017](https://github.com/Meir017), [@ShilpiRach](https://github.com/ShilpiRach), [@vhvb1989](https://github.com/vhvb1989), [@WeihanLi](https://github.com/WeihanLi), [@wtgodbe](https://github.com/wtgodbe), [@yreynhout](https://github.com/yreynhout), and [@zhiyuanliang-ms](https://github.com/zhiyuanliang-ms)

We're always excited to [see community contributions](/community/contributors/)! If you'd like to get involved, check out our [contributing guide](/community/contributor-guide/).

# What's new in Aspire 13.1

> Explore Aspire 13.1: comprehensive MCP support for AI coding agents, CLI channel persistence, dashboard improvements, Azure Managed Redis, and container registry updates.

Aspire 13.1 builds on Aspire 13’s multi-language foundation with expanded MCP support for AI coding agents, CLI and dashboard improvements, and more streamlined Azure deployments.

This release introduces:

* The new `aspire agent init` command and MCP tools help AI assistants discover integrations and interact with Aspire applications.
* CLI improvements include channel persistence, automatic instance detection, and installation path options.
* The dashboard adds a dedicated Parameters tab and GenAI visualizer enhancements.
* Azure Managed Redis is renamed from `AddAzureRedisEnterprise` to [`AddAzureManagedRedis`](/reference/api/csharp/aspire.hosting.azure.redis/azuremanagedredisextensions/methods/#addazuremanagedredis "Adds an Azure Managed Redis resource to the application model.")[`addAzureManagedRedis`](/reference/api/typescript/aspire.hosting.azure.redis/addazuremanagedredis/ "Adds an Azure Managed Redis resource to the application model.") with improved validation.
* The new `ContainerRegistryResource` supports general-purpose container registries.
* JavaScript updates include a new frontend starter template, Vite HTTPS configuration, and pnpm fixes.
* [📦 Aspire.Hosting.DevTunnels](https://www.nuget.org/packages/Aspire.Hosting.DevTunnels) is now **stable**.
* New APIs configure TLS termination with HTTPS certificates on containers and resources.
* Azure resource connection properties now support multi-language connection strings.

This release requires the [.NET 10 SDK or later](https://dotnet.microsoft.com/download/dotnet/10.0).

If you have feedback, questions, or want to contribute to Aspire, collaborate with us on [ GitHub](https://github.com/microsoft/aspire) or join us on our [ Discord](https://aka.ms/aspire-discord) to chat with the team and other community members.

## 🆙 Upgrade to Aspire 13.1

[Section titled “🆙 Upgrade to Aspire 13.1”](#-upgrade-to-aspire-131)

Caution

Aspire 13.1 includes breaking changes to Azure Redis APIs. Please review the [Breaking changes](#%EF%B8%8F-breaking-changes) section before upgrading.

If your Aspire CLI version is earlier than 13, first [install the latest stable version](/get-started/install-cli/).

The easiest way to upgrade to Aspire 13.1 is using the `aspire update` command:

1. Update your Aspire project using the [`aspire update` command](/reference/cli/commands/aspire-update/):

   Aspire CLI — Update all Aspire packages

   ```bash
   aspire update
   ```

2. Update the Aspire CLI itself:

   Aspire CLI — Update the CLI

   ```bash
   aspire update --self
   ```

When you run `aspire update --self` and select a channel, your selection is saved globally. Future `aspire new` and `aspire init` commands use this channel by default.

## 🤖 MCP for AI Coding Agents

[Section titled “🤖 MCP for AI Coding Agents”](#-mcp-for-ai-coding-agents)

Aspire 13.1 introduces comprehensive support for AI coding agents through MCP (Model Context Protocol) integration. Configure your favorite AI coding tools to understand and interact with your Aspire applications.

### Initialize MCP for your project

[Section titled “Initialize MCP for your project”](#initialize-mcp-for-your-project)

The new `aspire agent init` command detects your development environment and configures MCP servers for supported AI coding agents:

Initialize MCP configuration

```bash
aspire agent init
```

Command reference: [`aspire agent init`](/reference/cli/commands/aspire-agent-init/).

The command presents a streamlined two-step selection process:

```plaintext
Which agent environments do you want to configure?
[ ] Configure VS Code to use the Aspire MCP server
[ ] Configure GitHub Copilot CLI to use Aspire MCP server
[ ] Configure Claude Code to use Aspire MCP server
[ ] Configure Open Code to use Aspire MCP server


Which additional options do you want to enable?
[ ] Create an agent instructions file (AGENTS.md)
[ ] Configure Playwright MCP server
```

### MCP tools for AI agents

[Section titled “MCP tools for AI agents”](#mcp-tools-for-ai-agents)

AI coding agents connected via MCP can now discover and use Aspire integrations directly:

* `list_integrations` returns available Aspire hosting integrations such as Redis, PostgreSQL, and Azure services.
* `get_integration_docs` retrieves detailed documentation for a specific integration package.
* `list_apphosts` lists all detected AppHost projects in the workspace.
* `select_apphost` switches context to a specific AppHost when multiple exist.

### Dashboard MCP integration

[Section titled “Dashboard MCP integration”](#dashboard-mcp-integration)

When connected to an AppHost, the dashboard exposes MCP endpoints, enabling AI agents to query resource state, view logs, and inspect traces directly from your running application.

Learn more about the [MCP server integration](/get-started/aspire-mcp-server/).

## 🛠️ CLI enhancements

[Section titled “🛠️ CLI enhancements”](#️-cli-enhancements)

### Channel selection and persistence

[Section titled “Channel selection and persistence”](#channel-selection-and-persistence)

The `--channel` option is now available on `aspire new` and `aspire init` commands, letting you explicitly choose which Aspire version channel to use:

Channel selection

```bash
aspire new aspire-starter --channel preview
aspire init --channel stable
```

Command reference: [`aspire init`](/reference/cli/commands/aspire-init/#options).

When you update the CLI with `aspire update --self`, your channel selection is persisted to `~/.aspire/globalsettings.json` and becomes the default for future project creation.

### Automatic instance detection

[Section titled “Automatic instance detection”](#automatic-instance-detection)

Running `aspire run` when an instance is already running? Aspire 13.1 automatically detects running instances and terminates them.

### Installation path option

[Section titled “Installation path option”](#installation-path-option)

The installation scripts now support `--skip-path` to install the CLI without modifying your PATH:

* Bash

  ```bash
  curl -fsSL https://aspire.dev/install.sh | bash -s -- --skip-path
  ```

* PowerShell

  ```powershell
  iex "& { $(irm https://aspire.dev/install.ps1) } -SkipPath"
  ```

Learn more about [the Aspire CLI installation options](/reference/cli/install-script/#options).

## 📊 Dashboard improvements

[Section titled “📊 Dashboard improvements”](#-dashboard-improvements)

### Dedicated Parameters tab

[Section titled “Dedicated Parameters tab”](#dedicated-parameters-tab)

The Resources page now includes a dedicated Parameters tab, making it easier to view and manage configuration parameters without leaving the resource details.

![Resources parameters view](/_astro/resources-parameters-view.Dzwjb7Yx_1ulEuo.webp "Resources parameters view")

### GenAI visualizer enhancements

[Section titled “GenAI visualizer enhancements”](#genai-visualizer-enhancements)

The GenAI visualizer received several improvements:

* Tool definitions and evaluations associated with GenAI spans are displayed in the visualizer.
* Video and audio content can be previewed in the GenAI visualizer.
* Log entries associated with GenAI spans now include a direct link to the GenAI visualizer.
* Content parsing better handles various AI model response formats.

![GenAI visualizer tool definitions](/_astro/genai-visualizer-tooldefinitions.S98dZUC3_1tKPil.webp "GenAI visualizer tool definitions")

### Bug fixes

[Section titled “Bug fixes”](#bug-fixes)

* Fixed `OverflowException` in the Traces page when trace duration exceeds `int.MaxValue`.
* Fixed combobox filter behavior when no items match the search criteria.
* Fixed view options menu visibility when hidden resources exist.

## ☁️ Azure improvements

[Section titled “☁️ Azure improvements”](#️-azure-improvements)

### Azure Managed Redis

[Section titled “Azure Managed Redis”](#azure-managed-redis)

Caution

**Breaking Change**: The `AddAzureRedisEnterprise` method has been renamed to `AddAzureManagedRedis` to better reflect the Azure service naming.

Azure Managed Redis (before)

```csharp
// Before (Aspire 13.0)
var redis = builder.AddAzureRedisEnterprise("cache");
```

Azure Managed Redis (after)

```csharp
// After (Aspire 13.1)
var redis = builder.AddAzureManagedRedis("cache");
```

Note

`AddAzureRedis` is now obsolete. Migrate to `AddAzureManagedRedis` for new projects.

### Connection properties for Azure resources

[Section titled “Connection properties for Azure resources”](#connection-properties-for-azure-resources)

Azure resources now expose connection properties in a standardized format that works across all supported languages. This enables multi-language applications using Java, JavaScript, and Python SDKs to connect to Azure resources using consistent configuration patterns.

Resources now expose additional properties such as `HostName`, `Port`, and `JdbcConnectionString` where applicable, making it easier to configure clients in languages that don’t use .NET connection string formats.

### Azure App Service deployment slots

[Section titled “Azure App Service deployment slots”](#azure-app-service-deployment-slots)

New [`WithDeploymentSlot`](/reference/api/csharp/aspire.hosting.azure.appservice/azureappserviceenvironmentextensions/methods/#withdeploymentslot "Configures the slot to which the Azure App Services should be deployed.")[`withDeploymentSlot`](/reference/api/typescript/aspire.hosting.azure.appservice/withdeploymentslot/ "Configures the deployment slot for all Azure App Services in the environment") extension method to configure deployment slots for Azure App Service:

Configure deployment slot

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddAzureAppServiceEnvironment("appservice")
    .WithDeploymentSlot("staging");
```

### Clear default role assignments

[Section titled “Clear default role assignments”](#clear-default-role-assignments)

New [`ClearDefaultRoleAssignments`](/reference/api/csharp/aspire.hosting.azure/azureresourceextensions/methods/#cleardefaultroleassignments "Clears all default role assignments for the specified Azure resource.")[`clearDefaultRoleAssignments`](/reference/api/typescript/aspire.hosting.azure/cleardefaultroleassignments/ "Clears all default role assignments for the specified Azure resource.") extension method to disable automatic role assignments on Azure resources when you need fine-grained control over permissions.

### Bug fixes

[Section titled “Bug fixes”](#bug-fixes-1)

* Azure deployments now validate that required compute environments exist before attempting deployment, providing earlier and clearer error messages when infrastructure is missing.
* Fixed an issue with Azure authentication when working across multiple tenants.

## 🐳 Container and Docker Compose

[Section titled “🐳 Container and Docker Compose”](#-container-and-docker-compose)

### Container registry resource

[Section titled “Container registry resource”](#container-registry-resource)

Caution

This API is experimental and may change in future releases. Use diagnostic code `ASPIRECOMPUTE003` to suppress the experimental warning. For more information, see [ASPIRECOMPUTE003](/diagnostics/aspirecompute003/).

A new `ContainerRegistryResource` enables integration with general-purpose container registries beyond Azure Container Registry:

Container registry resource

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var registry = builder.AddContainerRegistry("myregistry", "registry.example.com");


var api = builder.AddProject("api")
    .WithContainerRegistry(registry);
```

Learn more about [Container registry configuration](/app-host/container-registry/).

The deployment pipeline now includes a `push` step for container registry operations.

```plaintext
$ aspire do push
16:03:38 (pipeline-execution) → Starting pipeline-execution...
16:03:38 (push-prereq) → Starting push-prereq...
16:03:38 (process-parameters) → Starting process-parameters...
16:03:38 (push-prereq) ✓ push-prereq completed successfully
16:03:38 (process-parameters) i [INF] 3 parameter values saved to deployment state.
16:03:38 (process-parameters) ✓ process-parameters completed successfully
16:03:38 (build-prereq) → Starting build-prereq...
16:03:38 (build-prereq) ✓ build-prereq completed successfully
16:03:38 (build-go-app) → Starting build-go-app...
16:03:38 (build-pythonapp-standalone) → Starting build-pythonapp-standalone...
16:03:38 (build-api) → Starting build-api...
16:03:38 (build-viteapp) → Starting build-viteapp...
...
16:03:43 (push-api) → Starting push-api...
16:03:43 (push-api) → Pushing api to container-registry
16:03:44 (push-api) i [INF] Docker tag for api -> docker.io/captainsafia/api:latest succeeded.
16:03:44 (push-pythonapp) i [INF] Docker tag for pythonapp:d5325602e04758397792c8332c5882846516b35c -> docker.io/captainsafia/pythonapp:latest succeeded.
16:03:48 (push-go-app) i [INF] Docker push for docker.io/captainsafia/go-app:latest succeeded.
16:03:48 (push-go-app) ✓ Successfully pushed go-app to docker.io/captainsafia/go-app:latest (5.1s)
16:03:48 (push-go-app) ✓ push-go-app completed successfully
16:03:48 (push-pythonapp-standalone) i [INF] Docker push for docker.io/captainsafia/pythonapp-standalone:latest succeeded.
16:03:48 (push-pythonapp-standalone) ✓ Successfully pushed pythonapp-standalone to docker.io/captainsafia/pythonapp-standalone:latest (5.4s)
16:03:48 (push-pythonapp-standalone) ✓ push-pythonapp-standalone completed successfully
16:03:49 (push-pythonapp) i [INF] Docker push for docker.io/captainsafia/pythonapp:latest succeeded.
16:03:49 (push-pythonapp) ✓ Successfully pushed pythonapp to docker.io/captainsafia/pythonapp:latest (5.7s)
16:03:49 (push-pythonapp) ✓ push-pythonapp completed successfully
16:04:05 (push-api) i [INF] Docker push for docker.io/captainsafia/api:latest succeeded.
16:04:05 (push-api) ✓ Successfully pushed api to docker.io/captainsafia/api:latest (21.3s)
16:04:05 (push-api) ✓ push-api completed successfully
16:04:05 (push) → Starting push...
16:04:05 (push) ✓ push completed successfully
16:04:05 (pipeline-execution) ✓ Completed successfully
------------------------------------------------------------
✓ 14/14 steps succeeded • Total time: 26.41s
```

### Explicit container registry support for Azure deployments

[Section titled “Explicit container registry support for Azure deployments”](#explicit-container-registry-support-for-azure-deployments)

Prior to Aspire 13.1, when deploying to Azure Container Apps using [`AddAzureContainerAppEnvironment`](/reference/api/csharp/aspire.hosting.azure.appcontainers/azurecontainerappextensions/methods/#addazurecontainerappenvironment "Adds a container app environment resource to the distributed application builder.")[`addAzureContainerAppEnvironment`](/reference/api/typescript/aspire.hosting.azure.appcontainers/addazurecontainerappenvironment/ "Adds a container app environment resource to the distributed application builder."), the Azure Container Registry (ACR) was provisioned implicitly as part of the environment. This automatic provisioning could cause deployment delays and made it difficult for developers to discover which registry was being used.

Aspire 13.1 addresses this by moving toward explicit container registry configuration, giving developers more control and visibility into where and when images are pushed. With the configuration below, the ACR associated with the “myenv” environment will be provisioned in parallel with the environment and image pushes will begin as soon as the registry has been successfully provisioned.

Explicit Azure Container Registry

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var acr = builder.AddAzureContainerAppEnvironment("myenv");


var api = builder.AddProject("api")
    .WithContainerRegistry(acr);
```

For a deeper dive into container registry improvements and their impact on Azure deployments, check out [Safia Abdalla’s blog post on fixing Aspire’s image problem](https://blog.safia.rocks/2025/12/15/aspire-image-push/).

### Docker Compose improvements

[Section titled “Docker Compose improvements”](#docker-compose-improvements)

* Bind mount sources are now replaced with environment placeholders for portability.
* Resource endpoints are displayed after Docker Compose deployment.
* Fixed race condition in Dockerfile materialization during parallel pipeline execution.

For advanced scenarios, use [`ConfigureEnvFile`](/reference/api/csharp/aspire.hosting.docker/dockercomposeenvironmentextensions/methods/#configureenvfile "Configures the captured environment variables for the Docker Compose environment before they are written to the .env file.")[`configureEnvFile`](/reference/api/typescript/aspire.hosting.docker/configureenvfile/ "Configures the captured environment variables for the Docker Compose environment before they are written to the .env file.") to customize the generated `.env` file:

Customize Docker Compose .env file

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddDockerComposeEnvironment("compose")
    .ConfigureEnvFile(env =>
    {
        env["CUSTOM_VAR"] = new CapturedEnvironmentVariable
        {
            Name = "CUSTOM_VAR",
            DefaultValue = "my-value"
        };
    });
```

Learn more about the [Docker Compose integration](/integrations/compute/docker/).

## 🌐 JavaScript and frontend support

[Section titled “🌐 JavaScript and frontend support”](#-javascript-and-frontend-support)

### JavaScript frontend starter template

[Section titled “JavaScript frontend starter template”](#javascript-frontend-starter-template)

A new `aspire-ts-cs-starter` template provides a ready-to-use JavaScript frontend setup:

Aspire CLI — Starter App ASP.NET Core/React

```bash
aspire new aspire-ts-cs-starter
```

The template includes:

* An ASP.NET Core minimal API backend named `Server`.
* A Vite-backed React client named `frontend`.
* An AppHost project to orchestrate both.

The template uses `npm` by default. You can switch to `yarn` or `pnpm` after project creation.

Learn more about the [JavaScript frontend integration](/integrations/frameworks/javascript/).

### Vite HTTPS configuration

[Section titled “Vite HTTPS configuration”](#vite-https-configuration)

Aspire now supports dynamically augmenting existing Vite configurations to enable HTTPS endpoints at runtime, eliminating manual certificate configuration for development.

### Bug fixes

[Section titled “Bug fixes”](#bug-fixes-2)

* Fixed Dockerfile generation for projects using `pnpm` by properly enabling corepack. If you’re unfamiliar with corepack, see the [corepack documentation](https://nodejs.org/api/corepack.html), and it works [well with `pnpm`](https://pnpm.io/docker).

## 🔒 Certificates and security

[Section titled “🔒 Certificates and security”](#-certificates-and-security)

Configuring and trusting local development certificates is now more straightforward with Aspire 13.1. For more details, see [Certificate configuration](/app-host/certificate-configuration/).

### TLS termination support

[Section titled “TLS termination support”](#tls-termination-support)

Caution

These APIs are experimental and may change in future releases. Use diagnostic code `ASPIRECERTIFICATES001` to suppress the experimental warning. The diagnostic warning is detailed in [ASPIRECERTIFICATES001](/diagnostics/aspirecertificates001/).

New APIs allow configuring HTTPS certificates for resources that need to terminate TLS connections.

The following containers have built-in TLS termination support:

| Container         | Default |
| ----------------- | ------- |
| YARP              | Enabled |
| Redis             | Enabled |
| Keycloak          | Enabled |
| Uvicorn (Python)  | Enabled |
| Vite (JavaScript) | Opt-in  |

When TLS is enabled by default, the ASP.NET Core developer certificate is automatically used if available and trusted.

To explicitly enable the developer certificate on a resource (e.g., for Vite):

Enable developer certificate

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddViteApp("frontend")
    .WithHttpsDeveloperCertificate();
```

To use a custom certificate:

TLS termination with custom certificate

```csharp
var certificate = new X509Certificate2("path/to/certificate.pfx", "password");


builder.AddYarp("gateway")
    .WithHttpsCertificate(certificate);
```

For YARP, you can also explicitly set the HTTPS port:

YARP with custom HTTPS port

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddYarp("gateway")
    .WithHostHttpsPort(8443);
```

To disable HTTPS certificate configuration for a resource:

Disable HTTPS certificate

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddRedis("cache")
    .WithoutHttpsCertificate();
```

To configure TLS termination for a resource without built-in support, you can use a configuration callback to pass custom arguments and environment variables:

TLS termination with configuration callback

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddContainer("my-service", "my-image")
    .WithHttpsCertificateConfiguration(ctx =>
    {
        // Pass the path to the cert in PFX format as an argument
        ctx.Arguments.Add("--https-certificate-path");
        ctx.Arguments.Add(ctx.PfxPath);


        // Set the public and private PEM format certificate paths as environment variables
        ctx.EnvironmentVariables["HTTPS_CERT"] = ctx.CertificatePath;
        ctx.EnvironmentVariables["HTTPS_CERT_KEY"] = ctx.KeyPath;


        return Task.CompletedTask;
    });
```

Learn more about [Certificate configuration](/app-host/certificate-configuration/).

## 🧩 App model updates

[Section titled “🧩 App model updates”](#-app-model-updates)

### Endpoint reference resolution

[Section titled “Endpoint reference resolution”](#endpoint-reference-resolution)

Endpoint references now properly wait for endpoint allocation when evaluating, fixing race conditions in complex orchestration scenarios.

### Container network context

[Section titled “Container network context”](#container-network-context)

Endpoint references now correctly honor their specific network context when resolving, ensuring proper networking in multi-network container deployments.

### System log formatting

[Section titled “System log formatting”](#system-log-formatting)

System-level logs from DCP now use a human-friendly format with a `[sys]` prefix instead of verbose JSON objects:

```plaintext
[sys] Starting process: Cmd = dotnet, Args = [run]
[sys] Failed to start Container: Error = container start failed (exit code 1)
```

This makes it easier to distinguish system logs from application output and improves readability in the console.

## 📦 Integration updates

[Section titled “📦 Integration updates”](#-integration-updates)

### DevTunnels stabilization

[Section titled “DevTunnels stabilization”](#devtunnels-stabilization)

The [📦 Aspire.Hosting.DevTunnels](https://www.nuget.org/packages/Aspire.Hosting.DevTunnels) package is now stable and no longer in preview. Use dev tunnels to expose your local Aspire applications to the internet for testing webhooks, mobile apps, and external integrations.

Learn more about the [Dev Tunnels integration](/integrations/devtools/dev-tunnels/).

### Endpoint proxy support stabilization

[Section titled “Endpoint proxy support stabilization”](#endpoint-proxy-support-stabilization)

The `WithEndpointProxySupport` API is now stable and no longer requires the experimental attribute.

### Keycloak improvements

[Section titled “Keycloak improvements”](#keycloak-improvements)

Keycloak containers can now export telemetry to your OTLP collector:

Keycloak with OTLP export

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddKeycloak("keycloak")
    .WithOtlpExporter();
```

Learn more about the [Keycloak integration](/integrations/security/keycloak/).

### OpenTelemetry updates

[Section titled “OpenTelemetry updates”](#opentelemetry-updates)

OpenTelemetry dependencies have been updated to the latest stable versions across the codebase.

### Azure Functions

[Section titled “Azure Functions”](#azure-functions)

In Aspire 13.1, the Azure Functions integration is officially out of preview. Azure Functions now support a local development story with Aspire and deployments to ACA Native Functions with support for KEDA-based auto-scaling rules.

* Aspire dashboard will notify if the Azure Functions Core Tools are not installed on the local machine.
* New overload `AddAzureFunctionsProject(name, projectPath)` for adding Functions projects without a generic type parameter:

Azure Functions without generic type

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddAzureFunctionsProject("myfunc", "../MyFunctions/MyFunctions.csproj");
```

Learn more about the [Azure Functions integration](/integrations/cloud/azure/azure-functions/azure-functions-get-started/) or [how to use Azure Functions with Aspire](https://learn.microsoft.com/azure/azure-functions/dotnet-aspire-integration).

## 🏗️ Templates

[Section titled “🏗️ Templates”](#️-templates)

All Aspire templates have been updated for 13.1 with consistent patterns:

* Dropped support for previous Aspire versions.
* Unified project structure across starter templates.

Note

Template changes may require updating existing projects created from older templates.

## 🐛 Bug fixes

[Section titled “🐛 Bug fixes”](#-bug-fixes)

* Fixed `aspire agent init` hanging in VS Code terminal on Windows.
* Fixed path normalization for AppHost paths on Windows.
* Fixed CLI tool detection on Windows with proper PATHEXT handling.
* Fixed saving parameters with custom config keys.
* Fixed container image builds for resources with dashes in names.
* Fixed relative endpoint URL handling.
* Fixed deployment state file case sensitivity on Linux.

## 🙏 Community

[Section titled “🙏 Community”](#-community)

Thank you to all community contributors who helped make Aspire 13.1 possible:

* Improved resource graph layout with adaptive force-directed positioning.
* Updated npm dependencies across playground apps.
* Documentation link updates.
* Various bug fixes and improvements.

### The Aspire core team is

* [![Adam Ratzman](https://github.com/adamint.png?size=96)Adam Ratzman](https://github.com/adamint)
* [![Ankit Jain](https://github.com/radical.png?size=96)Ankit Jain](https://github.com/radical)
* [![Damian Edwards](https://github.com/DamianEdwards.png?size=96)Damian Edwards](https://github.com/DamianEdwards)
* [![David Fowler](https://github.com/davidfowl.png?size=96)David Fowler](https://github.com/davidfowl)
* [![David Negstad](https://github.com/danegsta.png?size=96)David Negstad](https://github.com/danegsta)
* [![David Pine](https://github.com/IEvangelist.png?size=96)David Pine](https://github.com/IEvangelist)
* [![Ella Hathaway](https://github.com/ellahathaway.png?size=96)Ella Hathaway](https://github.com/ellahathaway)
* [![Eric Erhardt](https://github.com/eerhardt.png?size=96)Eric Erhardt](https://github.com/eerhardt)
* [![James Newton-King](https://github.com/JamesNK.png?size=96)James Newton-King](https://github.com/JamesNK)
* [![José Pérez](https://github.com/joperezr.png?size=96)José Pérez](https://github.com/joperezr)
* [![Karol Zadora-Przylecki](https://github.com/karolz-ms.png?size=96)Karol Zadora-Przylecki](https://github.com/karolz-ms)
* [![Maddy Montaquila](https://github.com/maddymontaquila.png?size=96)Maddy Montaquila](https://github.com/maddymontaquila)
* [![Mitch Denny](https://github.com/mitchdenny.png?size=96)Mitch Denny](https://github.com/mitchdenny)
* [![Sébastien Ros](https://github.com/sebastienros.png?size=96)Sébastien Ros](https://github.com/sebastienros)

Special thanks to everyone whose pull requests shipped in Aspire 13.1, including:

[@afscrome](https://github.com/afscrome), [@akoeplinger](https://github.com/akoeplinger), [@askpt](https://github.com/askpt), [@captainsafia](https://github.com/captainsafia), [@fabiocav](https://github.com/fabiocav), [@flcdrg](https://github.com/flcdrg), [@JakeRadMSFT](https://github.com/JakeRadMSFT), [@jamesmontemagno](https://github.com/jamesmontemagno), [@jfversluis](https://github.com/jfversluis), [@mattchenderson](https://github.com/mattchenderson), [@MattKotsenas](https://github.com/MattKotsenas), [@murataslan1](https://github.com/murataslan1), [@nohwnd](https://github.com/nohwnd), [@ojamte](https://github.com/ojamte), [@ShilpiRach](https://github.com/ShilpiRach), [@sliekens](https://github.com/sliekens), and [@vhvb1989](https://github.com/vhvb1989)

We're always excited to [see community contributions](/community/contributors/)! If you'd like to get involved, check out our [contributing guide](/community/contributor-guide/).

## ⚠️ Breaking changes

[Section titled “⚠️ Breaking changes”](#️-breaking-changes)

### Azure Redis API rename

[Section titled “Azure Redis API rename”](#azure-redis-api-rename)

| Change                            | Migration                                          |
| --------------------------------- | -------------------------------------------------- |
| `AddAzureRedisEnterprise` renamed | Use `AddAzureManagedRedis`                         |
| `AddAzureRedis` obsolete          | Migrate to `AddAzureManagedRedis` for new projects |

### Migration from Aspire 13.0 to 13.1

[Section titled “Migration from Aspire 13.0 to 13.1”](#migration-from-aspire-130-to-131)

1. Update the CLI by running `aspire update --self`.
2. Update your projects by running `aspire update` in your project directory.
3. Rename Azure Redis by replacing `AddAzureRedisEnterprise` with `AddAzureManagedRedis`.
4. Review MCP configuration by running `aspire agent init` to set up AI coding agent support.

### Connection Properties rename

[Section titled “Connection Properties rename”](#connection-properties-rename)

Some connection properties have been renamed for consistency across resources:

| Resource                  | Old property | New property   |
| ------------------------- | ------------ | -------------- |
| GitHub Models resource    | `Model`      | `ModelName`    |
| OpenAI model resource     | `Model`      | `ModelName`    |
| Milvus database resource  | `Database`   | `DatabaseName` |
| MongoDB database resource | `Database`   | `DatabaseName` |
| MySQL database resource   | `Database`   | `DatabaseName` |
| Oracle database resource  | `Database`   | `DatabaseName` |

***

If your client apps where using some of these properties, please update them to use the new names. For instance for a GitHub Models resource named `chat` the model name environment variable would change from `CHAT_MODEL` to `CHAT_MODELNAME`.

We’d love to hear about your experience with Aspire 13.1. Share feedback on [GitHub](https://github.com/microsoft/aspire/issues) or join the conversation on [Discord](https://aka.ms/aspire-discord).

# What's new in Aspire 13.2

> Aspire 13.2 is here with new CLI commands, TypeScript AppHost support, and new and improved integrations.

Aspire 13.2 expands the CLI, adds preview TypeScript AppHost support, and improves the dashboard, AI agent integrations, multi-language development, and cloud deployment. It also strengthens the infrastructure used to ship stable releases more frequently. Share questions and feedback on [Discord](https://aka.ms/aspire-discord) or [GitHub](https://github.com/microsoft/aspire/issues).

## 🆙 Upgrade to Aspire 13.2

[Section titled “🆙 Upgrade to Aspire 13.2”](#-upgrade-to-aspire-132)



Caution

Aspire 13.2 includes breaking changes to configuration files, resource commands, event handling, and the Azure AI Foundry (now Microsoft Foundry) integration. Please review the [Breaking changes](#breaking-changes) section before upgrading.

If your Aspire CLI version is earlier than 13, first [install the latest stable version](/get-started/install-cli/).

For general purpose upgrade guidance, see [Upgrade Aspire](/whats-new/upgrade-aspire/).

The easiest way to upgrade to Aspire 13.2 is using the `aspire update` command:

Tip

The `aspire update` command is currently in preview.

1. Update the Aspire CLI:

   Aspire CLI — Update the CLI

   ```bash
   aspire update --self
   ```

2. Update your Aspire apphost using the [`aspire update` command](/reference/cli/commands/aspire-update/):

   Aspire CLI — Update all Aspire packages

   ```bash
   aspire update
   ```

Or install the CLI from scratch:

* Bash

  Aspire CLI — Install Aspire CLI

  ```bash
  curl -sSL https://aspire.dev/install.sh | bash
  ```

* PowerShell

  Aspire CLI — Install Aspire CLI

  ```powershell
  irm https://aspire.dev/install.ps1 | iex
  ```

You can also manually update your apphost to reference Aspire version `13.2.0`:

* C# AppHost

  AppHost.cs

  ```csharp
  #:package Aspire.AppHost.Sdk@13.2.0
  ```

If you’re using a C# apphost, you can then upgrade both your hosting and client integrations via NuGet.

If you’re using a TypeScript apphost, run `aspire restore` after upgrading so the integration SDKs are regenerated.

For more details on installing the Aspire CLI, see [Install the CLI](/get-started/install-cli/).

## 🛠️ CLI enhancements

[Section titled “🛠️ CLI enhancements”](#️-cli-enhancements)

Aspire 13.2 introduces a wave of new CLI commands that dramatically expand what you can do from the terminal. The CLI now exposes all of the data that was previously trapped inside the dashboard and apphost, making it accessible from scripts, editors, and automation workflows.

### Language-specific templates and multi-language setup

[Section titled “Language-specific templates and multi-language setup”](#language-specific-templates-and-multi-language-setup)

Aspire 13.2 makes the `aspire new` (creates a full starter template) and `aspire init` (creates only an apphost) experiences much more language-aware. The CLI now has options to scaffold language-specific full stack starter apps for C#, TypeScript, Python, and both C# and TypesScript apphosts. Use `aspire new` to create a new project from a template, or `aspire init` to add Aspire to an existing project.

The new `aspire restore` command complements this workflow. For C# apphosts it restores the integration NuGet packages, and for TypeScript apphosts it regenerates the integration SDK code and required artifacts. This automatically happens on `aspire run`, but is also now exposed manually.

Aspire CLI — Templates and restore

```bash
# Create a new starter with the interactive template picker
aspire new


# Or, create a new blank apphost in an existing codebase
aspire init


# Restores integration packages and starts the apphost
aspire run


# Manually restore integrations
aspire restore
```

### Detached mode and process management

[Section titled “Detached mode and process management”](#detached-mode-and-process-management)

One of the most requested features in 13.2 is detached mode for running Aspirified apps. You can now run your apphost in the background, freeing up your terminal for other tasks.

Aspire CLI — Detached mode and process management

```bash
# Run in detached mode
aspire run --detach


# Shorthand command for run --detach
aspire start


# List all running apphosts
aspire ps


# Stop a running apphost in the background
aspire stop
```

The `aspire ps` command displays all currently running Aspire apphosts, making it easy to manage multiple projects simultaneously. When combined with `aspire stop`, you have full control over your application lifecycle directly from the command line.

The new `aspire start` shortcut makes background apphost startup easier to remember, and `aspire stop` can stop a selected apphost or all running apphosts. In JSON mode, `aspire ps` can include resources, which makes it a solid building block for automation and editor integrations.

Aspire CLI — Extended operations

```bash
aspire start --apphost .\MyApp.AppHost\MyApp.AppHost.csproj
aspire ps --resources --format json
aspire stop --all
```

Resource commands were also reorganized into the `aspire resource  ` form. Built-in commands such as `start`, `stop`, and `restart` now line up more naturally with what the dashboard exposes, and project resources can expose richer commands such as `rebuild`.

Aspire CLI — Resource commands

```bash
aspire resource api restart
aspire resource api rebuild
```

For automation and CI/CD scenarios, use `--format Json` to get machine-readable output:

Aspire CLI — Detached mode with JSON output

```bash
aspire run --detach --format Json
aspire ps --format Json
```

Command reference: [`aspire run`](/reference/cli/commands/aspire-run/), [`aspire ps`](/reference/cli/commands/aspire-ps/), and [`aspire stop`](/reference/cli/commands/aspire-stop/).

### Isolated mode for parallel development

[Section titled “Isolated mode for parallel development”](#isolated-mode-for-parallel-development)

The new `--isolated` flag runs an apphost with randomized ports and isolated user secrets, preventing port conflicts and configuration collisions:

Aspire CLI — Isolated mode

```bash
aspire run --isolated
aspire start --isolated
```

This is especially useful for agentic workflows, git worktrees, and integration tests where multiple instances of the same apphost need to run side by side.

### Resource monitoring with `aspire describe`

[Section titled “Resource monitoring with aspire describe”](#resource-monitoring-with-aspire-describe)

The new `aspire describe` command gives you and your coding agents CLI access to the same detailed resource information you get in the Aspire dashboard. You can inspect resource state, configuration, environment variables, health status, and more—all from the terminal.

Aspire CLI — Describe resources

```bash
# Show all resources in a running apphost
aspire describe


# Continuously stream resource state changes
aspire describe --follow
```

Command reference: [`aspire describe`](/reference/cli/commands/aspire-describe/).

### Environment diagnostics with `aspire doctor`

[Section titled “Environment diagnostics with aspire doctor”](#environment-diagnostics-with-aspire-doctor)

The new `aspire doctor` command provides comprehensive diagnostics of your development environment:

Aspire CLI — Environment diagnostics

```bash
aspire doctor
```

This command checks:

* HTTPS development certificate status (including detection of multiple certificates)
* Container runtime (Docker/Podman) availability and version
* Container tunnel requirements for Docker Engine
* .NET SDK installation and version
* WSL2 environment configuration
* Agent configuration status (detecting deprecated settings)

Not all checks appear in every run. Some checks, such as WSL2 configuration and agent configuration status, are conditional and only appear when the relevant environment or issues are detected.

The output provides actionable recommendations when issues are detected, making it easier to troubleshoot configuration problems.

### Enhanced `aspire add` with fuzzy search

[Section titled “Enhanced aspire add with fuzzy search”](#enhanced-aspire-add-with-fuzzy-search)

Finding the right integration package is now easier with fuzzy search in the `aspire add` command. Simply start typing and the CLI will suggest matching packages, reducing the friction of discovering and adding new integrations to your project. This release also improves friendly-name generation and better respects NuGet central package management for C# apps.

Command reference: [`aspire add`](/reference/cli/commands/aspire-add/).

### New CLI commands for certificates, exports, secrets, and resource lifecycles

[Section titled “New CLI commands for certificates, exports, secrets, and resource lifecycles”](#new-cli-commands-for-certificates-exports-secrets-and-resource-lifecycles)

Aspire 13.2 significantly expands the day-to-day CLI surface area with several new commands.

Certificate and parameter/secret management get first-class commands:

Aspire CLI — Certificate and secret management

```bash
aspire certs clean
aspire certs trust


aspire secret set ApiKey super-secret-value
aspire secret list --format json
```

`aspire certs` helps you clean stale developer certificates and trust the current certificate, while `aspire secret` gives apphost [user secrets](/fundamentals/external-parameters/#secret-values) their own dedicated CLI workflow for setting, reading, listing, locating, and deleting secret values. These are the same secret values that back [`AddParameter(..., secret: true)`](/fundamentals/external-parameters/) calls in the app model—`aspire secret set` writes to the user-secrets store so you no longer need have the .NET CLI installed to manage them via `dotnet user-secrets`.

Two new operational commands round out the experience:

Aspire CLI — Wait and export

```bash
aspire wait api --status healthy --timeout 120
aspire export --output .\artifacts\aspire-export.zip
```

Use `aspire wait` to block automation until a resource becomes `healthy`, `up`, or `down`, and use `aspire export` to capture telemetry and resource data from a running apphost into a zip file. You can also scope export to a single resource with `aspire export `.

For more details on parameters and secrets, see [External parameters](/fundamentals/external-parameters/). Command reference: [`aspire secret`](/reference/cli/commands/aspire-secret/).

### Agent integration (`aspire agent`)

[Section titled “Agent integration (aspire agent)”](#agent-integration-aspire-agent)

The `aspire mcp` command has been renamed to `aspire agent` to better reflect its purpose of managing AI agent integrations. It’s also been updated to add Aspire specific SKILL.md files into your repo. The new command structure includes:

Aspire CLI — Agent integration

```bash
# Initialize agent environment configuration including MCP and skills
aspire agent init


# Manually start the MCP (Model Context Protocol) server - only
aspire agent mcp
```

This enables AI agents to interact with your Aspire applications through a standardized protocol, opening up new possibilities for AI-assisted development workflows.

Command reference: [`aspire agent`](/reference/cli/commands/aspire-agent/), [`aspire agent mcp`](/reference/cli/commands/aspire-agent-mcp/), and [`aspire agent init`](/reference/cli/commands/aspire-agent-init/).

To learn how to configure AI agents with Aspire, see [Use AI coding agents](/get-started/ai-coding-agents/).

### Documentation commands from the CLI (`aspire docs`)

[Section titled “Documentation commands from the CLI (aspire docs)”](#documentation-commands-from-the-cli-aspire-docs)

The new `aspire docs` command brings the official [aspire.dev](https://aspire.dev) documentation directly into your terminal. Built on the same [MCP (Model Context Protocol) documentation tools](https://davidpine.dev/posts/aspire-docs-mcp-tools/) that power the Aspire agent integration, these commands let you browse, search, and read documentation without leaving your development workflow.

Note

These commands are intended for use by AI agents; although developers can use these directly, they aren’t ergonomic for manual use and the website is still the best place to access documentation.

Aspire CLI — Browse and search documentation

```bash
# List all available documentation pages
aspire docs list


# Search for specific topics
aspire docs search "redis"


# Read a full documentation page by its slug
aspire docs get redis-integration


# Read a specific section of a page
aspire docs get redis-integration --section "Add Redis resource"
```

Each command supports `--format Json` for machine-readable output, making them useful for scripting and automation. The `aspire docs search` command also accepts a `--limit` option to control the number of results returned.

Command reference: [`aspire docs`](/reference/cli/commands/aspire-docs/), [`aspire docs list`](/reference/cli/commands/aspire-docs-list/), [`aspire docs search`](/reference/cli/commands/aspire-docs-search/), and [`aspire docs get`](/reference/cli/commands/aspire-docs-get/).

### Improved configuration management

[Section titled “Improved configuration management”](#improved-configuration-management)

The `aspire config` command has been enhanced with better organization:

Aspire CLI — Configuration management

```bash
# List all configuration with organized sections and colors
aspire config list


# List all available feature flags
aspire config list --all


# Get a specific setting
aspire config get 


# Set a configuration value
aspire config set  
```

Configuration is now clearly separated into local and global settings, with feature flags displayed in an organized manner.

Aspire now also prefers a single `aspire.config.json` file that combines apphost location, language metadata, Aspire SDK version, channel selection, feature flags, launch profiles, and package pins:

aspire.config.json

```json
{
  "appHost": {
    "path": "apphost.mts",
    "language": "typescript/nodejs"
  },
  "sdk": {
    "version": "13.2.0"
  },
  "channel": "stable",
  "profiles": {
    "default": {
      "applicationUrl": "https://localhost:17000;http://localhost:15000"
    }
  }
}
```

This unified format replaces the older split across `.aspire/settings.json` and `apphost.run.json` and makes TypeScript apphosts much easier to move, inspect, and automate.

#### Auto migration from legacy configuration files

[Section titled “Auto migration from legacy configuration files”](#auto-migration-from-legacy-configuration-files)

If you have an existing project that uses `.aspire/settings.json` or `apphost.run.json`, the CLI handles migration automatically. The first time you run any `aspire` command (such as `aspire run`) against an existing project, the CLI merges your legacy `.aspire/settings.json` and `apphost.run.json` into a new `aspire.config.json` at the project root. Paths are automatically re-based—for example, an `appHostPath` that was relative to the `.aspire/` directory is adjusted to be relative to the project root. The legacy files are preserved during migration so you can continue using older CLI versions side by side if needed.

Global settings (`globalsettings.json` in your user-level Aspire directory) are also copied to the new `aspire.config.json` format in the same location. No manual steps are required—just update the CLI and run your project as usual.

Command reference: [`aspire config`](/reference/cli/commands/aspire-config/), [`aspire config list`](/reference/cli/commands/aspire-config-list/), [`aspire config get`](/reference/cli/commands/aspire-config-get/), and [`aspire config set`](/reference/cli/commands/aspire-config-set/).

### CLI option standardization

[Section titled “CLI option standardization”](#cli-option-standardization)

Several CLI options were standardized for consistency with common CLI conventions:

* `-v` is now a short alias for `--version`, following standard CLI conventions.
* The `--format` option description is now standardized to “Output format (Table or Json).” across all commands that support it.
* Commands that support log-level filtering now use `--log-level` and `-l` consistently.

### Other CLI improvements

[Section titled “Other CLI improvements”](#other-cli-improvements)

There are plenty of smaller but meaningful CLI improvements in 13.2:

* `aspire run` now supports `--no-build` for cases where you know the apphost artifacts are already up to date.
* `--format json` always sends JSON output to stdout, while status messages are sent to stderr. This ensures human-readable output is kept separate from structured JSON output, allowing scripts and editors that consume JSON to receive well-formed content.
* Tables, status indicators, help organization, logging, and error messages were refined across interactive and non-interactive scenarios.
* The unified self-extracting Aspire CLI bundle continues to improve multi-language experiences, especially when .NET isn’t already installed globally.
* Status messages that start with an emoji are consistently aligned. This is harder than you might think! If you see messy CLI output, [please let us know](https://github.com/microsoft/aspire).

## 🧩 VS Code extension

[Section titled “🧩 VS Code extension”](#-vs-code-extension)

The Aspire VS Code extension received its biggest update yet in 13.2, with over 20 PRs shipping new features that make VS Code a first-class Aspire development environment alongside Visual Studio.

### Aspire Activity Bar panel

[Section titled “Aspire Activity Bar panel”](#aspire-activity-bar-panel)

A dedicated Aspire panel in the Activity Bar gives you a live tree view of running apphosts and their resources. The panel uses `aspire describe --follow` to stream real-time resource state updates for the workspace apphost — no polling, no latency. A workspace/global toggle lets you switch between viewing just the current workspace’s apphost or all running apphosts on your machine.

Resources in the tree show health-aware icons (green for healthy, red for errors, amber for degraded, spinner for starting), rich markdown tooltips with type, state, and clickable endpoint URLs, and right-click context menus for common operations like viewing logs, stopping, or restarting resources.

### CodeLens and gutter decorations

[Section titled “CodeLens and gutter decorations”](#codelens-and-gutter-decorations)

When an Aspire apphost is running, the extension now shows inline CodeLens above each resource definition in your C# or TypeScript apphost file:

* Live resource state (Running, Starting, Stopped, Error) with health status
* Action buttons: Start, Stop, Restart, View Logs
* Custom resource commands from the runtime

Colored gutter decorations appear alongside resource definitions — green for running, blue for starting, red for errors, gray for stopped — giving you an at-a-glance view of your entire app’s health right in the editor. Both features are backed by language-aware parsers that understand `DistributedApplication.CreateBuilder` in C# and `createBuilder` in TypeScript.

### Getting Started walkthrough

[Section titled “Getting Started walkthrough”](#getting-started-walkthrough)

A new Getting Started walkthrough guides new users through installing the CLI, creating a project, running their app, exploring the dashboard, and next steps — all from within VS Code. The walkthrough includes clickable terminal links to install the Aspire CLI directly from the editor.

### Debugging improvements

[Section titled “Debugging improvements”](#debugging-improvements)

* Azure Functions projects referenced from an apphost can now be debugged directly.
* TypeScript apphosts now participate in debugging more naturally, with better tool detection, build and launch coordination, and support for browser debugging scenarios.
* `publish`, `deploy`, and `do` flows can now be debugged directly from the extension.
* Apphost exit messages now appear in the debug console for easier troubleshooting.

### `aspire.config.json` and MCP support

[Section titled “aspire.config.json and MCP support”](#aspireconfigjson-and-mcp-support)

The extension now reads `aspire.config.json` for apphost discovery instead of relying solely on `.csproj` file detection, making TypeScript apphosts work seamlessly. It can also auto-register the Aspire MCP server for AI agent workflows. The CLI is automatically detected at default install paths even when it’s not on PATH.

### Additional improvements

[Section titled “Additional improvements”](#additional-improvements)

* A new `enableAspireDashboardAutoLaunch` setting lets you disable automatic dashboard launch on run.
* File pickers replace raw string prompts in more places.
* Right-click context menus on resource endpoint URLs.
* Falls back to `code-insiders` when `code` is not found.

For more details, see [Use VS Code with Aspire](/get-started/aspire-vscode-extension/) and the [extension on the VS Code Marketplace](https://aka.ms/aspire/vscode).

## 🌐 TypeScript AppHost support (preview)

[Section titled “🌐 TypeScript AppHost support (preview)”](#-typescript-apphost-support-preview)

One of the most anticipated features in Aspire 13.2 is support for writing your apphost in TypeScript. The TypeScript AppHost is currently in preview.

### Writing an apphost in TypeScript

[Section titled “Writing an apphost in TypeScript”](#writing-an-apphost-in-typescript)

TypeScript apphosts use the same app model as C#—resources, references, integrations—expressed in idiomatic TypeScript via `createBuilder()`:

apphost.mts

```typescript
import { createBuilder } from './.aspire/modules/aspire.mjs';


const builder = await createBuilder();


const cache = await builder.addRedis("cache");
const api = await builder.addProject("api", "../api")
    .withReference(cache)
    .waitFor(cache);


await builder.build().run();
```

Under the hood, this runs as a guest process alongside Aspire’s .NET orchestration host, communicating via JSON-RPC over local transport. Your TypeScript defines the resource graph; the host handles orchestration, health checks, and the dashboard.

### Code generation

[Section titled “Code generation”](#code-generation)

When you run `aspire add`, the CLI inspects the integration’s .NET assembly and generates a TypeScript SDK into `.aspire/modules/`. Running `aspire restore` regenerates these SDKs—useful after upgrading or switching branches (this also runs automatically on `aspire run`).

In 13.2, the code generator gained AspireList support for richer collection handling and now covers Go, Java, and Rust test targets alongside TypeScript.

### Debugging, tooling, and templates

[Section titled “Debugging, tooling, and templates”](#debugging-tooling-and-templates)

TypeScript apphosts now have first-class support in the VS Code extension—CodeLens, gutter decorations, and debugging all work with `createBuilder()` calls. The `aspire.config.json` format means TypeScript apphosts are discovered automatically without needing a `.csproj`. Templates were also refreshed with updated dependencies and better starter defaults.

For more details, see [Multi-language architecture](/architecture/multi-language-architecture/).

## 📊 Dashboard improvements

[Section titled “📊 Dashboard improvements”](#-dashboard-improvements)

### Data export and import

[Section titled “Data export and import”](#data-export-and-import)

Aspire 13.2 adds comprehensive data export and import capabilities to the dashboard. You can bulk-manage telemetry through a centralized dialog, export individual resources and telemetry as JSON, and export environment variables as `.env` files.

#### Manage logs and telemetry dialog

[Section titled “Manage logs and telemetry dialog”](#manage-logs-and-telemetry-dialog)

The new Manage logs and telemetry dialog, available from Settings → Manage, provides one place to export, import, and remove dashboard data. Select resources and telemetry types, then export, remove, or import as needed.

Data is exported as JSON in a zip file. Share it with AI, teammates, or import it back into the dashboard later.

![Manage logs and telemetry dialog showing Export selected, Remove selected, and Import logs and telemetry buttons](/_astro/manage-dialog.jKSXpKaT_sMjUe.webp)

The dashboard can also import telemetry bundles captured with `aspire export`, making it easy to attach diagnostics to bug reports, preserve a point-in-time view of a session, or share a failing scenario with a teammate.

#### Export JSON for resources and telemetry

[Section titled “Export JSON for resources and telemetry”](#export-json-for-resources-and-telemetry)

Export data for specific resources and telemetry directly from the dashboard. Select Export JSON in context menus, then copy the data to your clipboard or download it to your machine.

![Export JSON button in the resource context menu](/_astro/export-json-menu.BHCktog__14P0NC.webp) ![Export JSON dialog with options to copy to clipboard or download](/_astro/export-json-dialog.CQ9KwlpR_Z20sngd.webp)

#### Export environment variables as `.env` files

[Section titled “Export environment variables as .env files”](#export-environment-variables-as-env-files)

Export a resource’s environment variables directly to a `.env` file format from the resource details view.

![Export Env dialog showing environment variables exported in .env format](/_astro/export-env-dialog.Bthk5S2B_Z1SLxok.webp)

#### Telemetry HTTP API

[Section titled “Telemetry HTTP API”](#telemetry-http-api)

The dashboard now exposes an HTTP API for querying telemetry data programmatically. These APIs power the `aspire agent mcp` and `aspire otel` Aspire CLI commands.

The API is served under `/api/telemetry` and returns data in OTLP JSON format. Available endpoints:

* `GET /api/telemetry/resources` — List resources that have telemetry data
* `GET /api/telemetry/spans` — Query spans with optional filters
* `GET /api/telemetry/logs` — Query logs with optional filters
* `GET /api/telemetry/traces` — List traces with optional filters
* `GET /api/telemetry/traces/{traceId}` — Get all spans for a specific trace

The spans and logs endpoints also support real-time streaming via `?follow=true`, which returns NDJSON (newline-delimited JSON) as new telemetry arrives. Multiple resource names can be specified by repeating the `resource` query parameter (e.g. `?resource=api&resource=worker`).

When running with an Aspire apphost, the telemetry API is enabled automatically. For standalone dashboard deployments, set the `DASHBOARD__API__ENABLED` environment variable to `true` and configure authentication with `DASHBOARD__API__AUTHMODE` (`ApiKey` or `Unsecured`) and `DASHBOARD__API__PRIMARYAPIKEY`.

### Set parameters from the dashboard

[Section titled “Set parameters from the dashboard”](#set-parameters-from-the-dashboard)

You can now set resource parameters directly in the dashboard. Click the key action on a parameter and enter a new value. To remember it next time, optionally save the value to your user secrets.

![Dashboard dialog for setting a parameter value with an option to save to user secrets](/_astro/dashboard-set-parameters.DMma6ucR_Z2nLx38.webp)

### GenAI visualizer improvements

[Section titled “GenAI visualizer improvements”](#genai-visualizer-improvements)

The GenAI visualizer keeps getting sharper. In 13.2 it handles more schema shapes, tolerates truncated payloads more gracefully, properly displays non-ASCII text, and makes tool inspection easier by letting you jump directly from a tool call to the corresponding tool definition.

These improvements make the dashboard more useful for inspecting AI-heavy workloads when traffic is incomplete or generated by real agents rather than controlled samples.

### Resource graph improvements

[Section titled “Resource graph improvements”](#resource-graph-improvements)

The resource graph layout has been significantly improved with adaptive force-directed positioning. Resources with many connections now have more space around them, making complex graphs feel less cluttered.

**After:**

![Resource graph after improvements, showing a cleaner layout with better spacing around highly-connected resources](/_astro/resource-graph-after.BVtxyDeu_Z3KWjU.webp)

### Dashboard UX refinements

[Section titled “Dashboard UX refinements”](#dashboard-ux-refinements)

Additional dashboard refinements in 13.2:

* Persistent collapsed/expanded state of resources
* A 12-hour or 24-hour time format setting.
* Consistent resource colors across the dashboard and CLI.
* Better JSON viewers for traces, spans, logs, and resources.
* Improved handling for large gRPC payloads.
* More stable graph layout and filtering behavior.
* Base path configuration for reverse proxy scenarios.
* Aggregate replica states—parent resources now show combined state from their replicas.
* More polished dialogs, menus, copy flows, and resource details views.

For more details, see [Explore the Aspire dashboard](/dashboard/explore/) and [Dashboard configuration](/dashboard/configuration/).

## 🧩 App model and resource improvements

[Section titled “🧩 App model and resource improvements”](#-app-model-and-resource-improvements)

### MCP endpoints from the app model

[Section titled “MCP endpoints from the app model”](#mcp-endpoints-from-the-app-model)

Aspire 13.2 adds [`WithMcpServer`](/reference/api/csharp/aspire.hosting/mcpserverresourcebuilderextensions/methods/#withmcpserver "Marks the resource as hosting a Model Context Protocol (MCP) server on the specified endpoint.")[`withMcpServer`](/reference/api/typescript/aspire.hosting/withmcpserver/ "Marks the resource as hosting a Model Context Protocol (MCP) server on the specified endpoint."), which lets you declare in the app model that a resource hosts a Model Context Protocol (MCP) server. Aspire tooling can then discover and proxy that endpoint directly.

* C# AppHost

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  var api = builder.AddProject("api")
      .WithMcpServer("/mcp");


  builder.Build().Run();
  ```

* TypeScript AppHost

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const api = await builder.addProject("api", "../api")
      .withMcpServer({ path: "/mcp" });


  await builder.build().run();
  ```

If you host the MCP server on a non-default endpoint or path, pass a custom `path` or `endpointName`.

### Project rebuilds and smarter change detection

[Section titled “Project rebuilds and smarter change detection”](#project-rebuilds-and-smarter-change-detection)

.NET Project resources now support a `rebuild` command in addition to the usual lifecycle commands. This gives you a clean way to apply source changes to a single project resource without tearing down the whole apphost session.

Aspire CLI — Rebuild a single resource

```bash
aspire resource api rebuild
```

Under the hood, Aspire coordinates stop, build, and restart through a hidden rebuilder resource and improved change detection, so the experience is much closer to “rebuild just this one thing” instead of “restart everything and hope.”

### OTLP endpoint as a first-class resource

[Section titled “OTLP endpoint as a first-class resource”](#otlp-endpoint-as-a-first-class-resource)

The OpenTelemetry Protocol (OTLP) endpoint is now modeled as a first-class resource in the application model, making it visible in the dashboard and configurable through standard resource APIs.

### Better secret and certificate handling

[Section titled “Better secret and certificate handling”](#better-secret-and-certificate-handling)

Container build secrets got a clearer API in 13.2. [`WithBuildSecret`](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods/#withbuildsecret "Adds a secret build argument when the container is built from a Dockerfile.")[`withBuildSecret`](/reference/api/typescript/aspire.hosting/withbuildsecret/ "Adds a secret build argument when the container is built from a Dockerfile.") replaces the old `WithSecretBuildArg` name and makes secure Docker or Podman build secret flows more readable.

* C# AppHost

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  var accessToken = builder.AddParameter("accessToken", secret: true);


  builder.AddContainer("worker", "contoso/worker")
      .WithDockerfile("../worker")
      .WithBuildSecret("ACCESS_TOKEN", accessToken);
  ```

* TypeScript AppHost

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const accessToken = await builder.addParameter("accessToken", { secret: true });


  await builder.addContainer("worker", { image: "contoso/worker", tag: "latest" })
      .withDockerfile("../worker")
      .withBuildSecret("ACCESS_TOKEN", accessToken);
  ```

Certificate trust handling also became more flexible. You can now create custom certificate bundles during run mode, which helps with scenarios like Java trust stores or custom bundle formats that don’t map cleanly to the default certificate layout.

Custom certificate trust configuration

```csharp
builder.AddContainer("my-java-app", "my-image:latest")
    .WithCertificateTrustConfiguration(ctx =>
    {
        ctx.EnvironmentVariables["JAVAX_NET_SSL_TRUSTSTORE"] =
            ctx.CreateCustomBundle((certs, ct) =>
        {
            var pkcs12Builder = new Pkcs12Builder();
            var safeContents = new Pkcs12SafeContents();


            foreach (var cert in certs)
            {
                safeContents.AddCertificate(cert);
            }


            pkcs12Builder.AddSafeContentsUnencrypted(safeContents);
            pkcs12Builder.SealWithMac(
                string.Empty, HashAlgorithmName.SHA256, 2048);


            return Task.FromResult(pkcs12Builder.Encode());
        });


        return Task.CompletedTask;
    });
```

`ReferenceExpression` now exposes [`GetValueAsync`](/reference/api/csharp/aspire.hosting/referenceexpression/methods/#getvalueasync "Gets the value of the expression. The final string value after evaluating the format string and its parameters.")[`getValueAsync`](/reference/api/typescript/aspire.hosting/referenceexpression/getvalueasync/ "Gets the value of the expression. The final string value after evaluating the format string and its parameters.") and supports conditional mode in multi-language code generation, which makes advanced hosting extensions easier to build without relying on synchronous value access patterns.

### Enhanced debugging experience

[Section titled “Enhanced debugging experience”](#enhanced-debugging-experience)

Several types now include `DebuggerDisplayAttribute` for better debugging:

* `DistributedApplication`
* Resource types
* `EndpointReferenceExpression`
* `ReferenceExpression`
* `PipelineStep`

This makes it easier to inspect your Aspire application state during debugging sessions.

### Resource event improvements

[Section titled “Resource event improvements”](#resource-event-improvements)

* Added `Logger` property to `IDistributedApplicationResourceEvent` for better logging context
* Improved `ResourceNotificationService.WaitFor` exception messages with more detailed information
* `BeforeResourceStartedEvent` now only fires when actually starting a resource (breaking change)

For more details on eventing, see [AppHost eventing APIs](/app-host/eventing/).

### Docker and container enhancements

[Section titled “Docker and container enhancements”](#docker-and-container-enhancements)

* The `Never` pull policy is exposed for scenarios that require local images.
* The Docker Compose Service class adds a `PullPolicy` property.
* Docker build secrets can now be files such as `.npmrc`, allowing private registry authentication without baking credentials into the image.
* The data volume path now supports PostgreSQL version 18 and later.

### Build improvements

[Section titled “Build improvements”](#build-improvements)

* Build error when `GenerateAssemblyInfo` is disabled in apphost projects
* Trailing commas now allowed in `launchSettings.json`
* JSON comments and trailing commas parsed without errors

### Contextual endpoint resolution

[Section titled “Contextual endpoint resolution”](#contextual-endpoint-resolution)

Aspire 13.2 introduces enhanced contextual endpoint resolution APIs that allow you to resolve endpoints from the perspective of specific resources or networks. This enables you to get the correct URL for a resource depending on where you’re accessing it from, whether it’s from a container, a host service, or a specific network.

The same resource can have different URLs depending on the context:

* From localhost: `http://localhost:1234`
* From a container on the host Docker network: `http://host.docker.internal:1234`
* From a container on the Aspire container network: `http://resource.dev.internal:4567`

#### Resolve from a specific resource (Caller)

[Section titled “Resolve from a specific resource (Caller)”](#resolve-from-a-specific-resource-caller)

You can resolve an endpoint URL from the perspective of a specific calling resource using the `Caller` property on `ValueProviderContext`:

Resolve endpoint from a resource's perspective

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var redis = builder.AddRedis("cache");
var containerApp = builder.AddContainer("worker", "myimage");


// Get the endpoint reference
var endpoint = redis.GetEndpoint("tcp");


// Resolve the URL from the container's perspective
var url = await endpoint.GetValueAsync(new ValueProviderContext {
    Caller = containerApp.Resource,
});


// The URL will be appropriate for container-to-container communication
// e.g., "redis:6379" or "cache:6379"
```

This is particularly useful when you need to pass connection information between resources that may be running in different contexts (containers vs. host processes).

#### Resolve from a specific network

[Section titled “Resolve from a specific network”](#resolve-from-a-specific-network)

You can also resolve an endpoint URL from the perspective of a specific network using the `Network` property on `ValueProviderContext`:

Resolve endpoint from a network's perspective

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var redis = builder.AddRedis("cache");


// Get the endpoint reference
var endpoint = redis.GetEndpoint("tcp");


// Resolve the URL for the default Aspire container network
var url = await endpoint.GetValueAsync(new ValueProviderContext {
    Network = KnownNetworkIdentifiers.DefaultAspireContainerNetwork
});


// The URL will be appropriate for the container network
// e.g., "cache:6379" using the resource name as the hostname
```

The `KnownNetworkIdentifiers` class provides predefined network identifiers:

* `LocalhostNetwork`: Resolves to localhost-based URLs
* `DefaultAspireContainerNetwork`: Resolves to container network URLs using resource names
* `PublicInternet`: Resolves to externally accessible URLs

These APIs existed in Aspire 13.1 but did not behave as expected. In Aspire 13.2, they correctly resolve endpoints based on the specified context.

For more details, see: - [GitHub Issue #7153](https://github.com/microsoft/aspire/issues/7153) - [GitHub PR #14278](https://github.com/microsoft/aspire/pull/14278) - [Context-based endpoint resolution](/architecture/resource-hierarchies/#context-based-endpoint-resolution)

## 📦 Integrations updates

[Section titled “📦 Integrations updates”](#-integrations-updates)

### Docker Compose publishing

[Section titled “Docker Compose publishing”](#docker-compose-publishing)

The Docker Compose publishing integration has moved from prerelease to a stable release in Aspire 13.2. When you add a Docker Compose environment to your app model, Aspire generates a `docker-compose.yaml` from your resources at publish time, making it easy to deploy your Aspire application to any environment that supports Docker Compose.

* C# AppHost

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddDockerComposeEnvironment("compose");


  builder.Build().Run();
  ```

* TypeScript AppHost

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder.addDockerComposeEnvironment("compose");


  await builder.build().run();
  ```

Aspire generates a complete `docker-compose.yaml` from the resources in your app model, including networking, volumes, and environment variables.

### Microsoft Foundry and hosted agents

[Section titled “Microsoft Foundry and hosted agents”](#microsoft-foundry-and-hosted-agents)

Aspire 13.2 replaces the earlier Azure AI Foundry-focused hosting surface with a broader Microsoft Foundry integration. The hosting package is now `Aspire.Hosting.Foundry`, replacing `Aspire.Hosting.Azure.AIFoundry`.

You can now add Foundry accounts, create Foundry Projects, attach model deployments with the generated `FoundryModel` catalog, and publish hosted agents from the regular Aspire app model:

* C# AppHost

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  var foundry = builder.AddFoundry("foundry");
  var project = foundry.AddProject("agents");


  var chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini);


  builder.AddPythonApp("agent", "..\\agent", "main:app")
      .WithReference(project)
      .WithReference(chat)
      .PublishAsHostedAgent(project);


  builder.Build().Run();
  ```

* TypeScript AppHost

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const foundry = await builder.addFoundry("foundry");
  const project = await foundry.addProject("agents");


  const chat = await project.addModelDeployment("chat", {
      name: "gpt-5-mini",
      version: "2025-06-01",
      format: "OpenAI",
  });


  await builder.addPythonApp("agent", "../agent", "main:app")
      .withReference(project)
      .withReference(chat)
      .withComputeEnvironment({ project });


  await builder.build().run();
  ```

New APIs in this area include [`AddProject`](/reference/api/csharp/aspire.hosting.foundry/azurecognitiveservicesprojectextensions/methods/#addproject "Adds a Microsoft Foundry project resource to the application model. This will also attach the project as a deployment target for agents.")[`addProject`](/reference/api/typescript/aspire.hosting.foundry/addproject/ "Adds a Microsoft Foundry project resource to the application model. This will also attach the project as a deployment target for agents."), [`AddModelDeployment`](/reference/api/csharp/aspire.hosting.foundry/azurecognitiveservicesprojectextensions/methods/#addmodeldeployment "Adds a model deployment to the parent Microsoft Foundry resource of the Microsoft Foundry project.")[`addModelDeployment`](/reference/api/typescript/aspire.hosting.foundry/addmodeldeployment/ "Adds a model deployment to the parent Microsoft Foundry resource."), [`WithAppInsights`](/reference/api/csharp/aspire.hosting.foundry/azurecognitiveservicesprojectextensions/methods/#withappinsights "Adds an Application Insights resource to the Microsoft Foundry project, overriding the default (which is to create a new Application Insights resource).")[`withAppInsights`](/reference/api/typescript/aspire.hosting.foundry/withappinsights/ "Adds an Application Insights resource to the Microsoft Foundry project, overriding the default (which is to create a new Application Insights resource)."), [`WithKeyVault`](/reference/api/csharp/aspire.hosting.foundry/azurecognitiveservicesprojectextensions/methods/#withkeyvault "Adds a Key Vault connection to the Microsoft Foundry project.")[`withKeyVault`](/reference/api/typescript/aspire.hosting.foundry/withkeyvault/ "Adds a Key Vault connection to the Microsoft Foundry project."), [`WithContainerRegistry`](/reference/api/csharp/aspire.hosting/containerregistryresourcebuilderextensions/methods/#withcontainerregistry "Configures the resource to use the specified container registry for container image operations.")[`withContainerRegistry`](/reference/api/typescript/aspire.hosting/withcontainerregistry/ "Configures the resource to use the specified container registry for container image operations."), `PublishAsHostedAgent`, and `AddAndPublishPromptAgent`. [`RunAsFoundryLocal`](/reference/api/csharp/aspire.hosting.foundry/foundryextensions/methods/#runasfoundrylocal "Configures a Microsoft Foundry resource to use an Aspire-managed Foundry Local service.")[`runAsFoundryLocal`](/reference/api/typescript/aspire.hosting.foundry/runasfoundrylocal/ "Configures a Microsoft Foundry resource to use an Aspire-managed or existing Foundry Local service.") is still available for local model development, but Foundry Projects aren’t supported when the parent resource is configured as Foundry Local.

Caution

This is a breaking change. `Aspire.Hosting.Azure.AIFoundry` has been replaced by `Aspire.Hosting.Foundry`. See the [Foundry package and namespace transition](#foundry-package-and-namespace-transition) in breaking changes for migration steps.

For more details, see [Microsoft Foundry integration](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/).

### Azure Virtual Network and private endpoint support

[Section titled “Azure Virtual Network and private endpoint support”](#azure-virtual-network-and-private-endpoint-support)

When deploying to Azure, securing network access to your resources is critical. The new `Aspire.Hosting.Azure.Network` integration lets you lock down your Azure resources by defining virtual networks, subnets, NAT gateways, network security groups (NSGs), and private endpoints directly in your apphost—ensuring your cloud infrastructure is secure by default.

AppHost.cs

```csharp
var vnet = builder.AddAzureVirtualNetwork("vnet");


// Add a subnet with NSG rules
var subnet = vnet.AddSubnet("web", "10.0.1.0/24")
    .AllowInbound(
        port: "443",
        from: AzureServiceTags.AzureLoadBalancer,
        protocol: SecurityRuleProtocol.Tcp)
    .DenyInbound(from: AzureServiceTags.Internet);


// Add a NAT gateway for deterministic outbound IPs
var natGateway = builder.AddNatGateway("nat");
subnet.WithNatGateway(natGateway);


// Add private endpoints for secure connectivity
var peSubnet = vnet.AddSubnet("private-endpoints", "10.0.2.0/27");
var storage = builder.AddAzureStorage("storage");
peSubnet.AddPrivateEndpoint(storage.AddBlobs("blobs"));
```

Key capabilities include:

* Create virtual networks with [`AddAzureVirtualNetwork`](/reference/api/csharp/aspire.hosting.azure.network/azurevirtualnetworkextensions/methods/#addazurevirtualnetwork "Adds an Azure Virtual Network resource to the application model.")[`addAzureVirtualNetwork`](/reference/api/typescript/aspire.hosting.azure.network/addazurevirtualnetwork/ "Adds an Azure Virtual Network resource to the application model.") and add subnets with [`AddSubnet`](/reference/api/csharp/aspire.hosting.azure.network/azurevirtualnetworkextensions/methods/#addsubnet "Adds an Azure Subnet to the Virtual Network.")[`addSubnet`](/reference/api/typescript/aspire.hosting.azure.network/addsubnet/ "Adds an Azure subnet resource to an Azure Virtual Network resource.").
* Provide deterministic outbound public IP addresses with [`AddNatGateway`](/reference/api/csharp/aspire.hosting.azure.network/azurenatgatewayextensions/methods/#addnatgateway "Adds an Azure NAT Gateway resource to the application model.")[`addNatGateway`](/reference/api/typescript/aspire.hosting.azure.network/addnatgateway/ "Adds an Azure NAT Gateway resource to the application model.") and [`WithNatGateway`](/reference/api/csharp/aspire.hosting.azure.network/azurevirtualnetworkextensions/methods/#withnatgateway "Associates a NAT Gateway with the subnet.")[`withNatGateway`](/reference/api/typescript/aspire.hosting.azure.network/withnatgateway/ "Associates a NAT Gateway with the subnet.").
* Control traffic with network security group shorthand methods ([`AllowInbound`](/reference/api/csharp/aspire.hosting.azure.network/azurevirtualnetworkextensions/methods/#allowinbound "Adds an inbound allow rule to the subnet's Network Security Group.")[`allowInbound`](/reference/api/typescript/aspire.hosting.azure.network/allowinbound/ "Adds an inbound allow rule to the subnet's Network Security Group."), [`DenyInbound`](/reference/api/csharp/aspire.hosting.azure.network/azurevirtualnetworkextensions/methods/#denyinbound "Adds an inbound deny rule to the subnet's Network Security Group.")[`denyInbound`](/reference/api/typescript/aspire.hosting.azure.network/denyinbound/ "Adds an inbound deny rule to the subnet's Network Security Group."), [`AllowOutbound`](/reference/api/csharp/aspire.hosting.azure.network/azurevirtualnetworkextensions/methods/#allowoutbound "Adds an outbound allow rule to the subnet's Network Security Group.")[`allowOutbound`](/reference/api/typescript/aspire.hosting.azure.network/allowoutbound/ "Adds an outbound allow rule to the subnet's Network Security Group."), [`DenyOutbound`](/reference/api/csharp/aspire.hosting.azure.network/azurevirtualnetworkextensions/methods/#denyoutbound "Adds an outbound deny rule to the subnet's Network Security Group.")[`denyOutbound`](/reference/api/typescript/aspire.hosting.azure.network/denyoutbound/ "Adds an outbound deny rule to the subnet's Network Security Group.")) or explicit [`AddNetworkSecurityGroup`](/reference/api/csharp/aspire.hosting.azure.network/azurenetworksecuritygroupextensions/methods/#addnetworksecuritygroup "Adds an Azure Network Security Group to the application model.")[`addNetworkSecurityGroup`](/reference/api/typescript/aspire.hosting.azure.network/addnetworksecuritygroup/ "Adds an Azure Network Security Group to the application model.") with [`WithSecurityRule`](/reference/api/csharp/aspire.hosting.azure.network/azurenetworksecuritygroupextensions/methods/#withsecurityrule "Adds a security rule to the Network Security Group.")[`withSecurityRule`](/reference/api/typescript/aspire.hosting.azure.network/withsecurityrule/ "Adds a security rule to the Network Security Group.").
* Connect securely to Azure services over private networks with [`AddPrivateEndpoint`](/reference/api/csharp/aspire.hosting.azure.network/azureprivateendpointextensions/methods/#addprivateendpoint "Adds an Azure Private Endpoint resource to the subnet.")[`addPrivateEndpoint`](/reference/api/typescript/aspire.hosting.azure.network/addprivateendpoint/ "Adds an Azure Private Endpoint resource to the subnet."), which automatically creates private DNS zones and virtual network links and disables public access on the target resource.

For more details, see [Azure Virtual Network integration](/integrations/cloud/azure/azure-virtual-network/).

### Azure AI and embedding support

[Section titled “Azure AI and embedding support”](#azure-ai-and-embedding-support)

The Azure AI Inference component now supports embeddings in addition to chat completions. You can register an `EmbeddingsClient` and then layer an `IEmbeddingGenerator>` on top of it:

Service project

```csharp
var builder = WebApplication.CreateBuilder(args);


builder.AddAzureEmbeddingsClient("embeddings")
    .AddEmbeddingGenerator();


var app = builder.Build();


app.MapGet("/embed", async (
    IEmbeddingGenerator> generator) =>
{
    var embedding = await generator.GenerateEmbeddingAsync("Hello, world!");
    return embedding.Vector.ToArray();
});
```

Keyed embeddings are also supported with `AddKeyedEmbeddingGenerator`.

For more details, see [Azure AI Inference integration](/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started/).

### Azure App Service enhancements

[Section titled “Azure App Service enhancements”](#azure-app-service-enhancements)

* Deployment slot support with new extension methods
* Sticky slot app settings fixes
* Configuration naming improvements
* `SearchIndexerClient` added as an extension method for Azure Search

For more details, see [Azure App Service integration](/integrations/cloud/azure/azure-app-service/azure-app-service-get-started/).

### Azure Container Registry

[Section titled “Azure Container Registry”](#azure-container-registry)

The Azure Container Registry integration now supports scheduled image cleanup with the new [`WithPurgeTask`](/reference/api/csharp/aspire.hosting.azure.containerregistry/azurecontainerregistryextensions/methods/#withpurgetask "Adds a scheduled ACR purge task to remove old or unused container images from the registry.")[`withPurgeTask`](/reference/api/typescript/aspire.hosting.azure.containerregistry/withpurgetask/ "Adds a scheduled ACR purge task to remove old or unused container images from the registry.") method. This provisions an [ACR purge task](https://learn.microsoft.com/azure/container-registry/container-registry-auto-purge) that automatically removes old or unused container images on a cron schedule:

Schedule ACR image cleanup

```csharp
var acr = builder.AddAzureContainerRegistry("my-acr")
    .WithPurgeTask("0 1 * * *", ago: TimeSpan.FromDays(7), keep: 5);
```

Additionally, the new [`GetAzureContainerRegistry`](/reference/api/csharp/aspire.hosting.azure.containerregistry/azurecontainerregistryextensions/methods/#getazurecontainerregistry "Gets the Aspire.Hosting.Azure.AzureContainerRegistryResource associated with the specified Azure compute environment resource.")[`getAzureContainerRegistry`](/reference/api/typescript/aspire.hosting.azure.containerregistry/getazurecontainerregistry/ "Gets the Azure Container Registry associated with a compute environment resource.") method makes it easy to access the registry from a compute environment for further configuration.

For more details, see [Azure Container Registry integration](/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started/).

### Azure Data Lake Storage integration

[Section titled “Azure Data Lake Storage integration”](#azure-data-lake-storage-integration)

Aspire 13.2 adds both hosting and client-side support for Azure Data Lake Storage. This closes an important gap for teams using hierarchical namespace storage and gives Data Lake users the usual Aspire integration benefits: DI registration, retries, health checks, logging, and telemetry.

* C# AppHost

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  var api = builder.AddProject("api");
  var storage = builder.AddAzureStorage("storage");
  var dataLake = storage.AddDataLake("data-lake");
  var fileSystem = storage.AddDataLakeFileSystem("data-lake-file-system");


  api.WithReference(dataLake)
     .WaitFor(dataLake)
     .WithReference(fileSystem)
     .WaitFor(fileSystem);
  ```

* TypeScript AppHost

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const api = await builder.addProject("api", "../api");
  const storage = await builder.addAzureStorage("storage");
  const dataLake = await storage.addDataLake("data-lake");
  const fileSystem = await storage.addDataLakeFileSystem("data-lake-file-system");


  await api.withReference(dataLake)
     .waitFor(dataLake)
     .withReference(fileSystem)
     .waitFor(fileSystem);
  ```

Service project

```csharp
builder.AddAzureDataLakeServiceClient("data-lake");
builder.AddAzureDataLakeFileSystemClient("data-lake-file-system");
```

For more details, see [Azure Data Lake Storage](/integrations/cloud/azure/azure-storage-datalake/).

### Database integrations

[Section titled “Database integrations”](#database-integrations)

* MongoDB connection string options now correctly prepend a forward slash.
* The new [`Aspire.MongoDB.EntityFrameworkCore` client integration](/integrations/databases/efcore/mongodb/mongodb-efcore-get-started/) adds Entity Framework Core support for MongoDB.
* Oracle EF Core adds multi-targeting support.
* SQL Server adds new `Aspire.Hosting.SqlServer` exports.

The new MongoDB EF Core provider makes it easier to use EF Core with MongoDB while keeping the normal Aspire enrichment experience:

Service project

```csharp
builder.AddMongoDbContext("mongodb", databaseName: "appdb");
```

If you register the `DbContext` yourself, you can still opt into Aspire instrumentation and health features with `EnrichMongoDbContext()`.

### JavaScript hosting with Bun

[Section titled “JavaScript hosting with Bun”](#javascript-hosting-with-bun)

JavaScript resources can now opt into Bun as their package manager with [`WithBun`](/reference/api/csharp/communitytoolkit.aspire.hosting.mcpinspector/mcpinspectorresourcebuilderextensions/methods/#withbun "Configures the MCP Inspector to use bun as the package manager.")[`withBun`](/reference/api/typescript/communitytoolkit.aspire.hosting.mcpinspector/withbun/ "Configures the MCP Inspector to use bun as the package manager."). Aspire configures the right package-manager annotations, install behavior, and container build image defaults for Bun-backed applications. This release also fixes reliability issues when using Yarn with [`AddViteApp`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#addviteapp "Adds a Vite app to the distributed application builder.")[`addViteApp`](/reference/api/typescript/aspire.hosting.javascript/addviteapp/ "Adds a Vite app to the distributed application builder.") via [`WithYarn`](/reference/api/csharp/communitytoolkit.aspire.hosting.mcpinspector/mcpinspectorresourcebuilderextensions/methods/#withyarn "Configures the MCP Inspector to use yarn as the package manager.")[`withYarn`](/reference/api/typescript/communitytoolkit.aspire.hosting.mcpinspector/withyarn/ "Configures the MCP Inspector to use yarn as the package manager.").

* C# AppHost

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddViteApp("frontend", "./frontend")
      .WithBun()
      .WithDockerfileBaseImage(buildImage: "oven/bun:latest");


  builder.Build().Run();
  ```

* TypeScript AppHost

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder.addViteApp("frontend", "./frontend")
      .withBun()
      .withDockerfileBaseImage({ buildImage: "oven/bun:latest" });


  await builder.build().run();
  ```

For more details, see the [Bun integration](/integrations/frameworks/bun-apps/) docs.

### Emulator updates

[Section titled “Emulator updates”](#emulator-updates)

* Azure ServiceBus emulator updated to 2.0.0
* Azure App Configuration emulator updated to 1.0.2
* CosmosDB preview emulator readiness check added
* Azure Managed Redis now uses `rediss://` as the default scheme
* Multiple Azurite storage accounts now supported with [`RunAsEmulator`](/reference/api/csharp/aspire.hosting.azure.storage/azurestorageextensions/methods/#runasemulator "Configures an Azure Storage resource to be emulated using Azurite. This resource requires an Aspire.Hosting.Azure.AzureStorageResource to be added to the...")[`runAsEmulator`](/reference/api/typescript/aspire.hosting.azure.storage/runasemulator/ "Configures the Azure Storage resource to be emulated using Azurite")

### AI model updates

[Section titled “AI model updates”](#ai-model-updates)

* Microsoft Foundry models automatically updated
* GitHub models updated
* AI model code generation now converts markdown to C# XML docs

## 🚀 Deployment and publishing

[Section titled “🚀 Deployment and publishing”](#-deployment-and-publishing)

### Kubernetes improvements

[Section titled “Kubernetes improvements”](#kubernetes-improvements)

* YAML publishing fixes for Kubernetes deployments
* Better handling of resources with [`ExcludeFromManifest`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#excludefrommanifest "Excludes a resource from being published to the manifest.")[`excludeFromManifest`](/reference/api/typescript/aspire.hosting/excludefrommanifest/ "Excludes a resource from being published to the manifest.")

### Azure deployment

[Section titled “Azure deployment”](#azure-deployment)

* Container Registry exposed from compute environments
* Improved handling of environment normalization in Azure App Service
* Better error messages for deployment failures
* Better waiting for Azure role assignments and private endpoints during provisioning
* Markdown support in publish and deploy pipeline summaries
* Azure portal links in pipeline summaries for the resource group
* Better multi-language export coverage for Azure integrations such as Cosmos DB and AppContainers

### Pipeline enhancements

[Section titled “Pipeline enhancements”](#pipeline-enhancements)

* Pipeline summary info displayed after successful completion
* Environment name validation in deployment state manager
* Deployment directory permissions restricted to current user

## 🐛 Bug fixes

[Section titled “🐛 Bug fixes”](#-bug-fixes)

This release includes numerous bug fixes across all areas:

* Fixed DCP path creation for AppHostServer
* Fixed dashboard URL port logging for randomized ports
* Fixed Windows startup error with AUX reserved device name
* Fixed race condition in RabbitMQEventSourceListener
* Fixed certificate serial number generation
* Fixed resource logger service disposal and memory leaks
* Fixed various GenAI tool definition parsing issues
* Improved search highlight contrast in CLI interactive prompts
* Fixed tooltip for view options button in resource details panel

## ⚠️ Breaking changes

[Section titled “⚠️ Breaking changes”](#️-breaking-changes)

### Service discovery environment variable naming

[Section titled “Service discovery environment variable naming”](#service-discovery-environment-variable-naming)

Service discovery environment variables now use the endpoint **scheme** instead of the endpoint **name**:

Before (13.0/13.1)

```csharp
// services__myservice__myendpoint__0 = https://localhost:5001
```

After (13.2)

```csharp
// services__myservice__https__0 = https://localhost:5001
```

This improves consistency when endpoints share the same scheme. If you have code or configuration that depends on specific endpoint name patterns in service discovery environment variables, update it to use scheme-based patterns instead.

### Consolidated configuration files

[Section titled “Consolidated configuration files”](#consolidated-configuration-files)

Aspire now prefers `aspire.config.json` over the older split configuration model.

New scaffolds and updated tooling write unified configuration there, and launch profiles that used to live in `apphost.run.json` are merged into the same file. Legacy files are still read during migration, but if you have custom automation that edits `.aspire/settings.json` or `apphost.run.json` directly, plan to move that logic to `aspire.config.json`.

### Resource command rename

[Section titled “Resource command rename”](#resource-command-rename)

Built-in resource commands now use the shorter names `start`, `stop`, and `restart`.

If you scripted command names directly, migrate away from `resource-start`, `resource-stop`, and `resource-restart`:

Aspire CLI — Updated resource commands

```bash
aspire resource api start
aspire resource api stop
aspire resource api restart
```

Note

`--apphost` is also now the preferred option name across commands, although the legacy `--project` alias is still accepted for compatibility.

### Dashboard telemetry API now opt-in

[Section titled “Dashboard telemetry API now opt-in”](#dashboard-telemetry-api-now-opt-in)

The standalone dashboard now defaults its HTTP API to off.

If you host the dashboard directly and rely on the API, enable it explicitly by setting `ASPIRE_DASHBOARD_API_ENABLED=true` or by supplying equivalent configuration:

Dashboard configuration

```json
{
  "Dashboard": {
    "Api": {
      "Enabled": true
    }
  }
}
```

Note

AppHost-integrated dashboard scenarios continue to work because Aspire.Hosting enables the dashboard API when it wires the dashboard up for CLI and tooling integration.

### `BeforeResourceStartedEvent` behavior

[Section titled “BeforeResourceStartedEvent behavior”](#beforeresourcestartedevent-behavior)

The `BeforeResourceStartedEvent` now only fires when actually starting a resource, not on every state change. Update your event handlers if they rely on the previous behavior.

### Connection property suffix

[Section titled “Connection property suffix”](#connection-property-suffix)

Several connection properties for “named entity” resources gained an explicit `Name` suffix so the property clearly refers to the entity’s name rather than the entity itself. This affects both the connection-property API ([`GetConnectionProperty`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#getconnectionproperty "Retrieves the value of a specified connection property from the resource's connection properties.")[`getConnectionProperty`](/reference/api/typescript/aspire.hosting/getconnectionproperty/ "Retrieves the value of a specified connection property from the resource's connection properties.")) and the environment variables Aspire injects via [`WithReference`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withreference "Injects a connection string as an environment variable from the source resource into the destination resource, using the source resource's name as the...")[`withReference`](/reference/api/typescript/aspire.hosting/withreference/ "Adds a reference to another resource") and `ReferenceEnvironmentInjectionFlags.ConnectionProperties`.

A subset of these renames first shipped in [13.1](/whats-new/aspire-13-1/#connection-properties-rename); 13.2 completes the rollout across the remaining built-in resources, so apps upgrading directly from 13.0 to 13.2 encounter all of them at once. The full list of renamed properties as of 13.2 is:

| Old property name | New property name   | Affected resources                                                                                                                                                                                                                 |
| ----------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Database`        | `DatabaseName`      | `PostgresDatabase`, `AzurePostgresFlexibleServerDatabase`, `MySqlDatabase`, `SqlServerDatabase`, `AzureSqlDatabase`, `OracleDatabase`, `MongoDBDatabase`, `MilvusDatabase`, `AzureCosmosDBDatabase`, `AzureKustoReadWriteDatabase` |
| `Model`           | `ModelName`         | `OpenAIModel`, `AzureOpenAIDeployment`, `FoundryDeployment`, `GitHubModel`                                                                                                                                                         |
| `ConsumerGroup`   | `ConsumerGroupName` | `AzureEventHubConsumerGroup`                                                                                                                                                                                                       |

When Aspire injects a connection property with the `[RESOURCE]_[PROPERTY]` pattern, it transforms the two parts differently. For the resource-name prefix, Aspire replaces each character that isn’t an ASCII letter or digit with an underscore, prefixes an underscore when the name starts with a digit, and uppercases the result. For the property suffix, Aspire only uppercases the property key. Any consuming app that reads the renamed properties from the environment must use the new names. For example, a SQL Server database resource named `sqldb`:

Environment variable

```diff
SQLDB_DATABASE=catalog
SQLDB_DATABASENAME=catalog
```

For an Event Hubs consumer group resource named `orders-cg`, the resource-name encoder produces `ORDERS_CG`; separately, uppercasing the `ConsumerGroupName` property key produces `CONSUMERGROUPNAME`. Aspire joins them as `ORDERS_CG_CONSUMERGROUPNAME`.

Update consuming app code that reads the variable directly:

* C#

  Read injected connection property

  ```diff
  -var database = Environment.GetEnvironmentVariable("SQLDB_DATABASE");
  +var database = Environment.GetEnvironmentVariable("SQLDB_DATABASENAME");
  ```

* Python

  Read injected connection property

  ```diff
  -database = os.getenv("SQLDB_DATABASE")
  +database = os.getenv("SQLDB_DATABASENAME")
  ```

* TypeScript

  Read injected connection property

  ```diff
  -const database = process.env.SQLDB_DATABASE;
  +const database = process.env.SQLDB_DATABASENAME;
  ```

* Go

  Read injected connection property

  ```diff
  -database := os.Getenv("SQLDB_DATABASE")
  +database := os.Getenv("SQLDB_DATABASENAME")
  ```

If your AppHost code reads connection properties through the `IResourceWithConnectionString` API, update those calls as well:

AppHost.cs

```diff
-var database = sqldb.Resource.GetConnectionProperty("Database");
+var database = sqldb.Resource.GetConnectionProperty("DatabaseName");
```

To migrate, search your solution for the affected uppercase environment variable names (for example, `_DATABASE`, `_MODEL`, and `_CONSUMERGROUP`) along with `GetConnectionProperty("Database")`, `GetConnectionProperty("Model")`, and `GetConnectionProperty("ConsumerGroup")`, and apply the rename. Also update any custom Bicep, Helm, or other deployment templates that hard-code the old property keys when emitting connection metadata. Properties not listed in the table — for example, `Endpoint`, `Host`, `Port`, `Username`, `Password`, `Uri`, and `Key` — are unchanged.

C# apps that consume the Aspire client integrations (for example, `AddNpgsqlDataSource`, `AddAzureOpenAIClient`, or `AddMongoDBClient`) don’t need source changes. Those packages resolve the connection string through `ConnectionStrings:`, which is unaffected by this rename.

Note

Properties that don’t refer to a named entity were not renamed. For example, the `AuthenticationDatabase` property on `MongoDBServerResource` and the `Organization` property on `GitHubModelResource` keep their existing names.

For the full per-resource property catalog, see the Connection properties section on each integration’s *connect* page — for example, [Connect to Azure Cosmos DB](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-connect/#connection-properties) or [Connect to SQL Server](/integrations/databases/sql-server/sql-server-connect/#connection-properties).

### Foundry package and namespace transition

[Section titled “Foundry package and namespace transition”](#foundry-package-and-namespace-transition)

Aspire 13.2 standardizes the Foundry hosting surface under `Aspire.Hosting.Foundry`.

| Previous 13.1 name                                   | 13.2 name                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hosting package: `Aspire.Hosting.Azure.AIFoundry`    | Hosting package: `Aspire.Hosting.Foundry`                                                                                                                                                                                                                                                                  |
| Resource and model namespace: `Aspire.Hosting.Azure` | Resource and model namespace: `Aspire.Hosting.Foundry`                                                                                                                                                                                                                                                     |
| `AddAzureAIFoundry(...)`                             | [`AddFoundry`](/reference/api/csharp/aspire.hosting.foundry/foundryextensions/methods/#addfoundry "Adds a Microsoft Foundry resource to the application model.")[`addFoundry`](/reference/api/typescript/aspire.hosting.foundry/addfoundry/ "Adds a Microsoft Foundry resource to the application model.") |
| `AzureAIFoundryResource`                             | `FoundryResource`                                                                                                                                                                                                                                                                                          |
| `AzureAIFoundryExtensions`                           | `FoundryExtensions`                                                                                                                                                                                                                                                                                        |
| `AzureAIFoundryDeploymentResource`                   | `FoundryDeploymentResource`                                                                                                                                                                                                                                                                                |
| `AIFoundryModel`                                     | `FoundryModel`                                                                                                                                                                                                                                                                                             |

Migration tip: update your package reference, add `using Aspire.Hosting.Foundry;` for direct resource or model type references, and rename `AddAzureAIFoundry(...)` to `AddFoundry(...)`. Remove `using Aspire.Hosting.Azure;` only if your code no longer uses other types from that namespace. Extension methods remain in the `Aspire.Hosting` namespace.

XML — AppHost project file

```xml

  

```

C# — Migration example

```csharp
// Before
var ai = builder.AddAzureAIFoundry("ai");


// After
var foundry = builder.AddFoundry("ai");
var project = foundry.AddProject("agents");
var chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini);
```

This aligns the hosting API with the current Foundry branding and unlocks the new project, deployment, and hosted-agent capabilities added in new Microsoft Foundry releases.

### `WithSecretBuildArg` renamed to `WithBuildSecret`

[Section titled “WithSecretBuildArg renamed to WithBuildSecret”](#withsecretbuildarg-renamed-to-withbuildsecret)

The container build secret API was renamed for clarity:

Migration example

```csharp
// Before
builder.AddContainer("worker", "contoso/worker")
    .WithDockerfile("../worker")
    .WithSecretBuildArg("ACCESS_TOKEN", accessToken);


// After
builder.AddContainer("worker", "contoso/worker")
    .WithDockerfile("../worker")
    .WithBuildSecret("ACCESS_TOKEN", accessToken);
```

If you only used the old name through shared helpers or extension methods, this is usually a straightforward rename.

### `IAzureContainerRegistry` obsolete

[Section titled “IAzureContainerRegistry obsolete”](#iazurecontainerregistry-obsolete)

The `IAzureContainerRegistry` interface has been marked as obsolete. Use the new `ContainerRegistry` property on compute environments instead.

### Default Azure credential behavior in client integrations

[Section titled “Default Azure credential behavior in client integrations”](#default-azure-credential-behavior-in-client-integrations)

Aspire Azure client integrations no longer use the parameterless `DefaultAzureCredential` constructor. This is a breaking change for anyone depending on credentials other than `ManagedIdentityCredential` working in an Azure service. For more information on the new behavior, see [Default Azure credential](/integrations/cloud/azure/azure-default-credential/).

## ⬆️ Upgrade today

[Section titled “⬆️ Upgrade today”](#️-upgrade-today)

Follow the directions in [Upgrade to Aspire 13.2](#upgrade-to-aspire-13-2) to move forward and start using the new CLI, TypeScript apphost, dashboard, hosting, and integration capabilities in this release.

For a complete list of issues addressed in this release, see the [Aspire 13.2 milestone on GitHub](https://github.com/microsoft/aspire/issues?q=is%3Aissue%20state%3Aclosed%20milestone%3A13.2). As always, we want to share a huge thank you to all our community contributors who filed issues, submitted pull requests, and helped shape this release — Aspire is better because of you.

## Aspire 13.2.1

[Section titled “Aspire 13.2.1”](#aspire-1321)

Aspire 13.2.1 is a patch release focused on reliability fixes.

### Breaking changes in the TypeScript AppHost SDK

[Section titled “Breaking changes in the TypeScript AppHost SDK”](#breaking-changes-in-the-typescript-apphost-sdk)

The following TypeScript AppHost APIs were renamed. Update any affected `apphost.mts` files accordingly:

| Previous name                                          | New name                                     | Notes                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runAsExistingFromParameters(name, resourceGroup)`     | `runAsExisting(name, { resourceGroup })`     | Name change plus positional → options object.                                                                                                                                                                                                                                                                                                                         |
| `publishAsExistingFromParameters(name, resourceGroup)` | `publishAsExisting(name, { resourceGroup })` | Name change plus positional → options object.                                                                                                                                                                                                                                                                                                                         |
| `withConnectionPropertyValue(name, value)`             | `withConnectionProperty(name, value)`        | Unified API for string/reference values.                                                                                                                                                                                                                                                                                                                              |
| `withParameterBuildArg(name, parameter)`               | `withBuildArg(name, parameter)`              | Renamed to the unified [`WithBuildArg`](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods/#withbuildarg "Adds a build argument when the container is build from a Dockerfile.")[`withBuildArg`](/reference/api/typescript/aspire.hosting/withbuildarg/ "Adds a build argument when the container is built from a Dockerfile.") surface. |

Note

`withConnectionPropertyValue` is still available as a compatibility alias in the generated SDKs, so it is not a runtime SDK break.

## 🙏 Community

[Section titled “🙏 Community”](#-community)

Aspire is built in the open, and this release wouldn’t be what it is without you. A huge thank you to everyone who helped make Aspire 13.2 possible.

### The Aspire core team is

* [![Adam Ratzman](https://github.com/adamint.png?size=96)Adam Ratzman](https://github.com/adamint)
* [![Ankit Jain](https://github.com/radical.png?size=96)Ankit Jain](https://github.com/radical)
* [![Damian Edwards](https://github.com/DamianEdwards.png?size=96)Damian Edwards](https://github.com/DamianEdwards)
* [![David Fowler](https://github.com/davidfowl.png?size=96)David Fowler](https://github.com/davidfowl)
* [![David Negstad](https://github.com/danegsta.png?size=96)David Negstad](https://github.com/danegsta)
* [![David Pine](https://github.com/IEvangelist.png?size=96)David Pine](https://github.com/IEvangelist)
* [![Ella Hathaway](https://github.com/ellahathaway.png?size=96)Ella Hathaway](https://github.com/ellahathaway)
* [![Eric Erhardt](https://github.com/eerhardt.png?size=96)Eric Erhardt](https://github.com/eerhardt)
* [![James Newton-King](https://github.com/JamesNK.png?size=96)James Newton-King](https://github.com/JamesNK)
* [![José Pérez](https://github.com/joperezr.png?size=96)José Pérez](https://github.com/joperezr)
* [![Karol Zadora-Przylecki](https://github.com/karolz-ms.png?size=96)Karol Zadora-Przylecki](https://github.com/karolz-ms)
* [![Maddy Montaquila](https://github.com/maddymontaquila.png?size=96)Maddy Montaquila](https://github.com/maddymontaquila)
* [![Mitch Denny](https://github.com/mitchdenny.png?size=96)Mitch Denny](https://github.com/mitchdenny)
* [![Sébastien Ros](https://github.com/sebastienros.png?size=96)Sébastien Ros](https://github.com/sebastienros)

Special thanks to everyone whose pull requests shipped in Aspire 13.2, including:

[@abdallahsellem](https://github.com/abdallahsellem), [@aelij](https://github.com/aelij), [@afscrome](https://github.com/afscrome), [@akoeplinger](https://github.com/akoeplinger), [@askpt](https://github.com/askpt), [@bart-vmware](https://github.com/bart-vmware), [@bbartels](https://github.com/bbartels), [@captainsafia](https://github.com/captainsafia), [@danspark](https://github.com/danspark), [@dkattan](https://github.com/dkattan), [@emilienbev](https://github.com/emilienbev), [@EmmittJ](https://github.com/EmmittJ), [@ericsuh](https://github.com/ericsuh), [@GryBsh](https://github.com/GryBsh), [@kieronlanning](https://github.com/kieronlanning), [@Kumima](https://github.com/Kumima), [@licon4812](https://github.com/licon4812), [@marcfreiheit](https://github.com/marcfreiheit), [@Marcus-Kanon](https://github.com/Marcus-Kanon), [@marshalhayes](https://github.com/marshalhayes), [@Meir017](https://github.com/Meir017), [@mmitche](https://github.com/mmitche), [@Muckenbatscher](https://github.com/Muckenbatscher), [@pvanbuijtene](https://github.com/pvanbuijtene), [@romansp](https://github.com/romansp), [@rynowak](https://github.com/rynowak), [@scottaddie](https://github.com/scottaddie), [@ShilpiRach](https://github.com/ShilpiRach), [@sliekens](https://github.com/sliekens), [@spboyer](https://github.com/spboyer), [@vhvb1989](https://github.com/vhvb1989), [@vsantele](https://github.com/vsantele), [@wahab-cide](https://github.com/wahab-cide), [@wicksipedia](https://github.com/wicksipedia), and [@zhiyuanliang-ms](https://github.com/zhiyuanliang-ms)

We're always excited to [see community contributions](/community/contributors/)! If you'd like to get involved, check out our [contributing guide](/community/contributor-guide/).

# What's new in Aspire 13.3

> Explore Aspire 13.3: aspire destroy, Helm-based Kubernetes deploy, browser screenshot capture, JavaScript publishing, default container tunnel, and Azure updates.

Aspire 13.3 expands deployment and observability with `aspire destroy`, browser telemetry and screenshots, preview Kubernetes deployment through a Helm engine, and first-class JavaScript publishing. It also enables the container tunnel by default and brings TypeScript AppHosts closer to C# parity.

We’d love to hear what you think. Drop by [ Discord](https://aka.ms/aspire-discord) to chat with the team and the community, or file feedback and issues on [ GitHub](https://github.com/microsoft/aspire/issues).

This release introduces:

* The new `aspire destroy` command tears down provisioned resources across Azure, Kubernetes, and Compose, while `aspire dashboard` runs the dashboard standalone. The Aspire CLI is also now available as a `dotnet tool`.
* The new `Aspire.Hosting.Browsers` integration captures frontend console logs, network requests, and screenshots and surfaces them in the dashboard next to server-side telemetry.
* Preview support for `aspire deploy` to Kubernetes generates a Helm chart and runs an end-to-end deployment pipeline from an [`AddKubernetesEnvironment`](/reference/api/csharp/aspire.hosting.kubernetes/kubernetesenvironmentextensions/methods/#addkubernetesenvironment "Adds a Kubernetes environment to the application model.")[`addKubernetesEnvironment`](/reference/api/typescript/aspire.hosting.kubernetes/addkubernetesenvironment/ "Adds a Kubernetes environment to the application model."). New Ingress and Gateway API routing resources describe traffic at the AppHost level.
* Preview JavaScript publish methods provide a unified `PublishAs*` family for static SPAs, SSR Node servers, and npm-script-based deployments, plus the new [`AddNextJsApp`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#addnextjsapp "Adds a Next.js app to the distributed application builder.")[`addNextJsApp`](/reference/api/typescript/aspire.hosting.javascript/addnextjsapp/ "Adds a Next.js app to the distributed application builder.") helper and first-class support for Bun, Yarn, and pnpm.
* The container tunnel is enabled by default, providing uniform host connectivity across Docker Desktop, Docker Engine, and Podman.
* TypeScript AppHost improvements close most of the remaining gap with C# AppHosts.
* The preview `aspire init` command bootstraps an AppHost into an existing repository with the new `aspireify` agent skill.
* New hosting integrations support Azure Front Door, Network Security Perimeter, and Azure Kubernetes Service (AKS). This release also adds Foundry Prompt Agent support.
* …and much more.

## 🆙 Upgrade to Aspire 13.3

[Section titled “🆙 Upgrade to Aspire 13.3”](#-upgrade-to-aspire-133)



Caution

Aspire 13.3 includes several breaking changes — most notably the rename of `--log-level` to `--pipeline-log-level`, the removal of the dashboard MCP server, and renames in Azure Network resources and AKS SKU APIs. Please review the [Breaking changes](#breaking-changes) section before upgrading.

If your Aspire CLI version is earlier than 13, first [install the latest stable version](/get-started/install-cli/).

For general purpose upgrade guidance, see [Upgrade Aspire](/whats-new/upgrade-aspire/).

The easiest way to upgrade to Aspire 13.3 is using the [`aspire update` command](/reference/cli/commands/aspire-update/):

1. Update the Aspire CLI itself:

   Aspire CLI — Update the CLI

   ```bash
   aspire update --self
   ```

2. Update your projects (run from the root of your repository):

   Aspire CLI — Update all Aspire packages

   ```bash
   aspire update
   ```

Or install the CLI from scratch:

* Bash

  Aspire CLI — Install Aspire CLI

  ```bash
  curl -sSL https://aspire.dev/install.sh | bash
  ```

* PowerShell

  Aspire CLI — Install Aspire CLI

  ```powershell
  irm https://aspire.dev/install.ps1 | iex
  ```

For more details on installing the Aspire CLI, see [Install the CLI](/get-started/install-cli/).

## 🛠️ CLI enhancements

[Section titled “🛠️ CLI enhancements”](#️-cli-enhancements)

### Aspire CLI as a NativeAOT dotnet tool

[Section titled “Aspire CLI as a NativeAOT dotnet tool”](#aspire-cli-as-a-nativeaot-dotnet-tool)

Aspire 13.3 publishes the Aspire CLI as a NativeAOT .NET global tool. The CLI has always shipped as a `dotnet tool`, but in 13.3 it takes advantage of new .NET 10 support for distributing NativeAOT-compiled tools — meaning instant startup with no JIT or runtime warmup, and no managed runtime dependency in the tool package. If you already have .NET 10 installed, you can install the CLI without using the curl/PowerShell installer:

Install via dotnet tool

```bash
dotnet tool install -g Aspire.Cli
```

For more details, see [Install the Aspire CLI](/get-started/install-cli/).

### `aspire dashboard` for the standalone dashboard

[Section titled “aspire dashboard for the standalone dashboard”](#aspire-dashboard-for-the-standalone-dashboard)

The new `aspire dashboard` command runs the Aspire Dashboard in standalone mode (without an AppHost), making it easy to consume telemetry from any OTLP-emitting application — your own services, third-party tools, or apps running outside the Aspire app model.

Previously, the only way to run the dashboard outside an AppHost was to pull the [standalone container image](/dashboard/standalone/) and configure ports, certificates, and the OTLP endpoint by hand. With `aspire dashboard run`, the CLI handles all of that for you using the same dashboard binary that ships with the SDK — no Docker or container runtime required.

Aspire CLI — Run the standalone dashboard

```bash
aspire dashboard run
```

Output

```text
   Dashboard:  http://localhost:18888/login?t=a360442eeb99c38fe60954dc4f045acc


   OTLP/gRPC:  http://localhost:4317


   OTLP/HTTP:  http://localhost:4318


        Logs:  ~/.aspire/logs/cli_20260506T065505_02e43b93.log
```

The command is interactive and blocking — it stays in the foreground while the dashboard is running. Open the Dashboard URL in your browser, then point any OTLP-compatible application at the OTLP/gRPC or OTLP/HTTP endpoint, and your logs, traces, and metrics show up live. The container image is still available for environments where running the CLI isn’t an option.

Command reference: [`aspire dashboard`](/reference/cli/commands/aspire-dashboard/) and [Standalone dashboard](/dashboard/standalone/).

### `aspire docs api` — API reference search from the CLI

[Section titled “aspire docs api — API reference search from the CLI”](#aspire-docs-api--api-reference-search-from-the-cli)

Search and read the Aspire API reference directly from the terminal:

Aspire CLI — Search and view API docs

```bash
aspire docs api list typescript
aspire docs api search "WithReference"
aspire docs api get typescript/aspire.hosting/withreference
```

Command references: [`aspire docs api list`](/reference/cli/commands/aspire-docs-api-list/), [`aspire docs api search`](/reference/cli/commands/aspire-docs-api-search/), and [`aspire docs api get`](/reference/cli/commands/aspire-docs-api-get/).

### Connect the CLI to a standalone dashboard

[Section titled “Connect the CLI to a standalone dashboard”](#connect-the-cli-to-a-standalone-dashboard)

The `aspire otel logs` and `aspire otel traces` commands now accept `--dashboard-url` and `--api-key` options, so you can query telemetry from a [standalone dashboard](/dashboard/standalone/) without launching an AppHost.

Either start the dashboard with `aspire dashboard run` or run the dashboard from the dashboard’s container image, then point the CLI at it:

Aspire CLI — Query a standalone dashboard

```bash
# Stream structured logs from a standalone dashboard
aspire otel logs --dashboard-url https://localhost:18888/login?t=TOKEN -f


# Search recent traces in a standalone dashboard
aspire otel traces --dashboard-url https://localhost:18888/login?t=TOKEN
```

`--dashboard-url` accepts either the dashboard’s base URL or a login URL — login URLs are normalized automatically.

### `aspire init` installs the `aspireify` agent skill

[Section titled “aspire init installs the aspireify agent skill”](#aspire-init-installs-the-aspireify-agent-skill)

Note

The new `aspire init` flow is in **preview** in 13.3.

`aspire init` now drops a minimal AppHost skeleton and an `aspire.config.json` file into an existing repository, and installs the aspireify agent skill alongside it. `aspire init` itself does not wire up resources, projects, or integrations — you complete the wiring by invoking the `aspireify` skill from your AI agent of choice (GitHub Copilot CLI, Claude Code, etc.).

Caution

This is a behavior change from prior releases — `aspire init` no longer fully wires up your AppHost on its own. See [`aspire init`](/reference/cli/commands/aspire-init/) for the new flow.

### Hidden resources are filtered by default

[Section titled “Hidden resources are filtered by default”](#hidden-resources-are-filtered-by-default)

`aspire ps`, `aspire describe`, and other CLI commands now hide resources that are marked as hidden in the AppHost (such as proxies, helper containers, and migrations). Use `--include-hidden` to include them.

### Pipeline step summary

[Section titled “Pipeline step summary”](#pipeline-step-summary)

At the end of `aspire do`, `aspire publish`, `aspire deploy`, and `aspire destroy` runs, the CLI now prints a summary of pipeline execution steps, showing which steps ran, their duration, and whether they succeeded or failed.

This makes it easy to identify bottlenecks, spot which step failed in a multi-step pipeline, and understand the overall execution flow at a glance — especially useful in CI/CD environments where you need to quickly triage deployment failures without digging through verbose logs.

Output

```text
------------------------------------------------------------
✅ 5/5 steps succeeded • Total time: 0.43s


Steps Summary:
                Step timeline:                 0s                       0.41s
                                               │───────┬──────┬─────┬───────│
      0.73ms  ✓ validate-compute-environments  │╴                           │
      0.21ms  ✓   before-start                 │╴                           │
       0.41s  ✓ pipeline-execution             │╶──────────────────────────╴│
       0.41s  ✓ custom-deploy-prereq           │╶──────────────────────────╴│
      0.33ms  ✓   deploy                       │                           ╴│


✅ Pipeline succeeded
------------------------------------------------------------
```

### `aspire do` improvements

[Section titled “aspire do improvements”](#aspire-do-improvements)

* `--list-steps` prints the pipeline steps that would run for `aspire do`, `aspire publish`, `aspire deploy`, or `aspire destroy` without executing them.
* The built-in `check-container-runtime` pipeline step fails fast when no container runtime is available, preventing late-stage build or publish failures.
* Independent steps continue when a sibling fails, so a single failed step no longer blocks unrelated work in the same pipeline run.

### Improved AI agent init

[Section titled “Improved AI agent init”](#improved-ai-agent-init)

`aspire agent init` gained a location selection step and now installs a refreshed standard skill set:

* The `aspire` skill orchestrates Aspire apps through the CLI by starting and stopping the AppHost, inspecting resources, viewing logs and telemetry, and adding integrations.
* The `aspireify` skill completes the one-time AppHost wiring after `aspire init` drops a skeleton into an existing repository.
* Pair these with `playwright-cli` and `dotnet-inspect` for browser testing and .NET API discovery.

Pick which skills to install with `--skills aspire,aspireify,...` or run `aspire agent init` interactively.

### CLI quality-of-life

[Section titled “CLI quality-of-life”](#cli-quality-of-life)

* The CLI’s global configuration now validates AppHost paths to prevent accidentally pointing at the wrong project.
* A container runtime health check runs before `aspire deploy` to catch missing or broken Docker and Podman setups early.
* `aspire ps` displays the dashboard URL alongside running AppHosts.
* Many CLI commands have new options that improve support for `--non-interactive`.

## 🚢 Deployment improvements

[Section titled “🚢 Deployment improvements”](#-deployment-improvements)

### New `aspire destroy` command

[Section titled “New aspire destroy command”](#new-aspire-destroy-command)

`aspire destroy` is the inverse of `aspire deploy` — it tears down what `aspire deploy` provisioned, using the same compute environments declared in your AppHost. That means a single command works across every deployment target:

* Azure resources are deleted through Azure Resource Manager.
* Kubernetes Helm releases and namespaces created during deployment are uninstalled.
* Published Docker Compose stacks are stopped and removed.

This is especially useful for CI environments, ephemeral preview deployments, and dev sandboxes where you want to reclaim resources cleanly without hand-tracking what was deployed.

Aspire CLI — Tear down a deployment

```bash
aspire destroy
```

Command reference: [`aspire destroy`](/reference/cli/commands/aspire-destroy/).

## 🐳 Container, Kubernetes, and Compose

[Section titled “🐳 Container, Kubernetes, and Compose”](#-container-kubernetes-and-compose)

### 🔗 Container tunnel enabled by default

[Section titled “🔗 Container tunnel enabled by default”](#-container-tunnel-enabled-by-default)

Aspire 13.3 enables the Aspire container tunnel by default, providing uniform container-to-host connectivity regardless of your container orchestrator.

Previously introduced as an opt-in experimental feature in Aspire 13.0, the container tunnel allows containers to reliably communicate with host-based services (such as the Aspire dashboard, OTEL collector, and other projects). Before this change, Docker Desktop users benefited from built-in host connectivity (`host.docker.internal`), while other container runtimes such as Docker Engine on Linux or Podman required manual workarounds.

With the tunnel enabled by default, all supported container orchestrators now behave consistently without any additional configuration.

Startup delay

Containers that reference host-based endpoints will start slightly later (\~3–4 seconds) than before, because the tunnel proxy container must start and allocate endpoints first. This is a one-time cost per application run and will improve in a future release when persistent tunnel support lands.

#### Disabling the container tunnel

[Section titled “Disabling the container tunnel”](#disabling-the-container-tunnel)

If you need to opt out, set the `ASPIRE_ENABLE_CONTAINER_TUNNEL` environment variable to `false` before starting your AppHost:

* Bash

  Disable container tunnel

  ```bash
  # Set the env var only for this aspire run invocation, then start the AppHost.
  ASPIRE_ENABLE_CONTAINER_TUNNEL=false aspire run
  ```

* PowerShell

  Disable container tunnel

  ```powershell
  # Set the env var only for this aspire run invocation, then start the AppHost.
  $env:ASPIRE_ENABLE_CONTAINER_TUNNEL = "false"; aspire run
  ```

You can also disable it in `launchSettings.json` by adding the variable to your existing AppHost launch profile:

launchSettings.json

```json
{
  "profiles": {
    "https": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPIRE_ENABLE_CONTAINER_TUNNEL": "false"
      }
    }
  }
}
```

For more details on container networking, see [Inner-loop networking overview](/fundamentals/networking-overview/).

### Kubernetes deployment with Helm engine

[Section titled “Kubernetes deployment with Helm engine”](#kubernetes-deployment-with-helm-engine)

Note

Native Kubernetes deployment (and the new Ingress / Gateway routing resources below) is in **preview** in 13.3.

Aspire 13.3 ships a Helm-based Kubernetes deployment engine. Declare a Kubernetes environment in your AppHost, run `aspire deploy`, and Aspire generates a complete Helm chart and applies it end-to-end against your cluster — no separate `helm install`, `kustomize`, or hand-rolled manifests required. `aspire destroy` removes the Helm release and namespace cleanly.

* apphost.mts

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Declare a Kubernetes environment. Aspire generates a Helm chart for it.
  const k8s = await builder.addKubernetesEnvironment('k8s');


  // Bind a project to the Kubernetes environment so it deploys there.
  const api = await builder.addProject('api', '../Api/Api.csproj');
  await api.withComputeEnvironment(k8s);


  await builder.build().run();
  ```

* AppHost.cs

  AppHost.cs

  ```csharp
  // Declare a Kubernetes environment. Aspire generates a Helm chart for it.
  var k8s = builder.AddKubernetesEnvironment("k8s");


  // Bind a project to the Kubernetes environment so it deploys there.
  builder.AddProject("api")
      .WithComputeEnvironment(k8s);
  ```

For more details, see [Deploy to Kubernetes](/deployment/kubernetes/clusters/).

### Kubernetes Ingress and Gateway API routing

[Section titled “Kubernetes Ingress and Gateway API routing”](#kubernetes-ingress-and-gateway-api-routing)

New first-class Ingress and Gateway API routing resources let you declare how traffic enters your Kubernetes cluster directly from the AppHost. Aspire generates the corresponding Ingress, IngressClass, Gateway, HTTPRoute, and (where applicable) cert-manager `Certificate` resources.

* apphost.mts

  Ingress with cert-manager

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Declare a Kubernetes environment.
  const k8s = await builder.addKubernetesEnvironment('k8s');


  // Add an ingress with a TLS cert.
  const ingress = await k8s.addIngress('public');
  await ingress.withHostname('api.example.com');
  await ingress.withTls('api-cert');


  await builder.build().run();
  ```

* AppHost.cs

  Ingress with cert-manager

  ```csharp
  // Declare a Kubernetes environment.
  var k8s = builder.AddKubernetesEnvironment("k8s");


  // Project that will be served behind the ingress.
  var api = builder.AddProject("api")
      .WithComputeEnvironment(k8s);


  // Add an ingress fronted by the nginx ingress class with a TLS cert.
  var ingress = k8s.AddIngress("public")
      .WithIngressClass("nginx")
      .WithHostname("api.example.com")
      .WithTls("api-cert");


  // Route requests at "/" to the project's HTTP endpoint.
  ingress.WithRoute("/", api.GetEndpoint("http"));
  ```

For more details, see [Kubernetes Ingress routing](/deployment/kubernetes-ingress/) and [AKS Gateway API routing](/deployment/kubernetes-gateway-aks/).

### Podman support for Docker Compose

[Section titled “Podman support for Docker Compose”](#podman-support-for-docker-compose)

The Docker Compose deployment engine now supports Podman as a container runtime out of the box, with no manual workarounds needed. Aspire detects Podman, generates Compose files compatible with `podman-compose`, and exposes the same lifecycle commands you’d use with Docker.

### Privileged mode for Docker Compose publishing

[Section titled “Privileged mode for Docker Compose publishing”](#privileged-mode-for-docker-compose-publishing)

You can now publish containers with the `privileged` flag enabled when targeting Docker Compose, which is required by some workloads (e.g., low-level networking utilities, nested containers).

* apphost.mts

  Privileged Docker Compose service

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Add a netshoot diagnostics container and publish it to Docker Compose
  // with privileged mode enabled (required for low-level network tooling).
  await builder
    .addContainer('netshoot', 'nicolaka/netshoot')
    .publishAsDockerComposeService(async (resource, service) => {
      await service.privileged.set(true);
    });


  await builder.build().run();
  ```

* AppHost.cs

  Privileged Docker Compose service

  ```csharp
  // Add a netshoot diagnostics container and publish it to Docker Compose
  // with privileged mode enabled (required for low-level network tooling).
  builder.AddContainer("netshoot", "nicolaka/netshoot")
      .PublishAsDockerComposeService((resource, service) =>
      {
          service.Privileged = true;
      });
  ```

### Dockerfile builder APIs for TypeScript AppHosts

[Section titled “Dockerfile builder APIs for TypeScript AppHosts”](#dockerfile-builder-apis-for-typescript-apphosts)

TypeScript AppHosts can now build Dockerfiles programmatically with `WithDockerfileBuilder` / `AddDockerfileBuilder`, mirroring the C# `WithDockerfile` extension. Diagnostic [`ASPIREDOCKERFILEBUILDER001`](/diagnostics/aspiredockerfilebuilder001/) covers the experimental warning.

For more details, see [Customize Dockerfile builds](/app-host/withdockerfile/).

## 🧩 App model and AppHost

[Section titled “🧩 App model and AppHost”](#-app-model-and-apphost)

### HTTP command result mode

[Section titled “HTTP command result mode”](#http-command-result-mode)

`HttpCommand` now supports a result mode that returns the response body to the dashboard’s notification center, so HTTP-triggered commands can return structured payloads instead of just success or failure:

* apphost.mts

  HTTP command with result body

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Expose POST /admin/sync as a dashboard command. resultMode "Auto" sends
  // the HTTP response body back to the dashboard's notification center.
  const api = await builder.addProject('api', '../Api/Api.csproj');
  await api.withHttpCommand('/admin/sync', 'Sync now', { resultMode: 'Auto' });


  await builder.build().run();
  ```

* AppHost.cs

  HTTP command with result body

  ```csharp
  // Expose POST /admin/sync as a dashboard command. ResultMode = Auto sends the
  // HTTP response body back to the dashboard's notification center.
  builder.AddProject("api")
      .WithHttpCommand("/admin/sync", "Sync now", commandOptions: new()
      {
          ResultMode = HttpCommandResultMode.Auto
      });
  ```

`HttpCommandResultMode` accepts `None`, `Auto` (infer from the response content type), `Json`, or `Text`.

For more details, see [HTTP commands](/fundamentals/http-commands/).

### Resource commands return structured results

[Section titled “Resource commands return structured results”](#resource-commands-return-structured-results)

Custom resource commands can now return an `ExecuteCommandResult` with structured `Data` payloads (`Text`, `Json`, or `Markdown`) that the dashboard renders from the notification center’s View response action. The `CommandResults.Success(string, CommandResultData)` overload makes it easy to return Markdown tables and other rich output. The new `Logger` property on `ExecuteCommandContext` lets command implementations log directly to the resource’s log stream.

* apphost.mts

  Issue an access token from a resource command

  ```typescript
  import {
    createBuilder,
    CommandResultFormat,
    type ExecuteCommandContext,
    type ExecuteCommandResult,
  } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder
    .addNodeApp('myservice', './myservice', 'src/server.ts')
    .withCommand(
      'issue-access-token',
      'Issue Access Token',
      async (_context: ExecuteCommandContext): Promise => {
        const token = crypto.randomUUID().replace(/-/g, '');


        return {
          success: true,
          message: 'Access token issued.',
          data: {
            value: token,
            format: CommandResultFormat.Text,
          },
        };
      }
    );


  await builder.build().run();
  ```

* AppHost.cs

  Issue an access token from a resource command

  ```csharp
  using System.Security.Cryptography;
  using Aspire.Hosting.ApplicationModel;


  builder.AddProject("myservice")
      .WithCommand(
          name: "issue-access-token",
          displayName: "Issue Access Token",
          executeCommand: context =>
          {
              var token = Convert.ToBase64String(RandomNumberGenerator.GetBytes(32));


              return Task.FromResult(CommandResults.Success(
                  message: "Access token issued.",
                  result: token,
                  resultFormat: CommandResultFormat.Text));
          });
  ```

The dashboard surfaces a View response action on the success toast, and the CLI splits status messages to `stderr` and the payload to `stdout` so it’s safe to pipe (`aspire resource myservice issue-access-token | pbcopy`).

For more details, see [Custom resource commands](/fundamentals/custom-resource-commands/).

### BeforeStart pipeline steps

[Section titled “BeforeStart pipeline steps”](#beforestart-pipeline-steps)

A new BeforeStart pipeline phase replaces the bespoke eventing-subscriber classes used by the Kubernetes, Docker Compose, and AKS deployment engines. Authors of compute environments can now add ordered startup logic via standard pipeline steps rather than custom subscribers.

### Subscribe extensions for lifecycle events

[Section titled “Subscribe extensions for lifecycle events”](#subscribe-extensions-for-lifecycle-events)

Lifecycle event subscriptions use the typed API available for each event. In C#, `OnBeforeStart` is a builder-level convenience method, while `AfterResourcesCreatedEvent` uses the lower-level eventing API:

* apphost.mts

  Subscribe to lifecycle events

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Run a callback right before the AppHost begins starting resources.
  await builder.subscribeBeforeStart(async (e) => {
    /* ... */
  });
  // Run a callback once all resources have been created.
  await builder.subscribeAfterResourcesCreated(async (e) => {
    /* ... */
  });


  await builder.build().run();
  ```

* AppHost.cs

  Subscribe to lifecycle events

  ```csharp
  // Run a callback right before the AppHost begins starting resources.
  builder.OnBeforeStart(async (e, ct) => { /* ... */ });
  // Run a callback once all resources have been created.
  builder.Eventing.Subscribe(
      async (e, ct) => { /* ... */ });
  ```

Thanks to community contributor [@afscrome](https://github.com/afscrome) for this addition.

For more details, see [Eventing](/app-host/eventing/).

### `WithEndpoint` updates existing endpoints

[Section titled “WithEndpoint updates existing endpoints”](#withendpoint-updates-existing-endpoints)

[`WithEndpoint`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withendpoint "Changes an existing endpoint or creates a new endpoint if it doesn't exist and invokes callback to modify the defaults.")[`withEndpoint`](/reference/api/typescript/aspire.hosting/withendpoint/ "Adds a network endpoint") no longer throws when an endpoint of the same name already exists. Calling it a second time updates the existing endpoint instead — making it easier to layer endpoint configuration across extension methods.

### Exclude management endpoints from `WithReference()`

[Section titled “Exclude management endpoints from WithReference()”](#exclude-management-endpoints-from-withreference)

Endpoint annotations now have an `ExcludeReferenceEndpoint` flag. Setting it to `true` excludes the endpoint (e.g. management or health endpoints) from the default [`WithReference`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withreference "Injects a connection string as an environment variable from the source resource into the destination resource, using the source resource's name as the...")[`withReference`](/reference/api/typescript/aspire.hosting/withreference/ "Adds a reference to another resource") injection, so consumers don’t accidentally receive admin URLs:

* apphost.mts

  Exclude an endpoint from withReference

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Mark the "admin" endpoint so it isn't injected into consumers via withReference().
  const api = await builder.addProject('api', '../Api/Api.csproj');
  await api.withEndpoint('admin', { excludeReferenceEndpoint: true });


  await builder.build().run();
  ```

* AppHost.cs

  Exclude an endpoint from WithReference

  ```csharp
  // Mark the "admin" endpoint so it isn't injected into consumers via WithReference().
  builder.AddProject("api")
      .WithEndpoint("admin", e => e.ExcludeReferenceEndpoint = true);
  ```

### `ASPIRE_ENVIRONMENT` variable

[Section titled “ASPIRE\_ENVIRONMENT variable”](#aspire_environment-variable)

The AppHost now honors a top-level `ASPIRE_ENVIRONMENT` environment variable that selects an environment-specific configuration profile, controlling which `appsettings.{environment}.json` is loaded and which environment is reported in dashboard telemetry.

### Aspire trusted developer certificate used everywhere

[Section titled “Aspire trusted developer certificate used everywhere”](#aspire-trusted-developer-certificate-used-everywhere)

The Aspire trusted developer certificate is now used in more places — including the Microsoft Developer Control Plane (DCP) on Windows, where it replaces the ephemeral certificate DCP previously generated. Set `ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE` to opt out if needed.

## 🌐 TypeScript AppHost parity

[Section titled “🌐 TypeScript AppHost parity”](#-typescript-apphost-parity)

Aspire 13.3 closes most of the remaining functional gap between C# AppHosts and the TypeScript AppHost SDK:

* A unified [`WithEnvironment`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withenvironment "Adds an environment variable to the resource.")[`withEnvironment`](/reference/api/typescript/aspire.hosting/withenvironment/ "Sets an environment variable") API handles all environment variable value kinds, including endpoints, parameters, connection strings, and expressions. Apps using the earlier per-kind helpers must migrate to the unified method.
* Endpoint property expressions (`endpoint.url`, `endpoint.host`, `endpoint.port`) are now usable inside TypeScript AppHost expressions.
* [`PublishAsDockerComposeService`](/reference/api/csharp/aspire.hosting.docker/dockercomposeserviceextensions/methods/#publishasdockercomposeservice "Publishes the specified resource as a Docker Compose service.")[`publishAsDockerComposeService`](/reference/api/typescript/aspire.hosting.docker/publishasdockercomposeservice/ "Publishes the specified resource as a Docker Compose service.")-equivalent hooks and post-processing provide Docker Compose API parity.
* Azure Container Apps custom domain configuration is now exposed in the TypeScript AppHost SDK.
* Unified YARP TypeScript route helpers, `addRoute(...)` and `addCatchAllRoute(...)`, replace several earlier ad-hoc helpers.
* `WithAdminDeploymentScriptSubnet` is now exported for TypeScript AppHosts.
* Image push options, endpoint mutation callbacks, `ConfigureEnvFile`, and builder pipeline APIs all reach TypeScript parity.
* The new `[AspireValue]` attribute and predefined catalogs (for example, `FoundryModels.OpenAI.Gpt41Mini`) make it easier to reference well-known values from TypeScript AppHosts.
* Diagnostic [`ASPIREEXPORT013`](/diagnostics/aspireexport013/) detects duplicate exported capability IDs at build time.

### Unified `withEnvironment` API

[Section titled “Unified withEnvironment API”](#unified-withenvironment-api)

Aspire 13.3 introduces a unified `withEnvironment(name, value)` API for non-C# AppHosts (TypeScript, Java, Python, Go, Rust). The public TypeScript API accepts plain strings, reference expressions, endpoint references, parameter resources, supported resources that expose connection strings, expression values, and awaitable forms of supported values:

apphost.mts

```typescript
const primaryEndpoint = await cache.primaryEndpoint();
const api = await builder.addProject('api', '../Api/Api.csproj');
await api
  .withEnvironment('SERVICE_URL', primaryEndpoint)
  .withEnvironment('API_KEY', apiKeyParam)
  .withEnvironment('DB', database);
```

The 13.3 TypeScript SDK doesn’t generate the earlier per-kind helper aliases. Update every existing call site to use `withEnvironment(name, value)` when you upgrade.

For more details, see [Authoring multi-language integrations](/extensibility/multi-language-integration-authoring/).

## 🟨 JavaScript and TypeScript apps

[Section titled “🟨 JavaScript and TypeScript apps”](#-javascript-and-typescript-apps)

Aspire 13.3 brings first-class JavaScript publishing to both C# and TypeScript AppHosts. A new family of `PublishAs*` extension methods replaces hand-rolled `Dockerfile` plumbing for the most common JS deployment shapes:

* [`PublishAsStaticWebsite`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#publishasstaticwebsite "Configures the JavaScript application to publish as a standalone static website served by YARP.")[`publishAsStaticWebsite`](/reference/api/typescript/aspire.hosting.javascript/publishasstaticwebsite/ "Publishes the JavaScript application as a standalone static website using YARP.") (preview) publishes a JS app as a static website served by a YARP image, with an optional API reverse proxy to a backend resource. It is intended for SPAs such as Vite and plain Next.js exports.
* [`PublishAsNodeServer`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#publishasnodeserver "Configures the JavaScript application to publish as a standalone Node.js server that runs a built artifact directly.")[`publishAsNodeServer`](/reference/api/typescript/aspire.hosting.javascript/publishasnodeserver/ "Configures the JavaScript application to publish as a standalone Node.js server that runs a built artifact directly.") publishes a self-contained Node entry point such as `server.js` without copying `node_modules` at runtime. It is intended for pre-bundled Node servers.
* `PublishAsNpmScript` publishes a Node app that runs an npm script (`start` or `serve`) at runtime, copying `package.json` and production dependencies. It is intended for full Nitro Next.js, Remix, and Astro SSR apps.

Aspire 13.3 also adds `AddNextJsApp` as a first-class Next.js helper alongside the existing [`AddViteApp`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#addviteapp "Adds a Vite app to the distributed application builder.")[`addViteApp`](/reference/api/typescript/aspire.hosting.javascript/addviteapp/ "Adds a Vite app to the distributed application builder.") and [`AddNodeApp`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#addnodeapp "Adds a node application to the application model. Node should be available on the PATH.")[`addNodeApp`](/reference/api/typescript/aspire.hosting.javascript/addnodeapp/ "Adds a node application to the application model. Node should be available on the PATH."), plus first-class support for Bun, Yarn, and pnpm in TypeScript AppHosts (npm remains the default).

Caution

The `PublishAsStaticWebsite` method is experimental in 13.3. Use diagnostic code [`ASPIREJAVASCRIPT001`](/diagnostics/aspirejavascript001/) to suppress the experimental warning. The Next.js, Vite, and Node app helpers themselves are stable.

### Next.js

[Section titled “Next.js”](#nextjs)

`AddNextJsApp` runs Next.js in development and automatically configures Next.js *standalone* publishing — no explicit `PublishAs*` call is needed. Make sure your `next.config.js` sets `output: "standalone"` so the build emits the standalone server.

* apphost.mts

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder.addNextJsApp('web', './web');


  await builder.build().run();
  ```

* AppHost.cs

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddNextJsApp("web", "./web");


  builder.Build().Run();
  ```

### Vite

[Section titled “Vite”](#vite)

`AddViteApp` runs Vite in development; `PublishAsStaticWebsite` ships the production build as a YARP-served static site, with an optional API reverse-proxy to a backend resource so the same `/api` path works in dev and production.

* apphost.mts

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const api = await builder.addProject('api', '../Api/Api.csproj');


  await builder
    .addViteApp('web', './web')
    .withReference(api)
    .publishAsStaticWebsite({ apiPath: '/api', apiTarget: api });


  await builder.build().run();
  ```

* AppHost.cs

  AppHost.cs

  ```csharp
  #pragma warning disable ASPIREEXTENSION001
  var builder = DistributedApplication.CreateBuilder(args);


  var api = builder.AddProject("api");


  builder.AddViteApp("web", "./web")
      .WithReference(api)
      .PublishAsStaticWebsite(apiPath: "/api", apiTarget: api);


  builder.Build().Run();
  #pragma warning restore ASPIREEXTENSION001
  ```

### TanStack Start (SSR)

[Section titled “TanStack Start (SSR)”](#tanstack-start-ssr)

For SSR frameworks like [TanStack Start](https://tanstack.com/start) and SvelteKit that bundle to a Node entry-point, pair `AddViteApp` (for development) with `PublishAsNodeServer` to ship the built `.output/server/index.mjs` as a slim runtime container without copying `node_modules`.

* apphost.mts

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder
    .addViteApp('web', './web')
    .publishAsNodeServer('.output/server/index.mjs', {
      outputPath: '.output',
    });


  await builder.build().run();
  ```

* AppHost.cs

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddViteApp("web", "./web")
      .PublishAsNodeServer(entryPoint: ".output/server/index.mjs",
          outputPath: ".output");


  builder.Build().Run();
  ```

For SSR frameworks that need `node_modules` at runtime, including Nuxt, Remix, Astro SSR, and Qwik, use `PublishAsNpmScript` instead. It copies `package.json` and runs `npm start`.

For more details, see [JavaScript/TypeScript apps](/integrations/frameworks/javascript/), [Publish JavaScript apps](/deployment/javascript-apps/), and [TypeScript AppHosts](/app-host/typescript-apphost/).

## 📊 Dashboard improvements

[Section titled “📊 Dashboard improvements”](#-dashboard-improvements)

### Notification center for command results

[Section titled “Notification center for command results”](#notification-center-for-command-results)

The dashboard now has a notification center that surfaces results of resource commands and lifecycle events without requiring you to scrape the logs panel. Commands return [structured results](#resource-commands-return-structured-results) which the dashboard renders inline.

The notification center is accessible via the bell icon in the top-right corner of the header. When there are unread notifications, a badge with the unread count appears on the icon.

![The Aspire dashboard showing a notification bell icon with a badge in the top-right corner](/_astro/notification-center-bell.C2k4g8u-_hcylH.webp)

Selecting the bell icon opens the Notifications dialog, which lists all notifications. From here you can view command responses.

![The Aspire dashboard notification panel open, showing a 'Rebuild succeeded' notification with a View response button](/_astro/notification-center-open.Bc95xsoJ_18hlgD.webp)

### Rebuild resource command

[Section titled “Rebuild resource command”](#rebuild-resource-command)

The dashboard now has a built-in Rebuild command for container and project resources. When triggered, it rebuilds the resource image and restarts the resource, making it faster to pick up code or Dockerfile changes without stopping and restarting the whole AppHost. The result (success or failure) appears in the notification center.

Caution

Aspire 13.3 removes the in-dashboard GitHub Copilot UI. Please review the [Breaking changes](#breaking-changes) section before upgrading.

## 🧰 VS Code extension

[Section titled “🧰 VS Code extension”](#-vs-code-extension)

### Open dashboard in VS Code Simple Browser

[Section titled “Open dashboard in VS Code Simple Browser”](#open-dashboard-in-vs-code-simple-browser)

When you launch your Aspire app from VS Code, the dashboard now opens in VS Code’s Simple Browser by default rather than spawning an external browser window. The behavior is controlled by the `aspire.dashboardBrowser` setting.

### AppHost CodeLens and gutter decorations

[Section titled “AppHost CodeLens and gutter decorations”](#apphost-codelens-and-gutter-decorations)

The extension now renders live resource state in the editor. CodeLens above each resource definition exposes one-click `Start`, `Stop`, `Restart`, and `View Logs` actions, while gutter decorations in the left margin reflect each resource’s current health. The same health-aware icons appear next to resources in the Aspire Activity Bar.

![The Aspire view in VS Code showing a tree of resources with health-aware icons reflecting each resource's state.](/_astro/code-extension-sidebar.DsBK1mmC_ZndIIb.webp)

### Other extension changes

[Section titled “Other extension changes”](#other-extension-changes)

* Set `aspire.enableAutoRestore` to have the extension automatically run `aspire restore` when a workspace opens or its configuration changes.
* Launch configurations can now specify `env` and `args` for the AppHost, just like a regular .NET launch configuration.
* Open AppHost source from the *Running AppHosts* view.
* Open the Aspire Dashboard from the VS Code Command Palette.
* Use right-click context menus on resource endpoint URLs to open or copy them.
* The walkthrough has been updated to cover TypeScript AppHosts.
* The extension auto-detects the Aspire CLI in default install paths even when it isn’t on `PATH`.

For more details, see [Aspire VS Code extension](/get-started/aspire-vscode-extension/).

## 📦 Integration updates

[Section titled “📦 Integration updates”](#-integration-updates)

### 🔍 Browser logs and screenshots

[Section titled “🔍 Browser logs and screenshots”](#-browser-logs-and-screenshots)

The new `Aspire.Hosting.Browsers` integration captures browser console logs, network requests, and screenshots from your frontend resources during development, surfacing them in the dashboard alongside server-side telemetry. Add [`WithBrowserLogs`](/reference/api/csharp/aspire.hosting.browsers/browserlogsbuilderextensions/methods/#withbrowserlogs "Adds a child resource that can open the application's primary browser endpoint in a tracked browser session, surface browser diagnostics, and capture...")[`withBrowserLogs`](/reference/api/typescript/aspire.hosting.browsers/withbrowserlogs/ "Adds a child resource that can open the application's primary browser endpoint in a tracked browser session, surface browser diagnostics, and capture...") to any frontend resource to enable it.

* apphost.mts

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Capture browser console logs, network requests, and screenshots from
  // this Vite frontend; they show up in the dashboard alongside server telemetry.
  const frontend = await builder.addViteApp('frontend', './frontend');
  await frontend.withBrowserLogs();


  await builder.build().run();
  ```

* AppHost.cs

  AppHost.cs

  ```csharp
  // Capture browser console logs, network requests, and screenshots from
  // this Vite frontend; they show up in the dashboard alongside server telemetry.
  builder.AddViteApp("frontend")
      .WithBrowserLogs();
  ```

Caution

This integration is experimental in 13.3. Use diagnostic code [`ASPIREBROWSERLOGS001`](/diagnostics/aspirebrowserlogs001/) to suppress the experimental warning.

For more details, see [Browser logs](/integrations/devtools/browser-logs/).

### Durable Task Scheduler for Azure Functions

[Section titled “Durable Task Scheduler for Azure Functions”](#durable-task-scheduler-for-azure-functions)

Azure Functions can now declare a Durable Task Scheduler dependency directly from the AppHost, with full local and Azure-deployed support. The APIs are released as experimental under [`ASPIREDURABLETASK001`](/diagnostics/aspiredurabletask001/).

For more details, see [Azure Functions hosting](/integrations/cloud/azure/azure-functions/azure-functions-host/).

### RabbitMQ v7 with publisher and subscriber tracing

[Section titled “RabbitMQ v7 with publisher and subscriber tracing”](#rabbitmq-v7-with-publisher-and-subscriber-tracing)

The RabbitMQ client integration has been updated to support RabbitMQ.Client v7, with OpenTelemetry tracing for both publishers and subscribers.

### `Aspire.Microsoft.Azure.StackExchangeRedis` is stable

[Section titled “Aspire.Microsoft.Azure.StackExchangeRedis is stable”](#aspiremicrosoftazurestackexchangeredis-is-stable)

The [📦 Aspire.Microsoft.Azure.StackExchangeRedis](https://www.nuget.org/packages/Aspire.Microsoft.Azure.StackExchangeRedis) package is no longer in preview. Use it for Entra-authenticated Azure Cache for Redis and Azure Managed Redis access.

### Npgsql metrics align with .NET 10

[Section titled “Npgsql metrics align with .NET 10”](#npgsql-metrics-align-with-net-10)

The Npgsql client integration emits OpenTelemetry metrics that align with the .NET 10 metric naming specification.

## ☁️ Azure improvements

[Section titled “☁️ Azure improvements”](#️-azure-improvements)

### Azure Front Door integration — global edge in one API call

[Section titled “Azure Front Door integration — global edge in one API call”](#azure-front-door-integration--global-edge-in-one-api-call)

![Azure Front Door logo](/_astro/azure-front-door-icon.2eNN_ZmD_Z3Mq5Y.webp)

You no longer need to stitch together ARM templates or click through portal blades to get a CDN in front of your app. Aspire 13.3 adds a new hosting integration for [Azure Front Door](https://learn.microsoft.com/azure/frontdoor/), Microsoft’s global edge network for fast, secure, and highly available web apps. Add a Front Door profile in front of your backends with [`AddAzureFrontDoor`](/reference/api/csharp/aspire.hosting.azure.frontdoor/azurefrontdoorextensions/methods/#addazurefrontdoor "Adds an Azure Front Door resource to the application model.")[`addAzureFrontDoor`](/reference/api/typescript/aspire.hosting.azure.frontdoor/addazurefrontdoor/ "Adds an Azure Front Door resource to the application model.") and attach origins with [`WithOrigin`](/reference/api/csharp/aspire.hosting.azure.frontdoor/azurefrontdoorextensions/methods/#withorigin "Adds an origin (backend) to the Azure Front Door resource. Each origin gets its own Front Door endpoint with a distinct *.azurefd.net hostname, its own...")[`withOrigin`](/reference/api/typescript/aspire.hosting.azure.frontdoor/withorigin/ "Adds an origin (backend) to the Azure Front Door resource. Each origin gets its own Front Door endpoint with a distinct *.azurefd.net hostname, its own..."):

* apphost.mts

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Two backend projects exposed as external HTTP endpoints.
  const api = await builder.addProject('api', '../Api/Api.csproj');
  await api.withExternalHttpEndpoints();


  const web = await builder.addProject('web', '../Web/Web.csproj');
  await web.withExternalHttpEndpoints();


  // Provision an Azure Front Door profile and attach each backend as an origin.
  // Each withOrigin call creates its own endpoint, origin group, origin, and route.
  const frontDoor = await builder.addAzureFrontDoor('frontdoor');
  await frontDoor.withOrigin(api);
  await frontDoor.withOrigin(web);


  await builder.build().run();
  ```

* AppHost.cs

  AppHost.cs

  ```csharp
  // Two backend projects exposed as external HTTP endpoints.
  var api = builder.AddProject("api")
      .WithExternalHttpEndpoints();


  var web = builder.AddProject("web")
      .WithExternalHttpEndpoints();


  // Provision an Azure Front Door profile and attach each backend as an origin.
  // Each WithOrigin call creates its own endpoint, origin group, origin, and route.
  builder.AddAzureFrontDoor("frontdoor")
      .WithOrigin(api)
      .WithOrigin(web);
  ```

Each `withOrigin` call provisions its own Front Door endpoint, origin group, origin, and route, so every backend is independently routable through its own `*.azurefd.net` hostname. The integration provisions Front Door in the Standard SKU by default; use [`ConfigureInfrastructure`](/reference/api/csharp/aspire.hosting.azure/azureprovisioningresourceextensions/methods/#configureinfrastructure "Configures the Azure provisioning resource Azure.Provisioning.Infrastructure.")[`configureInfrastructure`](/reference/api/typescript/aspire.hosting.azure/configureinfrastructure/ "Configures the Azure provisioning infrastructure callback") to customize the Front Door, for example to change SKUs, attach a Web Application Firewall (WAF) policy, enable caching, and more.

For more details, see [Azure Front Door integration](/integrations/cloud/azure/azure-front-door/).

### 🌐 Azure Network Security Perimeter support

[Section titled “🌐 Azure Network Security Perimeter support”](#-azure-network-security-perimeter-support)

Aspire 13.3 adds support for [Azure Network Security Perimeters (NSPs)](https://learn.microsoft.com/azure/private-link/network-security-perimeter-concepts), which provide a logical security boundary for Azure PaaS services. NSPs complement the existing virtual network and private endpoint support by operating at the PaaS layer — grouping resources like Storage, Key Vault, Cosmos DB, and SQL so they can communicate with each other while restricting public access via access rules.

#### Create a perimeter and associate resources

[Section titled “Create a perimeter and associate resources”](#create-a-perimeter-and-associate-resources)

* apphost.mts

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';
  import { NetworkSecurityPerimeterAccessRuleDirection } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Declare a Network Security Perimeter and add an inbound access rule.
  const nsp = await builder.addNetworkSecurityPerimeter('my-nsp');
  await nsp.withAccessRule({
    name: 'allow-my-ip',
    direction: NetworkSecurityPerimeterAccessRuleDirection.Inbound,
    addressPrefixes: ['203.0.113.0/24'],
  });


  // Associate Azure resources with the perimeter — they remain reachable from each
  // other but become subject to the perimeter's access rules for outside traffic.
  const storage = await builder.addAzureStorage('storage');
  await storage.withNetworkSecurityPerimeter(nsp);
  const keyVault = await builder.addAzureKeyVault('kv');
  await keyVault.withNetworkSecurityPerimeter(nsp);


  await builder.build().run();
  ```

* AppHost.cs

  AppHost.cs

  ```csharp
  // Declare a Network Security Perimeter and add an inbound access rule.
  var nsp = builder.AddNetworkSecurityPerimeter("my-nsp")
      .WithAccessRule(new AzureNspAccessRule
      {
          Name = "allow-my-ip",
          Direction = NetworkSecurityPerimeterAccessRuleDirection.Inbound,
          AddressPrefixes = { "203.0.113.0/24" }
      });


  // Associate Azure resources with the perimeter — they remain reachable from each
  // other but become subject to the perimeter's access rules for outside traffic.
  var storage = builder.AddAzureStorage("storage")
      .WithNetworkSecurityPerimeter(nsp);
  var keyVault = builder.AddAzureKeyVault("kv")
      .WithNetworkSecurityPerimeter(nsp);
  ```

NSPs support **Enforced** mode (blocks traffic that violates the rules) and **Learning** mode (logs violations without blocking), making it easy to audit traffic before locking down access.

For more details, see [Azure Virtual Network integration](/integrations/cloud/azure/azure-virtual-network/#add-a-network-security-perimeter).

### Azure Kubernetes Service (AKS) hosting integration — Kubernetes without the YAML

[Section titled “Azure Kubernetes Service (AKS) hosting integration — Kubernetes without the YAML”](#azure-kubernetes-service-aks-hosting-integration--kubernetes-without-the-yaml)

Note

The AKS hosting integration is in **preview** and may evolve before it’s marked stable.

Aspire 13.3 adds first-class support for provisioning and deploying to Azure Kubernetes Service without writing manifests by hand. Use [`AddAzureKubernetesEnvironment`](/reference/api/csharp/aspire.hosting.azure.kubernetes/azurekubernetesenvironmentextensions/methods/#addazurekubernetesenvironment "Adds an Azure Kubernetes Service (AKS) environment to the distributed application. This provisions an AKS cluster and configures it as a Kubernetes compute...")[`addAzureKubernetesEnvironment`](/reference/api/typescript/aspire.hosting.azure.kubernetes/addazurekubernetesenvironment/ "Adds an Azure Kubernetes Service (AKS) environment to the distributed application. This provisions an AKS cluster and configures it as a Kubernetes compute...") to declare an AKS environment, customize node pools, and generate a type-safe Bicep and Helm deployment pipeline from your AppHost.

* apphost.mts

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Declare an AKS environment and customize its system node pool.
  const aks = await builder.addAzureKubernetesEnvironment('aks');
  await aks.withSystemNodePool('Standard_D2s_v5', { minCount: 1, maxCount: 3 });


  // Bind a project to the AKS environment so it deploys there.
  const api = await builder.addProject('api', '../Api/Api.csproj');
  await api.withComputeEnvironment(aks);


  await builder.build().run();
  ```

* AppHost.cs

  AppHost.cs

  ```csharp
  // Declare an AKS environment and customize its system node pool.
  var aks = builder.AddAzureKubernetesEnvironment("aks")
      .WithSystemNodePool("Standard_D2s_v5", minCount: 1, maxCount: 3);


  // Bind a project to the AKS environment so it deploys there.
  builder.AddProject("api")
      .WithComputeEnvironment(aks);
  ```

[`WithSystemNodePool`](/reference/api/csharp/aspire.hosting.azure.kubernetes/azurekubernetesenvironmentextensions/methods/#withsystemnodepool "Replaces the default system node pool with a customized configuration.")[`withSystemNodePool`](/reference/api/typescript/aspire.hosting.azure.kubernetes/withsystemnodepool/ "Replaces the default system node pool with a customized configuration.") lets you customize the system node pool’s VM size and autoscaling bounds. By default the AKS cluster uses the **Free** control-plane SKU; the `AksSkuTier` enum is no longer part of the public API.

For more details, see [Azure Kubernetes Service integration](/integrations/cloud/azure/aks/) and [Deploy an Aspire app to AKS](/deployment/kubernetes/aks/).

### Private endpoint support for Azure Container Registry, OpenAI, and Foundry

[Section titled “Private endpoint support for Azure Container Registry, OpenAI, and Foundry”](#private-endpoint-support-for-azure-container-registry-openai-and-foundry)

`WithPrivateEndpoint` is now supported on additional Azure resources, allowing you to provision and connect to Azure Container Registry, Azure OpenAI, and Azure AI Foundry resources over a virtual network without exposing them publicly.

### Azure AI Foundry Prompt Agent

[Section titled “Azure AI Foundry Prompt Agent”](#azure-ai-foundry-prompt-agent)

Aspire 13.3 ships a new working implementation of Azure AI Foundry Prompt Agent support through [`AddPromptAgent`](/reference/api/csharp/aspire.hosting.foundry/promptagentbuilderextensions/methods/#addpromptagent "Adds a prompt agent to a Microsoft Foundry project with the specified tools.")[`addPromptAgent`](/reference/api/typescript/aspire.hosting.foundry/addpromptagent/ "Adds a prompt agent to a Microsoft Foundry project with the specified tools."). The previous `AddAndPublishPromptAgent` API and the original shape of `AzurePromptAgentResource` (which never functioned end-to-end) have been replaced. `AddPromptAgent` now returns a working `AzurePromptAgentResource`.

The Foundry model catalog also gained two new models: GPT-5.4 and Qwen3 VL.

For more details, see [Azure AI Foundry integration](/integrations/cloud/azure/azure-ai-foundry/).

### Automatic HTTPS upgrade for Azure App Service

[Section titled “Automatic HTTPS upgrade for Azure App Service”](#automatic-https-upgrade-for-azure-app-service)

Endpoints deployed to Azure App Service environments are now automatically upgraded to HTTPS, eliminating the need to manually configure HTTP-to-HTTPS redirects in your services.

### Configurable Azure credential process timeout

[Section titled “Configurable Azure credential process timeout”](#configurable-azure-credential-process-timeout)

The new `Azure:CredentialProcessTimeoutSeconds` configuration value lets you tune the timeout for Azure credential acquisition during deployments — useful for environments where authentication round-trips can take longer than the default.

appsettings.json

```json
{
  "Azure": {
    "CredentialProcessTimeoutSeconds": 60
  }
}
```

### Azure deployment quality-of-life

[Section titled “Azure deployment quality-of-life”](#azure-deployment-quality-of-life)

* Deployment summaries now include clickable links to the Azure Portal for resources that were just provisioned.
* Multi-environment deployments now require explicit compute environment binding. Every resource must specify which environment it deploys to, preventing accidental cross-environment leakage.

## 🏗️ Templates

[Section titled “🏗️ Templates”](#️-templates)

### 🐍 Python starter migrated to TypeScript AppHost

[Section titled “🐍 Python starter migrated to TypeScript AppHost”](#-python-starter-migrated-to-typescript-apphost)

The `aspire-py-starter` template (Starter App with FastAPI and React) has moved from the `dotnet new` template system to the Aspire CLI template system and now uses a TypeScript AppHost instead of a C# AppHost. This aligns it with the same pattern as the `aspire-ts-starter` template.

For users of this template:

* Use `aspire new aspire-py-starter` instead of `dotnet new aspire-py-starter`.
* The AppHost is now authored in TypeScript, so the **.NET SDK is no longer required** to scaffold or run the Python starter.
* The generated TypeScript AppHost uses `addUvicornApp` to run the FastAPI backend.
* A new `--use-redis-cache` option is available to scaffold the template with an optional Redis cache resource.

Aspire CLI

```bash
# Basic Python starter
aspire new aspire-py-starter


# Python starter with Redis cache
aspire new aspire-py-starter --use-redis-cache true
```

Breaking change

`dotnet new aspire-py-starter` is no longer available. Existing projects created with the old template continue to work, but new projects should use `aspire new aspire-py-starter` going forward.

For details on the `aspire new` command and all available templates, see [aspire new command](/reference/cli/commands/aspire-new/).

## 🙏 Community

[Section titled “🙏 Community”](#-community)

Aspire is built in the open, and this release wouldn’t be what it is without you. A huge thank you to all community contributors who helped make Aspire 13.3 possible — including [@afscrome](https://github.com/afscrome) for the lifecycle Subscribe extension methods, [@spboyer](https://github.com/spboyer) for documentation and template polish, [@holystix04](https://github.com/holystix04), and [@tranhoangtu-it](https://github.com/tranhoangtu-it).

### The Aspire core team is

* [![Adam Ratzman](https://github.com/adamint.png?size=96)Adam Ratzman](https://github.com/adamint)
* [![Ankit Jain](https://github.com/radical.png?size=96)Ankit Jain](https://github.com/radical)
* [![Damian Edwards](https://github.com/DamianEdwards.png?size=96)Damian Edwards](https://github.com/DamianEdwards)
* [![David Fowler](https://github.com/davidfowl.png?size=96)David Fowler](https://github.com/davidfowl)
* [![David Negstad](https://github.com/danegsta.png?size=96)David Negstad](https://github.com/danegsta)
* [![David Pine](https://github.com/IEvangelist.png?size=96)David Pine](https://github.com/IEvangelist)
* [![Ella Hathaway](https://github.com/ellahathaway.png?size=96)Ella Hathaway](https://github.com/ellahathaway)
* [![Eric Erhardt](https://github.com/eerhardt.png?size=96)Eric Erhardt](https://github.com/eerhardt)
* [![James Newton-King](https://github.com/JamesNK.png?size=96)James Newton-King](https://github.com/JamesNK)
* [![José Pérez](https://github.com/joperezr.png?size=96)José Pérez](https://github.com/joperezr)
* [![Karol Zadora-Przylecki](https://github.com/karolz-ms.png?size=96)Karol Zadora-Przylecki](https://github.com/karolz-ms)
* [![Maddy Montaquila](https://github.com/maddymontaquila.png?size=96)Maddy Montaquila](https://github.com/maddymontaquila)
* [![Mitch Denny](https://github.com/mitchdenny.png?size=96)Mitch Denny](https://github.com/mitchdenny)
* [![Sébastien Ros](https://github.com/sebastienros.png?size=96)Sébastien Ros](https://github.com/sebastienros)

Special thanks to everyone whose pull requests shipped in Aspire 13.3, including:

[@afscrome](https://github.com/afscrome), [@AndriySvyryd](https://github.com/AndriySvyryd), [@annatisch](https://github.com/annatisch), [@DavidZidar](https://github.com/DavidZidar), [@divyeshio](https://github.com/divyeshio), [@GeertvanHorrik](https://github.com/GeertvanHorrik), [@holystix04](https://github.com/holystix04), [@ideepakchauhan7](https://github.com/ideepakchauhan7), [@jgbright](https://github.com/jgbright), [@JoshuaKGoldberg](https://github.com/JoshuaKGoldberg), [@mitchcapper](https://github.com/mitchcapper), [@mmitche](https://github.com/mmitche), [@MO2k4](https://github.com/MO2k4), [@Muckenbatscher](https://github.com/Muckenbatscher), [@philliphoff](https://github.com/philliphoff), [@spboyer](https://github.com/spboyer), [@T-Gro](https://github.com/T-Gro), [@tommasodotNET](https://github.com/tommasodotNET), [@tranhoangtu-it](https://github.com/tranhoangtu-it), [@wtgodbe](https://github.com/wtgodbe), and [@yreynhout](https://github.com/yreynhout)

We're always excited to [see community contributions](/community/contributors/)! If you'd like to get involved, check out our [contributing guide](/community/contributor-guide/).

## ⚠️ Breaking changes

[Section titled “⚠️ Breaking changes”](#️-breaking-changes)

| Change                                                                                                           | Migration                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--log-level` renamed to `--pipeline-log-level` on `aspire publish` and `aspire deploy`                          | Update scripts/CI to use `--pipeline-log-level`.                                                                                                                                                                                                                                                                                                                                                                                     |
| `package.json` `engines.node` is no longer used to select Node images for generated Dockerfiles                  | Specify the Node version explicitly via [`WithDockerfile`](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods/#withdockerfile "Causes Aspire to build the specified container image from a Dockerfile.")[`withDockerfile`](/reference/api/typescript/aspire.hosting/withdockerfile/ "Causes Aspire to build the specified container image from a Dockerfile.") or your project’s Dockerfile base image. |
| `NameOutput` renamed to `NameOutputReference` in Azure Network resources                                         | Replace any usage of `*.NameOutput` with `*.NameOutputReference`.                                                                                                                                                                                                                                                                                                                                                                    |
| `OtlpEndpointEnvironmentVariableName` property removed                                                           | Remove references; the OTLP endpoint env var is now managed automatically.                                                                                                                                                                                                                                                                                                                                                           |
| **Dashboard MCP server removed** (along with `ASPIRE_DASHBOARD_MCP_ENDPOINT_URL`)                                | Use the AppHost-level MCP server with `aspire agent init`.                                                                                                                                                                                                                                                                                                                                                                           |
| `AksSkuTier` enum is no longer part of the public AKS API                                                        | The AKS control-plane SKU tier now defaults to **Free**; remove any references to `AksSkuTier`.                                                                                                                                                                                                                                                                                                                                      |
| `ASPIREEXTENSION001` JavaScript diagnostic ID renamed                                                            | Use [`ASPIREJAVASCRIPT001`](/diagnostics/aspirejavascript001/).                                                                                                                                                                                                                                                                                                                                                                      |
| Docker Swarm `UpdateConfig` property types changed                                                               | Update generated/hand-written Compose overrides accordingly.                                                                                                                                                                                                                                                                                                                                                                         |
| The non-functional `AddAndPublishPromptAgent` API and the original `AzurePromptAgentResource` shape were removed | Use the new `AddPromptAgent` API (which returns a working `AzurePromptAgentResource`).                                                                                                                                                                                                                                                                                                                                               |
| CLI telemetry JSON output schema aligned with the MCP tool format                                                | Update any consumers of `--format json` from telemetry-related CLI commands.                                                                                                                                                                                                                                                                                                                                                         |
| `aspire init` no longer fully wires up your AppHost on its own                                                   | Run the `aspireify` agent skill (e.g. via Copilot CLI) to complete wiring after `aspire init`.                                                                                                                                                                                                                                                                                                                                       |
| Kubernetes Ingress and Gateway routing types moved namespaces                                                    | Update `using` directives if you reference them directly.                                                                                                                                                                                                                                                                                                                                                                            |
| `dotnet new aspire-py-starter` removed                                                                           | Use `aspire new aspire-py-starter` from the Aspire CLI.                                                                                                                                                                                                                                                                                                                                                                              |
| TypeScript AppHost per-kind `withEnvironment*` helper methods removed                                            | Replace every per-kind helper call with the unified `withEnvironment(name, value)` API.                                                                                                                                                                                                                                                                                                                                              |

### In-dashboard GitHub Copilot UI replaced by agentic development

[Section titled “In-dashboard GitHub Copilot UI replaced by agentic development”](#in-dashboard-github-copilot-ui-replaced-by-agentic-development)



The GitHub Copilot chat UI previously built into the Aspire dashboard has been replaced by an agentic development model. The Copilot chat inside the dashboard has been disabled and instead AI coding agents now connect to your entire Aspire app through the CLI and MCP tools. This gives agents full context across structured logs, distributed traces, resource status, console output, and your source code.

Agents can now diagnose issues end-to-end, suggest fixes in your actual codebase, and act on telemetry rather than just display it. The old dashboard UI only supported GitHub Copilot in Visual Studio and VS Code; the new approach works with GitHub Copilot, Claude, Cursor, and any other AI coding agent that supports skills or MCP.

Set up agentic development with a single command:

Aspire CLI — Initialize AI agent configuration

```bash
aspire agent init
```

The `aspire agent init` command detects your development environment and configures skills and MCP tools for supported AI coding agents. Agents connect to the dashboard through the CLI regardless of how you launched your app — so you get the same AI-powered debugging whether you started with `aspire run`, VS Code, or Visual Studio.

For full setup instructions, see [Use AI coding agents](/get-started/ai-coding-agents/) and [Dashboard and AI coding agents](/dashboard/ai-coding-agents/). If you relied on a specific Copilot dashboard scenario that isn’t covered by the new approach, please [file an issue on GitHub](https://github.com/dotnet/aspire/issues) so the team can prioritize it.

### Migration from Aspire 13.2 to 13.3

[Section titled “Migration from Aspire 13.2 to 13.3”](#migration-from-aspire-132-to-133)

1. Update the CLI by running `aspire update --self`.
2. Update your projects by running `aspire update` from the root of your repository.
3. Audit `--log-level` usage in CI/CD pipelines and rename it to `--pipeline-log-level`.
4. Search for `NameOutput`, `AddAndPublishPromptAgent`, and `AksSkuTier` in your AppHost code and update them according to the table above.
5. Replace `dotnet new aspire-py-starter` with `aspire new aspire-py-starter` for any new Python starter projects.
6. Rerun `aspire agent init` if you previously relied on the dashboard MCP server.
7. Re-pin Node versions in your Dockerfiles if you relied on `package.json` `engines.node` for image selection.

We’d love to hear about your experience with Aspire 13.3. Share what you’re building on [GitHub](https://github.com/microsoft/aspire/issues) or join us on [Discord](https://aka.ms/aspire-discord).

# What's new in Aspire 13.4

> Explore Aspire 13.4: GA TypeScript AppHost, new Go, Blazor WebAssembly, and Bun hosting integrations, richer Kubernetes and AKS deployment APIs, AI agent readiness, process resource commands, CLI integration discovery, and dashboard updates.

Aspire 13.4 broadens the app model and streamlines daily operations. TypeScript AppHosts reach **general availability** alongside C#, with new Go, Blazor WebAssembly, and Bun hosting integrations. The release also expands Kubernetes and AKS deployment APIs, AI agent support, resource commands, CLI discovery and diagnostics, the dashboard, and Visual Studio Code tooling.

We’d love to hear what you think. Drop by [ Discord](https://aka.ms/aspire-discord) to chat with the team and the community, or file feedback and issues on [ GitHub](https://github.com/microsoft/aspire/issues).

This release introduces:

* C# and TypeScript AppHosts are both supported as first-class options, with stronger TypeScript startup validation, more complete SDK generation, new TypeScript samples, and documentation parity with C# AppHost examples.
* New hosting integrations provide AppHost APIs for [Go](/integrations/frameworks/go/go-get-started/) ([`AddGoApp`](/reference/api/csharp/aspire.hosting.go/gohostingextensions/methods/#addgoapp "Adds a Go application to the application model. The Go toolchain must be available on the PATH.")[`addGoApp`](/reference/api/typescript/aspire.hosting.go/addgoapp/ "Adds a Go application to the application model. The Go toolchain must be available on the PATH.")) and first-party Bun support in `Aspire.Hosting.JavaScript` for [Bun](/integrations/frameworks/bun-apps/) ([`AddBunApp`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#addbunapp "Adds a Bun application to the application model. Bun should be available on the PATH.")[`addBunApp`](/reference/api/typescript/aspire.hosting.javascript/addbunapp/ "Adds a Bun application to the application model. Bun should be available on the PATH.")).
* Kubernetes and AKS deployment improvements include [cert-manager integration, Gateway API and Azure Application Gateway for Containers (AGC) support](/deployment/kubernetes/aks/#expose-your-app-to-the-internet), Kubernetes manifest resources, external Helm charts, and consolidated Helm chart configuration.
* Aspire workflow skills move into the new [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills) bundle, with clearer separation between first-run setup, lifecycle orchestration, monitoring, AppHost wiring, and deployment guidance, plus eval-driven iteration on agent routing.
* Resource commands gain typed arguments, visibility controls, immediate result display, named CLI options, resource-scoped help, built-in parameter command options, and the experimental [`WithProcessCommand`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withprocesscommand "Adds a command to the resource that starts a local process when invoked.")[`withProcessCommand`](/reference/api/typescript/aspire.hosting/withprocesscommand/ "Adds a command to the resource that starts a local process when invoked.") API.
* CLI discovery and diagnostics add `aspire integration list`, `aspire integration search`, `--search` for logs and telemetry, version checks in `aspire doctor`, better logs output, and more consistent command error handling.
* Dashboard and editor updates include the AI Agents dialog, resource state fixes, CodeLens actions that appear without opening the Aspire panel, and improved VS Code terminal and debug output integration.
* NATS, Azure Front Door, Foundry hosted agents, and other integrations are updated.
* …and much more.

## 🆙 Upgrade to Aspire 13.4

[Section titled “🆙 Upgrade to Aspire 13.4”](#-upgrade-to-aspire-134)



Caution

Aspire 13.4 includes breaking changes. Please review the [Breaking changes](#breaking-changes) section before upgrading.

If your Aspire CLI version is earlier than 13, first [install the latest stable version](/get-started/install-cli/).

TypeScript AppHost users: run aspire update --self first

If you have a TypeScript AppHost on Aspire 13.3.x, you must update the Aspire CLI itself **before** running `aspire update` on your project. Running `aspire update` first will fail mid-update with an error like:

```text
❌ An unexpected error occurred: No code generator found for language: TypeScript
```

The 13.3.x CLI bundles an AppHost server that cannot load the 13.4 TypeScript code generator, so package restore succeeds but TypeScript SDK regeneration crashes. The failure leaves `aspire.config.json` pointing at 13.4 packages while the CLI is still 13.3.x, which also breaks `aspire run` and `aspire restore` until you finish the upgrade with `aspire update --self`.

Follow the steps below in order — `aspire update --self` first, then `aspire update`. See [microsoft/aspire#17077](https://github.com/microsoft/aspire/issues/17077) for background.

For general purpose upgrade guidance, see [Upgrade Aspire](/whats-new/upgrade-aspire/).

The easiest way to upgrade to Aspire 13.4 is using the [`aspire update` command](/reference/cli/commands/aspire-update/):

1. Update the Aspire CLI itself:

   Aspire CLI — Update the CLI

   ```bash
   aspire update --self
   ```

2. Update your projects (run from the root of your repository):

   Aspire CLI — Update all Aspire packages

   ```bash
   aspire update
   ```

Or install the CLI from scratch:

* Bash

  Aspire CLI — Install Aspire CLI

  ```bash
  curl -sSL https://aspire.dev/install.sh | bash
  ```

* PowerShell

  Aspire CLI — Install Aspire CLI

  ```powershell
  irm https://aspire.dev/install.ps1 | iex
  ```

For more details on installing the Aspire CLI, see [Install the CLI](/get-started/install-cli/).

## 🌐 TypeScript AppHost general availability

[Section titled “🌐 TypeScript AppHost general availability”](#-typescript-apphost-general-availability)

TypeScript AppHosts are now fully supported alongside C#, so both are first-class ways to model Aspire apps. TypeScript AppHosts use `apphost.mts`, the same code-first orchestration model as C#, and generated SDK modules for Aspire resources and integrations.

apphost.mts

```typescript
import { createBuilder } from "./.aspire/modules/aspire.mjs";


const builder = await createBuilder();


const cache = await builder.addRedis("cache");


const api = await builder
    .addNodeApp("api", "./api", "src/index.ts")
    .withHttpEndpoint({ env: "PORT" })
    .withReference(cache);


await builder.build().run();
```

Aspire 13.4 validates TypeScript AppHosts before startup, so type-checking and compile errors fail early. New TypeScript projects use `.aspire/modules/` for generated SDK files, and `aspire init --language typescript` creates a nested `aspire-apphost/` folder and package when run in an existing JavaScript or TypeScript app.

Docs now include TypeScript examples alongside C# where the API is available, and the release adds TypeScript samples you can start from.

The [Aspire Type System (ATS)](/extensibility/multi-language-integration-authoring/) APIs that power non-C# AppHost authoring are now generally available, so projects can remove `ASPIREATS001` suppressions. The generated TypeScript SDK also adds C# XML-doc JSDoc, fluent async method chaining, `ExternalServiceResource` support in `withEnvironment`, and fixes for generated names and exports.

Existing TypeScript AppHosts scaffolded by earlier CLI versions continue to work on 13.4 without changes. If your project uses `apphost.ts` and `./.modules/aspire.js`, see [Legacy `apphost.ts` projects (pre-13.4)](#legacy-apphostts-projects-pre-134) for compatibility details and an opt-in migration to the new `apphost.mts` layout.

For preview non-C# AppHosts behind feature flags, see [`aspire config set`](/reference/cli/commands/aspire-config-set/). For setup details, see [TypeScript AppHosts](/app-host/typescript-apphost/). To explore working examples, browse the [Aspire samples](/reference/samples/).

## 🧱 Go and Bun hosting integrations

[Section titled “🧱 Go and Bun hosting integrations”](#-go-and-bun-hosting-integrations)

Beyond TypeScript, Aspire 13.4 adds first-class hosting integrations for Go and Bun, so you can orchestrate those apps directly from the AppHost.

### 🦫 Go hosting integration

[Section titled “🦫 Go hosting integration”](#-go-hosting-integration)

Go application hosting has graduated into core Aspire as the `Aspire.Hosting.Go` package. Use `AddGoApp` / `addGoApp` to run a Go application from your AppHost — Aspire runs `go run .` from the application directory during local development and generates a Dockerfile that runs `go build` at publish time. Build-time options such as build tags, `ldflags`, and `gcflags` are configured directly on the resource, and the [Aspire VS Code extension](/get-started/aspire-vscode-extension/) can launch the Go debugger (`dlv-dap`) when you start the AppHost in debug mode.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const api = await builder.addGoApp('api', './api');
  await api.withHttpEndpoint({ port: 8080, env: 'PORT' });
  await api.withExternalHttpEndpoints();


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  var api = builder.AddGoApp("api", "./api")
    .WithHttpEndpoint(port: 8080, env: "PORT")
    .WithExternalHttpEndpoints();


  builder.Build().Run();
  ```

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const blazorApp = await builder.addBlazorWasmProject("app", "../MyBlazorApp/MyBlazorApp.csproj");


  const gateway = await builder.addBlazorGateway("gateway");
  await gateway.withExternalHttpEndpoints();
  await gateway.withBlazorClientApp(blazorApp);


  await builder.build().run();
  ```

Note

The previous `CommunityToolkit.Aspire.Hosting.Golang` package is deprecated now that Go support has graduated into core Aspire. Use `Aspire.Hosting.Go` and `AddGoApp` for new Aspire 13.4+ applications.

For setup details, see [Get started with the Go integration](/integrations/frameworks/go/go-get-started/) and [Set up Go apps in the AppHost](/integrations/frameworks/go/go-host/).

### 🥟 Bun apps

[Section titled “🥟 Bun apps”](#-bun-apps)

Aspire 13.4 adds `AddBunApp` / `addBunApp` for orchestrating [Bun](https://bun.sh/) applications alongside the rest of your resources. Bun support is now part of `Aspire.Hosting.JavaScript`.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from "./.aspire/modules/aspire.mjs";


  const builder = await createBuilder();


  const bunApi = await builder.addBunApp("bun-api", "../bun-app", "server.ts");
  await bunApi.withHttpEndpoint({ port: 3000, env: "PORT" });


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  var bunApi = builder.AddBunApp("bun-api", "../bun-app", "server.ts")
    .WithHttpEndpoint(port: 3000, env: "PORT");


  builder.Build().Run();
  ```

For setup details, see the [Bun integration](/integrations/frameworks/bun-apps/).

## 🌐 Blazor WebAssembly hosting preview

[Section titled “🌐 Blazor WebAssembly hosting preview”](#-blazor-webassembly-hosting-preview)

The new preview `Aspire.Hosting.Blazor` integration models standalone Blazor WebAssembly projects in your AppHost. Use [`AddBlazorWasmProject`](/reference/api/csharp/aspire.hosting.blazor/blazorgatewayextensions/methods/#addblazorwasmproject "Registers a Blazor WebAssembly project as a resource using the Aspire-generated IProjectMetadata type to discover the project path. The resource name becomes...")[`addBlazorWasmProject`](/reference/api/typescript/aspire.hosting.blazor/addblazorwasmproject/ "Registers a Blazor WebAssembly project as a resource without launching it as a process. Prefer AddBlazorWasmProject which uses IProjectMetadata for...") to add a Blazor WebAssembly project and [`AddBlazorGateway`](/reference/api/csharp/aspire.hosting.blazor/blazorgatewayextensions/methods/#addblazorgateway "Registers the built-in Blazor Gateway as a file-based C# app. The gateway is shipped as Gateway.cs alongside this library and launched via AddCSharpApp. No...")[`addBlazorGateway`](/reference/api/typescript/aspire.hosting.blazor/addblazorgateway/ "Registers the built-in Blazor Gateway as a file-based C# app. The gateway is shipped as Gateway.cs alongside this library and launched via AddCSharpApp. No...") to add a browser-facing gateway, then associate the hosted client with `WithBlazorClientApp` / `withBlazorClientApp`.

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  var blazorApp = builder.AddBlazorWasmProject("app", "../MyBlazorApp/MyBlazorApp.csproj");


  var gateway = builder.AddBlazorGateway("gateway")
    .WithExternalHttpEndpoints()
    .WithBlazorClientApp(blazorApp);


  builder.Build().Run();
  ```

For setup details, see [Set up Blazor hosting in the AppHost](/integrations/dotnet/blazor-hosting/).

## 🛠️ CLI enhancements

[Section titled “🛠️ CLI enhancements”](#️-cli-enhancements)

### Search logs and telemetry

[Section titled “Search logs and telemetry”](#search-logs-and-telemetry)

`aspire logs` and the `aspire otel` commands now support `--search`, so you can filter logs and telemetry by keyword directly from the CLI.

* For console logs, Aspire searches the log message text and resource prefix.
* For structured logs, Aspire searches the message, attributes, scope name, event name, trace and span IDs, severity, and resource name.
* For spans and traces, Aspire searches span names, trace and span IDs, attributes, status, kind, scope, events, resource names, and trace names.

Search, tail, and resource filters are applied before data is streamed back to the CLI, which keeps large log streams responsive. It also means your coding agent no longer has to load all the output into context and `grep`, speeding up the diagnostic process while using fewer tokens.

Aspire CLI — Search logs

```bash
aspire logs --search "failed"
aspire otel logs --search "checkout"
aspire otel traces --search "POST /orders"
aspire otel traces --search "@http.status_code:500"
```

Search now also supports field filters, so you can narrow telemetry results by matching attributes, names, sources, IDs, and other telemetry fields.

See [`aspire logs`](/reference/cli/commands/aspire-logs/) and [`aspire otel logs`](/reference/cli/commands/aspire-otel-logs/) for telemetry CLI usage.

### Better environment diagnostics

[Section titled “Better environment diagnostics”](#better-environment-diagnostics)

[`aspire doctor`](/reference/cli/commands/aspire-doctor/) now reports the current Aspire CLI version, shows an update notice when a newer version is available, and reports the AppHost SDK version when an AppHost is detected. This makes CLI/SDK version mismatches easier to spot before they become restore or runtime issues.

It also lists every Aspire CLI installation discovered on the machine — the active binary, peer installs, shadowed binaries, and `dotnet tool` store installs — so conflicting installs are easy to find.

Aspire CLI — Environment diagnostics

```text
Aspire Environment Check
Aspire
  ✅ Aspire CLI version 13.4.0 (channel: stable)
AppHost
  ✅ AppHost version 13.4.0 (src\apphost\MyApp.AppHost\MyApp.AppHost.csproj)
.NET SDK
  ✅ .NET 10.0.300 installed (x64)
Container Runtime
  ✅ Docker v29.5.2: running (auto-detected (default)) ← active
Environment
  ✅ HTTPS development certificate is trusted
Summary: 5 passed, 0 warnings, 0 failed


Aspire CLI Installations
Path                                      Version  Channel  Route      PATH status
C:\Users\you\.aspire\bin\aspire.exe       13.4.0   stable   installer  active
C:\Users\you\.dotnet\tools\aspire.exe     13.3.0   stable   dotnet     shadowed
```

### Resource command CLI improvements

[Section titled “Resource command CLI improvements”](#resource-command-cli-improvements)

Resource command inputs are now passed as named CLI options instead of positional arguments. This makes optional inputs easier to skip and lets users supply values in any order. Running `aspire resource  --help` also shows the commands available for that specific resource.

The built-in `set-parameter` and `delete-parameter` commands now use named options too, so scripts can manage parameter resources without interactive prompts. The examples below assume an AppHost parameter resource named `mydb-password`; for details on defining parameter resources, see [External parameters](/fundamentals/external-parameters/).

Aspire CLI — Resource command arguments

```bash
aspire resource cache seed-data --dataset small --force
aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword"
aspire resource mydb-password delete-parameter --delete-from-user-secrets true
aspire resource cache --help
aspire resource mydb-password set-parameter --help
```

Boolean resource command options require explicit `true` or `false` values. For example, `--delete-from-user-secrets true` requests deletion from user secrets.

For more information, see [`aspire resource`](/reference/cli/commands/aspire-resource/#built-in-parameter-commands).

### AI agent readiness with Aspire skills

[Section titled “AI agent readiness with Aspire skills”](#ai-agent-readiness-with-aspire-skills)

The Aspire workflow skills installed by `aspire agent init` are now packaged as the Aspire skills bundle from [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills). The bundle includes six workflow skills: `aspire`, `aspire-init`, `aspire-orchestration`, `aspire-monitoring`, `aspire-deployment`, and `aspireify`. Aspire 13.4 includes an embedded snapshot for default installs, and the optional remote fetch path can download matching GitHub release assets instead of relying only on skill content baked directly into the CLI binary. The CLI verifies bundle integrity before installing selected files. The install flow remains unchanged.

This split gives agents focused instructions for first-run setup, local lifecycle management, telemetry investigation, deployment, and AppHost wiring instead of loading one broad playbook for every Aspire task. The dedicated skills repository also gives the Aspire team a place to iterate on routing descriptions, trigger phrases, scenario evals, and handoff rules as agent workflows evolve.

Aspire CLI — Install Aspire workflow skills

```bash
aspire agent init --skill-locations standard --skills aspire,aspire-init,aspire-orchestration,aspire-monitoring,aspire-deployment,aspireify
```

For full `aspire agent init` usage and options, see [aspire agent init command](/reference/cli/commands/aspire-agent-init/). For the skills setup walkthrough, see [Use AI coding agents](/get-started/ai-coding-agents/). To follow bundle development, see the [`microsoft/aspire-skills` repository](https://github.com/microsoft/aspire-skills).

### Deployment commands are generally available

[Section titled “Deployment commands are generally available”](#deployment-commands-are-generally-available)

The Aspire CLI deployment commands — [`aspire publish`](/reference/cli/commands/aspire-publish/) and [`aspire deploy`](/reference/cli/commands/aspire-deploy/) — are now generally available, so you can generate deployment artifacts and deploy your app from the CLI as a supported workflow.

### Discover integrations from the CLI

[Section titled “Discover integrations from the CLI”](#discover-integrations-from-the-cli)

The new `aspire integration` command group helps you and your coding agent quickly search available Aspire hosting integrations without modifying an AppHost project. Use `aspire integration list` to browse all integrations or `aspire integration search` to search by keyword.

Aspire CLI — Search integrations

```bash
aspire integration list
aspire integration search redis
```

After you find the integration you need, use [`aspire add`](/reference/cli/commands/aspire-add/) to add it to your AppHost.

### CLI quality-of-life

[Section titled “CLI quality-of-life”](#cli-quality-of-life)

Aspire 13.4 includes a set of smaller CLI improvements and fixes:

* AppHost startup is faster thanks to direct launch and AppHost metadata caching, so `aspire run` and related commands spend less time getting going.
* A new `aspire ls` command lists candidate AppHost projects in the current directory without starting one, with both an interactive table and JSON output for scripting.
* The CLI automatically migrates the legacy `.aspire/settings.json` file to `aspire.config.json`, so older projects pick up the current configuration layout without manual edits.
* CLI commands now use centralized error and cancellation handling, so cancellation and help output are quieter and more consistent.
* `aspire logs` dims timestamps for readability and shows `No logs found.` when there are no entries, while preserving JSON output for automation.
* Log file paths in CLI output are clickable terminal links when the terminal supports hyperlinks and degrade gracefully to plain text otherwise.
* Package-manager installs such as WinGet, Homebrew, and `dotnet tool` keep the CLI bundle beside the CLI binary, so uninstall and upgrade flows clean up the bundle correctly.
* The Aspire CLI can now be installed from npm (`npm install -g @microsoft/aspire-cli`). When installed this way, `aspire update --self` and update notices print the matching `npm install -g @microsoft/aspire-cli@latest` command instead of overwriting the npm-managed binary. See [Install with a package manager](/get-started/install-cli/#install-with-a-package-manager).
* `aspire update` now requires `--yes` in non-interactive mode, matching `aspire destroy`.
* `aspire stop --all` output includes the AppHost name and, when needed, the PID for clearer multi-instance shutdown output.
* `aspire new`, `aspire init`, `aspire run`, and `aspire update` include fixes for NuGet feed errors, output paths, generated files, disabled dashboards, detached shutdown, and AppHost package-reference cleanup.
* The C# empty AppHost template (`aspire new aspire-empty`) no longer emits a duplicate `profiles` block in `aspire.config.json`. The template now writes launch profiles only to `apphost.run.json`, so newly scaffolded projects have a minimal `aspire.config.json` that only identifies the AppHost entry point. This was a regression introduced in 13.4 when `apphost.run.json` was added alongside `aspire.config.json`; it is now corrected.
* `aspire run` now handles AppHost shutdown more gracefully: backchannel log, resource-state, and publishing-activity streams complete immediately when a shutdown is already in progress, and a warning is shown if log capture is interrupted rather than surfacing an unhandled error.

## 🧩 App model and AppHost

[Section titled “🧩 App model and AppHost”](#-app-model-and-apphost)

### Resource command arguments, visibility, and results

[Section titled “Resource command arguments, visibility, and results”](#resource-command-arguments-visibility-and-results)

Custom resource commands can now declare typed input arguments with labels, descriptions, default values, required-state metadata, allowed values, and custom validation. Commands can also control where they appear with `ResourceCommandVisibility`, so you can expose a command to the dashboard UI, automation APIs and MCP tools, both, or neither.

Command results can be configured to display immediately in the dashboard, making interactive commands easier to use when they return structured output or captured text.

For the full API surface, see [Custom resource commands](/fundamentals/custom-resource-commands/).

### Hide implementation-detail resources

[Section titled “Hide implementation-detail resources”](#hide-implementation-detail-resources)

AppHost authors can keep resource views focused with [`WithHidden`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withhidden "Hides the resource from default resource lists.")[`withHidden`](/reference/api/typescript/aspire.hosting/withhidden/ "Hides the resource from default resource lists") and [`WithHiddenOnCompletion`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withhiddenoncompletion "Hides the resource from default resource lists after it completes successfully.")[`withHiddenOnCompletion`](/reference/api/typescript/aspire.hosting/withhiddenoncompletion/ "Hides the resource from default resource lists after successful completion"). Hidden resources stay in the app model and remain addressable by name, but are excluded from the dashboard and CLI resource lists — useful for setup helpers, one-off migration services, or certificate-collection resources that are implementation details rather than things you interact with directly.

### ⚙️ Process-backed resource commands

[Section titled “⚙️ Process-backed resource commands”](#️-process-backed-resource-commands)

Aspire 13.4 adds the experimental `WithProcessCommand` API for exposing local tools, scripts, and CLIs as resource commands. The helper starts a process on the AppHost machine, passes arguments without going through a shell, streams stdout and stderr to the command logger, captures bounded output, and maps process exit codes to resource command results.

Caution

`WithProcessCommand`, `ProcessCommandSpec`, and `ProcessCommandOptions` are experimental APIs. C# callers must suppress [`ASPIREPROCESSCOMMAND001`](/diagnostics/aspireprocesscommand001/) to use them.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const cache = await builder.addRedis('cache');


  await cache.withProcessCommand('node-version', 'Show Node.js version', {
    executablePath: 'node',
    arguments: ['--version'],
  });


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  #pragma warning disable ASPIREPROCESSCOMMAND001


  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddRedis("cache")
      .WithProcessCommand(
          commandName: "dotnet-version",
          displayName: "Show .NET version",
          executablePath: "dotnet",
          arguments: ["--version"]);


  builder.Build().Run();
  ```

For static commands, dynamic process specs, stdin, environment variables, and result options, see [Process-backed resource commands](/fundamentals/custom-resource-commands/#process-backed-resource-commands).

### 🔄 Persistent executable and project lifetimes

[Section titled “🔄 Persistent executable and project lifetimes”](#-persistent-executable-and-project-lifetimes)

Persistent lifetimes now extend beyond containers to executables and projects. Call [`WithPersistentLifetime`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withpersistentlifetime "Configures a resource to use a persistent lifetime.")[`withPersistentLifetime`](/reference/api/typescript/aspire.hosting/withpersistentlifetime/ "Configures a resource to use a persistent lifetime.") to leave a resource running when the AppHost exits and reuse the same instance on the next run, and [`WithSessionLifetime`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withsessionlifetime "Configures a resource to use a session lifetime.")[`withSessionLifetime`](/reference/api/typescript/aspire.hosting/withsessionlifetime/ "Configures a resource to use a session lifetime.") to return a resource to the default behavior. This is useful for resources that are expensive to initialize, need stable local endpoints, or should stay available while you restart or rebuild the AppHost.

Caution

The shared persistent and session lifetime APIs are experimental and emit the [`ASPIREPERSISTENCE001`](/diagnostics/aspirepersistence001/) diagnostic, which C# callers must suppress to use them. Persistent executables and projects default to proxyless endpoints, must use concrete ports for executables, don’t support replicas, and aren’t compatible with Aspire IDE debugging sessions. Persistent containers use proxied endpoints by default, the same as session containers. The existing container-specific `WithLifetime(ContainerLifetime.Persistent)` API is unchanged.

For the full lifetime model, see [Configure resource lifetimes](/app-host/resource-lifetimes/).

### AppHost and runtime reliability

[Section titled “AppHost and runtime reliability”](#apphost-and-runtime-reliability)

Aspire 13.4 also improves the AppHost runtime:

* The active container runtime (Docker or Podman) is propagated to project image builds through `PublishContainer`, keeping project builds aligned with the runtime used for container resources.
* The dashboard OTLP and resource-service endpoint ports are now assigned dynamically and no longer need to be set in `launchSettings.json`, which simplifies AppHost setup and makes it easier to enable the dashboard in tests.
* On macOS and Linux, DCP now uses the Aspire Developer certificate for TLS, bringing the HTTPS developer experience previously available only on Windows (opt out with `ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE=false`).
* YARP endpoint resolution is deferred until environment configuration generation, so late endpoint scheme changes are reflected in generated proxy configuration.
* Container resources can no longer use the reserved name `aspire`, which avoids conflicts with the container tunnel.
* Container tunnel errors include more diagnostic detail, and a startup deadlock for tunnel-dependent containers has been fixed.
* Foundry hosted agents validate environment variable names up front, avoiding deploy-time failures caused by unsupported characters.
* `AzureRoleAssignmentResource` is now public so deployment pipeline code can inspect Azure role assignments.

### Aspire CLI bundle opt-in for C# AppHosts

[Section titled “Aspire CLI bundle opt-in for C# AppHosts”](#aspire-cli-bundle-opt-in-for-c-apphosts)

C# AppHost projects can opt in to using the installed Aspire CLI bundle as the source for DCP and Dashboard orchestration dependencies by setting `true`. This is a preview transition path for the upcoming shift where AppHost orchestration dependencies come from the CLI bundle by default, instead of being restored from platform-specific NuGet packages per AppHost project.

For setup details, see [Use the Aspire CLI bundle for orchestration dependencies](/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies) in the Aspire SDK documentation.

## 🚢 Kubernetes, AKS, and Azure deployment

[Section titled “🚢 Kubernetes, AKS, and Azure deployment”](#-kubernetes-aks-and-azure-deployment)

### Cert-manager, Gateway API, and AGC support

[Section titled “Cert-manager, Gateway API, and AGC support”](#cert-manager-gateway-api-and-agc-support)

Kubernetes and Azure Kubernetes Service (AKS) deployment continue to expand in 13.4. Kubernetes environments can now model cert-manager resources through typed APIs, including cert-manager installation, ClusterIssuers backed by Let’s Encrypt or custom ACME servers, and TLS wiring for gateways.

For AKS, [`AddAzureKubernetesEnvironment`](/reference/api/csharp/aspire.hosting.azure.kubernetes/azurekubernetesenvironmentextensions/methods/#addazurekubernetesenvironment "Adds an Azure Kubernetes Service (AKS) environment to the distributed application. This provisions an AKS cluster and configures it as a Kubernetes compute...")[`addAzureKubernetesEnvironment`](/reference/api/typescript/aspire.hosting.azure.kubernetes/addazurekubernetesenvironment/ "Adds an Azure Kubernetes Service (AKS) environment to the distributed application. This provisions an AKS cluster and configures it as a Kubernetes compute...") now wires Azure Application Gateway for Containers (AGC) into the deployment flow. When [`AddLoadBalancer`](/reference/api/csharp/aspire.hosting.azure.kubernetes/azurekubernetesenvironmentextensions/methods/#addloadbalancer "Adds an Azure Application Gateway for Containers (AGC) ApplicationLoadBalancer to this AKS environment, bound to the supplied delegated subnet. Returns a...")[`addLoadBalancer`](/reference/api/typescript/aspire.hosting.azure.kubernetes/addloadbalancer/ "Adds an Azure Application Gateway for Containers (AGC) ApplicationLoadBalancer to this AKS environment, bound to the supplied delegated subnet. Returns a...") is used, Aspire provisions the AGC ingress profile on AKS, assigns the required Network Contributor role to the controller identity, and exposes Gateway API routing for the application.

For a complete walkthrough including custom domains, see [Deploy to AKS — Expose your app to the internet](/deployment/kubernetes/aks/#expose-your-app-to-the-internet).

### Kubernetes manifests and external Helm charts

[Section titled “Kubernetes manifests and external Helm charts”](#kubernetes-manifests-and-external-helm-charts)

Aspire 13.4 adds a Kubernetes manifest resource API for arbitrary manifests and an [`AddHelmChart`](/reference/api/csharp/aspire.hosting.kubernetes/kuberneteshelmchartextensions/methods/#addhelmchart "Adds an external Helm chart to be installed in the Kubernetes environment. The chart is installed via helm upgrade --install as a pipeline step after the...")[`addHelmChart`](/reference/api/typescript/aspire.hosting.kubernetes/addhelmchart/ "Adds an external Helm chart to be installed in the Kubernetes environment. The chart is installed via helm upgrade --install as a pipeline step after the...") API for installing external Helm charts as deployment pipeline steps. These APIs make it possible to include Kubernetes-native resources, ingress controllers, monitoring stacks, and other third-party charts alongside the resources generated from your Aspire application model.

### Consolidated Helm chart configuration

[Section titled “Consolidated Helm chart configuration”](#consolidated-helm-chart-configuration)

Helm chart name, version, description, release name, and namespace are now configured through the [`WithHelm`](/reference/api/csharp/aspire.hosting.kubernetes/kubernetesenvironmentextensions/methods/#withhelm "Configures the Kubernetes environment to deploy using Helm charts.")[`withHelm`](/reference/api/typescript/aspire.hosting.kubernetes/withhelm/ "Configures the Kubernetes environment to deploy using Helm charts.") extension method. This replaces the previous parallel property-based configuration surface on `KubernetesEnvironmentResource` with one fluent entry point.

For examples of `WithHelm(...)`, see the [Kubernetes integration](/integrations/compute/kubernetes/#configure-helm-chart-options).

### Reuse an existing ACR pull identity

[Section titled “Reuse an existing ACR pull identity”](#reuse-an-existing-acr-pull-identity)

When deploying to Azure Container Apps, Aspire normally emits a new user-assigned managed identity and an `AcrPull` role assignment so container apps can pull their images. If your deployment principal can’t create identities or role assignments, or you want to reuse an existing identity, supply one with [`WithAcrPullIdentity`](/reference/api/csharp/aspire.hosting.azure.appcontainers/azurecontainerappextensions/methods/#withacrpullidentity "Configures the container app environment to use the supplied Aspire.Hosting.Azure.AzureUserAssignedIdentityResource as the managed identity that container...")[`withAcrPullIdentity`](/reference/api/typescript/aspire.hosting.azure.appcontainers/withacrpullidentity/ "Configures the container app environment to use the supplied AzureUserAssignedIdentityResource as the managed identity that container apps in the environment..."). The same API is available for both Azure Container App Environments and Azure App Service Environments.

For details, see [Configure Azure Container Apps](/integrations/cloud/azure/configure-container-apps/).

### Azure Container Apps jobs are stable

[Section titled “Azure Container Apps jobs are stable”](#azure-container-apps-jobs-are-stable)

The Azure Container Apps jobs APIs — [`PublishAsAzureContainerAppJob`](/reference/api/csharp/aspire.hosting.azure.appcontainers/containerappextensions/methods/#publishasazurecontainerappjob "Allows configuring the specified compute resource as an Azure Container App Job.")[`publishAsAzureContainerAppJob`](/reference/api/typescript/aspire.hosting.azure.appcontainers/publishasazurecontainerappjob/ "Configures the compute resource as an Azure Container App Job") and [`PublishAsScheduledAzureContainerAppJob`](/reference/api/csharp/aspire.hosting.azure.appcontainers/containerappextensions/methods/#publishasscheduledazurecontainerappjob "Configures the specified compute resource as a scheduled Azure Container App Job with the provided cron expression.")[`publishAsScheduledAzureContainerAppJob`](/reference/api/typescript/aspire.hosting.azure.appcontainers/publishasscheduledazurecontainerappjob/ "Configures the compute resource as a scheduled Azure Container App Job") — have graduated to stable. You can declare any project, container, or executable resource as a finite-duration job for batch processing, scheduled tasks, and event-driven workloads directly from your AppHost, without suppressing an experimental diagnostic.

For trigger types and scheduling, see [Azure Container Apps jobs](/integrations/cloud/azure/container-app-jobs/).

## 📊 Dashboard improvements

[Section titled “📊 Dashboard improvements”](#-dashboard-improvements)

### 🤖 AI Agents dialog

[Section titled “🤖 AI Agents dialog”](#-ai-agents-dialog)

The dashboard header now includes an AI Agents dialog with guidance for connecting AI coding agents to your Aspire app. This builds on the Aspire CLI and MCP server workflow where agents can query resource status, structured logs, console logs, traces, and other dashboard data while they work in your codebase.

Administrators can hide the header button with the `Dashboard:UI:DisableAgentHelp` setting.

The MCP AI tools also return more telemetry context this release — trace and structured-log limits increased from 200 to 800 entries, and console logs from 500 to 2000 — so agents get a fuller picture when they query your app.

For the agent workflow, see [Dashboard and AI coding agents](/dashboard/ai-coding-agents/). For the dashboard setting, see [Dashboard configuration](/dashboard/configuration/).

### Structured search and trace filtering

[Section titled “Structured search and trace filtering”](#structured-search-and-trace-filtering)

The dashboard search experience is more powerful in 13.4. Text filters now support structured field qualifiers — for example `status:error`, `@attr:value`, negation, and numeric comparisons — so you can narrow logs and telemetry without leaving the search box. The Traces page adds a duration filter, and trace detail views support a structured filter dialog and minimum span-duration filtering, making it easier to focus on the slowest operations in a request.

### Clearer resource dependencies

[Section titled “Clearer resource dependencies”](#clearer-resource-dependencies)

When a resource is waiting on a dependency, the dashboard now shows the waiting dependency details with clickable links, so you can jump straight to the resource that’s holding up startup.

### Dashboard fixes

[Section titled “Dashboard fixes”](#dashboard-fixes)

Dashboard fixes in this release include:

* `!=` and `not contains` filters on the Traces page now return the expected results.
* Static web assets are served correctly when running the dashboard from source outside the `Development` environment.
* The resource details panel now displays an `Unknown` state consistently when a resource has no state.
* Containers in `FailedToStart` state now show a more accurate state detail instead of suggesting the container previously ran.
* The console logs view shows an empty-state message after a short delay when a resource hasn’t emitted any output yet, instead of appearing to hang.

## 🧰 VS Code extension

[Section titled “🧰 VS Code extension”](#-vs-code-extension)

The Aspire extension for Visual Studio Code now shows AppHost CodeLens actions directly in the editor without requiring the Aspire panel to be open. Run, Stop, Restart, Open Dashboard, and View Logs actions make common AppHost operations available where you’re editing code.

The extension also uses VS Code terminal shell integration when sending Aspire CLI commands to the Aspire terminal, forwards debug adapter output to dashboard logs, shows AppHost errors in the debug console, reduces TypeScript and C# AppHost debug-console noise, disables automatic `dotnet restore` on startup by default, and fixes a sticky Finding apphosts notification.

The [Go hosting integration](#go-hosting-integration) section covers the new Go debugging flow. This release also expands what the extension can do across workspaces: it adds live support for workspaces that contain multiple AppHosts, an AppHost logs viewer, resource command argument inputs collected through QuickInput, and faster, parser-backed AppHost and resource detection.

Learn more about the [Aspire Visual Studio Code extension](/get-started/aspire-vscode-extension/).

## 📦 Integration updates

[Section titled “📦 Integration updates”](#-integration-updates)

### Azure Front Door naming

[Section titled “Azure Front Door naming”](#azure-front-door-naming)

Azure Front Door CDN resources now use Azure.Provisioning’s built-in name-generation algorithm instead of Aspire’s custom logic. This removes Aspire’s manual name-length cap and aligns generated resource names with Azure.Provisioning behavior.

Caution

Upgrading from Aspire 13.3 can produce duplicate Front Door endpoint, origin group, or route names in existing deployments. Remove and re-add the affected resource, or set the resource `Name` explicitly with [`ConfigureInfrastructure`](/reference/api/csharp/aspire.hosting.azure/azureprovisioningresourceextensions/methods/#configureinfrastructure "Configures the Azure provisioning resource Azure.Provisioning.Infrastructure.")[`configureInfrastructure`](/reference/api/typescript/aspire.hosting.azure/configureinfrastructure/ "Configures the Azure provisioning infrastructure callback"), to avoid conflicts.

For Front Door setup, see the [Azure Front Door integration](/integrations/cloud/azure/azure-front-door/).

### NATS client updates

[Section titled “NATS client updates”](#nats-client-updates)

`AddNatsClient` now also registers `INatsClient` and defaults the serializer registry to `NatsClientDefaultSerializerRegistry`. This enables typed publish/subscribe scenarios without requiring explicit serializer configuration. User-provided serializer registries still take precedence, and primitive/raw byte scenarios are unaffected.

For client setup, see [Connect to NATS](/integrations/messaging/nats/nats-connect/).

### Foundry hosted agent commands and fixes

[Section titled “Foundry hosted agent commands and fixes”](#foundry-hosted-agent-commands-and-fixes)

You can now turn any project or app resource into a Microsoft Foundry hosted agent, interact directly with it via the Aspire dashboard, and deploy it with Aspire.

The [Foundry Hosted Agent Service](https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agents) is a way to write code as runnable, debuggable, containerized AI agents with streamlined deployment and management as part of your app. If your code implements the Foundry Hosted Agents responses or invocations protocols, tell Aspire to treat it as a hosted agent in the apphost:

* TypeScript

  apphost.mts

  ```typescript
  builder.addPythonApp("hostedagent", "./agent-code", "main.py")
    .withUv()
    .asHostedAgent();
  ```

* C#

  AppHost.cs

  ```csharp
  builder.AddPythonApp("hostedagent", "./agent-code", "main.py")
    .WithUv()
    .AsHostedAgent();
  ```

Microsoft Foundry hosted agents also include deployment fixes: project endpoints now use the correct `customSubDomainName` format, the Foundry-created agent identity receives the Cognitive Services User role automatically, and the app identity is no longer incorrectly injected into the hosted-agent environment. Foundry references also expose more environment variables, including a dedicated `ENDPOINT_AI_INFERENCE` value for the AI inference endpoint.

### RabbitMQ default image

[Section titled “RabbitMQ default image”](#rabbitmq-default-image)

The default RabbitMQ container image has been bumped from 4.2 to 4.3. Existing AppHosts pick up the new image automatically on the next run; pin a specific tag with [`WithImageTag`](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods/#withimagetag "Allows overriding the image tag on a container.")[`withImageTag`](/reference/api/typescript/aspire.hosting/withimagetag/ "Allows overriding the image tag on a container.") if you need to stay on a particular version.

For RabbitMQ hosting setup, see the [RabbitMQ integration](/integrations/messaging/rabbitmq/rabbitmq-host/).

### PostgreSQL default image

[Section titled “PostgreSQL default image”](#postgresql-default-image)

The default PostgreSQL container image has been bumped from 17.6 to 18.3. PostgreSQL 18 changed the on-disk data layout, so an existing `WithDataVolume()` data volume created on PostgreSQL 17 (Aspire 13.3 or earlier) is incompatible after upgrading and the container fails to start. Pin the image back to `17.6` with `WithImageTag("17.6")` before `WithDataVolume()` to keep using the existing volume with no migration. See [Breaking changes](#breaking-changes) for recovery options.

For PostgreSQL hosting setup and data volume guidance, see the [PostgreSQL integration](/integrations/databases/postgres/postgres-host/#postgresql-18-data-directory-change).

## 🙏 Community

[Section titled “🙏 Community”](#-community)

Aspire is built in the open, and this release wouldn’t be what it is without you. A huge thank you to all community contributors who helped make Aspire 13.4 possible — including [@edmondshtogu](https://github.com/edmondshtogu) for the work behind the Go hosting integration, [@javiercn](https://github.com/javiercn) for Blazor WebAssembly hosting, [@afscrome](https://github.com/afscrome) for `WithHidden()`, dynamically assigned dashboard endpoint ports, and an `aspire ps` hang fix, [@mtmk](https://github.com/mtmk) for the NATS client update, [@ellahathaway](https://github.com/ellahathaway) for friendlier `aspire new` NuGet feed errors, [@nightt5879](https://github.com/nightt5879) for the console logs empty state, [@vsantele](https://github.com/vsantele) for pnpm workspace Dockerfile support, [@sliekens](https://github.com/sliekens) for Docker Compose `.env` improvements, [@Bertolossi](https://github.com/Bertolossi) for fixing an `aspire run` watch-mode hang, and [@arpitjain099](https://github.com/arpitjain099) for CI permission hardening.

### The Aspire core team is

* [![Adam Ratzman](https://github.com/adamint.png?size=96)Adam Ratzman](https://github.com/adamint)
* [![Ankit Jain](https://github.com/radical.png?size=96)Ankit Jain](https://github.com/radical)
* [![Damian Edwards](https://github.com/DamianEdwards.png?size=96)Damian Edwards](https://github.com/DamianEdwards)
* [![David Fowler](https://github.com/davidfowl.png?size=96)David Fowler](https://github.com/davidfowl)
* [![David Negstad](https://github.com/danegsta.png?size=96)David Negstad](https://github.com/danegsta)
* [![David Pine](https://github.com/IEvangelist.png?size=96)David Pine](https://github.com/IEvangelist)
* [![Ella Hathaway](https://github.com/ellahathaway.png?size=96)Ella Hathaway](https://github.com/ellahathaway)
* [![Eric Erhardt](https://github.com/eerhardt.png?size=96)Eric Erhardt](https://github.com/eerhardt)
* [![James Newton-King](https://github.com/JamesNK.png?size=96)James Newton-King](https://github.com/JamesNK)
* [![José Pérez](https://github.com/joperezr.png?size=96)José Pérez](https://github.com/joperezr)
* [![Karol Zadora-Przylecki](https://github.com/karolz-ms.png?size=96)Karol Zadora-Przylecki](https://github.com/karolz-ms)
* [![Maddy Montaquila](https://github.com/maddymontaquila.png?size=96)Maddy Montaquila](https://github.com/maddymontaquila)
* [![Mitch Denny](https://github.com/mitchdenny.png?size=96)Mitch Denny](https://github.com/mitchdenny)
* [![Sébastien Ros](https://github.com/sebastienros.png?size=96)Sébastien Ros](https://github.com/sebastienros)

Special thanks to everyone whose pull requests shipped in Aspire 13.4, including:

[@afscrome](https://github.com/afscrome), [@alirezafzali](https://github.com/alirezafzali), [@arpitjain099](https://github.com/arpitjain099), [@Bertolossi](https://github.com/Bertolossi), [@edmondshtogu](https://github.com/edmondshtogu), [@javiercn](https://github.com/javiercn), [@McDonaldSean](https://github.com/McDonaldSean), [@mikeharder](https://github.com/mikeharder), [@mtmk](https://github.com/mtmk), [@nightt5879](https://github.com/nightt5879), [@RudyCo](https://github.com/RudyCo), [@sliekens](https://github.com/sliekens), [@spboyer](https://github.com/spboyer), [@tommasodotNET](https://github.com/tommasodotNET), [@Victor-johnsson](https://github.com/Victor-johnsson), [@vsantele](https://github.com/vsantele), and [@Waleed-KH](https://github.com/Waleed-KH)

We're always excited to [see community contributions](/community/contributors/)! If you'd like to get involved, check out our [contributing guide](/community/contributor-guide/).

## Legacy `apphost.ts` projects (pre-13.4)

[Section titled “Legacy apphost.ts projects (pre-13.4)”](#legacy-apphostts-projects-pre-134)

TypeScript AppHosts scaffolded by Aspire CLI versions earlier than 13.4 use a slightly different layout: the entry point was `apphost.ts` (not `apphost.mts`), and the generated TypeScript SDK lives in `./.modules/` (not `./.aspire/modules/`):

* my-apphost/

  * .modules/ Generated TypeScript SDK (do not edit)

    * aspire.ts
    * base.ts
    * transport.ts

  * apphost.ts Your AppHost entry point

  * aspire.config.json Aspire configuration

  * package.json

  * tsconfig.apphost.json

The pre-13.4 entry point imports the SDK with the `.js` extension:

apphost.ts (pre-13.4)

```typescript
import { createBuilder } from './.modules/aspire.js';
```

### Compatibility in 13.4

[Section titled “Compatibility in 13.4”](#compatibility-in-134)

The 13.4 Aspire CLI keeps these projects working without any changes:

* When the CLI sees an `apphost.ts` file with no `apphost.mts` alongside it — either because `aspire.config.json` sets `appHost.path` to `apphost.ts`, or because a disk scan finds `apphost.ts` and no `apphost.mts` — it switches to the legacy output layout for that project.
* Generated SDK files are written to `./.modules/` instead of `./.aspire/modules/`.
* Generated files are rewritten from `.mts`/`.mjs` to `.ts`/`.js`, including the inter-module import specifiers inside the SDK, so the existing `./.modules/aspire.js` import in your `apphost.ts` continues to resolve.

`aspire add`, `aspire restore`, `aspire run`, and `aspire start` all continue to work against an existing `apphost.ts` project with no edits required.

Tip

You don’t need to migrate to keep your existing TypeScript AppHost running on Aspire 13.4. The compatibility path is automatic. Migrate only if you want the new default layout — for example, to match the file tree shown in newer documentation and samples.

### Migrating to the new `apphost.mts` layout

[Section titled “Migrating to the new apphost.mts layout”](#migrating-to-the-new-apphostmts-layout)

If you’d like to move an existing project to the new default layout, the migration is mechanical. The steps below assume an AppHost root with `apphost.ts`, `./.modules/`, and the legacy `appHost.path` value:

1. Rename the entry point file.

   Rename the AppHost entry point

   ```bash
   git mv apphost.ts apphost.mts
   ```

2. Update the SDK import in `apphost.mts` to use the new folder and the `.mjs` extension:

   apphost.mts

   ```diff
   -import { createBuilder } from './.modules/aspire.js';
   +import { createBuilder } from './.aspire/modules/aspire.mjs';
   ```

3. Update `appHost.path` in `aspire.config.json`:

   aspire.config.json

   ```diff
   {
     "appHost": {
       "path": "apphost.ts",
       "path": "apphost.mts",
       "language": "typescript/nodejs"
     }
   }
   ```

4. Update `tsconfig.apphost.json` so its `include` (and any related glob) entries point at the new file and folder. Replace references to `apphost.ts` with `apphost.mts`, and references to `.modules/` with `.aspire/modules/`. For example:

   tsconfig.apphost.json

   ```diff
   {
     "compilerOptions": { /* ... */ },
     "include": [
       "apphost.ts",
       ".modules/**/*.ts",
       "apphost.mts",
       ".aspire/modules/**/*.mts"
     ]
   }
   ```

5. Delete the old generated SDK folder and regenerate. The CLI now writes the SDK under `./.aspire/modules/`, so the old folder is no longer used:

   Regenerate the TypeScript SDK

   ```bash
   rm -rf .modules
   aspire restore
   ```

   If your `.gitignore` ignores `.modules/`, replace that entry with `.aspire/` or `.aspire/modules/` to match the new location.

After migrating, `aspire run` behaves exactly the same as before — the CLI now uses the modern output path because `apphost.mts` is present.

## ⚠️ Breaking changes

[Section titled “⚠️ Breaking changes”](#️-breaking-changes)

Aspire 13.4 includes several breaking changes. Most are small renames or configuration moves, but a few affect deployment and the non-C# AppHost SDK layout. Review the subsections that apply to your app before upgrading.

### `aspire exec` command removed

[Section titled “aspire exec command removed”](#aspire-exec-command-removed)

The experimental `aspire exec` command — along with its AppHost backchannel and feature flag — has been removed.

Remove scripts or workflows that call `aspire exec`. For resource-specific actions, use [`aspire resource`](/reference/cli/commands/aspire-resource/) when the resource exposes a command.

### Generated TypeScript modules consolidated under `.aspire/modules/`

[Section titled “Generated TypeScript modules consolidated under .aspire/modules/”](#generated-typescript-modules-consolidated-under-aspiremodules)

Generated non-C# SDK modules now live under a single `.aspire/modules/` directory instead of being split across `.modules/` and `.aspire/`. Generated language references — TypeScript imports, Go replace directives, Python editable paths, Java source lists, and Rust module paths — are updated automatically to point at the new location.

Re-run `aspire run` (or your code-generation step) to regenerate references, and update any custom tooling or `.gitignore` entries that referenced the old `.modules/` path.

Note

Existing `apphost.ts` projects continue to use the legacy `./.modules/` layout for compatibility; new projects use `.aspire/modules/`.

### Persistent executable and project lifetimes

[Section titled “Persistent executable and project lifetimes”](#persistent-executable-and-project-lifetimes)

Support for persistent lifetimes on executables and projects updates the underlying DCP executable model (new `persistent`, `start`, and `stop` fields). Persistent executables and projects default to proxyless endpoints, require concrete ports for executables, don’t support replicas, and aren’t compatible with Aspire IDE debugging sessions. Persistent containers use proxied endpoints by default, matching session container behavior, so integrations that depend on endpoint allocation before startup work correctly without changes.

If you adopt `WithPersistentLifetime()`, review endpoint and port configuration. Tooling pinned to the previous DCP executable schema may need to be updated. See [Configure resource lifetimes](/app-host/resource-lifetimes/).

### Kubernetes `Ingress` `WithRoute(...)` renamed to `WithPath(...)`

[Section titled “Kubernetes Ingress WithRoute(...) renamed to WithPath(...)”](#kubernetes-ingress-withroute-renamed-to-withpath)

The Kubernetes `Ingress` routing API has been renamed from `WithRoute(...)` to `WithPath(...)` to match Kubernetes Ingress path-rule terminology and disambiguate it from the Gateway API. The shared `IngressPathType` enum is also split into `KubernetesIngressPathType` (Ingress) and `KubernetesGatewayPathType` (Gateway API).

Update `ingress.WithRoute(...)` calls to `ingress.WithPath(...)`, and switch any `IngressPathType` references to the appropriate split enum. The Gateway API `gateway.WithRoute(...)` is unchanged.

### Kubernetes ingress and gateway routes require external endpoints

[Section titled “Kubernetes ingress and gateway routes require external endpoints”](#kubernetes-ingress-and-gateway-routes-require-external-endpoints)

Routing a non-external endpoint through a Kubernetes ingress or gateway now throws an `InvalidOperationException` at publish time instead of generating routes that can’t resolve.

Call [`WithExternalHttpEndpoints`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withexternalhttpendpoints "Marks existing http or https endpoints on a resource as external.")[`withExternalHttpEndpoints`](/reference/api/typescript/aspire.hosting/withexternalhttpendpoints/ "Marks existing http or https endpoints on a resource as external.") (or otherwise mark the endpoint external) on any resource whose endpoint you route through an ingress or gateway.

### Kubernetes Helm configuration consolidated on `WithHelm(...)`

[Section titled “Kubernetes Helm configuration consolidated on WithHelm(...)”](#kubernetes-helm-configuration-consolidated-on-withhelm)

Helm chart name, version, description, release name, and namespace are now configured through the `WithHelm(...)` extension method, replacing the parallel property-based configuration surface on `KubernetesEnvironmentResource`.

Move property assignments into the `WithHelm(...)` builder. See the [Kubernetes integration](/integrations/compute/kubernetes/#configure-helm-chart-options).

### Azure Front Door uses Azure.Provisioning name generation

[Section titled “Azure Front Door uses Azure.Provisioning name generation”](#azure-front-door-uses-azureprovisioning-name-generation)

Azure Front Door CDN resources now use Azure.Provisioning’s built-in name-generation algorithm instead of Aspire’s custom logic. Upgrading an existing deployment can produce duplicate endpoint, origin group, or route names.

Remove and re-add the affected resource, or set its `Name` explicitly with `ConfigureInfrastructure`, to avoid conflicts.

### Foundry hosted agents: `WithComputeEnvironment` and `AddPromptAgent`

[Section titled “Foundry hosted agents: WithComputeEnvironment and AddPromptAgent”](#foundry-hosted-agents-withcomputeenvironment-and-addpromptagent)

The Azure AI Foundry hosted-agent API has been aligned with the rest of the app model: `PublishAsHostedAgent` is renamed to [`WithComputeEnvironment`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withcomputeenvironment "Configures the compute environment for the compute resource.")[`withComputeEnvironment`](/reference/api/typescript/aspire.hosting/withcomputeenvironment/ "Configures the compute environment for the compute resource."), [`AddPromptAgent`](/reference/api/csharp/aspire.hosting.foundry/promptagentbuilderextensions/methods/#addpromptagent "Adds a prompt agent to a Microsoft Foundry project with the specified tools.")[`addPromptAgent`](/reference/api/typescript/aspire.hosting.foundry/addpromptagent/ "Adds a prompt agent to a Microsoft Foundry project with the specified tools.") now takes the resource name as its first parameter (before the model), and the preview-only [`AsHostedAgent`](/reference/api/csharp/aspire.hosting.foundry/hostedagentresourcebuilderextensions/methods/#ashostedagent "Configures the resource to run and publish as a Microsoft Foundry hosted agent.")[`asHostedAgent`](/reference/api/typescript/aspire.hosting.foundry/ashostedagent/ "Configures the resource to run and publish as a hosted agent in Microsoft Foundry using the Responses protocol version 2.0.0.") / `RunAsHostedAgent` methods were removed.

Update hosted-agent registrations to call `WithComputeEnvironment` and pass the resource name first to `AddPromptAgent`.

### `PublishAsNpmPackageScript` renamed to `PublishAsPackageScript`

[Section titled “PublishAsNpmPackageScript renamed to PublishAsPackageScript”](#publishasnpmpackagescript-renamed-to-publishaspackagescript)

The npm-specific publish helper has been generalized to support npm, pnpm, Yarn, and Bun. `PublishAsNpmPackageScript` is renamed to [`PublishAsPackageScript`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#publishaspackagescript "Configures the JavaScript application to publish as a server that runs a package manager script at runtime.")[`publishAsPackageScript`](/reference/api/typescript/aspire.hosting.javascript/publishaspackagescript/ "Configures the JavaScript application to publish as a server that runs a package manager script at runtime."), and its `startScriptName` parameter is renamed to `scriptName`.

Rename call sites from `PublishAsNpmPackageScript(...)` to `PublishAsPackageScript(...)` and update the parameter name.

### Keycloak exposes an HTTPS primary endpoint

[Section titled “Keycloak exposes an HTTPS primary endpoint”](#keycloak-exposes-an-https-primary-endpoint)

The primary Keycloak endpoint is now HTTPS when the developer certificate is enabled, which fixes token invalidation on restart.

Update references that assumed an HTTP primary endpoint to use the HTTPS endpoint.

### PostgreSQL default image bumped to 18.3, breaking existing data volumes

[Section titled “PostgreSQL default image bumped to 18.3, breaking existing data volumes”](#postgresql-default-image-bumped-to-183-breaking-existing-data-volumes)

The default PostgreSQL container image used by [`AddPostgres`](/reference/api/csharp/aspire.hosting.postgresql/postgresbuilderextensions/methods/#addpostgres "Adds a PostgreSQL resource to the application model. A container is used for local development.")[`addPostgres`](/reference/api/typescript/aspire.hosting.postgresql/addpostgres/ "Adds a PostgreSQL resource to the application model. A container is used for local development.") moved from 17.6 to 18.3. PostgreSQL 18 changed the on-disk data layout: the official `postgres` image now stores cluster files under a major-version-specific subdirectory of `/var/lib/postgresql` (for example, `/var/lib/postgresql/18/docker`), whereas PostgreSQL 17 and earlier stored data directly in `/var/lib/postgresql/data`.

As a result, existing PostgreSQL data persisted with `WithDataVolume()` (a Docker volume) or `WithDataBindMount()` (a host bind mount) on PostgreSQL 17 (Aspire 13.3 or earlier) is incompatible with PostgreSQL 18 after upgrading to 13.4. The container fails to start with an error similar to:

```text
Error: in 18+, these Docker images are configured to store database data in a format which is compatible with "pg_ctlcluster" ... Counter to that, there appears to be PostgreSQL data in: /var/lib/postgresql
```

You have two ways to recover:

* **Stay on PostgreSQL 17 (recommended, no migration).** Pin the image back to a 17 tag with `WithImageTag("17.6")` **before** calling `WithDataVolume()`. The data directory is selected from the configured tag at the time `WithDataVolume()` runs, so the tag must be set first. Aspire then chooses the legacy `/var/lib/postgresql/data` path and your existing volume keeps working:

  ```csharp
  var db = builder.AddPostgres("pgsql").WithImageTag("17.6").WithDataVolume();
  ```

* **Upgrade the persisted data to PostgreSQL 18.** Follow the official [PostgreSQL upgrade documentation](https://www.postgresql.org/docs/current/upgrading.html) using `pg_dumpall`/restore or `pg_upgrade`, and always back up the data first. If the data is disposable, stop the app, remove any container still referencing it, then remove the volume or bind mount data so Aspire creates fresh PostgreSQL 18 data on the next run.

For full guidance and the container path mapping, see [PostgreSQL 18 data directory change](/integrations/databases/postgres/postgres-host/#postgresql-18-data-directory-change).

### Behavior changes to audit

[Section titled “Behavior changes to audit”](#behavior-changes-to-audit)

* `aspire update` now requires `--yes` in non-interactive mode, matching `aspire destroy`.
* Resource command arguments are named options in the CLI instead of positional values.
* TypeScript AppHosts are validated before startup, so invalid TypeScript fails earlier.
* `CreateHttpClient` and `GetEndpointUriString` in `Aspire.Hosting.Testing` now prefer the `https` endpoint when no endpoint name is given; pass an explicit endpoint name if your tests relied on the previous `http`-first behavior.
* The default RabbitMQ container image moved from 4.2 to 4.3, which rejects transient non-exclusive queue declarations by default.
* The default PostgreSQL container image moved from 17.6 to 18.3, which changes the on-disk data layout and breaks PostgreSQL 17 data persisted with `WithDataVolume()` or `WithDataBindMount()`.
* `AddNatsClient` now also registers `INatsClient` and a default serializer registry; user-provided registries still take precedence.

### Migration from Aspire 13.3 to 13.4

[Section titled “Migration from Aspire 13.3 to 13.4”](#migration-from-aspire-133-to-134)

1. Update the CLI by running `aspire update --self`. This step is **required** for TypeScript AppHosts; running `aspire update` against a 13.3.x TypeScript project before updating the CLI fails with `No code generator found for language: TypeScript` and leaves the project in a partially-upgraded, unrunnable state (see [microsoft/aspire#17077](https://github.com/microsoft/aspire/issues/17077)).
2. Update your projects by running `aspire update` from the root of your repository. For non-C# AppHosts, this regenerates SDK modules under `.aspire/modules/`.
3. Run `aspire doctor` to check your environment setup and spot conflicting CLI installs.
4. Audit scripts and CI for removed or changed commands, including `aspire exec` and non-interactive `aspire update` calls.
5. Update Kubernetes deployment code by moving Helm chart properties into `WithHelm(...)`, renaming `ingress.WithRoute(...)` to `ingress.WithPath(...)`, and marking routed endpoints external with `WithExternalHttpEndpoints()`.
6. Update renamed APIs: `PublishAsNpmPackageScript` became `PublishAsPackageScript`, and Foundry hosted agents use `WithComputeEnvironment` instead of `PublishAsHostedAgent`, with the new `AddPromptAgent` parameter order.
7. Review Keycloak references for the HTTPS primary endpoint and Azure Front Door deployments for naming conflicts with Azure.Provisioning. Set explicit names if needed.
8. Review RabbitMQ queue declarations if your app creates transient, non-exclusive queues. The default RabbitMQ image is now 4.3, which rejects that deprecated queue pattern by default. For migration guidance, see [RabbitMQ 4.3 queue declaration requirements](/integrations/messaging/rabbitmq/rabbitmq-host/#rabbitmq-4-3-queue-declaration-requirements).
9. Review PostgreSQL data persistence if your app uses `WithDataVolume()` or `WithDataBindMount()`. The default PostgreSQL image is now 18.3, which changes the on-disk data layout and breaks PostgreSQL 17 data persisted by either API. Pin `WithImageTag("17.6")` before `WithDataVolume()` to keep using the existing volume, or migrate the data. See [PostgreSQL 18 data directory change](/integrations/databases/postgres/postgres-host/#postgresql-18-data-directory-change).

We’d love to hear about your experience with Aspire 13.4. Share what you’re building on [GitHub](https://github.com/microsoft/aspire/issues) or join us on [Discord](https://aka.ms/aspire-discord).

# What's new in Aspire 13.5

> Explore Aspire 13.5 updates for interactive AppHosts, TypeScript GA, the CLI, dashboard, Visual Studio Code, and cloud deployment.

Aspire 13.5 makes AppHosts more interactive with terminal sessions, an Interaction Service shared by C# and TypeScript, and user-defined resource command arguments. It also brings TypeScript AppHosts to **general availability**, adds HTTPS developer certificates and persistent Kubernetes volumes, and refreshes the CLI, dashboard, and Aspire extension for Visual Studio Code.

We’d love to hear what you think. Drop by [ Discord](https://aka.ms/aspire-discord) to chat with the team and the community, or file feedback and issues on [ GitHub](https://github.com/microsoft/aspire/issues).

This release introduces:

* More interactive AppHosts with terminal sessions, richer user interactions, command arguments, HTTPS certificates, and cross-scope Azure references.
* Generally available TypeScript AppHosts with custom health checks, container file copying, faster startup, and reliability fixes.
* A smoother toolchain across the Aspire CLI, dashboard, and Visual Studio Code extension, with easier installation, sharper telemetry filtering, debugging, discovery, and resource commands.
* Persistent storage for Kubernetes and AKS and more predictable Azure hosting.
* A preview Radius deployment target through the new `Aspire.Hosting.Radius` package, plus updates to Foundry Local, Redis modules, dev tunnels, and Blazor gateway publishing.
* Updated project templates, including .NET 11 preview support.
* …and much more.

## 🆙 Upgrade to Aspire 13.5

[Section titled “🆙 Upgrade to Aspire 13.5”](#-upgrade-to-aspire-135)



Caution

Aspire 13.5 includes breaking changes. Please review the [Breaking changes](#breaking-changes) section before upgrading.

If your Aspire CLI version is earlier than 13, first [install the latest stable version](/get-started/install-cli/).

For general purpose upgrade guidance, see [Upgrade Aspire](/whats-new/upgrade-aspire/).

The easiest way to upgrade to Aspire 13.5 is using the [`aspire update` command](/reference/cli/commands/aspire-update/):

1. Update the Aspire CLI itself:

   Aspire CLI — Update the CLI

   ```bash
   aspire update --self
   ```

2. Update your projects (run from the root of your repository):

   Aspire CLI — Update all Aspire packages

   ```bash
   aspire update
   ```

Or install the CLI from scratch. The Aspire CLI ships through the package managers you already use — added in the 13.4 timeframe and now the recommended way to get it — so pick whichever fits your environment:

* Homebrew

  Install with Homebrew

  ```bash
  brew install --cask microsoft/aspire/aspire
  ```

* npm

  Install with npm

  ```bash
  npm install -g @microsoft/aspire-cli
  ```

* NuGet

  Install with the .NET CLI

  ```bash
  dotnet tool install -g Aspire.Cli
  ```

* WinGet

  Install with WinGet

  ```powershell
  winget install Microsoft.Aspire
  ```

* mise

  Install with mise

  ```bash
  mise use -g aspire
  ```

* Nix

  Install with Nix

  ```bash
  nix profile add github:microsoft/aspire#aspire-cli
  ```

Prefer the one-line install script? It still works everywhere:

* Bash

  Aspire CLI — Install Aspire CLI

  ```bash
  curl -sSL https://aspire.dev/install.sh | bash
  ```

* PowerShell

  Aspire CLI — Install Aspire CLI

  ```powershell
  irm https://aspire.dev/install.ps1 | iex
  ```

For every installation method, see [Install the CLI](/get-started/install-cli/).

C# AppHosts now default to the CLI bundle

New C# AppHosts created from the 13.5 templates set `AspireUseCliBundle=true`, so they resolve the [Aspire CLI bundle](#cli-bundle-by-default) instead of referencing the Dashboard and DCP packages directly. If you run from the .NET CLI, there’s nothing manual to do — `dotnet run` acquires the bundle on the fly with `dnx` and delegates to `aspire run`. It’s a behavior change worth knowing about; existing projects are unaffected unless they opt in, because the SDK default remains `AspireUseCliBundle=false`.

## 🧩 App model and AppHost

[Section titled “🧩 App model and AppHost”](#-app-model-and-apphost)

The AppHost is where 13.5 invests most heavily. These additions make local development more interactive and bring the C# and TypeScript app models closer to parity — from terminal sessions and richer user interactions to modeling more kinds of resources.

### 🖥️ Interactive terminal sessions with WithTerminal()

[Section titled “🖥️ Interactive terminal sessions with WithTerminal()”](#️-interactive-terminal-sessions-with-withterminal)

AppHost authors can now call [`WithTerminal`](/reference/api/csharp/aspire.hosting/terminalresourcebuilderextensions/methods/#withterminal "Configures a resource to expose an interactive terminal session.")[`withTerminal`](/reference/api/typescript/aspire.hosting/withterminal/ "Adds an interactive terminal session to a resource using the default terminal options.") on a resource to enable an interactive terminal session. The dashboard can attach to and detach from the session at will, so you can drive REPLs, shells, and other terminal programs that run as Aspire resources — right from the dashboard’s terminal view. Terminal dimensions are configurable through `TerminalOptions`, which exposes `Columns` (default `120`), `Rows` (default `30`), and `ShowTerminalHost`.

Caution

`WithTerminal()` and `TerminalOptions` are experimental. C# callers must suppress the `ASPIRETERMINAL001` diagnostic to use them, and the API may change in a future release. The matching `aspire terminal` CLI command is hidden behind a feature flag while the feature is experimental — enable it with `aspire config set features.terminalCommandsEnabled true`.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  // Polyglot AppHosts expose a parameterless withTerminal(). Terminal dimensions
  // (TerminalOptions.Columns/Rows) can only be configured from C#.
  await builder.addContainer('db', 'postgres').withTerminal();


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  #pragma warning disable ASPIRETERMINAL001


  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddContainer("db", "postgres")
      .WithTerminal(options =>
      {
          options.Columns = 200;
          options.Rows = 50;
      });


  builder.Build().Run();
  ```

For details, see [Interactive terminal sessions with WithTerminal()](/app-host/with-terminal/).

### 💬 Interaction Service for C# and TypeScript AppHosts

[Section titled “💬 Interaction Service for C# and TypeScript AppHosts”](#-interaction-service-for-c-and-typescript-apphosts)

The Interaction Service and its related types now work the same way from C# and TypeScript AppHosts, including prompts, message boxes, notifications, and dynamic inputs. The core prompt and input APIs (`PromptInputAsync`, `PromptInputsAsync`, `InteractionInput`, `InputType`, and `InteractionInputCollection`) are now **stable**, so you no longer have to suppress `ASPIREINTERACTION001` in production code.

The example below adds a resource command that prompts the user to choose a region, then acts on the selection.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';
  import type { InteractionChoiceOption } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const api = await builder.addContainer('api', 'nginx');


  await api.withCommand('configure-region', 'Configure region', async (ctx) => {
    const interaction = await ctx.services().getInteractionService();


    if (!(await interaction.isAvailable())) {
      return { success: true, message: 'No interactive dashboard.' };
    }


    const regionInput = await interaction.createChoiceInput('region', {
      choices: [
        { value: 'us', label: 'United States' },
        { value: 'eu', label: 'Europe' },
      ] as InteractionChoiceOption[],
    });


    const result = await interaction.promptInputs(
      'Configure region',
      'Choose the region to deploy to.',
      [regionInput],
      { primaryButtonText: 'Apply' }
    );


    if (await result.canceled()) {
      return { success: false, message: 'Canceled.' };
    }


    const region = await result.inputs().value('region');
    return { success: true, message: `region=${region ?? ''}` };
  });


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  using Aspire.Hosting.ApplicationModel;
  using Microsoft.Extensions.DependencyInjection;


  var builder = DistributedApplication.CreateBuilder(args);


  var api = builder.AddContainer("api", "nginx");


  api.WithCommand("configure-region", "Configure region", async ctx =>
  {
      var interaction = ctx.Services.GetRequiredService();


      // Commands invoked from the CLI run with NonInteractive = true, where
      // PromptInputsAsync throws. Only prompt when a UI is attached.
      if (!interaction.IsAvailable)
      {
          return CommandResults.Success();
      }


      var result = await interaction.PromptInputsAsync(
          title: "Configure region",
          message: "Choose the region to deploy to.",
          inputs:
          [
              new InteractionInput
              {
                  Name = "region",
                  Label = "Region",
                  InputType = InputType.Choice,
                  Options =
                  [
                      new("us", "United States"),
                      new("eu", "Europe"),
                  ]
              }
          ],
          cancellationToken: ctx.CancellationToken);


      if (result.Canceled)
      {
          return CommandResults.Canceled();
      }


      var region = result.Data["region"].Value;
      return CommandResults.Success();
  });


  builder.Build().Run();
  ```

For the full API surface and TypeScript examples, see [Interaction service](/extensibility/interaction-service/).

### 📤 File uploads and progress dialogs

[Section titled “📤 File uploads and progress dialogs”](#-file-uploads-and-progress-dialogs)

The Interaction Service can now request a file upload. Add an `InteractionInput` with `InputType.File`, and the dashboard renders a file picker constrained by an optional `FileFilter` and `MaxFileSize`. C# AppHosts read the uploaded content through `InteractionFile` with `ReadAllBytesAsync()` or `OpenRead()`. TypeScript AppHosts receive an on-disk path in `file.filePath` to read with Node’s `fs` APIs. File input is **stable**, and long-running commands can show a progress dialog with `PromptProgressAsync`.

Caution

`PromptProgressAsync`, `ProgressInteractionOptions`, and `ProgressContext` are experimental. C# callers must suppress [`ASPIREINTERACTION001`](/diagnostics/aspireinteraction001/) to use the progress-dialog APIs. The file-upload input (`InputType.File`) is stable and needs no suppression.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';
  import { statSync } from 'node:fs';


  const builder = await createBuilder();


  const importer = await builder.addContainer('importer', 'nginx');


  await importer.withCommand('import-data', 'Import data', async (ctx) => {
    const interaction = await ctx.services().getInteractionService();


    // Commands invoked from the CLI run without an attached UI, where prompting
    // throws. Only prompt when the interaction service is available.
    if (!(await interaction.isAvailable())) {
      return { success: true, message: 'No interactive dashboard.' };
    }


    const fileInput = await interaction.createFileInput('dataFile', {
      label: 'Data file',
      fileFilter: '.json',
      maxFileSize: 10 * 1024 * 1024, // 10 MB
      required: true,
    });


    const result = await interaction.promptInput(
      'Import data',
      'Select a JSON file to import.',
      fileInput,
      { primaryButtonText: 'Import' });


    if (result.canceled) {
      return { success: false, message: 'Canceled.' };
    }


    // Uploaded files are written to disk; read them through their filePath.
    const file = result.input?.files?.[0];
    if (!file?.filePath) {
      return { success: false, message: 'No file was uploaded.' };
    }


    const bytes = statSync(file.filePath).size;


    // The work callback runs while the progress dialog is shown; the dialog
    // closes when the callback completes.
    await interaction.promptProgress(`Processing ${bytes} bytes`, {
      title: 'Importing...',
      options: {
        work: async () => {
          await new Promise((resolve) => setTimeout(resolve, 2000));
        },
      },
    });


    return { success: true, message: 'Imported.' };
  });


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  #pragma warning disable ASPIREINTERACTION001


  using Aspire.Hosting.ApplicationModel;
  using Microsoft.Extensions.DependencyInjection;


  var builder = DistributedApplication.CreateBuilder(args);


  var importer = builder.AddContainer("importer", "nginx");


  importer.WithCommand("import-data", "Import data", async ctx =>
  {
      var interaction = ctx.Services.GetRequiredService();


      // Commands invoked from the CLI run with NonInteractive = true, where
      // PromptInputsAsync throws. Only prompt when a UI is attached.
      if (!interaction.IsAvailable)
      {
          return CommandResults.Success();
      }


      var result = await interaction.PromptInputsAsync(
          title: "Import data",
          message: "Select a JSON file to import.",
          inputs:
          [
              new InteractionInput
              {
                  Name = "dataFile",
                  Label = "Data file",
                  InputType = InputType.File,
                  FileFilter = ".json",
                  MaxFileSize = 10 * 1024 * 1024, // 10 MB
                  Required = true
              }
          ],
          cancellationToken: ctx.CancellationToken);


      if (result.Canceled)
      {
          return CommandResults.Canceled();
      }


      var file = result.Data["dataFile"].Files?[0];
      if (file is null)
      {
          return CommandResults.Failure("No file was uploaded.");
      }


      var bytes = await file.ReadAllBytesAsync(ctx.CancellationToken);


      // Progress dialog is experimental (ASPIREINTERACTION001). Run the work in
      // ProgressInteractionOptions.Work so the dialog closes when the work
      // completes; without a Work callback it stays open until the token cancels.
      await interaction.PromptProgressAsync(
          message: $"Processing {bytes.Length} bytes",
          title: "Importing...",
          options: new ProgressInteractionOptions
          {
              Work = async progress =>
              {
                  // Long-running processing runs here while the dialog is shown.
                  await Task.Delay(TimeSpan.FromSeconds(2), progress.CancellationToken);
              }
          },
          cancellationToken: ctx.CancellationToken);


      return CommandResults.Success();
  });


  builder.Build().Run();
  ```

For inputs, validation, and result handling, see [Interaction service](/extensibility/interaction-service/).

### ⚙️ Resource commands with user-defined arguments

[Section titled “⚙️ Resource commands with user-defined arguments”](#️-resource-commands-with-user-defined-arguments)

Resource commands can now declare named arguments. The dashboard prompts for them before the command runs, while the CLI exposes each argument as a `--` option and reports an error when a required option is missing. Populate `CommandOptions.Arguments` with `InteractionInput` descriptors, then read the values from `ExecuteCommandContext.Arguments` in the command callback. TypeScript AppHosts get the same capability through Aspire Type System (ATS) exports. The mechanism is **stable** and supports interactive deployment or setup workflows.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder, InputType } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder.addContainer('api', 'nginx').withCommand('echo', 'Echo', async (ctx) => {
    const args = await ctx.arguments();
    const message = await args.value('message');
    // Use the collected argument...
    return { success: true, message: `message=${message ?? ''}` };
  }, {
    commandOptions: {
      arguments: [
        { name: 'message', inputType: InputType.Text, required: true },
      ],
    },
  });


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  using Aspire.Hosting.ApplicationModel;


  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddContainer("api", "nginx")
      .WithCommand(
          name: "echo",
          displayName: "Echo",
          executeCommand: ctx =>
          {
              var message = ctx.Arguments["message"].Value;
              // Use the collected argument...
              return Task.FromResult(CommandResults.Success());
          },
          commandOptions: new CommandOptions
          {
              Description = "Echo a message.",
              Arguments =
              [
                  new InteractionInput
                  {
                      Name = "message",
                      Label = "Message",
                      InputType = InputType.Text,
                      Required = true
                  }
              ]
          });


  builder.Build().Run();
  ```

For the full command API, see [Custom resource commands](/fundamentals/custom-resource-commands/).

### 🔐 HTTPS certificates for project resources

[Section titled “🔐 HTTPS certificates for project resources”](#-https-certificates-for-project-resources)

Project and executable resources can now be configured with HTTPS certificates directly from the AppHost. Use [`WithHttpsDeveloperCertificate`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withhttpsdevelopercertificate "Indicates that a resource should use the developer certificate key pair for HTTPS endpoints at run time. Currently this indicates use of the ASP.NET Core...")[`withHttpsDeveloperCertificate`](/reference/api/typescript/aspire.hosting/withhttpsdevelopercertificate/ "Indicates that a resource should use the developer certificate key pair for HTTPS endpoints at run time. Currently this indicates use of the ASP.NET Core...") to inject the local ASP.NET Core developer certificate, `WithHttpsCertificate(certificate, password)` to supply an explicit `X509Certificate2`, or [`WithHttpsCertificateConfiguration`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withhttpscertificateconfiguration "Adds a callback that allows configuring the resource to use a specific HTTPS/TLS certificate key pair for server authentication.")[`withHttpsCertificateConfiguration`](/reference/api/typescript/aspire.hosting/withhttpscertificateconfiguration/ "Adds a callback that allows configuring the resource to use a specific HTTPS/TLS certificate key pair for server authentication.") for full control. [`WithoutHttpsCertificate`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withouthttpscertificate "Disable HTTPS/TLS server certificate configuration for the resource. No HTTPS/TLS termination configuration will be applied.")[`withoutHttpsCertificate`](/reference/api/typescript/aspire.hosting/withouthttpscertificate/ "Disable HTTPS/TLS server certificate configuration for the resource. No HTTPS/TLS termination configuration will be applied.") opts a resource out.

Caution

The HTTPS certificate APIs are experimental. C# callers must suppress [`ASPIRECERTIFICATES001`](/diagnostics/aspirecertificates001/) to use them.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder.addProject('api', './src/Api').withHttpsDeveloperCertificate();


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  #pragma warning disable ASPIRECERTIFICATES001


  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddProject("api")
      .WithHttpsDeveloperCertificate();


  builder.Build().Run();
  ```

For certificate options and deployment considerations, see [Certificate configuration](/app-host/certificate-configuration/).

### ☁️ Reference existing Azure resources across scopes

[Section titled “☁️ Reference existing Azure resources across scopes”](#️-reference-existing-azure-resources-across-scopes)

Aspire 13.5 makes it easier to point at Azure resources that live **outside** your app’s own resource group, subscription, or tenant. The `AsExistingInResourceGroup(name, resourceGroup, subscription)`, `AsExistingInSubscription(name, subscription)`, and `AsExistingInTenant(name)` methods — along with their `RunAsExisting*` and `PublishAsExisting*` variants — attach an existing-resource annotation so provisioning references the resource in the scope you specify. Each accepts either literal strings or `ParameterResource` values, so scope details can come from parameters and secrets.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const name = await builder.addParameter('sb-name');
  const resourceGroup = await builder.addParameter('sb-rg');
  const subscription = await builder.addParameter('sb-sub');


  await builder.addAzureServiceBus('sb')
    .asExistingInResourceGroup(name, resourceGroup, subscription);


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  var name = builder.AddParameter("sb-name");
  var resourceGroup = builder.AddParameter("sb-rg");
  var subscription = builder.AddParameter("sb-sub");


  builder.AddAzureServiceBus("sb")
      .AsExistingInResourceGroup(name, resourceGroup, subscription);


  builder.Build().Run();
  ```

For run- versus publish-mode behavior, see [Use existing Azure resources](/integrations/cloud/azure/customize-resources/).

## 🟦 TypeScript AppHost improvements

[Section titled “🟦 TypeScript AppHost improvements”](#-typescript-apphost-improvements)

TypeScript (and polyglot) AppHost support is now **generally available** in 13.5 — the `ASPIREATS001` experimental diagnostic is gone, so you no longer suppress anything to author an AppHost in TypeScript. With GA in place, this release closes several remaining gaps with C#.

### 💚 Custom health checks

[Section titled “💚 Custom health checks”](#-custom-health-checks)

TypeScript AppHosts can now register custom health check callbacks with `builder.addHealthCheck(name, check)` and attach them (or the built-in checks) to a resource with `resource.withHealthCheck(key)`. The callback returns a `HealthCheckResult` with a `status`, optional `description`, and optional `data`. Project resources also gain `withEndpointsInEnvironment(endpointNames)` to control which endpoints are injected into environment variables. This brings TypeScript to parity with C#, where custom checks are registered through `AddHealthChecks().AddCheck(...)` and attached with the same `WithHealthCheck(key)` method.

apphost.mts

```typescript
import { createBuilder, HealthStatus } from './.aspire/modules/aspire.mjs';
import type { HealthCheckResult } from './.aspire/modules/aspire.mjs';


const builder = await createBuilder();


const myCheck = async (): Promise => ({
  status: HealthStatus.Healthy,
  description: 'All systems nominal',
  data: { version: '1.0' },
});
await builder.addHealthCheck('my_check', myCheck);


await builder.addRedis('cache').withHealthCheck('my_check');


await builder.build().run();
```

For the TypeScript AppHost model, see [TypeScript AppHost](/app-host/typescript-apphost/), and for health checks in general, see [Health checks](/fundamentals/health-checks/).

### 🐳 Container file copying

[Section titled “🐳 Container file copying”](#-container-file-copying)

TypeScript AppHosts can now copy host files into container resources, reaching parity with C#. Use `withContainerFiles(destinationPath, sourcePath, options)` to copy a directory, or `withContainerFilesCallback(destinationPath, callback, options)` to generate files dynamically at build time. Ownership and permissions are controlled through `ContainerFilesOptions` (`defaultOwner`, `defaultGroup`, `umask`). C# exposes the same capability through the `WithContainerFiles(...)` overloads, which accept either a source directory or a build-time callback.

apphost.mts

```typescript
import { createBuilder } from './.aspire/modules/aspire.mjs';


const builder = await createBuilder();


await builder.addContainer('myapp', 'nginx')
  .withContainerFiles('/usr/share/nginx/html', './wwwroot', {
    defaultOwner: 101, // nginx user UID
    defaultGroup: 101,
    umask: 0o022,
  })
  .withContainerFilesCallback('/etc/nginx/conf.d', async (ctx) => {
    const conf = await ctx.createFile('default.conf', {
      contents: 'server { listen 80; }',
      mode: 0o644,
    });
    return [conf];
  });


await builder.build().run();
```

For the full callback surface, see [Container files](/app-host/container-files/).

### ⚡ Faster startup and reliability fixes

[Section titled “⚡ Faster startup and reliability fixes”](#-faster-startup-and-reliability-fixes)

TypeScript AppHost startup no longer waits a fixed delay before the CLI attempts to connect; the CLI now races the RPC connection retry loop against process exit, reducing the time from `aspire run` to an active AppHost. This release also fixes several reliability issues:

* A deadlock where async callbacks stored in `IOptions.Configure` were invoked during `BeforeStartEvent`.
* A startup reliability issue with [`WithBrowserLogs`](/reference/api/csharp/aspire.hosting.browsers/browserlogsbuilderextensions/methods/#withbrowserlogs "Adds a child resource that can open the application's primary browser endpoint in a tracked browser session, surface browser diagnostics, and capture...")[`withBrowserLogs`](/reference/api/typescript/aspire.hosting.browsers/withbrowserlogs/ "Adds a child resource that can open the application's primary browser endpoint in a tracked browser session, surface browser diagnostics, and capture...") where tracked browser sessions could fail even when the browser eventually became responsive; the CDP startup timeout has been increased.
* Failures when proxyless container endpoint references were accessed before the container was created.
* `aspire run` failing for polyglot AppHosts that use `*.dev.localhost` resource service URLs.

## 🖥️ Aspire CLI

[Section titled “🖥️ Aspire CLI”](#️-aspire-cli)

The CLI is central to the Aspire developer experience, and 13.5 makes it easier to install, keep current, and reason about how it runs.

### 📦 Install via npm and Nix

[Section titled “📦 Install via npm and Nix”](#-install-via-npm-and-nix)

The Aspire CLI is now available as an npm package (`@microsoft/aspire-cli`), and on Nix via the flake (`nix profile add github:microsoft/aspire#aspire-cli`). The update command and update notifier detect npm-installed versions and print the matching npm command instead of overwriting the managed binary. When the CLI can’t fetch the Aspire skills bundle from GitHub release assets, it falls back to an embedded bundle and shows a non-fatal warning instead of failing the command.

For every installation method, see [Install the CLI](/get-started/install-cli/).

### 🎯 CLI bundle by default

[Section titled “🎯 CLI bundle by default”](#-cli-bundle-by-default)

The *CLI bundle* is a copy of the Aspire CLI that an AppHost can resolve for itself, so `dotnet run` and `aspire run` behave identically and everyone on the team — and CI — uses a consistent CLI version without a separate global install. In 13.5, new C# AppHosts created from the templates opt in automatically by setting `AspireUseCliBundle=true`, so the bundle is resolved out of the box.

Here’s what that means in practice:

* **Nothing manual for new projects.** When the bundle is enabled and the CLI is 13.5.0 or later, `dotnet run` acquires the bundle on the fly through `dnx` and delegates to `aspire run`. It’s a change in behavior from earlier releases, but not one you have to configure.
* **Existing projects are unaffected** unless they opt in. The SDK-level default remains opt-in (`false`); set `AspireUseCliBundle=true` in your AppHost to adopt it, or pin the CLI through a local tool manifest for reproducible `dnx` invocation.
* **The state is always explicit.** Diagnostics tell you exactly what’s happening rather than failing silently: `ASPIRE009` (error) when the bundle can’t be resolved, `ASPIRE010` (warning) when a project opts out, and `ASPIRE011` when `dnx` isn’t available. You can force the DNX invocation path with `AspireCliInvocationMode=Dnx`.

### 🛠️ Command improvements

[Section titled “🛠️ Command improvements”](#️-command-improvements)

* **`aspire stop --force`** performs a normal stop and then cleans up the AppHost’s persistent resources, permanently deleting their data without an additional confirmation prompt.
* **`aspire update --migrate`** migrates legacy TypeScript AppHost entry points (`apphost.ts` → `apphost.mts`).
* **`aspire doctor`** reports operating-system details (including Linux distro info from `/etc/os-release`), detects Visual Studio Code, and adds DCP health checks. JSON output includes a structured `operating-system` check for tooling.
* **`aspire docs search`** returns more relevant results.
* Stale AppHost backchannel sockets are pruned automatically so they no longer block commands like `aspire add`, and Ctrl+C/SIGTERM handling is more responsive during startup.

See the reference for [`aspire stop`](/reference/cli/commands/aspire-stop/), [`aspire update`](/reference/cli/commands/aspire-update/), and [`aspire doctor`](/reference/cli/commands/aspire-doctor/).

## 📊 Dashboard

[Section titled “📊 Dashboard”](#-dashboard)

The dashboard is often the first thing you see when you run an Aspire app, and 13.5 gives it a substantial refresh — official branding, sharper telemetry filtering, and a built-in terminal view.

### 🎨 Refreshed, officially branded UI

[Section titled “🎨 Refreshed, officially branded UI”](#-refreshed-officially-branded-ui)

The dashboard adopts official Aspire branding and a refreshed visual design built on a new design-token system, with accessibility improvements across the UI.

![The Aspire dashboard resources page showing the refreshed, officially branded UI with a list of running resources and their endpoints.](/_astro/projects.DUzpqXcM_Z1aIiSQ.webp)

### 🔎 Sharper telemetry filtering

[Section titled “🔎 Sharper telemetry filtering”](#-sharper-telemetry-filtering)

* Filter logs and traces by timestamp with a dedicated search qualifier.
* Match exact numeric values with the new `==` and `!=` operators.
* Filter console-log output by text.
* See a clearer reconnect dialog when the dashboard loses its AppHost connection.

![The Aspire dashboard structured logs page with a filter applied to narrow the displayed log entries.](/_astro/structured-logs-filtered.BlG-SMa0_S1U9v.webp) ![The Aspire dashboard traces page showing filtering controls used to focus on a specific set of traces.](/_astro/traces-filtering.B15XucZZ_Z2j351C.webp)

### 🖥️ Terminal view

[Section titled “🖥️ Terminal view”](#️-terminal-view)

Running resources configured with `WithTerminal()` open in a terminal view in the dashboard by default, so you can interact with the live session immediately. Resources that are waiting, starting, exited, or failed fall back to the console-logs view until they reach the running state.

The dashboard’s AI Assistant chat has been removed in Aspire 13.5.

Additional dashboard fixes include friendlier health-check error messages (in place of raw exception stacks), deduplicated replica display names, and correct telemetry streaming when resource filters are applied.

## 🧰 Visual Studio Code extension

[Section titled “🧰 Visual Studio Code extension”](#-visual-studio-code-extension)

The Aspire extension for Visual Studio Code is rebranded to **Aspire** (with an updated icon and display name) and gains a batch of new capabilities:

* Open the dashboard in a side panel instead of an external browser.
* Debug Bun through the WebKit Inspector Protocol and debug MAUI projects.
* Run Start, Stop, and custom resource commands from the tree view.
* Work with idle AppHosts discovered in the workspace through context-menu actions, including `launchUrl` from `launchSettings.json`.
* See consistent secret masking, missing-value warnings, and parameter truncation across panels.
* Respect workspace exclusions, debounce file changes during discovery, and pass terminal commands as structured shell arguments to prevent command injection.
* Use a richer extension API surface for C# Dev Kit integration.

Caution

The extension no longer opens the dashboard automatically. Opt in with the **Aspire: Dashboard Browser** setting or a `dashboardBrowser` value in `launch.json`.

For setup and usage, see [Aspire Visual Studio Code extension](/get-started/aspire-vscode-extension/).

## 🚀 Deployment

[Section titled “🚀 Deployment”](#-deployment)

Getting from local development to a deployed environment keeps getting smoother. This release adds first-class Kubernetes and AKS storage, plus more predictable Azure Container Apps naming and networking.

### 📦 Persistent volumes for Kubernetes and AKS

[Section titled “📦 Persistent volumes for Kubernetes and AKS”](#-persistent-volumes-for-kubernetes-and-aks)

You can now model Kubernetes `PersistentVolumeClaim`s as first-class resources. Call `AddPersistentVolume(name)` on a Kubernetes environment, configure it with [`WithStorageClass`](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeextensions/methods/#withstorageclass "Sets the Kubernetes storage class name on the PVC's spec.storageClassName. When unset, the cluster's default storage class is used.")[`withStorageClass`](/reference/api/typescript/aspire.hosting.kubernetes/withstorageclass/ "Sets the storage class for a persistent volume"), [`WithCapacity`](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeextensions/methods/#withcapacity "Sets the requested storage capacity on the PVC's spec.resources.requests.storage field.")[`withCapacity`](/reference/api/typescript/aspire.hosting.kubernetes/withcapacity/ "Sets the requested storage capacity for a persistent volume"), and [`WithAccessMode`](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeextensions/methods/#withaccessmode "Adds an access mode to the PVC's spec.accessModes. Call multiple times to declare more than one mode. When unset, the environment's...")[`withAccessMode`](/reference/api/typescript/aspire.hosting.kubernetes/withaccessmode/ "Adds an access mode to a persistent volume"), and bind it to a workload with [`WithPersistentVolume`](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeextensions/methods/#withpersistentvolume "Binds a workload to a Kubernetes Aspire.Hosting.Kubernetes.KubernetesPersistentVolumeResource using name matching. The workload must declare a volume with a...")[`withKubernetesPersistentVolume`](/reference/api/typescript/aspire.hosting.kubernetes/withkubernetespersistentvolume/ "Binds a workload to a Kubernetes persistent volume by matching volume name"). Any workload bound to a persistent volume is rendered as a `StatefulSet` rather than a `Deployment`. The same [`AddPersistentVolume`](/reference/api/csharp/aspire.hosting.azure.kubernetes/azurekubernetespersistentvolumeextensions/methods/#addpersistentvolume "Adds a Kubernetes PersistentVolumeClaim resource to the application model for the specified AKS environment.")[`addPersistentVolume`](/reference/api/typescript/aspire.hosting.azure.kubernetes/addpersistentvolume/ "Adds a Kubernetes PersistentVolumeClaim resource to an AKS environment") API is available on the AKS environment via `Aspire.Hosting.Azure.Kubernetes`.

Caution

The compute-environment volume APIs are experimental and emit [`ASPIRECOMPUTE002`](/diagnostics/aspirecompute002/), which C# callers must suppress to use them.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder, PersistentVolumeAccessMode } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const k8s = await builder.addKubernetesEnvironment('k8s');


  const data = await k8s.addPersistentVolume('data')
    .withStorageClass('managed-csi')
    .withCapacity('20Gi')
    .withAccessMode(PersistentVolumeAccessMode.ReadWriteOnce);


  // The polyglot withVolume() reorders parameters to (target, name?), so the
  // mount path comes first. withKubernetesPersistentVolume() then binds by name.
  await builder.addContainer('postgres', 'postgres:16')
    .withVolume('/var/lib/postgresql/data', 'data')
    .withKubernetesPersistentVolume(data);


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  #pragma warning disable ASPIRECOMPUTE002


  using Aspire.Hosting.Kubernetes;


  var builder = DistributedApplication.CreateBuilder(args);


  var k8s = builder.AddKubernetesEnvironment("k8s");


  var data = k8s.AddPersistentVolume("data")
      .WithStorageClass("managed-csi")
      .WithCapacity("20Gi")
      .WithAccessMode(PersistentVolumeAccessMode.ReadWriteOnce);


  builder.AddContainer("postgres", "postgres:16")
      .WithVolume("data", "/var/lib/postgresql/data")
      .WithPersistentVolume(data);


  builder.Build().Run();
  ```

For details, see [Persistent volumes](/deployment/kubernetes/persistent-volumes/) and [Deploy to AKS](/deployment/kubernetes/aks/).

### 🏷️ Unique resource naming for Azure Container Apps

[Section titled “🏷️ Unique resource naming for Azure Container Apps”](#️-unique-resource-naming-for-azure-container-apps)

Azure Container Apps environments can opt into deterministic, collision-resistant resource names with [`WithUniqueResourceNaming`](/reference/api/csharp/aspire.hosting.azure.appcontainers/azurecontainerappextensions/methods/#withuniqueresourcenaming "Configures the container app environment to incorporate its resource name into the generated managed environment name, so that multiple environments in the...")[`withUniqueResourceNaming`](/reference/api/typescript/aspire.hosting.azure.appcontainers/withuniqueresourcenaming/ "Configures the container app environment to incorporate its resource name into the generated managed environment name, so that multiple environments in the..."), which is useful when you deploy more than one environment into the same resource group. Names incorporate a `uniqueString(resourceGroup().id)` suffix while preserving each environment’s digits, so `cae1` and `cae2` stay distinct.

Caution

`WithUniqueResourceNaming()` is experimental and emits [`ASPIREACANAMING002`](/diagnostics/aspireacanaming002/), which C# callers must suppress to use it. Enabling it on an already-deployed environment changes the environment’s `name`, which causes Azure to recreate it — apply it to new deployments, or to environments that specifically need distinct names.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder.addAzureContainerAppEnvironment('acaenv')
    .withUniqueResourceNaming();


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  #pragma warning disable ASPIREACANAMING002


  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddAzureContainerAppEnvironment("acaenv")
      .WithUniqueResourceNaming();


  builder.Build().Run();
  ```

For more configuration options, see [Configure Azure Container Apps environments](/integrations/cloud/azure/configure-container-apps/).

### 🔗 Virtual network integration for Azure environments

[Section titled “🔗 Virtual network integration for Azure environments”](#-virtual-network-integration-for-azure-environments)

Azure Container Apps and Azure App Service environments can now be placed into a delegated subnet. Declare a subnet with `WithServiceDelegation(serviceName)`, then attach it to an environment with `WithDelegatedSubnet(subnet)`. The virtual-network builder APIs live in `Aspire.Hosting.Azure.Network` and emit the [`ASPIREAZURE003`](/diagnostics/aspireazure003/) experimental diagnostic.

For App Service hosting, see [Azure App Service hosting integration](/integrations/cloud/azure/azure-app-service/azure-app-service-host/).

## ✨ New integrations

[Section titled “✨ New integrations”](#-new-integrations)

Aspire 13.5 adds a preview [Radius](https://radapp.io/) deployment target through the new `Aspire.Hosting.Radius` package. Use `AddRadiusEnvironment(name)` with [`WithNamespace`](/reference/api/csharp/aspire.hosting.radius/radiusextensions/methods/#withnamespace "Sets the Kubernetes namespace for the Radius environment.")[`withNamespace`](/reference/api/typescript/aspire.hosting.radius/withnamespace/ "Sets the Kubernetes namespace for the Radius environment.") to publish your app to a Radius environment. Publish-time infrastructure configuration (`ConfigureRadiusInfrastructure`) and project container-image overrides are gated behind experimental diagnostics.

## 📦 Integration updates

[Section titled “📦 Integration updates”](#-integration-updates)

Existing integrations pick up new capabilities:

* **Foundry Local.** `AddFoundry(name).RunAsFoundryLocal()` now drives the installed **foundry CLI** for lifecycle management, and resources can be exposed as hosted agents with [`AsHostedAgent`](/reference/api/csharp/aspire.hosting.foundry/hostedagentresourcebuilderextensions/methods/#ashostedagent "Configures the resource to run and publish as a Microsoft Foundry hosted agent.")[`asHostedAgent`](/reference/api/typescript/aspire.hosting.foundry/ashostedagent/ "Configures the resource to run and publish as a hosted agent in Microsoft Foundry using the Responses protocol version 2.0.0."), where `HostedAgentProtocol` is `Responses` or `Invocations`.
* **Redis modules.** `AddRedis(...).WithModule(path)` loads a Redis module into the container, with `RedisModules` constants (`Json`, `Search`, `BloomFilter`, `TimeSeries`) pointing at the modules shipped in Redis 8+ images — see the sample below.
* **Dev tunnels regions.** `DevTunnelOptions.Region` (a `DevTunnelRegion?` enum) lets you pin the region a tunnel is created in.
* **Blazor gateway on Docker Compose.** Blazor gateway resources now support Docker Compose publishing.

- TypeScript

  apphost.mts

  ```typescript
  import { createBuilder, RedisModules } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder.addRedis('cache')
    .withModule(RedisModules.Json)
    .withModule(RedisModules.Search);


  await builder.build().run();
  ```

- C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddRedis("cache")
      .WithModule(RedisModules.Json)
      .WithModule(RedisModules.Search);


  builder.Build().Run();
  ```

For Redis hosting, see [Redis hosting integration](/integrations/caching/redis/redis-host/); for tunnels, see [Dev tunnels](/integrations/devtools/dev-tunnels/); for Foundry, see [Azure AI Foundry](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/).

## 🏗️ Templates

[Section titled “🏗️ Templates”](#️-templates)

New project templates target **.NET 11 preview** in addition to the current LTS, and C# AppHost templates set `AspireUseCliBundle=true` by default so freshly scaffolded projects resolve the CLI bundle out of the box.

## ⚠️ Breaking changes

[Section titled “⚠️ Breaking changes”](#️-breaking-changes)

The following breaking changes are included in Aspire 13.5:

1. **`ServiceProvider` renamed to `Services`.** The `ServiceProvider` property on hosting context types is now `Services`. Update your code to use the new property name.

2. **[`PublishAsConnectionString`](/reference/api/csharp/aspire.hosting.azure/azureresourceextensions/methods/#publishasconnectionstring "Changes the resource to be published as a connection string reference in the manifest.")[`publishAsConnectionString`](/reference/api/typescript/aspire.hosting.azure/publishasconnectionstring/ "Changes the resource to be published as a connection string reference in the manifest.") marked obsolete.** Switch to [`AddConnectionString`](/reference/api/csharp/aspire.hosting/parameterresourcebuilderextensions/methods/#addconnectionstring "Adds a parameter to the distributed application but wrapped in a resource with a connection string for use with...")[`addConnectionString`](/reference/api/typescript/aspire.hosting/addconnectionstring/ "Adds a connection string resource") in publish-mode app model code.

3. **`aspire ps --resources` and `--include-hidden` removed.** `aspire ps` now focuses on AppHost-level summaries; use `aspire describe` for detailed resource data. (`--include-hidden` remains on the `aspire resource` subcommand.)

4. **GitHub Models integration deprecated.** GitHub Models is no longer available to new customers, so `Aspire.Hosting.GitHub.Models` is deprecated. Its public APIs are marked `[Obsolete]` and the package no longer appears in `aspire add` output; it will be removed in a future release. Migrate to the [Azure AI Foundry integration](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/).

5. **Proxyless endpoint port allocation timing changed.** Proxyless endpoints without an explicit public `port` now receive one during service preparation, before workload resources are created. The default allocation range is `10000-32767` and can be overridden with `ASPIRE_PROXYLESS_ENDPOINT_PORT_RANGE=start-end`.

6. **Go polyglot: a single optional `options` DTO is now passed directly.** When an exported API has exactly one optional `options` DTO parameter, the Go code generator now passes the DTO type directly instead of wrapping it in a generated method-options struct. Go AppHosts that used the wrapper form must update their call sites after regenerating the SDK.

7. **`TerminalOptions.Shell` removed; `Columns`/`Rows` validated.** `TerminalOptions` no longer has a `Shell` property, and `Columns`/`Rows` now throw `ArgumentOutOfRangeException` when set to zero or a negative value. The internal terminal implementation types are gated behind the `ASPIRETERMINAL001` experimental diagnostic.

8. **`DevTunnelRegion` enum values normalized.** Region enum names were normalized — for example, `UKSouth` (not `UkSouth`) and `SoutheastAsia` (not `SouthEastAsia`). Update any code that referenced the old spellings.

9. **Dashboard AI Assistant removed.** The AI Assistant chat UI has been removed from the dashboard.

10. **VS Code dashboard auto-launch removed.** The extension no longer opens the dashboard automatically; opt in with the `dashboardBrowser` setting or `launch.json` value.

11. **Orleans provider annotation is internal.** `OrleansProviderTypeAnnotation` and `ProviderConfiguration` are now internal.

12. **`DotnetProjectResource` moved to `Aspire.Hosting.Dotnet` and made experimental.** It now lives in the `Aspire.Hosting.Dotnet` namespace and emits the `ASPIREDOTNETPROJECT001` diagnostic. The related [`AddDotnetProject`](/reference/api/csharp/aspire.hosting.dotnet/dotnetprojecthostingextensions/methods/#adddotnetproject "Adds a C# project or file-based app to the application model.")[`addDotnetProject`](/reference/api/typescript/aspire.hosting.dotnet/adddotnetproject/ "Adds a C# application resource.") API for modeling .NET projects by path is covered by the same diagnostic.

Review deprecated APIs

Review your code for uses of `ServiceProvider` on hosting context types and `PublishAsConnectionString` extension methods. These generate compiler warnings in Aspire 13.5 and may become harder errors in future releases. If you use the `Aspire.Hosting.GitHub.Models` integration, plan to migrate off it before the package is removed.

## 🚧 Known issues

[Section titled “🚧 Known issues”](#-known-issues)

### Mixed Aspire 13.4 and 13.5 packages can fail at runtime

[Section titled “Mixed Aspire 13.4 and 13.5 packages can fail at runtime”](#mixed-aspire-134-and-135-packages-can-fail-at-runtime)

Aspire 13.5 SDK and core packages aren’t binary-compatible with some Aspire 13.4.6 hosting integration packages. An AppHost that mixes the 13.4 and 13.5 package families can fail at startup with a `MissingMethodException` or a `TypeLoadException` (sometimes surfaced as multiple `TypeLoadExceptions`).

Affected mixed-version scenarios include:

* `Aspire.Hosting.Kubernetes` and `Aspire.Hosting.Azure.Kubernetes`: `MissingMethodException` involving `ProjectResource.get_DefaultHttpsEndpoint`.
* `Aspire.Hosting.Azure.Functions`: `MissingMethodException` involving `WithDebugSupport`.
* `Aspire.Hosting.Go`, `Aspire.Hosting.JavaScript`, and `Aspire.Hosting.Python`: `TypeLoadException` involving `ExecutableLaunchConfiguration`.

Don’t mix Aspire 13.4 and 13.5 packages. Either stay wholly on the Aspire 13.4 SDK and integration packages, or upgrade the SDK and every `Aspire.Hosting.*` integration package together to the matching 13.5 series. Stable packages use version 13.5.0; preview integrations use the corresponding version from the `13.5.0-preview.*` series.

If you discover an issue, please [report it on GitHub](https://github.com/microsoft/aspire/issues).

## 🙏 Community

[Section titled “🙏 Community”](#-community)

Aspire is built in the open, and this release wouldn’t be what it is without you. A huge thank you to everyone who helped make Aspire 13.5 possible.

### The Aspire core team is

* [![Adam Ratzman](https://github.com/adamint.png?size=96)Adam Ratzman](https://github.com/adamint)
* [![Ankit Jain](https://github.com/radical.png?size=96)Ankit Jain](https://github.com/radical)
* [![Damian Edwards](https://github.com/DamianEdwards.png?size=96)Damian Edwards](https://github.com/DamianEdwards)
* [![David Fowler](https://github.com/davidfowl.png?size=96)David Fowler](https://github.com/davidfowl)
* [![David Negstad](https://github.com/danegsta.png?size=96)David Negstad](https://github.com/danegsta)
* [![David Pine](https://github.com/IEvangelist.png?size=96)David Pine](https://github.com/IEvangelist)
* [![Ella Hathaway](https://github.com/ellahathaway.png?size=96)Ella Hathaway](https://github.com/ellahathaway)
* [![Eric Erhardt](https://github.com/eerhardt.png?size=96)Eric Erhardt](https://github.com/eerhardt)
* [![James Newton-King](https://github.com/JamesNK.png?size=96)James Newton-King](https://github.com/JamesNK)
* [![José Pérez](https://github.com/joperezr.png?size=96)José Pérez](https://github.com/joperezr)
* [![Karol Zadora-Przylecki](https://github.com/karolz-ms.png?size=96)Karol Zadora-Przylecki](https://github.com/karolz-ms)
* [![Maddy Montaquila](https://github.com/maddymontaquila.png?size=96)Maddy Montaquila](https://github.com/maddymontaquila)
* [![Mitch Denny](https://github.com/mitchdenny.png?size=96)Mitch Denny](https://github.com/mitchdenny)
* [![Sébastien Ros](https://github.com/sebastienros.png?size=96)Sébastien Ros](https://github.com/sebastienros)

Special thanks to everyone whose pull requests shipped in Aspire 13.5, including:

[@0xharkirat](https://github.com/0xharkirat), [@afscrome](https://github.com/afscrome), [@air-hand](https://github.com/air-hand), [@alirezafzali](https://github.com/alirezafzali), [@AndriySvyryd](https://github.com/AndriySvyryd), [@aradalvand](https://github.com/aradalvand), [@Arasz](https://github.com/Arasz), [@bart-vmware](https://github.com/bart-vmware), [@eso-cyber](https://github.com/eso-cyber), [@Falco20019](https://github.com/Falco20019), [@flensrocker](https://github.com/flensrocker), [@guanzhousongmicrosoft](https://github.com/guanzhousongmicrosoft), [@heintz06](https://github.com/heintz06), [@inlineHamed](https://github.com/inlineHamed), [@Jah-yee](https://github.com/Jah-yee), [@javiercn](https://github.com/javiercn), [@jeffhandley](https://github.com/jeffhandley), [@jfversluis](https://github.com/jfversluis), [@kola-tm](https://github.com/kola-tm), [@krubenok](https://github.com/krubenok), [@LittleLittleCloud](https://github.com/LittleLittleCloud), [@martincostello](https://github.com/martincostello), [@mcumming](https://github.com/mcumming), [@mehara-rothila](https://github.com/mehara-rothila), [@mturac](https://github.com/mturac), [@nanookclaw](https://github.com/nanookclaw), [@ndhansen](https://github.com/ndhansen), [@nellshamrell](https://github.com/nellshamrell), [@neoGeneva](https://github.com/neoGeneva), [@richlander](https://github.com/richlander), [@shauryalowkeygotaura](https://github.com/shauryalowkeygotaura), [@shivamgoel008](https://github.com/shivamgoel008), [@sliekens](https://github.com/sliekens), [@tommasodotNET](https://github.com/tommasodotNET), and [@vivekjm](https://github.com/vivekjm)

We're always excited to [see community contributions](/community/contributors/)! If you'd like to get involved, check out our [contributing guide](/community/contributor-guide/).

# What's new in Aspire 13.6

> Explore Aspire 13.6 dashboard run history, first-party Java and Rust hosting, portable volume paths, CLI workflows, deployment, and integration updates.

Aspire 13.6 lets you revisit completed application runs with **SQLite-backed telemetry and run history**, and work with **AppHost-owned terminals** without leaving the dashboard. It adds **first-party Java and Rust hosting**, preview **Azure Connector Namespace** support, and preview **Azure Container Apps Sandboxes**. Portable volume paths, coordinated .NET builds, and new CLI workflows make local development and deployment more consistent.

We’d love to hear what you think. Drop by [ Discord](https://aka.ms/aspire-discord) to chat with the team and the community, or file feedback and issues on [ GitHub](https://github.com/microsoft/aspire/issues).

This release introduces:

* Persistent dashboards that store resource snapshots and telemetry in SQLite, so you can revisit up to ten completed runs, keep more logs and traces, and dock AppHost-owned terminals, all on a new Native AOT dashboard with a refreshed Fluent UI v5 interface.
* First-party Java and Rust hosting, preview Azure Connector Namespace support, and experimental Azure Container Apps Sandboxes as a deployment target.
* More flexible AppHosts, with coordinated .NET project builds, portable volume paths that work the same locally and in containers, and TypeScript AppHost configuration loaded from `appsettings.json`.
* A sharper CLI that pins repository-local versions, selects launch profiles, exports TypeScript API data, and scripts terminals.
* A Visual Studio Code extension that drives AppHosts from coding agents, runs deployment and pipeline actions from the Aspire pane, and handles multi-root workspaces and git worktrees.
* More predictable deployment, with Azure infrastructure customization from polyglot AppHosts, isolated deployment state, and preserved Kubernetes hostnames and parameter values.
* Integration updates including docked database and cache REPLs, Deno hosting, MongoDB replica sets, Foundry Toolboxes, remote Foundry Local services, and Blazor WebAssembly debugging.
* Updated emulator images, including Azure App Configuration `1.2.0` and the Linux-based vNext Cosmos DB emulator as the new default.
* …and much more.

## 🆙 Upgrade to Aspire 13.6

[Section titled “🆙 Upgrade to Aspire 13.6”](#-upgrade-to-aspire-136)



Caution

Review the [Breaking changes](#breaking-changes) before upgrading, especially if you use MongoDB, the Cosmos DB emulator, Azure Front Door, custom connection-string consumers, or experimental terminal APIs.

For general purpose upgrade guidance, see [Upgrade Aspire](/whats-new/upgrade-aspire/).

To upgrade to Aspire 13.6, use the [`aspire update` command](/reference/cli/commands/aspire-update/):

1. Update the Aspire CLI itself:

   Aspire CLI — Update the CLI

   ```bash
   aspire update --self
   ```

2. Update your projects from the repository root:

   Aspire CLI — Update all Aspire packages

   ```bash
   aspire update
   ```

For more details on installing the Aspire CLI, see [Install the CLI](/get-started/install-cli/).

## 📊 Dashboard persistence and run history

[Section titled “📊 Dashboard persistence and run history”](#-dashboard-persistence-and-run-history)

The Aspire dashboard now stores resource snapshots and telemetry in a versioned SQLite database. The dashboard started by an AppHost uses **Run** persistence by default, retains up to ten runs per application, and adds a header selector for switching between the live run and completed runs. Historical runs are read-only, so you can compare resources, logs, traces, and metrics without changing the earlier application state.

![Aspire 13.6 dashboard displaying persisted demo checkout logs from an earlier run, with the run selector open.](/_astro/run-history-dark.CqYNGXlf_cCY6e.webp)

The standalone dashboard still defaults to temporary **None** persistence. To keep one standalone dashboard database across restarts, give it a stable application name and select **Resume**:

Aspire CLI — Resume a standalone dashboard

```bash
aspire dashboard run --application-name my-app --persistence Resume
```

When you run the dashboard in a container, mount `ASPIRE_DASHBOARD_DATA_DIRECTORY` from persistent storage and reuse the same application name, directory, and persistence mode.

Filtering, searching, paging, and aggregation operate on persisted telemetry, so you can investigate an earlier run using the same tools as a live one.

Protect persisted telemetry

The SQLite database can contain sensitive resource and telemetry values. It has no independent encryption or authorization layer. Aspire restricts the application data directory to its owner on Unix, but doesn’t set or validate Windows ACLs. Protect the data directory, backups, and copies accordingly.

#### AppHost terminals and automation

[Section titled “AppHost terminals and automation”](#apphost-terminals-and-automation)

AppHosts can create terminals for setup tools, interactive commands, and other workflows through the experimental `TerminalService` API. Terminals can appear in a resizable dashboard dock, in an interaction dialog, or in a separate window. AppHost code can send input, read snapshots, and wait for text instead of relying on fixed delays to automate a terminal.

![Aspire 13.6 resources page with AppHost-owned Workspace and Catalog checks terminal tabs in the dock.](/_astro/terminal-dock-dark.DV2TPXi7_1sPOaG.webp)

Terminal interactions bring setup workflows into a focused dialog:

![Aspire 13.6 terminal interaction dialog running and completing a local configuration workflow.](/_astro/terminal-interaction-dark.TzZOvN-r_4AEDM.webp)

These APIs use `ASPIRETERMINAL001`. An AppHost-owned terminal belongs to its creator: closing a viewer isn’t a general substitute for disposing the terminal, and stopping the AppHost stops its owned terminals. Resource terminals configured with [`WithTerminal`](/reference/api/csharp/aspire.hosting/terminalresourcebuilderextensions/methods/#withterminal "Configures a resource to expose an interactive terminal session.")[`withTerminal`](/reference/api/typescript/aspire.hosting/withterminal/ "Adds an interactive terminal session to a resource using the default terminal options.") remain separate from AppHost-owned dock tabs. For example, the following AppHost gives a Python REPL its own resource terminal:

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder
    .addExecutable('repl', 'python3', '.', ['-i', '-q'])
    .withTerminal();


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  #pragma warning disable ASPIRETERMINAL001
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddExecutable("repl", "python3", ".", "-i", "-q")
      .WithTerminal();


  builder.Build().Run();
  ```

#### Database and cache REPLs

[Section titled “Database and cache REPLs”](#database-and-cache-repls)

Opt into `WithRepl` / `withRepl` on [PostgreSQL](/integrations/databases/postgres/postgres-host/#open-an-interactive-repl), [MySQL](/integrations/databases/mysql/mysql-host/#open-an-interactive-repl), [MongoDB](/integrations/databases/mongodb/mongodb-host/#open-an-interactive-repl), [SQL Server](/integrations/databases/sql-server/sql-server-host/#open-an-interactive-repl), [Redis](/integrations/caching/redis/redis-host/#open-an-interactive-repl), or [Valkey](/integrations/caching/valkey/valkey-host/#open-an-interactive-repl) to open the container’s bundled client from a **REPL** dashboard command. No local database client installation is needed.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder.addRedis('cache').withRepl();


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddRedis("cache").WithRepl();


  builder.Build().Run();
  ```

REPL commands are run-only and disabled unless you opt in. They use the resource’s actual credentials and aren’t read-only, so enable them only for trusted dashboard users. Exit the client explicitly before closing its terminal tab; closing the viewer alone can leave the client process running inside the container.

See [resource terminals](/app-host/with-terminal/) and [interactive terminals in the dashboard](/dashboard/explore/#interactive-terminals).

#### More telemetry and independent dashboard sessions

[Section titled “More telemetry and independent dashboard sessions”](#more-telemetry-and-independent-dashboard-sessions)

The default limits for console log messages, structured logs, and traces increase to **100,000 each**. These are bounded retention limits, not unlimited history; the dashboard removes older entries when a limit is exceeded.

Authentication and antiforgery cookie names now include an application-specific suffix derived from `Dashboard:ApplicationName`. This avoids cookie collisions between dashboards on the same hostname. Changing the application name requires signing in again; application-name scoping isn’t a security boundary.

Other dashboard improvements include:

* The dashboard ships as Native AOT and uses Fluent UI v5. Normal startup selects the packaged dashboard automatically, without a new configuration switch.
* Pinning or unpinning a historical run keeps the selector open and preserves the current selection.
* The backtick key opens and hides the terminal dock; the dashboard header and mobile navigation don’t include a terminal entry. The empty dock shows **No docked terminals** and a **More information** link.
* Management UI integrations expose **Manage** links on the resources they administer, reducing the need to find a separate management container.
* The `azure-environment` resource uses a filled cloud icon instead of the generic resource icon.
* Cross-origin or malformed `/_blazor` WebSocket upgrades are rejected before a dashboard circuit is allocated.
* Pausing telemetry displays a consistent warning across telemetry pages.
* Dashboard Markdown links use stricter URL validation.
* Database spans resolve to the correct database resource, and multi-path icons no longer break the graph view.
* Filter controls disable browser autocomplete.
* The `azure-environment` control resource now shows a filled cloud icon on the Resources page instead of the generic fallback icon.
* Dialogs expand to use the available vertical space before scrolling, and disabled text inputs, dropdowns, number inputs, and checkboxes use consistent dark-theme surfaces.

Read about [dashboard data persistence](/dashboard/data-persistence/) and [dashboard security considerations](/dashboard/security-considerations/).

#### Native AOT standalone dashboard and refreshed UI

[Section titled “Native AOT standalone dashboard and refreshed UI”](#native-aot-standalone-dashboard-and-refreshed-ui)

The standalone dashboard now publishes and runs as a **Native AOT** executable, shipping as a self-contained, dedicated bundle instead of routing through the managed `dashboard` subcommand. Existing `aspire dashboard run`, AppHost startup, and CLI profile-capture workflows select the right dashboard automatically, and older AppHosts keep a managed fallback, so no command-line changes are required.

The dashboard also moves to **Fluent UI Blazor v5**. Resources, console logs, structured logs, traces, and metrics keep the same workflows, and the desktop navigation becomes a collapsible rail that you can expand to show page labels or collapse to icons. Your choice of mode persists across reloads.

## ✨ New integrations

[Section titled “✨ New integrations”](#-new-integrations)

Aspire 13.6 adds first-party hosting integrations for Java, Rust, Azure Connector Namespace, and Azure Container Apps Sandboxes. Java and Rust build on implementations that originated in the Aspire Community Toolkit.

Prerelease packages

`Aspire.Hosting.Java`, `Aspire.Hosting.Rust`, `Aspire.Hosting.Azure.ConnectorNamespace`, and `Aspire.Hosting.Azure.Sandboxes` ship as prerelease (`-preview`) packages in Aspire 13.6. Their APIs may change in future releases.

#### ☕ Java

[Section titled “☕ Java”](#-java)

The new `Aspire.Hosting.Java` package supports executable JARs, Maven and Gradle wrappers, Spring Boot, Quarkus, and prebuilt Java container images. It can detect the target Java release from Maven or Gradle, generate a multi-stage Dockerfile for publishing, attach the OpenTelemetry Java agent, and run both Java resources and Java AppHosts under the Visual Studio Code debugger.

The generated container path uses the repository’s Maven or Gradle wrapper rather than a machine-global tool, rejects paths outside the build context, and runs the application as a non-root user.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const catalog = await builder.addSpringBootApp('catalog', '../catalog');
  await catalog.withExternalHttpEndpoints();


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddSpringBootApp("catalog", "../catalog")
      .WithExternalHttpEndpoints();


  builder.Build().Run();
  ```

[`AddSpringBootApp`](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods/#addspringbootapp "Adds a Spring Boot application to the application model, built and launched with its own Maven or Gradle wrapper.")[`addSpringBootApp`](/reference/api/typescript/aspire.hosting.java/addspringbootapp/ "Adds a Spring Boot application to the application model, built and launched with its own Maven or Gradle wrapper.") detect Maven or Gradle from the build file, build the app, and declare an HTTP endpoint through `SERVER_PORT`. Use [`AddJavaApp`](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods/#addjavaapp "Adds a Java application to the application model, launched with java.")[`addJavaApp`](/reference/api/typescript/aspire.hosting.java/addjavaapp/ "Adds a Java application to the application model, launched with java."), [`AddQuarkusApp`](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods/#addquarkusapp "Adds a Quarkus application to the application model, built and launched with its own Maven or Gradle wrapper.")[`addQuarkusApp`](/reference/api/typescript/aspire.hosting.java/addquarkusapp/ "Adds a Quarkus application to the application model, built and launched with its own Maven or Gradle wrapper."), or [`AddJavaContainer`](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods/#addjavacontainer "Adds a Java application that runs from an existing container image.")[`addJavaContainer`](/reference/api/typescript/aspire.hosting.java/addjavacontainer/ "Adds a Java application that runs from an existing container image.") for other application shapes.

See [Java hosting and Toolkit migration](/integrations/frameworks/java/java-host/).

#### 🦀 Rust

[Section titled “🦀 Rust”](#-rust)

The new `Aspire.Hosting.Rust` package models Cargo applications through [`AddRustApp`](/reference/api/csharp/aspire.hosting.rust/rusthostingextensions/methods/#addrustapp "Adds a Rust application to the application model.")[`addRustApp`](/reference/api/typescript/aspire.hosting.rust/addrustapp/ "Adds a Rust application to the application model."). Configure the Cargo binary target, arguments, and features independently from application arguments, then let Aspire generate a multi-stage Dockerfile for publish and deploy. Visual Studio Code can discover, run, and debug both Rust resources and `apphost.rs` AppHosts.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder
      .addRustApp('api', '../rust-api')
      .withHttpEndpoint({ env: 'PORT' })
      .withExternalHttpEndpoints();


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddRustApp("api", "../rust-api")
      .WithHttpEndpoint(env: "PORT")
      .WithExternalHttpEndpoints();


  builder.Build().Run();
  ```

The first-party package doesn’t yet include the Community Toolkit integration’s Bacon support. Custom build and runtime images also remain responsible for ABI and linker compatibility.

See [Rust hosting and Toolkit migration](/integrations/frameworks/rust/rust-host/).

#### 🔌 Azure Connector Namespace

[Section titled “🔌 Azure Connector Namespace”](#-azure-connector-namespace)

The preview `Aspire.Hosting.Azure.ConnectorNamespace` package lets you model connections to external services and expose selected operations through managed MCP server configurations. Configure explicit operation allow-lists and Microsoft Entra access policies in your AppHost rather than managing each connection separately.

The service requires preview access in your Azure subscription and region. Referencing a connection supplies connection information, not authorization: you must grant the consuming identity access and complete any required OAuth consent separately. Removing a connection or access policy from the AppHost doesn’t revoke an already deployed Azure resource; delete it explicitly when retiring access.

See the [Connector Namespace integration guide](/integrations/cloud/azure/azure-connector-namespace/).

#### ☁️ Azure Container Apps Sandboxes

[Section titled “☁️ Azure Container Apps Sandboxes”](#️-azure-container-apps-sandboxes)

The prerelease `Aspire.Hosting.Azure.Sandboxes` package adds Azure Container Apps Sandboxes as a deployment target. Add a sandbox group to your AppHost, and `aspire deploy` provisions the group, an Azure Container Registry, and the identities and role assignments the group needs. It then runs your project, container, and Dockerfile resources as isolated sandboxes. When the sandbox group is the only compute environment, Aspire assigns compute resources to it automatically.

When an AppHost defines multiple compute environments, select the target sandbox group with [`WithComputeEnvironment`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withcomputeenvironment "Configures the compute environment for the compute resource.")[`withComputeEnvironment`](/reference/api/typescript/aspire.hosting/withcomputeenvironment/ "Configures the compute environment for the compute resource."). [`PublishAsAzureSandbox`](/reference/api/csharp/aspire.hosting.azure.sandboxes/azuresandboxesextensions/methods/#publishasazuresandbox "Configures the specified compute resource when it is published as an Azure sandbox container.")[`publishAsAzureSandbox`](/reference/api/typescript/aspire.hosting.azure.sandboxes/publishasazuresandbox/ "Configures the specified compute resource when it is published as an Azure sandbox container.") configures sandbox-specific runtime options without taking a sandbox-group parameter.

Use `PublishAsAzureSandbox` / `publishAsAzureSandbox` to choose one of five resource tiers and to configure auto-suspend and auto-delete:

* TypeScript

  apphost.mts

  ```typescript
  import {
      AzureSandboxAutoSuspendMode,
      AzureSandboxTier,
      createBuilder
  } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  await builder.addAzureSandboxGroup('sandboxes');


  await builder
      .addDockerfile('web', './web')
      .withHttpEndpoint({ port: 8080, targetPort: 8080, name: 'http' })
      .withExternalHttpEndpoints()
      .publishAsAzureSandbox({
          tier: AzureSandboxTier.Small,
          autoSuspendEnabled: true,
          autoSuspendInterval: 900_000, // 15 minutes, in milliseconds
          autoSuspendMode: AzureSandboxAutoSuspendMode.Disk
      });


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  using Aspire.Hosting.Azure;


  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddAzureSandboxGroup("sandboxes");


  builder.AddDockerfile("web", "./web")
      .WithHttpEndpoint(port: 8080, targetPort: 8080, name: "http")
      .WithExternalHttpEndpoints()
      .PublishAsAzureSandbox(new AzureSandboxOptions
      {
          Tier = AzureSandboxTier.Small,
          AutoSuspendEnabled = true,
          AutoSuspendInterval = TimeSpan.FromMinutes(15),
          AutoSuspendMode = AzureSandboxAutoSuspendMode.Disk
      });


  builder.Build().Run();
  ```

Only endpoints marked as external get a public HTTPS URL. Those URLs require Microsoft Entra ID authentication unless you opt in to anonymous access for a specific endpoint. Aspire resolves images to immutable Linux/amd64 digests and applies a deny-by-default egress policy. It also removes stale sandboxes and disk images on redeploy and on `aspire destroy`. For setup, identity, endpoint, and lifecycle details, see [Deploy to Azure Container Apps Sandboxes](/deployment/azure/sandboxes/).

Preview service

Azure Container Apps Sandboxes requires preview access in your Azure subscription and region, and its Aspire package remains prerelease. The integration doesn’t yet support volumes, TCP ports, private service discovery, or Windows and ARM64 images.

See [Java hosting](/integrations/frameworks/java/java-host/), [Rust hosting](/integrations/frameworks/rust/rust-host/), and [Deploy to Azure Container Apps Sandboxes](/deployment/azure/sandboxes/).

## 🧩 App model and AppHost

[Section titled “🧩 App model and AppHost”](#-app-model-and-apphost)

#### Coordinated .NET project builds and publishing

[Section titled “Coordinated .NET project builds and publishing”](#coordinated-net-project-builds-and-publishing)

The [`AddDotnetProject`](/reference/api/csharp/aspire.hosting.dotnet/dotnetprojecthostingextensions/methods/#adddotnetproject "Adds a C# project or file-based app to the application model.")[`addDotnetProject`](/reference/api/typescript/aspire.hosting.dotnet/adddotnetproject/ "Adds a C# application resource.") APIs now coordinate compatible projects into shared restore and build groups, avoiding repeated restores of overlapping project graphs. File-based C# apps use serialized direct builds. Use the resource’s **Rebuild** command after source changes; **Start** and **Restart** reuse the coordinated output.

These resources also participate in .NET SDK container publishing. You can select launch profiles from either AppHost language and separate MSBuild inputs with [`WithBuildEnvironment`](/reference/api/csharp/aspire.hosting.dotnet/dotnetprojecthostingextensions/methods/#withbuildenvironment "Adds an environment variable to the build process for a .NET project.")[`withBuildEnvironment`](/reference/api/typescript/aspire.hosting.dotnet/withbuildenvironment/ "Adds an environment variable to the build process for a .NET project.") from runtime environment variables. Build-only variables aren’t supported for file-based apps and must not be used for secrets.

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const api = await builder.addDotnetProject('api', '../Api/Api.csproj');
  await api.withBuildEnvironment('ContinuousIntegrationBuild', 'true');


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddDotnetProject("api", "../Api/Api.csproj")
      .WithBuildEnvironment("ContinuousIntegrationBuild", "true");


  builder.Build().Run();
  ```

`AddDotnetProject`, `DotnetProjectResource`, and the related `WithBuildEnvironment` overloads no longer require [`ASPIREDOTNETPROJECT001`](/diagnostics/aspiredotnetproject001/) suppression in Aspire 13.6. This diagnostic was unnecessary for `Aspire.Hosting.Dotnet` because the package is already prerelease. Its APIs remain unstable and may change in future releases.

The diagnostic is also removed from [`AddDotnetProjectBlazorGateway`](/reference/api/csharp/aspire.hosting.blazor/blazorgatewayextensions/methods/#adddotnetprojectblazorgateway "Registers the built-in Blazor Gateway backed by an experimental Aspire.Hosting.Dotnet.DotnetProjectResource from Aspire.Hosting.Dotnet (the run/watch-capable...")[`addDotnetProjectBlazorGateway`](/reference/api/typescript/aspire.hosting.blazor/adddotnetprojectblazorgateway/ "Adds the built-in Blazor gateway as a .NET program resource.") and its `WithBlazorClientApp` overload in `Aspire.Hosting.Blazor`. This package also remains prerelease, and its APIs remain unstable and may change. The separate [`ASPIREBLAZOR001`](/diagnostics/aspireblazor001/) diagnostic still applies to experimental Blazor hosting types.

Projects that depend on per-project restore hooks can opt into individual restore with `Aspire:Dotnet:RestoreProjectsIndividually` in the AppHost configuration.

Aspire also enables MSBuild’s multithreaded task execution (`-mt`) when the selected SDK supports it. Project and traversal builds require .NET SDK `11.0.100-rc.1` or later; file-based apps require `11.0.100-rtm.26473.104` or a stable `11.0.100` or later. Older or undetected SDKs keep the existing behavior.

To move an existing AppHost onto this model, the CLI bundles a Project V2 migration skill that guides AI coding agents through the conversion.

See [coordinated builds and restore](/integrations/dotnet/project-resources/#coordinated-builds-and-restore).

#### Portable volume paths

[Section titled “Portable volume paths”](#portable-volume-paths)

Applications often need a host filesystem path during local process execution and an in-container mount path after deployment. The new `env` argument on project and executable volume mounts lets the application consume one environment variable in both modes:

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const api = await builder.addProject('api', '../Api/Api.csproj');
  await api.withVolume('/data', 'data', 'DATA_PATH');


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  builder.AddProject("api")
      .WithVolume("data", "/data", env: "DATA_PATH");


  builder.Build().Run();
  ```

In run mode, `DATA_PATH` contains a deterministic, workload-scoped directory in the AppHost’s local store. Docker Compose, Kubernetes, Azure Container Apps, and other published workloads receive `/data`, so application code doesn’t need separate local and deployment path logic.

This convention also applies to Kubernetes persistent volumes through `WithPersistentVolume(..., env: ...)` and `withKubernetesPersistentVolumeMount(..., { env })`.

See [Persist data with volume resources](/fundamentals/persist-data-volumes/).

#### TypeScript AppHost configuration

[Section titled “TypeScript AppHost configuration”](#typescript-apphost-configuration)

TypeScript AppHosts now load the standard configuration stack from the directory that contains `apphost.mts`. Place `appsettings.json` and environment-specific files beside the AppHost:

appsettings.json

```json
{
  "Deployment": {
    "Region": "westus"
  }
}
```

Read the value through the generated builder API:

apphost.mts

```typescript
import { createBuilder } from './.aspire/modules/aspire.mjs';


const builder = await createBuilder();
const configuration = await builder.getConfiguration();
const region = await configuration.getConfigValue('Deployment:Region');
```

The managed server keeps its logging defaults, while application settings can override them. Environment variables and command-line arguments remain part of the configuration stack.

#### Deno as a TypeScript AppHost runtime

[Section titled “Deno as a TypeScript AppHost runtime”](#deno-as-a-typescript-apphost-runtime)

Deno 2 or later can now run the TypeScript AppHost itself, independently of any Deno guest applications it orchestrates. The CLI detects Deno from `packageManager`, `deno.lock`, `deno.json`, or `deno.jsonc`, uses its native type checking and watch mode, and configures certificate trust through `DENO_CERT`.

See [TypeScript AppHost toolchains](/app-host/typescript-apphost/#use-deno-as-the-apphost-runtime) for detection, permissions, and runtime requirements.

#### Testing, interactions, and extension points

[Section titled “Testing, interactions, and extension points”](#testing-interactions-and-extension-points)

* **Dashboard-enabled integration tests.** Set `DistributedApplicationTestingBuilderOptions.EnableDashboard` and call `GetDashboardUrlAsync()` to start a dashboard on dynamic loopback endpoints and obtain an authenticated URL without writing its browser token to logs.
* **Consistent file upload limits.** The Interaction Service now enforces one file for single-file prompts and 100 files for multi-file prompts across dashboard, CLI, and custom clients. Server-generated temporary names and deterministic cleanup protect uploaded content.
* **Resolved debug environments.** Extension authors can opt into the new experimental `WithDebugSupport` overload that receives `LaunchConfigurationCallbackContext`, including the resource’s resolved environment variables. Existing mode-based overloads keep their signatures; recompile and confirm binding because the synchronous overload now has `OverloadResolutionPriority(-1)`.
* **More reliable local orchestration.** DCP startup gets a readiness-aware timeout on contended hosts, terminal hosts clean up orphaned sockets, and proxied executable target ports use Aspire’s non-ephemeral range to avoid bind races.
* **Project and executable references to container network endpoints.** Projects and executables can now resolve `KnownNetworkIdentifiers.DefaultAspireContainerNetwork` endpoints belonging to themselves or other project and executable resources. When the container tunnel is enabled, Aspire registers the referenced endpoint with the tunnel; when it’s disabled, Aspire resolves the endpoint through the container host name. In either case, configuration resolves instead of waiting indefinitely.
* **Cleaner emulator-only dashboards.** When every Azure resource in the app model runs as a local emulator, Aspire hides the `azure-environment` resource from the dashboard instead of showing it stuck in **Not started**. Adding any Azure resource that requires provisioning keeps `azure-environment` visible.
* **Preserve explicit certificates.** Project defaults no longer replace an application’s Kestrel default certificate when its environment already specifies a certificate path, key path, or subject.

See [Interaction Service file uploads](/extensibility/interaction-service/), the [`ASPIREEXTENSION001` diagnostic](/diagnostics/aspireextension001/), [container network endpoints for projects and executables](/fundamentals/container-networking/#container-network-endpoints-for-projects-and-executables), and [local emulators](/integrations/cloud/azure/overview/#local-emulators).

## 🛠️ Aspire CLI enhancements

[Section titled “🛠️ Aspire CLI enhancements”](#️-aspire-cli-enhancements)

#### Select an AppHost launch profile

[Section titled “Select an AppHost launch profile”](#select-an-apphost-launch-profile)

`aspire run` and `aspire start` now accept `--launch-profile` with the `-lp` alias:

Aspire CLI — Select a launch profile

```bash
aspire run --launch-profile Development
aspire start -lp Development
```

The selected profile flows through direct AppHost launches, detached child processes, and Visual Studio Code delegation. When the CLI can’t safely reproduce a .NET profile, it delegates to `dotnet run` so the .NET SDK retains responsibility for validation and diagnostics.

#### Export canonical TypeScript API data

[Section titled “Export canonical TypeScript API data”](#export-canonical-typescript-api-data)

The new `aspire sdk export` command emits a deterministic TypeScript API reference as JSON. It exports `Aspire.Hosting` at the running CLI SDK version by default, or an exact `PackageName@Version` supplied through `--package`. The exporter and generated TypeScript SDK now share one projector, preventing optional parameters, promise wrappers, DTOs, and enums from drifting between the two representations.

Aspire CLI — Export TypeScript API data

```bash
aspire sdk export --language typescript
```

#### Repository updates, file-based AppHosts, and certificates

[Section titled “Repository updates, file-based AppHosts, and certificates”](#repository-updates-file-based-apphosts-and-certificates)

`aspire update` can update repository-local Aspire CLI references in npm and .NET tool manifests alongside AppHost packages, rather than replacing a globally installed CLI. For a lightweight C# AppHost, `aspire init --language csharp --file-based` creates `apphost.cs` in the current directory without discovering or modifying a solution.

A C# AppHost that enables the CLI bundle (`AspireUseCliBundle=true`) can also control which CLI `dotnet run` launches through `AspireCliInvocationMode`. With `Dnx`, the AppHost runs `Aspire.Cli` through DNX without a version, so DNX honors an in-scope `.config/dotnet-tools.json` manifest or selects the latest package when no manifest applies. With `DnxPinned`, it runs the `Aspire.Cli` version paired with the AppHost’s `Aspire.AppHost.Sdk`, ignoring any tool manifest.

The `aspire new` and `aspire init` agent setup also changed. Both now preselect the recommended repository-local skills, including `aspireify`, while leaving the Aspire MCP server unselected. MCP configuration is strictly opt-in.

On Linux, certificate trust now includes Firefox NSS databases. Use the global `certificates.nssDbPaths` setting when browser profiles live outside the auto-discovered locations.

See [Aspire certificate configuration](/app-host/certificate-configuration/) and [running an AppHost with `dotnet run`](/get-started/aspire-sdk/#running-with-dotnet-run).

#### Terminal tape playback

[Section titled “Terminal tape playback”](#terminal-tape-playback)

`aspire terminal ps` lists resource-owned and AppHost-owned terminals. The new `aspire terminal tape play` command runs a tape against a resource terminal, so repeatable terminal interactions can be scripted alongside your application.

Terminal CLI commands no longer require the `features.terminalCommandsEnabled` flag in 13.6. AppHosts still need the `terminals.v1` capability, and the terminal hosting APIs remain experimental. A tape can send input to a real process; only run scripts you trust.

See the [`aspire terminal` command](/reference/cli/commands/aspire-terminal/).

#### More predictable updates and resource observation

[Section titled “More predictable updates and resource observation”](#more-predictable-updates-and-resource-observation)

* **Explicit MCP setup.** `aspire agent init` defaults to skills without MCP. Standalone interactive setup offers MCP as an opt-in, or you can pass `--mcp`; setup chained from `aspire new` and `aspire init` doesn’t offer it.

* **Project v2 migration skill.** The seven-skill catalog includes `aspire-project-v2-migration`, which proposes approval-first migrations for eligible 13.6 AppHosts without upgrading their Aspire version.

* **GitHub Copilot app detection.** Agent setup recognizes an installed Copilot app even when the standalone Copilot CLI isn’t on `PATH`. See [AI coding agents](/get-started/ai-coding-agents/).

* **In-process NuGet operations.** Bundled package search and restore no longer launch `aspire-managed` and now initialize installed credential-provider plugins. See [authenticated-feed troubleshooting](/get-started/troubleshooting/#authenticated-feeds-return-401).

* **Repository-aware DNX.** C# AppHosts can opt into DNX invocation that respects local tool manifests. New C# templates and file-based AppHosts created by `aspire init` use the CLI bundle by default. See [Aspire SDK](/get-started/aspire-sdk/) for repository-pinned invocation.

* **Channel-aware self-update.** A CLI installed or updated from a nonstable channel preserves that acquisition channel for later self-updates.

* **Complete `describe --follow` startup.** The current state of every resource is emitted immediately, even when no later update occurs, before subsequent state changes stream.

* **Stricter `wait` failures.** `aspire wait` exits with code `18` as soon as a resource reaches `FailedToStart`, including when the requested target status is `down`.

* **Safer resource descriptions.** `aspire describe` redacts a resource’s own secret environment-variable values as well as secrets passed to dependents. Secrets embedded inside larger connection strings aren’t automatically detected.

* **Clearer terminal output.** `aspire ps` colorizes statuses, and progress rendering is suppressed when console logging is enabled.

* **Opt-in volume cleanup.** `aspire stop --force` continues to preserve persistent volumes by default. Add `--volumes` to also remove volumes that Aspire created and owns:

  Aspire CLI — Remove persistent volumes on stop

  ```bash
  aspire stop --force --volumes
  ```

  `--volumes` requires `--force`. Only Aspire-owned named volumes are removed. Anonymous volumes and bind mounts aren’t targeted by `--volumes`, but anonymous volumes associated with a persistent container may be removed when `--force` removes that container. Volumes that existed before the AppHost started are left intact.

See the [`aspire run`](/reference/cli/commands/aspire-run/), [`aspire describe`](/reference/cli/commands/aspire-describe/), [`aspire wait`](/reference/cli/commands/aspire-wait/), and [`aspire stop`](/reference/cli/commands/aspire-stop/) command references.

## 🧰 Visual Studio Code extension

[Section titled “🧰 Visual Studio Code extension”](#-visual-studio-code-extension)

The Aspire extension brings more of the development lifecycle into the Aspire pane and makes complex workspaces more predictable:

* **Agent-driven AppHosts.** Coding agents can start and stop AppHosts through the extension’s lifecycle tools instead of spawning an unrelated CLI process.
* **Deployment actions where you work.** AppHost items expose **Deploy**, **Publish**, **Run pipeline step**, and **Debug pipeline step** alongside run actions. The pane also adds **Create with Aspire…** for creating an app or adding Aspire to the current workspace.
* **Multi-root and worktree awareness.** The Aspire pane discovers AppHosts from every workspace root. AppHost lifecycle operations are scoped to the current git worktree, and launch arguments survive extension delegation.
* **Outdated-CLI warning.** When an extension operation uses an Aspire CLI that’s behind its installed release lane, the extension surfaces a one-click **Update Aspire CLI** action that updates that exact executable. **Don’t Show Again** suppresses the warning for that specific path and version.
* **Cleaner debugging.** AppHost logs appear once in the debug console with log-level color, and resources show setup guidance when their Visual Studio Code debugger extension is missing.
* **Fewer disruptive prompts.** The C# Dev Kit Hot Reload advisory appears at most once per workspace and can be disabled. Reloading Visual Studio Code no longer forces the Aspire view into focus or restores a hidden Activity Bar entry.
* **More reliable sessions.** Closing the window stops extension-owned CLI processes, browser launch no longer blocks startup completion, and Azure Functions and browser-debugging lifecycles report exits accurately.

See [Aspire Visual Studio Code extension](/get-started/aspire-vscode-extension/) and [AI coding agents](/get-started/ai-coding-agents/).

## 🚢 Deployment

[Section titled “🚢 Deployment”](#-deployment)

#### Azure infrastructure customization from polyglot AppHosts

[Section titled “Azure infrastructure customization from polyglot AppHosts”](#azure-infrastructure-customization-from-polyglot-apphosts)

The new experimental `Aspire.Hosting.Azure.Provisioning.*` packages expose Azure Provisioning SDK model proxies to polyglot AppHosts. Opt into the package for the service you need, then use [`ConfigureInfrastructure`](/reference/api/csharp/aspire.hosting.azure/azureprovisioningresourceextensions/methods/#configureinfrastructure "Configures the Azure provisioning resource Azure.Provisioning.Infrastructure.")[`configureInfrastructure`](/reference/api/typescript/aspire.hosting.azure/configureinfrastructure/ "Configures the Azure provisioning infrastructure callback") to customize supported resource properties and compose Bicep expressions.

These packages extend existing hosting integrations; they aren’t new deployment targets, and installing a hosting package doesn’t automatically install its provisioning proxies. The shared runtime reports `ASPIREAZUREPROVISIONING001`, and the projected SDK surface has documented exclusions.

See [typed Azure infrastructure customization](/integrations/cloud/azure/customize-resources/#enable-typed-provisioning-proxies).

#### Deployment state and output improvements

[Section titled “Deployment state and output improvements”](#deployment-state-and-output-improvements)

Deployment state and Kubernetes output are more portable and predictable:

* **Isolated state under `ASPIRE_HOME`.** Deployment state now lives under `/deployments//.json`, keeping side-by-side CLI and CI runs out of the shared user profile. Sibling single-file AppHosts in one directory also receive distinct state identities.
* **Correct hostname inheritance.** Kubernetes Ingress paths and Gateway routes without an explicit host inherit `WithHostname(...)`; explicit path hosts still win, and default backends remain catch-all.
* **Complete Helm values.** Parameters embedded in environment expressions are emitted as their own values and resolved during deployment instead of producing incomplete strings such as `http:///`.
* **Portable volume paths.** The AppHost volume convention described earlier publishes the same environment-variable contract through Docker Compose, Kubernetes, and Azure Container Apps.
* **AKS persistent storage.** Azure Kubernetes Service environments can provision persistent volume resources for workloads that need data to survive container restarts.
* **Inline CSI volumes.** `CsiVolumeSourceV1` and `VolumeV1.Csi` model ephemeral, pod-scoped CSI mounts, including secret and certificate projections. These aren’t persistent volume claims; see [inline CSI volumes](/integrations/compute/kubernetes/#inline-ephemeral-csi-volumes).
* **Reliable AKS cleanup.** Destroy acquires target-cluster credentials and performs Helm cleanup before removing the Azure provisioning resources. See [AKS cleanup](/deployment/kubernetes/aks/#clean-up-a-deployment).
* **Portable connection-string names.** Aspire projects connection-string environment variables into names accepted by stricter deployment targets. Updated client integrations resolve the logical name first and fall back to its portable alias. Direct consumers and older clients should review the [migration guidance](#portable-connection-string-environment-variable-names).

See [Deployment state caching](/deployment/deployment-state-caching/), [Kubernetes ingress](/deployment/kubernetes-ingress/), and [Kubernetes clusters](/deployment/kubernetes/clusters/).

#### Azure Container Apps Express environments

[Section titled “Azure Container Apps Express environments”](#azure-container-apps-express-environments)

Azure Container Apps environments can opt into the Express preview with [`AsExpress`](/reference/api/csharp/aspire.hosting.azure.appcontainers/azurecontainerappextensions/methods/#asexpress "Configures the container app environment to publish and deploy HTTP applications using Azure Container Apps Express.")[`asExpress`](/reference/api/typescript/aspire.hosting.azure.appcontainers/asexpress/ "Configures the container app environment to publish and deploy HTTP applications using Azure Container Apps Express."). Express offers rapid provisioning and fewer infrastructure settings to configure, helping you get HTTP APIs, web frontends, and AI backends deployed quickly. Automatic scaling to zero when idle, on-demand scale-out, and optimized cold starts make it a good fit for apps with intermittent or unpredictable traffic.

Experimental

Express support is experimental and reports [ASPIREACAEXPRESS001](/diagnostics/aspireacaexpress001/), which you must suppress to build. Check the [Azure Container Apps Express overview](https://learn.microsoft.com/azure/container-apps/express-overview) for current availability and supported features.

See [Express environments](/deployment/azure/container-apps/#express-environments).

## 📦 Integration updates

[Section titled “📦 Integration updates”](#-integration-updates)

Existing integrations add new workflows and safer defaults:

* **Docked database and cache REPLs.** Opt into `WithRepl()` / `withRepl()` on PostgreSQL, Redis, Valkey, MongoDB, MySQL, and SQL Server resources to open an interactive client for the resource in the dashboard terminal dock, using bundled clients and the resource’s configured credentials. It’s run-mode only and leaves existing apps unchanged unless you enable it. See [Database and cache REPLs](#database-and-cache-repls).
* **Deno hosting.** `Aspire.Hosting.JavaScript` adds experimental [`AddDenoApp`](/reference/api/csharp/aspire.hosting.javascript/javascripthostingextensions/methods/#adddenoapp "Adds a Deno application to the application model. Deno should be available on the PATH.")[`addDenoApp`](/reference/api/typescript/aspire.hosting.javascript/adddenoapp/ "Adds a Deno application to the application model. Deno should be available on the PATH."), which runs a script from an app directory, with task and serve modes, permission controls, and runtime flags. These APIs report `ASPIREDENO001`, and Deno must be installed for local execution. The first-party API differs from the Community Toolkit’s [Deno integration](/integrations/frameworks/deno/deno-host/).
* **MongoDB replica sets.** Experimental [`WithReplicaSet`](/reference/api/csharp/aspire.hosting.mongodb/mongodbbuilderextensions/methods/#withreplicaset "Configures and initializes the MongoDB server as a single-member replica set for local development.")[`withReplicaSet`](/reference/api/typescript/aspire.hosting.mongodb/withreplicaset/ "Configures and initializes the MongoDB server as a single-member replica set for local development.") configures and initializes a single-member replica set, enabling transactions and change streams after readiness. A separate [`AddMongoDBReplicaSet`](/reference/api/csharp/aspire.hosting.mongodb/mongodbreplicasetbuilderextensions/methods/#addmongodbreplicaset "Adds a MongoDB replica set resource to the application model.")[`addMongoDBReplicaSet`](/reference/api/typescript/aspire.hosting.mongodb/addmongodbreplicaset/ "Adds a MongoDB replica set resource to the application model.") API supports multi-member local scenarios. Both paths are local-run-only and reject publishing; see [MongoDB replica sets](/integrations/databases/mongodb/mongodb-host/#enable-transactions-and-change-streams-with-a-single-member-replica-set).
* **MongoDB automatic TLS.** Local MongoDB resources now use Aspire’s shared certificate configuration, including standalone servers. Existing plaintext clients should review the [TLS migration guidance](#mongodb-now-uses-automatic-tls-during-local-runs).
* **Microsoft Foundry Toolboxes.** [`AddToolbox`](/reference/api/csharp/aspire.hosting.foundry/foundrytoolboxbuilderextensions/methods/#addtoolbox "Adds a Microsoft Foundry Toolbox endpoint to a Microsoft Foundry project.")[`addToolbox`](/reference/api/typescript/aspire.hosting.foundry/addtoolbox/ "Adds a Microsoft Foundry Toolbox endpoint to a Microsoft Foundry project.") bundles tools behind one MCP endpoint and manages immutable versions as tool configuration changes. MCP approval policies are discovery metadata that the consuming application must enforce. See the [Toolbox walkthrough](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#add-a-toolbox).
* **Remote Foundry Local services.** [`RunAsFoundryLocal`](/reference/api/csharp/aspire.hosting.foundry/foundryextensions/methods/#runasfoundrylocal "Configures a Microsoft Foundry resource to use an Aspire-managed Foundry Local service.")[`runAsFoundryLocal`](/reference/api/typescript/aspire.hosting.foundry/runasfoundrylocal/ "Configures a Microsoft Foundry resource to use an Aspire-managed or existing Foundry Local service.") now accepts an endpoint, so an AppHost, including one on WSL2 or Linux, can observe a Foundry Local service already running on another host (for example, a Windows GPU box) without starting, stopping, or downloading models on it. The integration also handles the newer `foundry server` CLI generation. See [Connect to a remote Foundry Local service](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#connect-to-a-remote-foundry-local-service).
* **Blazor WebAssembly debugging.** Standalone and hosted WebAssembly apps can expose dashboard commands for starting and stopping an Edge or Chrome debugging session during local runs. The related Dotnet project gateway APIs are also available to polyglot AppHosts and participate in publishing, but remain unstable and may change. See [Blazor gateway hosting](/integrations/dotnet/blazor-hosting/#add-a-blazor-gateway-for-a-c-project-resource).
* **Dev Tunnel discovery and expiration.** Tunnel, inspect, and local endpoint URLs appear as highlighted resource properties, and a **Show tunnel URLs** command surfaces them through the dashboard Interaction Service. [`WithExpiration`](/reference/api/csharp/aspire.hosting.devtunnels/devtunnelsresourcebuilderextensions/methods/#withexpiration "Configures how long the tunnel can remain unused or unmodified before it expires.")[`withExpiration`](/reference/api/typescript/aspire.hosting.devtunnels/withexpiration/ "Configures how long the tunnel can remain unused or unmodified before it expires.") also configures idle expiration for new or reused tunnels, in whole hours from one hour through 30 days.
* **Radius recipe configuration.** Experimental APIs configure recipe parameters and required secrets globally or per resource from the AppHost. The integration now recommends [Radius v0.60.2](https://github.com/radius-project/radius/releases/tag/v0.60.2); v0.60.0 remains the minimum supported control-plane version.
* **Radius backing connections.** Consumer addresses and credentials now come from the backing resource’s deployed schema and recipe outputs rather than local endpoint guesses. New publish diagnostics catch unsupported endpoints, database mappings, credentials, and secret collisions. Review the [Radius deployment guide](/deployment/radius/) before upgrading.
* **Safer Azure location changes.** Changing a location-immutable Azure resource requires an explicit confirmation before Aspire deletes and recreates it. The CLI projects that confirmation as `--confirm-delete`.
* **Azure identity reliability.** Role-assignment Bicep detects service principal and federated workload identity credentials more accurately.
* **Cosmos DB client health.** `AddAzureCosmosClient` and `AddKeyedAzureCosmosClient` register default-on health checks that probe account reachability. Set `DisableHealthChecks` to opt out.
* **AI Inference client health.** Chat-completions and embeddings health checks now call `GetModelInfoAsync` against `/info`. Endpoints without this route may need `DisableHealthChecks`; this doesn’t add Azure OpenAI health checks. See [AI Inference health checks](/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-connect/#client-integration-health-checks).
* **Cosmos DB emulator telemetry.** The vNext emulator exports its own traces and metrics to the dashboard automatically, separately from consuming application instrumentation.
* **Cosmos DB emulator defaults.** [`RunAsEmulator`](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosextensions/methods/#runasemulator "Configures an Azure Cosmos DB resource to be emulated using the Azure Cosmos DB Linux-based (vNext) emulator with the NoSQL API. This resource requires an...")[`runAsEmulator`](/reference/api/typescript/aspire.hosting.azure.cosmosdb/runasemulator/ "Configures the Azure Cosmos DB resource to run using the local Linux-based (vNext) emulator") now uses the Linux-based vNext emulator. Use [`RunAsClassicEmulator`](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosextensions/methods/#runasclassicemulator "Configures an Azure Cosmos DB resource to be emulated using the classic Azure Cosmos DB emulator with the NoSQL API. This resource requires an...")[`runAsClassicEmulator`](/reference/api/typescript/aspire.hosting.azure.cosmosdb/runasclassicemulator/ "Configures the Azure Cosmos DB resource to run using the classic emulator") to retain the classic emulator, or configure the vNext Data Explorer without suppressing `ASPIRECOSMOSDB001`. See the [Cosmos DB emulator guide](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#run-as-emulator) and [migration guidance](#breaking-changes).
* **Foundry model refreshes.** Generated Foundry model constants were refreshed throughout the release cycle without changing the hosting API shape.
* **Typed guest callbacks.** Callbacks with `Action>` arguments retain the concrete resource identity, fixing Python callback methods that previously received an unwrapped handle. See [multi-language integration authoring](/extensibility/multi-language-integration-authoring/).
* **Front Door origin identity.** Generated origin names now include the origin’s backend hostname, so switching backends creates a distinct origin instead of reusing the previous origin’s Azure identity. Review the [breaking-change guidance](#breaking-changes) before upgrading.
* **GitHub Models integration removed.** [GitHub Models was retired for all customers on July 30, 2026](https://github.blog/changelog/2026-07-30-github-models-is-now-retired/). `Aspire.Hosting.GitHub.Models` was deprecated in Aspire 13.5 and its source, tests, and playground sample are removed from the repository in 13.6. The final `13.5.x` package stays published for apps that already reference it. `Aspire.Hosting.GitHub.Models` is hidden from `aspire add`. Migrate to the [Microsoft Foundry integration](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/).

The following AppHost combines two of these additions: a first-party Deno app that can only reach one host, and a Foundry Toolbox that a project references:

* TypeScript

  apphost.mts

  ```typescript
  import {
    createBuilder,
    DenoPermissionKind,
  } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const deno = await builder.addDenoApp('deno-api', '../deno-api', 'main.ts');
  await deno.withDenoAllow(DenoPermissionKind.Net, ['api.example.com']);


  const foundry = await builder.addFoundry('foundry');
  const project = await foundry.addProject('project');
  const toolbox = await project.addToolbox('field-tools');
  await toolbox.withWebSearchTool({
    name: 'web-search',
    description: 'Search the public web.',
  });


  const api = await builder.addProject('api', '../Api/Api.csproj');
  await api.withReference(toolbox);


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  using Aspire.Hosting.Foundry;
  using Aspire.Hosting.JavaScript;


  var builder = DistributedApplication.CreateBuilder(args);


  #pragma warning disable ASPIREDENO001
  builder.AddDenoApp("deno-api", "../deno-api", "main.ts")
      .WithDenoAllow(DenoPermissionKind.Net, "api.example.com");
  #pragma warning restore ASPIREDENO001


  var toolbox = builder.AddFoundry("foundry")
      .AddProject("project")
      .AddToolbox("field-tools")
      .WithWebSearchTool("web-search", "Search the public web.");


  builder.AddProject("api")
      .WithReference(toolbox);


  builder.Build().Run();
  ```

Note

Radius recipe APIs, the Dotnet project Blazor gateway, and Azure Container Apps Sandboxes remain experimental.

See [Blazor hosting](/integrations/dotnet/blazor-hosting/), [Dev tunnels](/integrations/devtools/dev-tunnels/), and [Radius](https://docs.radapp.io/).

## 🐳 Default container image updates

[Section titled “🐳 Default container image updates”](#-default-container-image-updates)

Two emulator defaults changed:

| Integration             | Image                                                                  | Aspire 13.5 | Aspire 13.6    |
| ----------------------- | ---------------------------------------------------------------------- | ----------- | -------------- |
| Azure App Configuration | `mcr.microsoft.com/azure-app-configuration/app-configuration-emulator` | `1.0.2`     | `1.2.0`        |
| Azure Cosmos DB         | `mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`               | `stable`    | `vnext-latest` |

Aspire’s App Configuration emulator now checks the `/health` endpoint on the `1.2.0` image, so [`OnResourceReady`](/reference/api/csharp/aspire.hosting/distributedapplicationeventingextensions/methods/#onresourceready "Subscribes a callback to the Aspire.Hosting.ApplicationModel.ResourceReadyEvent event for builder.")[`onResourceReady`](/reference/api/typescript/aspire.hosting/onresourceready/ "Subscribes to the ResourceReady event.") runs only after the emulator accepts requests. The Cosmos DB change also affects runtime behavior and persisted data; review the [breaking-change guidance](#breaking-changes) before upgrading.

## 🐛 Bug fixes

[Section titled “🐛 Bug fixes”](#-bug-fixes)

For the complete list of fixes, see the [Aspire 13.6 release notes](https://github.com/microsoft/aspire/releases/tag/v13.6.0) when the release is published.

## 🙏 Community

[Section titled “🙏 Community”](#-community)

Aspire is built in the open, and this release wouldn’t be what it is without you. A huge thank you to everyone who helped make Aspire 13.6 possible.

### The Aspire core team is

* [![Adam Ratzman](https://github.com/adamint.png?size=96)Adam Ratzman](https://github.com/adamint)
* [![Ankit Jain](https://github.com/radical.png?size=96)Ankit Jain](https://github.com/radical)
* [![Damian Edwards](https://github.com/DamianEdwards.png?size=96)Damian Edwards](https://github.com/DamianEdwards)
* [![David Fowler](https://github.com/davidfowl.png?size=96)David Fowler](https://github.com/davidfowl)
* [![David Negstad](https://github.com/danegsta.png?size=96)David Negstad](https://github.com/danegsta)
* [![David Pine](https://github.com/IEvangelist.png?size=96)David Pine](https://github.com/IEvangelist)
* [![Ella Hathaway](https://github.com/ellahathaway.png?size=96)Ella Hathaway](https://github.com/ellahathaway)
* [![Eric Erhardt](https://github.com/eerhardt.png?size=96)Eric Erhardt](https://github.com/eerhardt)
* [![James Newton-King](https://github.com/JamesNK.png?size=96)James Newton-King](https://github.com/JamesNK)
* [![José Pérez](https://github.com/joperezr.png?size=96)José Pérez](https://github.com/joperezr)
* [![Karol Zadora-Przylecki](https://github.com/karolz-ms.png?size=96)Karol Zadora-Przylecki](https://github.com/karolz-ms)
* [![Maddy Montaquila](https://github.com/maddymontaquila.png?size=96)Maddy Montaquila](https://github.com/maddymontaquila)
* [![Mitch Denny](https://github.com/mitchdenny.png?size=96)Mitch Denny](https://github.com/mitchdenny)
* [![Sébastien Ros](https://github.com/sebastienros.png?size=96)Sébastien Ros](https://github.com/sebastienros)

Special thanks to everyone whose pull requests shipped in Aspire 13.6, including:

[@afscrome](https://github.com/afscrome), [@air-hand](https://github.com/air-hand), [@aradalvand](https://github.com/aradalvand), [@askpt](https://github.com/askpt), [@bart-vmware](https://github.com/bart-vmware), [@danfiedler-msft](https://github.com/danfiedler-msft), [@danroth27](https://github.com/danroth27), [@denisivan0v](https://github.com/denisivan0v), [@flojon](https://github.com/flojon), [@Formatted](https://github.com/Formatted), [@gabisonia](https://github.com/gabisonia), [@jesuszarate](https://github.com/jesuszarate), [@jfversluis](https://github.com/jfversluis), [@krubenok](https://github.com/krubenok), [@maraf](https://github.com/maraf), [@marshalhayes](https://github.com/marshalhayes), [@missymessa](https://github.com/missymessa), [@nellshamrell](https://github.com/nellshamrell), [@prom3theu5](https://github.com/prom3theu5), [@rickylabs](https://github.com/rickylabs), [@rsd-darshan](https://github.com/rsd-darshan), [@SankeerthNara](https://github.com/SankeerthNara), [@Shaurya2k06](https://github.com/Shaurya2k06), [@spboyer](https://github.com/spboyer), [@thomhurst](https://github.com/thomhurst), [@timritzer](https://github.com/timritzer), [@vivekjm](https://github.com/vivekjm), [@Vladipz](https://github.com/Vladipz), and [@zhiyuanliang-ms](https://github.com/zhiyuanliang-ms)

We're always excited to [see community contributions](/community/contributors/)! If you'd like to get involved, check out our [contributing guide](/community/contributor-guide/).

## ⚠️ Breaking changes

[Section titled “⚠️ Breaking changes”](#️-breaking-changes)

#### MongoDB now uses automatic TLS during local runs

[Section titled “MongoDB now uses automatic TLS during local runs”](#mongodb-now-uses-automatic-tls-during-local-runs)

Starting in Aspire 13.6, MongoDB server resources participate in shared certificate configuration. When a certificate is configured and available, normally the developer certificate under default settings, Aspire starts the server with `--tlsMode requireTLS` and adds `tls=true` to its generated connection string. This changes the previous plaintext default for **ordinary [`AddMongoDB`](/reference/api/csharp/aspire.hosting.mongodb/mongodbbuilderextensions/methods/#addmongodb "Adds a MongoDB resource to the application model. A container is used for local development.")[`addMongoDB`](/reference/api/typescript/aspire.hosting.mongodb/addmongodb/ "Adds a MongoDB container resource") resources**, even if you don’t use replica sets.

Use the complete generated connection string instead of constructing a URI from host and port. Clients must trust the server certificate and use a hostname it covers. A container client connecting by the MongoDB resource name can encounter a hostname mismatch with the developer certificate; trusting the certificate alone doesn’t fix that.

For an explicit local-development opt-out, use [`WithoutHttpsCertificate`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withouthttpscertificate "Disable HTTPS/TLS server certificate configuration for the resource. No HTTPS/TLS termination configuration will be applied.")[`withoutHttpsCertificate`](/reference/api/typescript/aspire.hosting/withouthttpscertificate/ "Disable HTTPS/TLS server certificate configuration for the resource. No HTTPS/TLS termination configuration will be applied.") on a standalone server or the simple `WithReplicaSet()` / `withReplicaSet()` configuration. This disables transport encryption. Don’t apply it to advanced `AddMongoDBReplicaSet(...).WithMember(...)` members, which require TLS/SNI for split-horizon discovery.

`PreferTls` accepts plaintext and TLS clients but still advertises TLS in generated connection strings. The global `ASPIRE_DEVELOPER_CERTIFICATE_DEFAULT_HTTPS_TERMINATION=false` switch affects ambient defaults for other resources too; it doesn’t disable explicit member certificates. These local-run defaults don’t automatically configure certificates for published MongoDB containers.

See [MongoDB automatic TLS and migration](/integrations/databases/mongodb/mongodb-host/#automatic-tls-and-migration-from-earlier-versions) for C# and TypeScript examples, certificate arrangements, and the limits of each option.

#### Azure Cosmos DB now defaults to the Linux-based vNext emulator

[Section titled “Azure Cosmos DB now defaults to the Linux-based vNext emulator”](#azure-cosmos-db-now-defaults-to-the-linux-based-vnext-emulator)

`RunAsEmulator` / `runAsEmulator` now selects the `vnext-latest` Linux-based emulator instead of the `stable` classic emulator. To keep the previous behavior, switch to `RunAsClassicEmulator` / `runAsClassicEmulator`:

* TypeScript

  apphost.mts

  ```typescript
  import { createBuilder } from './.aspire/modules/aspire.mjs';


  const builder = await createBuilder();


  const cosmos = await builder.addAzureCosmosDB('cosmos-db');
  await cosmos.runAsClassicEmulator();


  await builder.build().run();
  ```

* C#

  AppHost.cs

  ```csharp
  var builder = DistributedApplication.CreateBuilder(args);


  var cosmos = builder.AddAzureCosmosDB("cosmos-db")
      .RunAsClassicEmulator();


  builder.Build().Run();
  ```

If you adopt the new default:

* Re-seed persisted emulator data. The vNext emulator stores data under `/data`, while the classic emulator uses `/tmp/cosmos/appdata`; existing classic data doesn’t carry over.
* Remove [`WithPartitionCount`](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosextensions/methods/#withpartitioncount "Configures the partition count for the Azure Cosmos DB emulator.")[`withPartitionCount`](/reference/api/typescript/aspire.hosting.azure.cosmosdb/withpartitioncount/ "Configures the partition count for the Azure Cosmos DB emulator."). Partition count isn’t supported by the vNext emulator and now throws `NotSupportedException`.
* Call [`WithDataExplorer`](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosextensions/methods/#withdataexplorer "Configures the Azure Cosmos DB Linux-based (vNext) emulator to expose the Data Explorer endpoint.")[`withDataExplorer`](/reference/api/typescript/aspire.hosting.azure.cosmosdb/withdataexplorer/ "Configures the Azure Cosmos DB Linux-based (vNext) emulator to expose the Data Explorer endpoint.") if you need the Data Explorer. Aspire disables it by default for vNext, and the API isn’t supported with the classic emulator.
* Update experimental calls from [`RunAsPreviewEmulator`](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosextensions/methods/#runaspreviewemulator "Configures an Azure Cosmos DB resource to be emulated using the Azure Cosmos DB Linux-based (vNext) emulator with the NoSQL API.")[`runAsPreviewEmulator`](/reference/api/typescript/aspire.hosting.azure.cosmosdb/runaspreviewemulator/ "Configures the Azure Cosmos DB resource to run using the local Linux-based (vNext) emulator. Use runAsEmulator instead.") to `RunAsEmulator` / `runAsEmulator`. The preview methods remain as obsolete compatibility aliases, and `ASPIRECOSMOSDB001` is retired.
* Revalidate emulator-dependent tests and startup expectations. The classic emulator requires its TLS certificate, while the vNext emulator uses a different startup and health model.

See the [Azure Cosmos DB Linux emulator documentation](https://learn.microsoft.com/azure/cosmos-db/emulator-linux).

#### Front Door origin names now include the backend hostname

[Section titled “Front Door origin names now include the backend hostname”](#front-door-origin-names-now-include-the-backend-hostname)

Azure Front Door origin names generated by the Aspire hosting integration now combine the resource group ID with the origin’s backend hostname, instead of hashing the resource group ID alone. This is a breaking deployment change: upgrading to Aspire 13.6 changes the generated origin resource names, even when the backend hostname hasn’t changed. Endpoint, origin-group, and route names are unchanged.

[Incremental ARM deployments](https://learn.microsoft.com/azure/azure-resource-manager/templates/deployment-modes#incremental-mode) don’t remove resources omitted from the new template, so existing origins can remain alongside the newly named origins in the same origin group.

**Recommended approach:** Adopt the new naming policy, which gives an origin a new identity when its backend hostname changes:

1. Deploy your app with Aspire 13.6 using the new default origin names.
2. Confirm that the newly named origins are healthy and serve the intended backends.
3. Manually delete the old origins from each affected origin group.

**Fallback:** If the recommended deployment and cleanup approach isn’t feasible, preserve the previous default origin names by overriding them in an infrastructure customization callback before the first deployment after upgrading:

Both snippets extend an existing AppHost: `builder` is your application builder, and `api` is an existing backend resource with external HTTP endpoints and an Azure compute environment configured for publishing, such as Azure Container Apps or Azure App Service. Add the override before building and running your application.

* TypeScript

  Add the CDN provisioning package to enable typed origin lookups. It also includes the Azure Front Door hosting integration, so a separate `aspire add azure-frontdoor` isn’t required:

  Add CDN provisioning support

  ```bash
  aspire add Aspire.Hosting.Azure.Provisioning.Cdn --version 13.6.0-preview.1.26479.8
  ```

  These provisioning APIs are experimental and may change in future releases. This example was validated with Aspire 13.6.0 and CDN provisioning package version `13.6.0-preview.1.26479.8`.

  apphost.mts

  ```typescript
  const frontdoor = await builder.addAzureFrontDoor('frontdoor');
  await frontdoor.withOrigin(api);
  await frontdoor.configureInfrastructure(async (infrastructure) => {
    const bicep = await infrastructure.bicep();
    const groupId = await bicep.member(await bicep.resourceGroup(), 'id');
    const suffix = await bicep.uniqueString([groupId]);


    for (const origin of await infrastructure.getFrontDoorOrigins()) {
      // Match the previous default: remove underscores and hash only the resource-group ID.
      const identifier = await origin.bicepIdentifier();
      const prefix = await bicep.string(`${identifier.replaceAll('_', '')}-`);
      const name = await bicep.concat([prefix, suffix]);
      // Front Door origin names have a maximum length of 90 characters.
      await origin.name.set(await bicep.take(name, 90));
    }
  });
  ```

* C#

  Use the Azure Front Door hosting integration already installed in your AppHost (`Aspire.Hosting.Azure.FrontDoor`).

  AppHost.cs

  ```csharp
  using Azure.Provisioning;
  using Azure.Provisioning.Cdn;
  using Azure.Provisioning.Expressions;


  builder.AddAzureFrontDoor("frontdoor")
      .WithOrigin(api)
      .ConfigureInfrastructure(infrastructure =>
      {
          foreach (var origin in infrastructure.GetProvisionableResources()
              .OfType())
          {
              // Match the previous default: remove underscores and hash only the resource-group ID.
              origin.Name = BicepFunction.Take(
                  BicepFunction.Interpolate($"{origin.BicepIdentifier.Replace("_", "")}-{BicepFunction.GetUniqueString(BicepFunction.GetResourceGroup().Id)}"),
                  origin.GetResourceNameRequirements().MaxLength);
          }
      });
  ```

The callback runs after the integration’s defaults and applies to every configured origin. This override opts out of hostname-based origin identity, so switching backends no longer creates a new origin; if the new naming scheme has already been deployed, applying the override doesn’t delete the newly created origins, so disable or remove unwanted origins separately after confirming which origins should serve traffic.

To verify the override without deploying, run `aspire publish --non-interactive` in your AppHost directory and inspect the generated Front Door Bicep module. Each origin’s `name` should use `uniqueString(resourceGroup().id)` without the backend hostname and be truncated to 90 characters.

See the [Azure Front Door integration](/integrations/cloud/azure/azure-front-door/) documentation.

#### Portable connection-string environment variable names

[Section titled “Portable connection-string environment variable names”](#portable-connection-string-environment-variable-names)

Connection names containing hyphens or repeated underscores now have a portable environment-variable alias. For example, the logical connection name `my-db` maps to `ConnectionStrings__my_db`. Aspire supplies both the original and portable names when the target supports them, but Azure App Service, Kubernetes-based publishers, and Foundry Hosted Agents emit only the portable alias.

If your application reads environment variables directly, or uses an older client integration, don’t assume `ConnectionStrings__my-db` is present after deployment. Update Aspire client integrations with your AppHost packages, use a portable explicit connection name such as `my_db` consistently in both the reference and consumer, or add logical-name-then-portable-name fallback in custom configuration code.

Names that collapse to the same physical alias, such as `my-db` and `my_db`, now fail during environment resolution rather than overwriting each other. Give those references distinct connection names.

See [connection-string naming and migration](/fundamentals/environment-variables/#migrating-connection-string-consumers).

#### Terminal APIs moved to `Aspire.Hosting.ApplicationModel`

[Section titled “Terminal APIs moved to Aspire.Hosting.ApplicationModel”](#terminal-apis-moved-to-aspirehostingapplicationmodel)

The experimental terminal types previously in `Aspire.Hosting.Terminals` now live in `Aspire.Hosting.ApplicationModel`, alongside `ResourceNotificationService` and the rest of the app model. `TerminalService`, `AspireTerminal`, `AspireTerminalKey`, `TerminalLaunchOptions`, `TerminalOwner`, and `TerminalPlacement` move without a compatibility shim, so any code referencing the old namespace fails to build until updated:

Update terminal namespace imports

```csharp
// Before
using Aspire.Hosting.Terminals;


// After
using Aspire.Hosting.ApplicationModel;
```

AppHosts that rely on the SDK’s implicit usings already import `Aspire.Hosting.ApplicationModel` and require no source change beyond removing an explicit `using Aspire.Hosting.Terminals;` if present. `TerminalInteractionOptions` and the `WithTerminal` builder extensions remain in `Aspire.Hosting` and are unaffected. If your code resolves `TerminalService` from the DI container or calls `IInteractionService.PromptTerminalAsync`, update the type references there too:

Resolve TerminalService from the built application

```csharp
using Aspire.Hosting.ApplicationModel;
using Microsoft.Extensions.DependencyInjection;


#pragma warning disable ASPIRETERMINAL001


var terminalService = app.Services.GetRequiredService();
```

The category produced by `ILogger` also changes to `Aspire.Hosting.ApplicationModel.TerminalService`. Update namespace-specific logging filters if you configured any against the old category. Terminal ownership, lifetimes, wire protocols, and dashboard/CLI behavior are unchanged, and the experimental diagnostic remains `ASPIRETERMINAL001`.

See [Test TUI and shell apps using WithTerminal](/app-host/with-terminal/) and the [`ASPIRETERMINAL001` diagnostic](/diagnostics/aspireterminal001/).

# What's new in Aspire 9.0

> Explore Aspire 9.0: ANSI console log formatting, browser telemetry, waiting-for-resource health gates, persistent containers, Redis Insight, and Azure Functions support.

📢 Aspire 9.0 is the next major general availability (GA) release of Aspire; it supports *both*:

* .NET 8.0 Long Term Support (LTS) *or*
* .NET 9.0 Standard Term Support (STS).

Note

You’re able to use Aspire 9.0 with either .NET 8 or .NET 9!

This release addresses some of the most highly requested features and pain points from the community. The best features are community-driven! To join the community on, visit us on [Discord](https://discord.com/invite/h87kDAHQgJ) to chat with team members and collaborate with us on [GitHub](https://github.com/microsoft/aspire).

For more information on the official .NET version and Aspire version support, see:

* [.NET support policy](https://dotnet.microsoft.com/platform/support/policy): Definitions for LTS and STS.
* [Aspire support policy](https://dotnet.microsoft.com/platform/support/policy/aspire): Important unique product life cycle details.

## Upgrade to Aspire 9

[Section titled “Upgrade to Aspire 9”](#upgrade-to-aspire-9)

To upgrade from earlier versions of Aspire to Aspire 9, follow the instructions in the official upgrade guide. The guide provides detailed instructions on how to upgrade your existing Aspire solutions to Aspire 9. Regardless of you’re doing it manually, or using the Upgrade Assistant, the guide makes short work of the process.

### Tooling improvements

[Section titled “Tooling improvements”](#tooling-improvements)

Aspire 9 makes it simpler to configure your environment to develop Aspire applications. You no longer need a .NET workload. Instead, you install the new [Aspire SDK](/get-started/aspire-sdk/) into the AppHost project of your Aspire solutions. For more information, see [Aspire setup and tooling](/get-started/prerequisites/).

### Templates have moved

[Section titled “Templates have moved”](#templates-have-moved)

Aspire 9 is moving the contents that used to be installed via the workload into separate NuGet packages. This includes the templates for creating new Aspire projects and solutions. These templates are installed using the `dotnet new install` command. These can be installed by running the following command:

```bash
dotnet new install Aspire.ProjectTemplates::9.0.0
```

For more information, see Aspire templates.

## Dashboard UX enhancements and new interactivity features

[Section titled “Dashboard UX enhancements and new interactivity features”](#dashboard-ux-enhancements-and-new-interactivity-features)

The [Aspire dashboard](/dashboard/overview/) continues to improve with each release.

### Manage resource lifecycle

[Section titled “Manage resource lifecycle”](#manage-resource-lifecycle)

The most requested feature for the dashboard is to manage the lifecycles of your orchestrated named resources. Specifically, the ability to stop, start, and restart resources. This feature works for projects, containers, and executables. It enables restarting individual resources without having to restart the entire AppHost. For project resources, when the debugger is attached, it’s reattached on restart. For more information, see [Aspire dashboard: Stop or Start a resource](/dashboard/explore/#stop-or-start-a-resource).

### Mobile and responsive support

[Section titled “Mobile and responsive support”](#mobile-and-responsive-support)

The Aspire dashboard is now mobile-friendly, responsively adapting to a wide range of screen sizes and enabling on-the-go management of deployed Aspire applications. Other accessibility improvements were made, including the display of settings and content overflow on mobile.

### Sensitive properties, volumes, and health checks in resource details

[Section titled “Sensitive properties, volumes, and health checks in resource details”](#sensitive-properties-volumes-and-health-checks-in-resource-details)

The display of resource details contains several improvements:

* Properties can be marked as sensitive, automatically masking them in the dashboard UI. This security feature helps to avoid accidentally disclosing keys or passwords when screen sharing the dashboard with other people. For example, container arguments could pass sensitive information and so are masked by default.
* Configured container volumes are listed in resource details.
* Aspire 9 adds support for health checks. Detailed information about these checks can now be viewed in the resource details pane, showing why a resource might be marked as unhealthy or degraded. For more information, see [Resource health check](#resource-health-checks).

### Colorful console log

[Section titled “Colorful console log”](#colorful-console-log)

[ANSI escape codes](https://wikipedia.org/wiki/ANSI_escape_code) format text in terminals by controlling colors (foreground and background) and styles like bold, underline, and italics. Previously, the dashboard’s console logs page could only render one ANSI escape code at a time, failing when multiple codes were combined. For example, it could display red text, but not text that was both red and bold.

A community contribution from [@mangeg](https://github.com/mangeg) improved support for ANSI escape codes and removed this limitation.

![Colorful console logs](/_astro/console-logs-ansi-text-format.BSrCIQeX_Z2jxeN4.webp)

Another improvement to console logs is hiding unsupported escape codes. Codes that aren’t related to displaying text, such as positioning the cursor or communicating with the operating system don’t make sense in this UI, and are hidden.

## Telemetry user-centric additions

[Section titled “Telemetry user-centric additions”](#telemetry-user-centric-additions)

[Telemetry](/fundamentals/telemetry/) remains a vital aspect of Aspire. In Aspire 9, many new features were introduced to the Telemetry service.

### Improved telemetry filtering

[Section titled “Improved telemetry filtering”](#improved-telemetry-filtering)

Traces can be filtered with attribute values. For example, if you only want to view traces for one endpoint in your app, the `http.route` attribute on HTTP requests can be filtered to a specified value.

Telemetry filtering also supports autocomplete of existing values. The **Add filter** dialog provides a combo box for selecting from values that dashboard has available. This feature makes it much easier to filter to real data and helps avoid typos by entered a value yourself.

For more information, see [Aspire dashboard: Filter traces](/dashboard/explore/#filter-traces).

### Combine telemetry from multiple resources

[Section titled “Combine telemetry from multiple resources”](#combine-telemetry-from-multiple-resources)

When a resource has multiple replicas, you can now filter telemetry to view data from all instances at once. Select the parent resource, labeled `(application)`. For more information, see [Aspire dashboard: Combine telemetry from multiple resources](/dashboard/explore/#combine-telemetry-from-multiple-resources).

### Browser telemetry support

[Section titled “Browser telemetry support”](#browser-telemetry-support)

The dashboard supports OpenTelemetry Protocol (OTLP) over HTTP and cross-origin resource sharing (CORS). These features unlock the ability to send OpenTelemetry from browser apps to the Aspire dashboard.

For example, a browser-based single page app (SPA) can configure the [JavaScript OpenTelemetry SDK](https://opentelemetry.io/docs/languages/js/getting-started/browser/) to send structured logs, traces, and metrics created in the browser to the dashboard. Browser telemetry is displayed alongside server telemetry.

![Trace detail page with browser telemetry](/_astro/dashboard-browser-telemetry.De66OII2_eDJNp.webp)

For more information on configuring browser telemetry, see [Enable browser telemetry](/dashboard/enable-browser-telemetry/) documentation.

## AppHost (Orchestration)

[Section titled “AppHost (Orchestration)”](#apphost-orchestration)

The [Aspire AppHost](/get-started/app-host/) is one of the **most important** features of Aspire. In Aspire 9, several new features were added specific to the AppHost.

### Waiting for dependencies

[Section titled “Waiting for dependencies”](#waiting-for-dependencies)

If you’ve been following along with Aspire, you already know that your AppHost project is where you define your app model. You create a distributed application builder, add and configure resources, and express their dependencies. Now, you can specify that a resource should *wait* for another resource before starting. This can help avoid connection errors during startup by only starting resources when their dependencies are “ready.”

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var rabbit = builder.AddRabbitMQ("rabbit");


builder.AddProject("api")
       .WithReference(rabbit)
       .WaitFor(rabbit); // Don't start "api" until "rabbit" is ready...


builder.Build().Run();
```

When the AppHost starts, it waits for the `rabbit` resource to be ready before starting the `api` resource.

There are two methods exposed to wait for a resource:

* [`WaitFor`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#waitfor "Waits for the dependency resource to enter the Running state before starting the resource.")[`waitFor`](/reference/api/typescript/aspire.hosting/waitfor/ "Waits for another resource to be ready"): Wait for a resource to be ready before starting another resource.
* [`WaitForCompletion`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#waitforcompletion "Waits for the dependency resource to enter the Exited or Finished state before starting the resource.")[`waitForCompletion`](/reference/api/typescript/aspire.hosting/waitforcompletion/ "Waits for the dependency resource to enter the Exited or Finished state before starting the resource."): Wait for a resource to complete before starting another resource.

For more information, see [Aspire AppHost: Waiting for resources](/get-started/app-host/#adding-an-api-resource-and-declaring-a-dependency).

#### Resource health checks

[Section titled “Resource health checks”](#resource-health-checks)

The `WaitFor` API uses standard [.NET health checks](/fundamentals/health-checks/) to determine if a resource is ready. But what does “a resource being ready” mean? The best part is, that’s configurable by the consumer beyond their default values.

When a resource doesn’t expose any health checks (no health checks registered in the app), the AppHost waits for the resource to be in the running state before starting the dependent resource.

For resources that expose HTTP endpoints, you can easily add a health check that polls a specific path for an HTTP 200 response.

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var catalogApi = builder.AddContainer("catalog-api", "catalog-api")
                        .WithHttpEndpoint(targetPort: 8080)
                        .WithHttpHealthCheck("/health");


builder.AddProject("store")
       .WithReference(catalogApi.GetEndpoint("http"))
       .WaitFor(catalogApi);


builder.Build().Run();
```

The preceding example adds a health check to the `catalog-api` resource. The AppHost waits for the health check to return a healthy status before starting the `store` resource. It determines that the resource is ready when the `/health` endpoint returns an HTTP 200 status code.

While `store` is waiting for `catalog-api` to become healthy, the resources in the dashboard appear as:

![Waiting for an unhealthy resource before starting](/_astro/waiting-for-unhealthy-resource.BfH2GYKf_Z1FX8vf.webp)

The AppHost’s health check mechanism builds upon the `IHealthChecksBuilder` implementation from the health checks namespace.

Health checks report data, which is displayed in the dashboard:

![Health check details in the dashboard's resource details view](/_astro/health-check-details.DyLMHd5c_BCKB3.webp)

Creating a custom health check is straightforward. Start by defining the health check, then associate its name with any resources it applies to.

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var healthyAfter = DateTime.Now.AddSeconds(20);


builder.Services.AddHealthChecks().AddCheck(
    "delay20secs",
    () => DateTime.Now > healthyAfter
        ? HealthCheckResult.Healthy()
        : HealthCheckResult.Unhealthy()
    );


var cache = builder.AddRedis("cache")
                   .WithHealthCheck("delay20secs");


builder.AddProject("myapp")
       .WithReference(cache)
       .WaitFor(cache);
```

The preceding example adds a health check to the `cache` resource, which reports it as unhealthy for the first 20 seconds after the AppHost starts. So, the `myapp` resource waits for 20 seconds before starting, ensuring the `cache` resource is healthy.

The health check methods provide a simple mechanism to create health checks and associate them with specific resources.

### Persistent containers

[Section titled “Persistent containers”](#persistent-containers)

The AppHost now supports *persistent* containers. Persistent containers deviate from the typical container life cycle of Aspire orchestrated apps. While they’re *created* and *started* (when not already available) by the Aspire orchestrator, they’re not destroyed by Aspire.

This is useful when you want to keep the container running even after the AppHost has stopped.

Caution

To delete these containers, you must manually stop them using the container runtime.

To define an `IResourceBuilder` with a persistent lifetime, call the [`WithLifetime`](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods/#withlifetime "Sets the lifetime behavior of the container resource.")[`withLifetime`](/reference/api/typescript/aspire.hosting/withlifetime/ "Sets the lifetime behavior of the container resource.") method and pass in persistent container lifetime:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var queue = builder.AddRabbitMQ("rabbit")
                   .WithLifetime(ContainerLifetime.Persistent);


builder.AddProject("api")
       .WithReference(queue)
       .WaitFor(queue);


builder.Build().Run();
```

The dashboard shows persistent containers with a pin icon:

![Persistent containers](/_astro/persistent-container.B3qvqKn7_1vkmV2.webp)

After the AppHost is stopped, the container will continue to run:

![Docker desktop showing RabbitMQ](/_astro/persistent-container-docker-desktop.fBhTDXpR_1uyp24.webp)

The container persistence mechanism attempts to identify when you might wish to recreate the container. For example, if the environment for the container changes, then the container is restarted so that you don’t need to manually stop the container if the input configuration for the resource has changed.

### Resource commands

[Section titled “Resource commands”](#resource-commands)

The AppHost supports adding custom commands to resources. This is useful when you want to add custom functionality that is not natively supported by the AppHost. There’s likely many opportunities where exposing custom extension methods on resources will be useful. The [Aspire Community Toolkit](/integrations/overview/) might be a good place to share these extensions.

When you define a custom command, it’s available in the dashboard as a user experience feature.

Caution

These Aspire dashboard commands are only available when running the dashboard locally. They’re not available when running the dashboard in Azure Container Apps.

For more information on creating custom resource commands, see [How-to: Create custom resource commands in Aspire](/fundamentals/custom-resource-commands/).

### Container networking

[Section titled “Container networking”](#container-networking)

The AppHost now adds all containers to a common network named `default-aspire-network`. This is useful when you want to communicate between containers without going through the host network. This also makes it easier to migrate from docker compose to the AppHost, as containers can communicate with each other using the container name.

### Eventing model

[Section titled “Eventing model”](#eventing-model)

The eventing model allows developers to hook into the lifecycle of the application and resources. This is useful for running custom code at specific points in the application lifecycle. There are various ways to subscribe to events, including global events and per-resource events.

**Global events:**

* `BeforeStartEvent`: An event that is triggered before the application starts. This is the last place that changes to the app model are observed. This runs in both “Run” and “Publish” modes. This is a blocking event, meaning that the application doesn’t start until all handlers have completed.
* `AfterResourcesCreatedEvent`: An event that is triggered after the resources are created. This runs in Run mode only.
* `AfterEndpointsAllocatedEvent`: An event that is triggered after the endpoints are allocated for all resources. This runs in Run mode only.

The global events are analogous to the AppHost life cycle events. For more information, see [AppHost life cycles](/app-host/eventing/#apphost-eventing).

**Per-resource events:**

* `BeforeResourceStartedEvent`: An event that is triggered before a single resource starts. This runs in Run mode only. This is a blocking event, meaning that the resource doesn’t start until all handlers complete.
* `ConnectionStringAvailableEvent`: An event that is triggered when a connection string is available for a resource. This runs in Run mode only.
* `ResourceReadyEvent`: An event that is triggered when a resource is ready to be used. This runs in Run mode only.

For more information, see [Eventing in Aspire](/app-host/eventing/).

## Integrations

[Section titled “Integrations”](#integrations)

Aspire continues to add integrations that make it easy to get started with your favorite services and tools. For more information, see [Aspire integrations overview](/integrations/overview/).

### Redis Insight

[Section titled “Redis Insight”](#redis-insight)

Support for [Redis Insights](https://redis.io/insight/) is available on a Redis resource:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddRedis("redis")
       .WithRedisInsight(); // Starts a Redis Insight container image
                            // that is pre-configured to work with the
                            // Redis instance.
```

The [`WithRedisInsight`](/reference/api/csharp/aspire.hosting.redis/redisbuilderextensions/methods/#withredisinsight "Configures a container resource for Redis Insight which is pre-configured to connect to the Aspire.Hosting.ApplicationModel.RedisResource that this method is...")[`withRedisInsight`](/reference/api/typescript/aspire.hosting.redis/withredisinsight/ "Adds Redis Insight management UI") extension method can be applied to multiple Redis resources and they’ll each be visible on the Redis Insight dashboard.

![Redis Insight dashboard showing multiple Redis instances](/_astro/redis-insight.oU6J_zOG_1IPTOb.webp)

For more information, see [Add Redis resource with Redis Insights](/integrations/caching/redis/redis-host/#add-redis-resource-with-redis-insight).

### OpenAI (Preview)

[Section titled “OpenAI (Preview)”](#openai-preview)

Starting with Aspire 9, an additional OpenAI integration is available which allows to use the latest official OpenAI dotnet library directly. The client integration registers the OpenAIClient as a singleton service in the service collection. The client can be used to interact with the OpenAI REST API.

* [📦 Aspire.OpenAI](https://www.nuget.org/packages/Aspire.OpenAI/9.0.0)

Moreover, the already available Aspire Azure OpenAI integration was improved to provide a flexible way to configure an `OpenAIClient` for either an Azure AI OpenAI service or a dedicated OpenAI REST API one with the new builder method. The following example detects if the connection string is for an Azure AI OpenAI service and registers the most appropriate `OpenAIClient` instance automatically.

```csharp
builder.AddOpenAIClientFromConfiguration("openai");
```

For instance, if the `openai` connection looked like `Endpoint=https://{account}.azure.com;Key={key};` it would guess it can register an Azure AI OpenAI client because of the domain name. Otherwise a common `OpenAIClient` would be used.

Read [Azure-agnostic client resolution](https://github.com/microsoft/aspire/blob/release/9.0/src/Components/Aspire.Azure.AI.OpenAI/README.md#azure-agnostic-client-resolution) for more details.

### MongoDB

[Section titled “MongoDB”](#mongodb)

Added support for specifying the MongoDB username and password when using the [`AddMongoDB`](/reference/api/csharp/aspire.hosting.mongodb/mongodbbuilderextensions/methods/#addmongodb "Adds a MongoDB resource to the application model. A container is used for local development.")[`addMongoDB`](/reference/api/typescript/aspire.hosting.mongodb/addmongodb/ "Adds a MongoDB container resource") extension method. If not specified, a random username and password is generated but can be manually specified using parameter resources.

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var username = builder.AddParameter("mongousername");
var password = builder.AddParameter("mongopassword", secret: true);


var db = builder.AddMongo("db", username, password);
```

### Important Azure improvements

[Section titled “Important Azure improvements”](#important-azure-improvements)

The following sections describe Azure improvements added in Aspire 9. For a complete listing of all the breaking changes, see Breaking changes in Aspire 9.

#### Azure resource customization

[Section titled “Azure resource customization”](#azure-resource-customization)

In Aspire 8, customizing Azure resources were marked experimental because the underlying `Azure.Provisioning` libraries were new and gathering feedback before they could be marked stable. In Aspire 9 these APIs were updated and removes the experimental attribute.

**Azure Resource naming breaking change**

As part of the update to the provisioning libraries, the default naming scheme for Azure resources was updated with better support for various naming policies. However, this update resulted in a change to how resources are named. The new naming policy might result in the existing Azure resources being abandoned and new Azure resources being created, after updating your Aspire application from 8 to 9. To keep using the same naming policies from Aspire 8, you can add the following code to your AppHost *Program.cs*:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.Services.Configure(options =>
{
    options.ProvisioningBuildOptions.InfrastructureResolvers.Insert(0, new AspireV8ResourceNamePropertyResolver());
});
```

#### Azure SQL, PostgreSQL, and Redis Update

[Section titled “Azure SQL, PostgreSQL, and Redis Update”](#azure-sql-postgresql-and-redis-update)

Azure SQL, PostgreSQL, and Redis resources are different than other Azure resources because there are local container resources for these technologies. In Aspire 8, in order to create these Azure resources you needed to start with a local container resource and then either “As” or “PublishAs” it to an Azure resource. This design introduced problems and didn’t fit with other APIs.

For example, you might have this code in Aspire 8:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var sql = builder.AddSqlServer("sql")
                 .PublishAsAzureSqlDatabase();


var pgsql = builder.AddPostgres("pgsql")
                   .PublishAsAzurePostgresFlexibleServer();


var cache = builder.AddRedis("cache")
                   .PublishAsAzureSqlDatabase();
```

In Aspire 9 these APIs were marked as obsolete and a new API pattern implemented:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var sql = builder.AddAzureSqlServer("sql")
                 .RunAsContainer();


var pgsql = builder.AddAzurePostgresFlexibleServer("pgsql")
                   .RunAsContainer();


var cache = builder.AddAzureRedis("cache")
                   .RunAsContainer();
```

##### Microsoft Entra ID by default

[Section titled “Microsoft Entra ID by default”](#microsoft-entra-id-by-default)

In order to make Aspire applications more secure, Azure Database for PostgreSQL and Azure Cache for Redis resources were updated to use Microsoft Entra ID by default. This requires changes to applications that need to connect to these resources. See the following for updating applications to use Microsoft Entra ID to connect to these resources:

* [Azure Database for PostgreSQL](https://devblogs.microsoft.com/dotnet/using-postgre-sql-with-dotnet-and-entra-id/)
* [Azure Cache for Redis](https://github.com/Azure/Microsoft.Azure.StackExchangeRedis)

The following examples demonstrate how to configure your application to connect to the Azure resources using Microsoft Entra ID:

* [Aspire: Azure PostgreSQL hosting integration](/integrations/cloud/azure/azure-postgresql/azure-postgresql-host/).
* [Aspire: Azure Redis hosting integration](/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host/).

If you need to use password or access key authentication (not recommended), you can opt-in with the following code:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var pgsql = builder.AddAzurePostgresFlexibleServer("pgsql")
                   .WithPasswordAuthentication();


var cache = builder.AddAzureRedis("cache")
                   .WithAccessKeyAuthentication();
```

#### Support for Azure Functions (Preview)

[Section titled “Support for Azure Functions (Preview)”](#support-for-azure-functions-preview)

Support for Azure Functions is one of the most widely requested features on the Aspire issue tracker and we’re excited to introduce preview support for it in this release. To demonstrate this support, let’s use Aspire to create and deploy a webhook.

To get started, create a new Azure Functions project using the **Visual Studio New Project** dialog. When prompted, select the **Enlist in Aspire orchestration** checkbox when creating the project.

![Create new Aspire Azure Functions project](/_astro/functions-step-1.CA_WB3AE_1Wr8H7.webp)

In the AppHost project, observe that there’s a `PackageReference` to the new [📦 Aspire.Hosting.Azure.Functions](https://www.nuget.org/packages/Aspire.Hosting.Azure.Functions) NuGet package:

```xml

    
    

```

This package provides an [`AddAzureFunctionsProject`](/reference/api/csharp/aspire.hosting.azure.functions/azurefunctionsprojectresourceextensions/methods/#addazurefunctionsproject "Adds an Azure Functions project to the distributed application.")[`addAzureFunctionsProject`](/reference/api/typescript/aspire.hosting.azure.functions/addazurefunctionsproject/ "Adds an Azure Functions project to the distributed application.") API that can be invoked in the AppHost to configure Azure Functions projects within an Aspire host:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddAzureFunctionsProject("piglatinapp");


builder.Build().Run();
```

In this example, the webhook is responsible for translating an input string into Pig Latin. Update the contents of our trigger with the following code:

```csharp
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;
using System.Text;
using FromBodyAttribute = Microsoft.Azure.Functions.Worker.Http.FromBodyAttribute;


namespace PigLatinApp;


public class Function1(ILogger logger)
{
    public record InputText(string Value);
    public record PigLatinText(string Value);


    [Function("Function1")]
    public IActionResult Run(
        [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req,
        [FromBody] InputText inputText)
    {
        logger.LogInformation("C# HTTP trigger function processed a request.");


        var result = TranslateToPigLatin(inputText.Value);


        return new OkObjectResult(new PigLatinText(result));
    }


    private static string TranslateToPigLatin(string input)
    {
        if (string.IsNullOrEmpty(input))
        {
            return input;
        }


        var words = input.Split(' ');
        StringBuilder pigLatin = new();


        foreach (string word in words)
        {
            if (IsVowel(word[0]))
            {
                pigLatin.Append(word + "yay ");
            }
            else
            {
                int vowelIndex = FindFirstVowelIndex(word);
                if (vowelIndex is -1)
                {
                    pigLatin.Append(word + "ay ");
                }
                else
                {
                    pigLatin.Append(
                        word.Substring(vowelIndex) + word.Substring(0, vowelIndex) + "ay ");
                }
            }
        }


        return pigLatin.ToString().Trim();
    }


    private static int FindFirstVowelIndex(string word)
    {
        for (var i = 0; i < word.Length; i++)
        {
            if (IsVowel(word[i]))
            {
                return i;
            }
        }
        return -1;
    }


    private static bool IsVowel(char c) =>
        char.ToLower(c) is 'a' or 'e' or 'i' or 'o' or 'u';
}
```

Set a breakpoint on the first `logger.LogInformation` line of the `Run` method and press F5`F5`F5`F5`F5`F5` to start the Functions host. Once the Aspire dashboard launches, you observe the following:

![Screenshot of the Aspire running with an Azure Function app](/_astro/functions-dashboard-screenshot.DmcffsY8_Z1Ev3J0.webp)

Aspire has:

* Configured an emulated Azure Storage resource to be used for bookkeeping by the host.
* Launched the Functions host locally with the target as the Functions project registered.
* Wired the port defined in *launchSettings.json* of the functions project for listening.

Use your favorite HTTP client of choice to send a request to the trigger and observe the inputs bound from the request body in the debugger.

**Unix:**

```bash
curl --request POST \
  --url http://localhost:7282/api/Function1 \
  --header 'Content-Type: application/json' \
  --data '{
  "value": "Welcome to Azure Functions"
}'
```

**Windows:**

```powershell
curl --request POST `
  --url http://localhost:7282/api/Function1 `
  --header 'Content-Type: application/json' `
  --data '{
  "value": "Welcome to Azure Functions"
}'
```

![Screenshot of the Aspire dashboard: Debugging an Azure Function app](/_astro/functions-debug-screenshot.CfEA6Il9_1xhlBj.webp)

Now you’re ready to deploy our application to Azure Container Apps (ACA). Deployment currently depends on preview builds of Azure Functions Worker and Worker SDK packages. If necessary, upgrade the versions referenced in the Functions project:

```xml

    
    

```

You also need to expose a public endpoint for our Azure Functions project so that requests can be sent to our HTTP trigger:

```csharp
builder.AddAzureFunctionsProject("piglatinapp")
       .WithExternalHttpEndpoints();
```

To deploy the application with the `azd` CLI, you need get the latest version first. To install the latest version, you see a warning if your version is out of date. Follow the instructions to update to the latest version.

After it’s installed, navigate to the folder containing the AppHost project and run `azd init`:

```bash
$ azd init


Initializing an app to run on Azure (azd init)


? How do you want to initialize your app? Use code in the current directory
  (✓) Done: Scanning app code in current directory


Detected services:


  .NET (Aspire)
  Detected in: ./PigLatinApp/PigLatinApp.AppHost/PigLatinApp.AppHost.csproj


azd will generate the files necessary to host your app on Azure using Azure Container Apps.


? Select an option Confirm and continue initializing my app
? Enter a new environment name: azfunc-piglatin


Generating files to run your app on Azure:


  (✓) Done: Generating ./azure.yaml
  (✓) Done: Generating ./next-steps.md


SUCCESS: Your app is ready for the cloud!
```

Then, deploy the application by running `azd up`:

```bash
$ azd up
? Select an Azure Subscription to use: 130. [redacted]
? Select an Azure location to use: 50. (US) West US 2 (westus2)


Packaging services (azd package)


Provisioning Azure resources (azd provision)
Provisioning Azure resources can take some time.


Subscription: [redacted]
Location: West US 2


  You can view detailed progress in the Azure Portal:
  [redacted]


  (✓) Done: Resource group: rg-azfunc-piglatin (967ms)
  (✓) Done: Container Registry: [redacted] (13.316s)
  (✓) Done: Log Analytics workspace: [redacted] (16.467s)
  (✓) Done: Container Apps Environment: [redacted] (1m35.531s)
  (✓) Done: Storage account: [redacted] (21.37s)


Deploying services (azd deploy)


  (✓) Done: Deploying service piglatinapp
  - Endpoint: {{endpoint-url}}


  Aspire Dashboard: {{dashboard-url}}
```

Finally, test your deployed Functions application using your favorite HTTP client:

**Unix:**

```bash
curl --request POST \
  --url {{endpoint-url}}/api/Function1 \
  --header 'Content-Type: application/json' \
  --data '{
  "value": "Welcome to Azure Functions"
}'
```

**Windows:**

```powershell
curl --request POST `
  --url {{endpoint-url}}/api/Function1 `
  --header 'Content-Type: application/json' `
  --data '{
  "value": "Welcome to Azure Functions"
}'
```

Support for Azure Functions in Aspire is still in preview with support for a limited set of triggers including:

* [HTTP triggers](https://learn.microsoft.com/azure/azure-functions/functions-triggers-bindings?pivots=programming-language-csharp#supported-bindings)
* [Azure Storage Queue triggers](https://learn.microsoft.com/azure/azure-functions/functions-bindings-storage-queue?pivots=programming-language-csharp)
* [Azure Storage Blob triggers](https://learn.microsoft.com/azure/azure-functions/functions-bindings-storage-blob?pivots=programming-language-csharp)
* [Azure Service Bus triggers](https://learn.microsoft.com/azure/azure-functions/functions-bindings-service-bus?pivots=programming-language-csharp)
* [Azure Event Hubs triggers](https://learn.microsoft.com/azure/azure-functions/functions-bindings-event-hubs?pivots=programming-language-csharp)

For more information, see the official [Aspire Azure Functions integration (Preview)](/integrations/cloud/azure/azure-functions/azure-functions-get-started/).

#### Customization of Azure Container Apps

[Section titled “Customization of Azure Container Apps”](#customization-of-azure-container-apps)

One of the most requested features is the ability to customize the Azure Container Apps that the AppHost creates without touching Bicep. This is possible by using the `PublishAsAzureContainerApp` APIs in the `Aspire.Hosting.Azure.AppContainers` namespace. These methods customizes the Azure Container App definition that the AppHost creates.

Add the package reference to your project file:

```xml

  

```

The following example demonstrates how to scale an Azure Container App to zero (`0`) replicas:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var db = builder.AddAzurePostgresFlexibleServer("pg")
                .RunAsContainer()
                .AddDatabase("db");


// Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
#pragma warning disable AZPROVISION001


builder.AddProject("api")
       .WithReference(db)
       .PublishAsAzureContainerApp((module, containerApp) =>
       {
           // Scale to 0
           containerApp.Template.Value!.Scale.Value!.MinReplicas = 0;
       });


#pragma warning restore AZPROVISION001


builder.Build().Run();
```

The preceding code example defers generation of the Azure Container App definition to the AppHost. This allows you to customize the Azure Container App definition without needing to run `azd infra synth` and unsafely modifying the generated bicep files.

## 🙏 Community

[Section titled “🙏 Community”](#-community)

Aspire is built in the open, and this release wouldn’t be what it is without you. A huge thank you to everyone who helped make Aspire 9.0 possible.

### The Aspire core team is

* [![Adam Ratzman](https://github.com/adamint.png?size=96)Adam Ratzman](https://github.com/adamint)
* [![Ankit Jain](https://github.com/radical.png?size=96)Ankit Jain](https://github.com/radical)
* [![Damian Edwards](https://github.com/DamianEdwards.png?size=96)Damian Edwards](https://github.com/DamianEdwards)
* [![David Fowler](https://github.com/davidfowl.png?size=96)David Fowler](https://github.com/davidfowl)
* [![David Negstad](https://github.com/danegsta.png?size=96)David Negstad](https://github.com/danegsta)
* [![David Pine](https://github.com/IEvangelist.png?size=96)David Pine](https://github.com/IEvangelist)
* [![Ella Hathaway](https://github.com/ellahathaway.png?size=96)Ella Hathaway](https://github.com/ellahathaway)
* [![Eric Erhardt](https://github.com/eerhardt.png?size=96)Eric Erhardt](https://github.com/eerhardt)
* [![James Newton-King](https://github.com/JamesNK.png?size=96)James Newton-King](https://github.com/JamesNK)
* [![José Pérez](https://github.com/joperezr.png?size=96)José Pérez](https://github.com/joperezr)
* [![Karol Zadora-Przylecki](https://github.com/karolz-ms.png?size=96)Karol Zadora-Przylecki](https://github.com/karolz-ms)
* [![Maddy Montaquila](https://github.com/maddymontaquila.png?size=96)Maddy Montaquila](https://github.com/maddymontaquila)
* [![Mitch Denny](https://github.com/mitchdenny.png?size=96)Mitch Denny](https://github.com/mitchdenny)
* [![Sébastien Ros](https://github.com/sebastienros.png?size=96)Sébastien Ros](https://github.com/sebastienros)

Special thanks to everyone whose pull requests shipped in Aspire 9.0, including:

[@afscrome](https://github.com/afscrome), [@Alirexaa](https://github.com/Alirexaa), [@bart-vmware](https://github.com/bart-vmware), [@captainsafia](https://github.com/captainsafia), [@cmeyertons](https://github.com/cmeyertons), [@davidebbo](https://github.com/davidebbo), [@drewnoakes](https://github.com/drewnoakes), [@duskembayev](https://github.com/duskembayev), [@hansmbakker](https://github.com/hansmbakker), [@HofmeisterAn](https://github.com/HofmeisterAn), [@jeffl8n](https://github.com/jeffl8n), [@martincostello](https://github.com/martincostello), [@MichaelSimons](https://github.com/MichaelSimons), [@mmitche](https://github.com/mmitche), [@mu88](https://github.com/mu88), [@normj](https://github.com/normj), [@oising](https://github.com/oising), [@SimonCropp](https://github.com/SimonCropp), [@sliekens](https://github.com/sliekens), [@tmat](https://github.com/tmat), [@vicancy](https://github.com/vicancy), [@vladimir-shirmanov](https://github.com/vladimir-shirmanov), [@vlesierse](https://github.com/vlesierse), and [@Zombach](https://github.com/Zombach)

We're always excited to [see community contributions](/community/contributors/)! If you'd like to get involved, check out our [contributing guide](/community/contributor-guide/).

# What's new in Aspire 9.1

> Explore Aspire 9.1: parent and child resource grouping, dashboard language picker, telemetry filtering, console log downloads, and resource detail enhancements.

📢 Aspire 9.1 is the next minor version release of Aspire; it supports *both*:

* .NET 8.0 Long Term Support (LTS) *or*
* .NET 9.0 Standard Term Support (STS).

Note

You’re able to use Aspire 9.1 with either .NET 8 or .NET 9!

As always, we focused on highly requested features and pain points from the community. Our theme for 9.1 was “polish, polish, polish”—so you see quality of life fixes throughout the whole platform. Some highlights from this release are resource relationships in the dashboard, support for working in GitHub Codespaces, and publishing resources as a Dockerfile.

If you have feedback, questions, or want to contribute to Aspire, collaborate with us on [GitHub](https://github.com/microsoft/aspire) or join us on [Discord](https://discord.com/invite/h87kDAHQgJ) to chat with team members.

Whether you’re new to Aspire or have been with us since the preview, it’s important to note that Aspire releases out-of-band from .NET releases. While major versions of Aspire align with .NET major versions, minor versions are released more frequently. For more details on .NET and Aspire version support, see:

* [.NET support policy](https://dotnet.microsoft.com/platform/support/policy): Definitions for LTS and STS.
* [Aspire support policy](https://dotnet.microsoft.com/platform/support/policy/aspire): Important unique product life cycle details.

## ⬆️ Upgrade to Aspire 9.1

[Section titled “⬆️ Upgrade to Aspire 9.1”](#️-upgrade-to-aspire-91)

Moving between minor releases of Aspire is simple:

1. In your AppHost project file (that is, *MyApp.AppHost.csproj*), update the [📦 Aspire.AppHost.Sdk](https://www.nuget.org/packages/Aspire.AppHost.Sdk) NuGet package to version `9.1.0`:

   ```xml
   


       


       


   
   ```

   For more information, see [Aspire SDK](/get-started/aspire-sdk/).

2. Check for any NuGet package updates, either using the NuGet Package Manager in Visual Studio or the **Update NuGet Package** command in VS Code.

3. Update to the latest Aspire templates by running the following .NET command line:

   ```bash
   dotnet new update
   ```

   Note

   The `dotnet new update` command updates all of your templates to the latest version.

If your AppHost project file doesn’t have the `Aspire.AppHost.Sdk` reference, you might still be using Aspire 8. To upgrade to 9.0, you can follow the documentation from last release.

## 🌱 Improved onboarding experience

[Section titled “🌱 Improved onboarding experience”](#-improved-onboarding-experience)

The onboarding experience for Aspire is improved with 9.1. The team worked on creating a GitHub Codespaces template that installs all the necessary dependencies for Aspire, making it easier to get started, including the templates and the ASP.NET Core developer certificate. Additionally, there’s support for Dev Containers. For more information, see:

* [Aspire and GitHub Codespaces](/get-started/github-codespaces/)
* [Aspire and Visual Studio Code Dev Containers](/get-started/dev-containers/)

## 🔧 Dashboard UX and customization

[Section titled “🔧 Dashboard UX and customization”](#-dashboard-ux-and-customization)

With every release of Aspire, the [dashboard](/dashboard/overview/) gets more powerful and customizable, this release is no exception. The following features were added to the dashboard in Aspire 9.1:

### 🧩 Resource relationships

[Section titled “🧩 Resource relationships”](#-resource-relationships)

The dashboard now supports “parent” and “child” resource relationships. For instance, when you create a Postgres instance with multiple databases, these databases are nested under the same instance on the **Resource** page.

![A screenshot of the Aspire dashboard showing the Postgres resource with a database nested underneath it](/_astro/dashboard-parentchild.BskzU4XP_CvrA7.webp)

For more information, see [Explore the Aspire dashboard](/dashboard/explore/).

### 🔤 Localization overrides

[Section titled “🔤 Localization overrides”](#-localization-overrides)

The dashboard defaults to the language set in your browser. This release introduces the ability to override this setting and change the dashboard language independently from the browser language. Consider the following screen capture that demonstrates the addition of the language dropdown in the dashboard:

![A screenshot of the Aspire dashboard showing the new flyout menu to change language](/_astro/dashboard-language.C-mH-xqR_VN88J.webp)

### 🗑️ Clear logs and telemetry from the dashboard

[Section titled “🗑️ Clear logs and telemetry from the dashboard”](#️-clear-logs-and-telemetry-from-the-dashboard)

New buttons were added to the **Console logs**, **Structured logs**, **Traces** and **Metrics** pages to clear data. There’s also a “Remove all” button in the settings popup to remove everything with one action.

Now you use this feature to reset the dashboard to a blank slate, test your app, view only the relevant logs and telemetry, and repeat.

![A screenshot of the Aspire dashboard showing the remove button on the structured logs page](/_astro/dashboard-remove-telemetry.mDXzVBZ7_Z2plK77.webp)

We 💜 love the developer community and thrive on its feedback, collaboration, and contributions. This feature is a community contribution from [@Daluur](https://github.com/Daluur). Join us in celebrating their contribution by using the feature!

Tip

If you’re interested in contributing to Aspire, look for issues labeled with [good first issue](https://github.com/microsoft/aspire/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) and follow the [contributor guide](https://github.com/microsoft/aspire/blob/main/docs/contributing.md).

### 🔢 New filtering

[Section titled “🔢 New filtering”](#-new-filtering)

You can now filter what you see in the **Resource** page by **Resource type**, **State**, and **Health state**. Consider the following screen capture, which demonstrates the addition of the filter options in the dashboard:

![A screenshot of the Aspire dashboard showing the new filter options](/_astro/dashboard-filter.CLfzcqCD_Z27poes.webp)

### 📝 More resource details

[Section titled “📝 More resource details”](#-more-resource-details)

When you select a resource in the dashboard, the details pane now displays new data points, including **References**, **Back references**, and **Volumes** with their mount types. This enhancement provides a clearer and more comprehensive view of your resources, improving the overall user experience by making relevant details more accessible.

![A screenshot of the Aspire dashboard with references and back references showing](/_astro/dashboard-resourcedetails.DkgK8ZwV_2eWbIB.webp)

For more information, see [Aspire dashboard: Resources page](/dashboard/explore/#resources-page).

### 🛡️ CORS support for custom local domains

[Section titled “🛡️ CORS support for custom local domains”](#️-cors-support-for-custom-local-domains)

You can now set the `ASPIRE_DASHBOARD_CORS_ALLOWED_ORIGINS` environment variable to allow the dashboard to receive telemetry from other browser apps, such as if you have resources running on custom localhost domains.

For more information, see [Aspire AppHost: Dashboard configuration](/app-host/configuration/#dashboard).

### 🪵 Flexibility with console logs

[Section titled “🪵 Flexibility with console logs”](#-flexibility-with-console-logs)

The console log page has two new options. You’re now able to download your logs so you can view them in your own diagnostics tools. Plus, you can turn timestamps on or off to reduce visual clutter when needed.

![A screenshot of the console logs page with the download button, turn off timestamps button, and logs that don't show timestamps](/_astro/consolelogs-download.k9-sE6XM_Z2690Ns.webp)

For more information, see [Aspire dashboard: Console logs page](/dashboard/explore/#console-logs-page).

### 🎨 Various UX improvements

[Section titled “🎨 Various UX improvements”](#-various-ux-improvements)

Several new features in Aspire 9.1 enhance and streamline the following popular tasks:

* ▶️ Resource commands, such as **Start** and **Stop** buttons, are now available on the **Console logs** page.
* 🔍 Single selection to open in the *text visualizer*.
* 🔗 URLs within logs are now automatically clickable, with commas removed from endpoints.

Additionally, the 🖱️ scroll position resets when switching between different resources—this helps to visually reset the current resource view.

For more details on the latest dashboard enhancements, check out [James Newton-King on Bluesky](https://bsky.app/profile/james.newtonking.com), where he’s been sharing new features daily.

## ⚙️ Local development enhancements

[Section titled “⚙️ Local development enhancements”](#️-local-development-enhancements)

In Aspire 9.1, several improvements to streamline your local development experience were an emphasis. These enhancements are designed to provide greater flexibility, better integration with Docker, and more efficient resource management. Here are some of the key updates:

### ▶️ Start resources on demand

[Section titled “▶️ Start resources on demand”](#️-start-resources-on-demand)

You can now tell resources not to start with the rest of your app by using [`WithExplicitStart`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withexplicitstart "Adds a Aspire.Hosting.ApplicationModel.ExplicitStartupAnnotation annotation to the resource so it doesn't automatically start with the AppHost startup.")[`withExplicitStart`](/reference/api/typescript/aspire.hosting/withexplicitstart/ "Prevents resource from starting automatically") on the resource in your AppHost. Then, you can start it whenever you’re ready from inside the dashboard.

### 🐳 Better Docker integration

[Section titled “🐳 Better Docker integration”](#-better-docker-integration)

The `PublishAsDockerfile()` feature was introduced for all projects and executable resources. This enhancement allows for complete customization of the Docker container and Dockerfile used during the publish process.

While this API was available in previous versions, it couldn’t be used with project or executable resource types.

### 🧹 Cleaning up Docker networks

[Section titled “🧹 Cleaning up Docker networks”](#-cleaning-up-docker-networks)

In 9.1, we addressed a persistent issue where Docker networks created by Aspire would remain active even after the application was stopped. This bug, tracked in [Aspire GitHub issue #6504](https://github.com/microsoft/aspire/issues/6504), is resolved. Now, Docker networks are properly cleaned up, ensuring a more efficient and tidy development environment.

### ✅ Socket address issues fixed

[Section titled “✅ Socket address issues fixed”](#-socket-address-issues-fixed)

Several users reported issues ([#6693](https://github.com/microsoft/aspire/issues/6693), [#6704](https://github.com/microsoft/aspire/issues/6704), [#7095](https://github.com/microsoft/aspire/issues/7095)) with restarting the Aspire AppHost, including reconciliation errors and “address already in use” messages.

This release introduces a more robust approach to managing socket addresses, ensuring only one instance of each address is used at a time. Additionally, improvements were made to ensure proper project restarts and resource releases, preventing hanging issues. These changes enhance the stability and reliability of the AppHost, especially during development and testing.

## 🔌 Integration updates

[Section titled “🔌 Integration updates”](#-integration-updates)

Aspire continues to excel through its [integrations](/integrations/overview/) with various platforms. This release includes numerous updates to existing integrations and details about ownership migrations, enhancing the overall functionality and user experience.

### ☁️ Azure updates

[Section titled “☁️ Azure updates”](#️-azure-updates)

This release also focused on improving various [Azure integrations](/integrations/cloud/azure/overview/):

#### 🆕 New emulators

[Section titled “🆕 New emulators”](#-new-emulators)

We’re excited to bring new emulators for making local development easier. The following integrations got new emulators in this release:

* [Azure Service Bus](/integrations/cloud/azure/azure-service-bus/azure-service-bus-host/#add-azure-service-bus-emulator-resource)
* [Azure Cosmos DB Linux-based (preview)](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#run-as-emulator)
* [Azure SignalR](/integrations/cloud/azure/azure-signalr/azure-signalr-host/#add-azure-signalr-service-emulator-resource)

```csharp
var serviceBus = builder.AddAzureServiceBus("servicebus")
                        .RunAsEmulator();


#pragma warning disable ASPIRECOSMOSDB001
var cosmosDb = builder.AddAzureCosmosDB("cosmosdb")
                      .RunAsPreviewEmulator();


var signalr = builder.AddAzureSignalR("signalr", AzureSignalRServiceMode.Serverless)
                      .RunAsEmulator();
```

These new emulators work side-by-side with the existing emulators for:

* [Azure Storage](/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started/)
* [Azure Event Hubs](/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-host/#run-as-emulator)
* [Azure Cosmos DB](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#run-as-emulator)

#### 🌌 Cosmos DB

[Section titled “🌌 Cosmos DB”](#-cosmos-db)

Along with support for the new emulator, Cosmos DB added the following features.

##### 🔒 Support for Entra ID authentication by default

[Section titled “🔒 Support for Entra ID authentication by default”](#-support-for-entra-id-authentication-by-default)

Previously, the Cosmos DB integration used access keys and a Key Vault secret to connect to the service. Aspire 9.1 added support for using more secure authentication using managed identities by default. If you need to keep using access key authentication, you can get back to the previous behavior by calling [`WithAccessKeyAuthentication`](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosextensions/methods/#withaccesskeyauthentication "Configures the resource to use access key authentication with Azure Cosmos DB.")[`withAccessKeyAuthentication`](/reference/api/typescript/aspire.hosting.azure.cosmosdb/withaccesskeyauthentication/ "Configures Azure Cosmos DB to use access key authentication").

##### 💽 Support for modeling Database and Containers in the AppHost

[Section titled “💽 Support for modeling Database and Containers in the AppHost”](#-support-for-modeling-database-and-containers-in-the-apphost)

You can define a Cosmos DB database and containers in the AppHost and these resources are available when you run the application in both the emulator and in Azure. This allows you to define these resources up front and no longer need to create them from the application, which might not have permission to create them.

For example API usage to add database and containers, see the following related articles:

* [Aspire Azure Cosmos DB integration](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#add-azure-cosmos-db-database-and-container-resources)
* [Aspire Cosmos DB Entity Framework Core integration](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#add-azure-cosmos-db-database-and-container-resources)

##### ⚡ Support for Cosmos DB-based triggers in Azure Functions

[Section titled “⚡ Support for Cosmos DB-based triggers in Azure Functions”](#-support-for-cosmos-db-based-triggers-in-azure-functions)

The Azure Cosmos DB resource was modified to support consumption in Azure Functions applications that uses the Cosmos DB trigger. A Cosmos DB resource can be initialized and added as a reference to an Azure Functions resource with the following code:

```csharp
var cosmosDb = builder.AddAzureCosmosDB("cosmosdb")
                      .RunAsEmulator();
var database = cosmosDb.AddCosmosDatabase("mydatabase");
database.AddContainer("mycontainer", "/id");


var funcApp = builder.AddAzureFunctionsProject("funcapp")
       .WithReference(cosmosDb)
    .WaitFor(cosmosDb);
```

The resource can be used in the Azure Functions trigger as follows:

```csharp
public class MyCosmosDbTrigger(ILogger logger)
{
    [Function(nameof(MyCosmosDbTrigger))]
    public void Run([CosmosDBTrigger(
        databaseName: "mydatabase",
        containerName: "mycontainer",
        CreateLeaseContainerIfNotExists = true,
        Connection = "cosmosdb")] IReadOnlyList input)
    {
        logger.LogInformation(
            "C# cosmosdb trigger function processed: {Count} messages",
            input.Count);
    }
}
```

For more information using Azure Functions with Aspire, see [Aspire Azure Functions integration (Preview)](/integrations/cloud/azure/azure-functions/azure-functions-get-started/).

#### 🚚 Service Bus and Event Hubs

[Section titled “🚚 Service Bus and Event Hubs”](#-service-bus-and-event-hubs)

Similar to Cosmos DB, the Service Bus and Event Hubs integrations now allow you to define Azure Service Bus queues, topics, subscriptions, and Azure Event Hubs instances and consumer groups directly in your AppHost code. This enhancement simplifies your application logic by enabling the creation and management of these resources outside the application itself.

For more information, see the following updated articles:

* [Aspire Azure Service Bus integration](/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/)
* [Aspire Azure Event Hubs integration](/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/)

#### ♻️ Working with existing resources

[Section titled “♻️ Working with existing resources”](#️-working-with-existing-resources)

There’s consistent feedback about making it easier to connect to existing Azure resources in Aspire. With 9.1, you can now easily connect to an existing Azure resource either directly by `string` name, or with [app model parameters](/fundamentals/external-parameters/) which can be changed at deployment time. For example to connect to an Azure Service Bus account, we can use the following code:

```csharp
var existingServiceBusName = builder.AddParameter("serviceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("serviceBusResourceGroup");


var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);
```

The preceding code reads the name and resource group from the parameters, and connects to the existing resource when the application is run or deployed. For more information, see [use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources).

#### 🌍 Azure Container Apps

[Section titled “🌍 Azure Container Apps”](#-azure-container-apps)

Experimental support for configuring custom domains in Azure Container Apps (ACA) was added. For example:

```csharp
#pragma warning disable ASPIREACADOMAINS001


var customDomain = builder.AddParameter("customDomain");
var certificateName = builder.AddParameter("certificateName");


builder.AddProject("api")
       .WithExternalHttpEndpoints()
       .PublishAsAzureContainerApp((infra, app) =>
       {
           app.ConfigureCustomDomain(customDomain, certificateName);
       });
```

For more information, see [Aspire diagnostics overview](/diagnostics/overview/).

### ➕ Even more integration updates

[Section titled “➕ Even more integration updates”](#-even-more-integration-updates)

* OpenAI now supports the [📦 Microsoft.Extensions.AI](https://www.nuget.org/packages/Microsoft.Extensions.AI) NuGet package.

* RabbitMQ updated to version 7, and MongoDB to version 3. These updates introduced breaking changes, leading to the release of new packages with version-specific suffixes. The original packages continue to use the previous versions, while the new packages are as follows:

  * [📦 Aspire.RabbitMQ.Client.v7](https://www.nuget.org/packages/Aspire.RabbitMQ.Client.v7) NuGet package. For more information, see the [Aspire RabbitMQ client integration](/integrations/messaging/rabbitmq/rabbitmq-client/) documentation.
  * [📦 Aspire.MongoDB.Driver.v3](https://www.nuget.org/packages/Aspire.MongoDB.Driver.v3) NuGet package. For more information, see the [Aspire MongoDB client integration](/integrations/databases/mongodb/mongodb-client/) documentation.

* Dapr migrated to the [CommunityToolkit](https://github.com/CommunityToolkit/Aspire/tree/main/src/CommunityToolkit.Aspire.Hosting.Dapr) to facilitate faster innovation.

* Numerous other integrations received updates, fixes, and new features. For detailed information, refer to our [GitHub release notes](https://github.com/microsoft/aspire/releases).

The [📦 Aspire.Hosting.AWS](https://www.nuget.org/packages/Aspire.Hosting.AWS) NuGet package and source code migrated under [Amazon Web Services (AWS)) ownership](https://github.com/aws/integrations-on-dotnet-aspire-for-aws). This migration happened as part of Aspire 9.0, we’re just restating that change here.

## 🧪 Testing in Aspire

[Section titled “🧪 Testing in Aspire”](#-testing-in-aspire)

Aspire 9.1 simplifies writing cross-functional integration tests with a robust approach. The AppHost allows you to create, evaluate, and manage containerized environments seamlessly within a test run. This functionality supports popular testing frameworks like xUnit, NUnit, and MSTest, enhancing your testing capabilities and efficiency.

Now, you’re able to disable port randomization or enable the [dashboard](/dashboard/overview/). For more information, see [Aspire testing overview](/testing/overview/). Additionally, you can now [Pass arguments to your AppHost](/testing/manage-app-host/#pass-arguments-to-your-apphost).

Some of these enhancements were introduced as a result of stability issues that were reported, such as [Aspire GitHub issue #6678](https://github.com/microsoft/aspire/issues/6678)—where some resources failed to start do to “address in use” errors.

## 🚀 Deployment

[Section titled “🚀 Deployment”](#-deployment)

Significant improvements to the Azure Container Apps (ACA) deployment process are included in Aspire 9.1, enhancing both the `azd` CLI and AppHost options. One of the most requested features—support for deploying `npm` applications to ACA—is now implemented. This new capability allows `npm` apps to be deployed to ACA just like other resources, streamlining the deployment process and providing greater flexibility for developers.

We recognize there’s more work to be done in the area of deployment. Future releases will continue to address these opportunities for improvement. For more information on deploying Aspire to ACA, see [Deploy an Aspire project to Azure Container Apps](/deployment/azure/container-apps/).

## ⚠️ Breaking changes

[Section titled “⚠️ Breaking changes”](#️-breaking-changes)

Aspire is moving quickly, and with that comes breaking changes. Breaking are categorized as either:

* **Binary incompatible**: The assembly version has changed, and you need to recompile your code.
* **Source incompatible**: The source code has changed, and you need to change your code.
* **Behavioral change**: The code behaves differently, and you need to change your code.

Typically APIs are decorated with the obsolete attribute giving you a warning when you compile, and an opportunity to adjust your code. For an overview of breaking changes in Aspire 9.1, see Breaking changes in Aspire 9.1.

## 🎯 Upgrade today

[Section titled “🎯 Upgrade today”](#-upgrade-today)

Follow the directions outlined in the [Upgrade to Aspire 9.1](#-upgrade-to-aspire-91) section to make the switch to 9.1 and take advantage of all these new features today! As always, we’re listening for your feedback on [GitHub](https://github.com/microsoft/aspire/issues)-and looking out for what you want to see in 9.2 ☺️.

For a complete list of issues addressed in this release, see [Aspire GitHub repository—9.1 milestone](https://github.com/microsoft/aspire/issues?q=is%3Aissue%20state%3Aclosed%20milestone%3A9.1%20).

## 🙏 Community

[Section titled “🙏 Community”](#-community)

Aspire is built in the open, and this release wouldn’t be what it is without you. A huge thank you to everyone who helped make Aspire 9.1 possible.

### The Aspire core team is

* [![Adam Ratzman](https://github.com/adamint.png?size=96)Adam Ratzman](https://github.com/adamint)
* [![Ankit Jain](https://github.com/radical.png?size=96)Ankit Jain](https://github.com/radical)
* [![Damian Edwards](https://github.com/DamianEdwards.png?size=96)Damian Edwards](https://github.com/DamianEdwards)
* [![David Fowler](https://github.com/davidfowl.png?size=96)David Fowler](https://github.com/davidfowl)
* [![David Negstad](https://github.com/danegsta.png?size=96)David Negstad](https://github.com/danegsta)
* [![David Pine](https://github.com/IEvangelist.png?size=96)David Pine](https://github.com/IEvangelist)
* [![Ella Hathaway](https://github.com/ellahathaway.png?size=96)Ella Hathaway](https://github.com/ellahathaway)
* [![Eric Erhardt](https://github.com/eerhardt.png?size=96)Eric Erhardt](https://github.com/eerhardt)
* [![James Newton-King](https://github.com/JamesNK.png?size=96)James Newton-King](https://github.com/JamesNK)
* [![José Pérez](https://github.com/joperezr.png?size=96)José Pérez](https://github.com/joperezr)
* [![Karol Zadora-Przylecki](https://github.com/karolz-ms.png?size=96)Karol Zadora-Przylecki](https://github.com/karolz-ms)
* [![Maddy Montaquila](https://github.com/maddymontaquila.png?size=96)Maddy Montaquila](https://github.com/maddymontaquila)
* [![Mitch Denny](https://github.com/mitchdenny.png?size=96)Mitch Denny](https://github.com/mitchdenny)
* [![Sébastien Ros](https://github.com/sebastienros.png?size=96)Sébastien Ros](https://github.com/sebastienros)

Special thanks to everyone whose pull requests shipped in Aspire 9.1, including:

[@aaronpowell](https://github.com/aaronpowell), [@adamsitnik](https://github.com/adamsitnik), [@adelinowona](https://github.com/adelinowona), [@afscrome](https://github.com/afscrome), [@Alirexaa](https://github.com/Alirexaa), [@bart-vmware](https://github.com/bart-vmware), [@benjaminpetit](https://github.com/benjaminpetit), [@captainsafia](https://github.com/captainsafia), [@Cethric](https://github.com/Cethric), [@ChinoUkaegbu](https://github.com/ChinoUkaegbu), [@cqnguy23](https://github.com/cqnguy23), [@Daluur](https://github.com/Daluur), [@danmoseley](https://github.com/danmoseley), [@drewnoakes](https://github.com/drewnoakes), [@Evangelink](https://github.com/Evangelink), [@FullStackChef](https://github.com/FullStackChef), [@g7ed6e](https://github.com/g7ed6e), [@gansb](https://github.com/gansb), [@kiapanahi](https://github.com/kiapanahi), [@larsfjerm](https://github.com/larsfjerm), [@los93sol](https://github.com/los93sol), [@MarcinJuraszek](https://github.com/MarcinJuraszek), [@martincostello](https://github.com/martincostello), [@matthebrown](https://github.com/matthebrown), [@mbwilding](https://github.com/mbwilding), [@mfcollins3](https://github.com/mfcollins3), [@Mrxx99](https://github.com/Mrxx99), [@NinoFloris](https://github.com/NinoFloris), [@oising](https://github.com/oising), [@OptimusPi](https://github.com/OptimusPi), [@paule96](https://github.com/paule96), [@paulomorgado](https://github.com/paulomorgado), [@RafaelJCamara](https://github.com/RafaelJCamara), [@ReubenBond](https://github.com/ReubenBond), [@SteveSandersonMS](https://github.com/SteveSandersonMS), [@Thovenaar](https://github.com/Thovenaar), [@vicancy](https://github.com/vicancy), [@vnbaaij](https://github.com/vnbaaij), [@WeihanLi](https://github.com/WeihanLi), and [@wtgodbe](https://github.com/wtgodbe)

We're always excited to [see community contributions](/community/contributors/)! If you'd like to get involved, check out our [contributing guide](/community/contributor-guide/).

# What's new in Aspire 9.2

> Explore Aspire 9.2: dashboard cardinality limits, UTC console logs, telemetry pause, resource icons, and broader app-host and integrations updates across the stack.

📢 Aspire 9.2 is the next minor version release of Aspire; it supports:

* .NET 8.0 Long Term Support (LTS)
* .NET 9.0 Standard Term Support (STS)

If you have feedback, questions, or want to contribute to Aspire, collaborate with us on [GitHub](https://github.com/microsoft/aspire) or join us on [Discord](https://discord.com/invite/h87kDAHQgJ) to chat with team members.

It’s important to note that Aspire releases out-of-band from .NET releases. While major versions of Aspire align with .NET major versions, minor versions are released more frequently. For more information on .NET and Aspire version support, see:

* [.NET support policy](https://dotnet.microsoft.com/platform/support/policy): Definitions for LTS and STS.
* [Aspire support policy](https://dotnet.microsoft.com/platform/support/policy/aspire): Important unique product life cycle details.

## ⬆️ Upgrade to Aspire 9.2

[Section titled “⬆️ Upgrade to Aspire 9.2”](#️-upgrade-to-aspire-92)

Caution

If you are using `azd` to deploy Azure PostgreSQL or Azure SQL Server, you now have to configure Azure Managed Identities. For more information, see [🛡️ Improved Managed Identity defaults](#improved-managed-identity-defaults).

Moving between minor releases of Aspire is simple:

1. In your AppHost project file (that is, *MyApp.AppHost.csproj*), update the [📦 Aspire.AppHost.Sdk](https://www.nuget.org/packages/Aspire.AppHost.Sdk) NuGet package to version `9.2.0`:

   ```diff
   


       


       
           Exe
           net9.0
          true
           
       


       
           
       


       
   
   ```

   Caution

   The `IsAspireHost` property is no longer required in the project file. For more information, see [🚧 Project file changes](#project-file-changes).

   For more information, see [Aspire SDK](/get-started/aspire-sdk/).

2. Check for any NuGet package updates, either using the NuGet Package Manager in Visual Studio or the **Update NuGet Package** command in VS Code.

3. Update to the latest Aspire templates by running the following .NET command line:

   ```bash
   dotnet new update
   ```

   Caution

   The `dotnet new update` command updates all of your templates to the latest version.

If your AppHost project file doesn’t have the `Aspire.AppHost.Sdk` reference, you might still be using Aspire 8. To upgrade to 9.0, follow [the upgrade guide](/whats-new/upgrade-aspire/).

## 🖥️ AppHost enhancements

[Section titled “🖥️ AppHost enhancements”](#️-apphost-enhancements)

The [AppHost](/get-started/app-host/) is the core of Aspire, providing the local hosting environment for your distributed applications. In Aspire 9.2, we’ve made several improvements to the AppHost:

### 🚧 Project file changes

[Section titled “🚧 Project file changes”](#-project-file-changes)

The Aspire AppHost project file no longer requires the `IsAspireHost` property. This property was moved to the `Aspire.AppHost.Sdk` SDK, therefore, you can remove it from your project file. For more information, see [microsoft/aspire issue #8144](https://github.com/microsoft/aspire/pull/8144).

### 🔗 Define custom resource URLs

[Section titled “🔗 Define custom resource URLs”](#-define-custom-resource-urls)

Resources can now define custom URLs. This makes it easier to build custom experiences for your resources. For example, you can define a custom URL for a database resource that points to the database management console. This makes it easier to access the management console directly from the dashboard, you can even give it a friendly name.

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var catalogDb = builder.AddPostgres("postgres")
                       .WithDataVolume()
                       .WithPgAdmin(resource =>
                       {
                           resource.WithUrlForEndpoint("http", u => u.DisplayText = "PG Admin");
                       })
                       .AddDatabase("catalogdb");
```

The preceding code sets the display text for the `PG Admin` URL to `PG Admin`. This makes it easier to access the management console directly from the dashboard.

For more information, see [Define custom resource URLs](/fundamentals/custom-resource-urls/).

## 🔧 Dashboard user experience improvements

[Section titled “🔧 Dashboard user experience improvements”](#-dashboard-user-experience-improvements)

Aspire 9.2 adds new features to the [dashboard](/dashboard/overview/), making it a more powerful developer tool than ever. The following features were added to the dashboard in Aspire 9.2:

### 🧩 Resource graph

[Section titled “🧩 Resource graph”](#-resource-graph)

The resource graph is a new way to visualize the resources in your apps. It displays a graph of resources, linked by relationships. Click the ‘Graph’ tab on the Resources page to view the resource graph. See it in action on [James’s BlueSky](https://bsky.app/profile/james.newtonking.com/post/3lj7odu4re22p).

For more information, see [Aspire dashboard: Resources page](/dashboard/explore/#resources-page).

### 🎨 Resource icons

[Section titled “🎨 Resource icons”](#-resource-icons)

We’ve added resource icons to the resources page. The icon color matches the resource’s telemetry in structured logs and traces.

![Screenshot of dashboard resource's page showing the new resource icons.](/_astro/dashboard-resource-icons.BLIGGrPJ_Z29O7R7.webp)

### ⏯️ Pause and resume telemetry

[Section titled “⏯️ Pause and resume telemetry”](#️-pause-and-resume-telemetry)

New buttons were added to the **Console logs**, **Structured logs**, **Traces** and **Metrics** pages to pause collecting telemetry. Click the pause button again to resume collecting telemetry.

This feature allows you to pause telemetry in the dashboard while continuing to interact with your app.

![Screenshot of the dashboard showing the pause button.](/_astro/dashboard-pause-telemetry.DkHyRia1_XOR5O.webp)

### ❤️‍🩹 Metrics health warning

[Section titled “❤️‍🩹 Metrics health warning”](#️-metrics-health-warning)

The dashboard now warns you when a metric exceeds the configured cardinality limit. Once exceeded, the metric no longer provides accurate information.

![Screenshot of a metric with the cardinality limit warning.](/_astro/dashboard-cardinality-limit.DkiDd8rP_Z26ca7n.webp)

### 🕰️ UTC Console logs option

[Section titled “🕰️ UTC Console logs option”](#️-utc-console-logs-option)

Console logs now supports UTC timestamps. The setting is accessible via the console logs options button.

![Screenshot of console logs page showing the UTC timestamps option.](/_astro/dashboard-console-logs-utc.Ys3ltSuZ_Z2adInp.webp)

### 🔎 Trace details search text box

[Section titled “🔎 Trace details search text box”](#-trace-details-search-text-box)

We’ve added a search text box to trace details. Now you can quickly filter large traces to find the exact span you need. See it in action on [BluSky](https://bsky.app/profile/james.newtonking.com/post/3llunn7fc4s2p).

### 🌐 HTTP-based resource command functionality

[Section titled “🌐 HTTP-based resource command functionality”](#-http-based-resource-command-functionality)

[Custom resource commands](/fundamentals/custom-resource-commands/) now support HTTP-based functionality with the addition of the [`WithHttpCommand`](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods/#withhttpcommand "Adds a command to the resource that when invoked sends an HTTP request to the specified endpoint and path.")[`withHttpCommand`](/reference/api/typescript/aspire.hosting/withhttpcommand/ "Adds an HTTP resource command") API, enabling you to define endpoints for tasks like database migrations or resets. These commands can be run directly from the Aspire dashboard.

Adds WithHttpCommand(), which lets you define a resource command that sends an HTTP request to your app during development. Useful for triggering endpoints like seed or reset from the dashboard.

```csharp
if (builder.Environment.IsDevelopment())
{
    var resetDbKey = Guid.NewGuid().ToString();


    catalogDbApp.WithEnvironment("DatabaseResetKey", resetDbKey)
                .WithHttpCommand("/reset-db", "Reset Database",
                    commandOptions: new()
                    {
                        Description = "Reset the catalog database to its initial state. This will delete and recreate the database.",
                        ConfirmationMessage = "Are you sure you want to reset the catalog database?",
                        IconName = "DatabaseLightning",
                        PrepareRequest = requestContext =>
                        {
                            requestContext.Request.Headers.Add("Authorization", $"Key {resetDbKey}");
                            return Task.CompletedTask;
                        }
                    });
}
```

For more information, see [Custom HTTP commands in Aspire](/fundamentals/http-commands/).

### 🗂️ Connection string resource type

[Section titled “🗂️ Connection string resource type”](#️-connection-string-resource-type)

We’ve introduced a new `ConnectionStringResource` type that makes it easier to build dynamic connection strings without defining a separate resource type. This makes it easier to work with and build dynamic parameterized connection strings.

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var apiKey = builder.AddParameter("apiKey");
var cs = builder.AddConnectionString("openai",
    ReferenceExpression.Create($"Endpoint=https://api.openai.com/v1;AccessKey={apiKey};"));


var api = builder.AddProject("api")
                .WithReference(cs);
```

### 📥 Container resources can now specify an image pull policy

[Section titled “📥 Container resources can now specify an image pull policy”](#-container-resources-can-now-specify-an-image-pull-policy)

Container resources can now specify an `ImagePullPolicy` to control when the image is pulled. This is useful for resources that are updated frequently or that have a large image size. The following policies are supported:

* `Default`: Default behavior (which is the same as `Missing` in 9.2).
* `Always`: Always pull the image.
* `Missing`: Ensures the image is always pulled when the container starts.

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var cache = builder.AddRedis("cache")
                   .WithImageTag("latest")
                   .WithImagePullPolicy(ImagePullPolicy.Always)
                   .WithRedisInsight();
```

The `ImagePullPolicy` is set to `Always`, which means the image will always be pulled when the resource is created. This is useful for resources that are updated frequently.

### 📂 New container files API

[Section titled “📂 New container files API”](#-new-container-files-api)

In Aspire 9.2, we’ve added a new [`WithContainerFiles`](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods/#withcontainerfiles "Creates or updates files and/or folders at the destination path in the container.")[`withContainerFiles`](/reference/api/typescript/aspire.hosting/withcontainerfiles/ "Creates or updates files and folders in a container by copying them from a source path on the host.") API, a way to create files and folders inside a container at runtime by defining them in code. Under the hood, it uses `docker cp` / `podman cp` to copy the files in. Supports setting contents, permissions, and ownership—no bind mounts or temp files needed.

## 🤝 Integrations updates

[Section titled “🤝 Integrations updates”](#-integrations-updates)

Integrations are a key part of Aspire, allowing you to easily add and configure services in your app. In Aspire 9.2, we’ve made several updates to integrations:

### 🔐 Redis/Valkey/Garnet: Password support enabled by default

[Section titled “🔐 Redis/Valkey/Garnet: Password support enabled by default”](#-redisvalkeygarnet-password-support-enabled-by-default)

The Redis, Valkey, and Garnet containers enable password authentication by default. This is part of our goal to be secure by default—protecting development environments with sensible defaults while still making them easy to configure. Passwords can be set explicitly or generated automatically if not provided.

### 💾 Automatic database creation support

[Section titled “💾 Automatic database creation support”](#-automatic-database-creation-support)

There’s [plenty of feedback and confusion](https://github.com/microsoft/aspire/issues/7101) around the [`AddDatabase`](/reference/api/csharp/aspire.hosting.sqlserver/sqlserverbuilderextensions/methods/#adddatabase "Adds a SQL Server database to the application model. This is a child resource of a Aspire.Hosting.ApplicationModel.SqlServerServerResource.")[`addDatabase`](/reference/api/typescript/aspire.hosting.sqlserver/adddatabase/ "Adds a SQL Server database resource") API. The name implies that it adds a database, but it didn’t actually create the database. In Aspire 9.2, the `AddDatabase` API now creates a database for the following hosting integrations:

| Hosting integration                                                                      | API reference |
| ---------------------------------------------------------------------------------------- | ------------- |
| [📦 Aspire.Hosting.SqlServer](https://www.nuget.org/packages/Aspire.Hosting.SqlServer)   | `AddDatabase` |
| [📦 Aspire.Hosting.PostgreSql](https://www.nuget.org/packages/Aspire.Hosting.PostgreSql) | `AddDatabase` |

The Azure SQL and Azure PostgreSQL hosting integrations also expose `AddDatabase` APIs which work with their respective `RunAsContainer` methods. For more information, see [Understand Azure integration APIs](/integrations/cloud/azure/overview/#understand-azure-integration-apis).

By default, Aspire will create an empty database if it doesn’t exist. You can also optionally provide a custom script to run during creation for advanced setup or seeding.

Example using Postgres:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var postgres = builder.AddPostgres("pg1");


postgres.AddDatabase("todoapp")
    .WithCreationScript($$"""
        CREATE DATABASE {{databaseName}}
            ENCODING = 'UTF8';
        """);
```

For more information and examples of using the `AddDatabase` API, see:

* [Add PostgreSQL resource with database scripts](/integrations/databases/postgres/postgres-host/#add-postgresql-resource-with-database-scripts)
* [Add SQL Server resource with database scripts](/integrations/databases/sql-server/sql-server-host/#add-sql-server-resource-with-database-creation-script)

The following hosting integrations don’t currently support database creation:

* [📦 Aspire.Hosting.MongoDb](https://www.nuget.org/packages/Aspire.Hosting.MongoDb)
* [📦 Aspire.Hosting.MySql](https://www.nuget.org/packages/Aspire.Hosting.MySql)
* [📦 Aspire.Hosting.Oracle](https://www.nuget.org/packages/Aspire.Hosting.Oracle)

## ☁️ Azure integration updates

[Section titled “☁️ Azure integration updates”](#️-azure-integration-updates)

In Aspire 9.2, we’ve made significant updates to Azure integrations, including:

### ⚙️ Configure Azure Container Apps environments

[Section titled “⚙️ Configure Azure Container Apps environments”](#️-configure-azure-container-apps-environments)

Aspire 9.2 introduces [`AddAzureContainerAppEnvironment`](/reference/api/csharp/aspire.hosting.azure.appcontainers/azurecontainerappextensions/methods/#addazurecontainerappenvironment "Adds a container app environment resource to the distributed application builder.")[`addAzureContainerAppEnvironment`](/reference/api/typescript/aspire.hosting.azure.appcontainers/addazurecontainerappenvironment/ "Adds a container app environment resource to the distributed application builder."), allowing you to define an Azure Container App environment directly in your app model. This adds an `AzureContainerAppsEnvironmentResource` that lets you configure the environment and its supporting infrastructure (like container registries and volume file shares) using C# and the Azure Provisioning APIs—without relying on `azd` for infrastructure generation.

Caution

This uses a different resource naming scheme than `azd`. If you’re upgrading an existing deployment, this may create duplicate resources. To avoid this, you can opt into `azd`’s naming convention:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


builder.AddAzureContainerAppEnvironment("my-env")
       .WithAzdResourceNaming();
```

For more information, see [Configure Azure Container Apps environments](/integrations/cloud/azure/configure-container-apps/).

### 🆕 New Client integrations: Azure PostgreSQL (Npgsql & EF Core)

[Section titled “🆕 New Client integrations: Azure PostgreSQL (Npgsql & EF Core)”](#-new-client-integrations-azure-postgresql-npgsql--ef-core)

Aspire 9.2 adds client integrations for working with **Azure Database for PostgreSQL**, supporting both local development and secure cloud deployment.

These integrations automatically use **Managed Identity (Entra ID)** in the cloud and during local development by default. They also support username/password, if configured in your AppHost. No application code changes are required to switch between authentication models.

* [📦 Aspire.Azure.Npgsql](https://www.nuget.org/packages/Aspire.Azure.Npgsql)
* [📦 Aspire.Azure.Npgsql.EntityFrameworkCore.PostgreSQL](https://www.nuget.org/packages/Aspire.Azure.Npgsql.EntityFrameworkCore.PostgreSQL)

**In AppHost:**

```csharp
var postgres = builder.AddAzurePostgresFlexibleServer("pg")
                      .AddDatabase("postgresdb");


builder.AddProject()
       .WithReference(postgres);
```

**In MyService:**

```csharp
builder.AddAzureNpgsqlDbContext("postgresdb");
```

### 🖇️ Resource Deep Linking for Cosmos DB, Event Hubs, Service Bus, and OpenAI

[Section titled “🖇️ Resource Deep Linking for Cosmos DB, Event Hubs, Service Bus, and OpenAI”](#️-resource-deep-linking-for-cosmos-db-event-hubs-service-bus-and-openai)

CosmosDB databases and containers, EventHub hubs, ServiceBus queues/topics, and Azure OpenAI deployments now support **resource deep linking**. This allows connection information to target specific child resources—like a particular **Cosmos DB container**, **Event Hubs**, or **OpenAI deployment**—rather than just the top-level account or namespace.

Hosting integrations preserve the full resource hierarchy in connection strings, and client integrations can resolve and inject clients scoped to those specific resources.

**AppHost:**

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var cosmos = builder.AddAzureCosmosDB("cosmos")
                    .RunAsPreviewEmulator(e => e.WithDataExplorer());


var db = cosmos.AddCosmosDatabase("appdb");
db.AddContainer("todos", partitionKey: "/userId");
db.AddContainer("users", partitionKey: "/id");


builder.AddProject("api")
       .WithReference(db);
```

**In the API project:**

```csharp
var builder = WebApplication.CreateBuilder(args);


builder.AddAzureCosmosDatabase("appdb")
       .AddKeyedContainer("todos")
       .AddKeyedContainer("users");


app.MapPost("/todos", async ([FromKeyedServices("todos")] Container container, TodoItem todo) =>
{
    todo.Id = Guid.NewGuid().ToString();
    await container.CreateItemAsync(todo, new PartitionKey(todo.UserId));
    return Results.Created($"/todos/{todo.Id}", todo);
});
```

This makes it easy and convenient to use the SDKs to interact with specific resources directly—without extra wiring or manual configuration. It’s especially useful in apps that deal with multiple containers or Azure services.

### 🛡️ Improved Managed Identity defaults

[Section titled “🛡️ Improved Managed Identity defaults”](#️-improved-managed-identity-defaults)

Starting in **Aspire 9.2**, each Azure Container App now gets its **own dedicated managed identity** by default. This is a significant change from previous versions, where all apps shared a single, highly privileged identity.

This change strengthens Aspire’s *secure by default* posture:

* Each app only gets access to the Azure resources it needs.
* It enforces the principle of least privilege.
* It provides better isolation between apps in multi-service environments.

By assigning identities individually, Aspire can now scope role assignments more precisely—improving security, auditability, and alignment with Azure best practices.

This is a **behavioral breaking change** and may impact apps using:

* **Azure SQL Server** - Azure SQL only supports one Azure AD admin. With multiple identities, only the *last deployed app* will be granted admin access by default. Other apps will need explicit users and role assignments.
* **Azure PostgreSQL** - The app that creates the database becomes the owner. Other apps (like those running migrations or performing data operations) will need explicit `GRANT` permissions to access the database correctly.

This new identity model is an important step toward more secure and maintainable applications in Aspire. While it introduces some setup considerations, especially for database integrations, it lays the groundwork for better default security across the board.

### 🔑 Least-privilege role assignment functionality

[Section titled “🔑 Least-privilege role assignment functionality”](#-least-privilege-role-assignment-functionality)

Aspire now supports APIs for modeling **least-privilege role assignments** when referencing Azure resources. This enables more secure defaults by allowing you to define exactly which roles each app needs for specific Azure resources.

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var storage = builder.AddAzureStorage("storage")
                     .RunAsEmulator(c => c.WithLifetime(ContainerLifetime.Persistent));


var blobs = storage.AddBlobs("blobs");


builder.AddProject("api")
       .WithExternalHttpEndpoints()
       .WithReference(blobs)
       .WithRoleAssignments(storage, StorageBuiltInRole.StorageBlobDataContributor);
```

In this example, the API project is granted **Storage Blob Data Contributor** only for the referenced storage account. This avoids over-provisioning permissions and helps enforce the principle of least privilege.

Each container app automatically gets its own **managed identity**, and Aspire now generates the necessary role assignment infrastructure for both default and per-reference roles. When targeting existing Azure resources, role assignments are scoped correctly using separate Bicep resources.

### 1️⃣ First-class Azure Key Vault Secret support

[Section titled “1️⃣ First-class Azure Key Vault Secret support”](#1️⃣-first-class-azure-key-vault-secret-support)

Aspire now supports `IAzureKeyVaultSecretReference`, a new primitive for modeling secrets directly in the app model. This replaces `BicepSecretOutputReference` and gives finer grain control over Key Vault creation when using `AzureBicepResource`.

You can now:

* Add a shared Key Vault in C#
* Configure services that support keys (e.g., Redis, Cosmos DB) to store their secrets there
* Reference those secrets in your app as environment variables or via the Key Vault config provider

Use KeyVault directly in the “api” project:

```csharp
var builder = DistributedApplication.CreateBuilder(args);


var vault = builder.AddAzureKeyVault("kv");


var redis = builder.AddAzureRedis("redis")
                   .WithAccessKeyAuthentication(vault);


builder.AddProject("api")
       .WithReference(vault);
```

Let the compute environment handle the secret management for you:

```csharp
var redis = builder.AddAzureRedis("redis")
                   .WithAccessKeyAuthentication();


builder.AddProject("api")
       .WithReference(redis);
```

**Previous behavior:**

`azd` created and managed secret outputs using a key vault per resource, with no visibility in the app model. These Key Vault resources were handled implicitly and couldn’t be customized in C#.

**New behavior in 9.2:**

Calling `WithKeyAccessAuthentication` or [`WithPasswordAuthentication`](/reference/api/csharp/aspire.hosting.azure.postgresql/azurepostgresextensions/methods/#withpasswordauthentication "Configures the resource to use password authentication for Azure PostgreSQL Flexible Server.")[`withPasswordAuthentication`](/reference/api/typescript/aspire.hosting.azure.postgresql/withpasswordauthentication/ "Configures password authentication for Azure PostgreSQL Flexible Server") now creates an actual `AzureKeyVaultResource` (or accepts a reference to one), and stores connection strings there. Secret names follow the pattern `connectionstrings--{resourcename}` to prevent naming conflicts with other vault entries.

### 🔒 Improved default permissions for Azure Key Vault references

[Section titled “🔒 Improved default permissions for Azure Key Vault references”](#-improved-default-permissions-for-azure-key-vault-references)

When referencing a Key Vault, Aspire previously granted the broad **Key Vault Administrator** role by default. In 9.2, this has been changed to **Key Vault Secrets User**, which provides read-only access to secrets—suitable for most application scenarios.

This update continues the security-focused improvements in this release.

## 🚀 Deployment improvements

[Section titled “🚀 Deployment improvements”](#-deployment-improvements)

We’re excited to announce several new deployment features in Aspire 9.2, including:

### 📦 Publishers (Preview)

[Section titled “📦 Publishers (Preview)”](#-publishers-preview)

Publishers are a new extensibility point in Aspire that allow you to define how your distributed application gets transformed into deployable assets. Rather than relying on an [intermediate manifest format](/deployment/azure/manifest-format/), publishers can now plug directly into the application model to generate Docker Compose files, Kubernetes manifests, Azure resources, or whatever else your environment needs.

When Aspire launched, it introduced a deployment manifest format—a serialized snapshot of the application model. While useful it burdened deployment tools with interpreting the manifest and resource authors with ensuring accurate serialization. This approach also complicated schema evolution and target-specific behaviors.

Publishers simplify this process by working directly with the full application model in-process, enabling richer, more flexible, and maintainable publishing experiences.

The following NuGet packages expose preview publishers:

* [📦 Aspire.Hosting.Azure](https://www.nuget.org/packages/Aspire.Hosting.Azure)
* [📦 Aspire.Hosting.Docker (Preview)](https://www.nuget.org/packages/Aspire.Hosting.Docker)
* [📦 Aspire.Hosting.Kubernetes (Preview)](https://www.nuget.org/packages/Aspire.Hosting.Kubernetes)

Caution

The Docker and Kubernetes publishers were contributed by community contributor, [Dave Sekula](https://github.com/Prom3theu5)—a great example of the community stepping up to extend the model. 💜 Thank you, Dave!

To use a publisher, add the corresponding NuGet package to your AppHost project file and then call the `Add[Name]Publisher()` method in your AppHost builder.

```csharp
builder.AddDockerComposePublisher();
```

Tip

Publisher registration methods follow the `Add[Name]Publisher()` convention.

You can also build your own publisher by implementing the publishing APIs and calling your custom registration method. Some publishers are still in preview, and the APIs are subject to change. The goal is to provide a more flexible and extensible way to publish distributed applications, making it easier to adapt to different deployment environments and scenarios.

### 🆕 Aspire CLI (Preview)

[Section titled “🆕 Aspire CLI (Preview)”](#-aspire-cli-preview)

Aspire 9.2 introduces the new **`aspire` CLI**, a tool for creating, running, and publishing Aspire applications from the command line. It provides a rich, interactive experience tailored for Aspire users.

The CLI is available as a .NET tool and can be installed with:

```bash
dotnet tool install --global aspire.cli --prerelease
```

#### Example usage:

[Section titled “Example usage:”](#example-usage)

```bash
aspire new
aspire run
aspire add redis
aspire publish --publisher docker-compose
```

#### Available commands:

[Section titled “Available commands:”](#available-commands)

* `new