diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts
index 2af25b4f42..5085b76fa6 100644
--- a/src/frontend/config/sidebar/docs.topics.ts
+++ b/src/frontend/config/sidebar/docs.topics.ts
@@ -1164,6 +1164,11 @@ export const docsTopics = {
label: 'Multi-language integrations',
slug: 'extensibility/multi-language-integration-authoring',
},
+ {
+ label: 'TypeScript hosting integrations',
+ slug: 'extensibility/typescript-hosting-integrations',
+ badge: 'Experimental',
+ },
],
},
{
diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-home-light.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-home-light.png
new file mode 100644
index 0000000000..42a04c006d
Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-home-light.png differ
diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-home.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-home.png
new file mode 100644
index 0000000000..2a6447ecc4
Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-home.png differ
diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics-light.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics-light.png
new file mode 100644
index 0000000000..524e3e047b
Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics-light.png differ
diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics.png
new file mode 100644
index 0000000000..94788432b0
Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics.png differ
diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview-light.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview-light.png
new file mode 100644
index 0000000000..c8a27481d3
Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview-light.png differ
diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview.png
new file mode 100644
index 0000000000..2e5412ac3d
Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview.png differ
diff --git a/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources-light.png b/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources-light.png
deleted file mode 100644
index e174f6bea3..0000000000
Binary files a/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources-light.png and /dev/null differ
diff --git a/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources.png b/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources.png
deleted file mode 100644
index cc73850a25..0000000000
Binary files a/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources.png and /dev/null differ
diff --git a/src/frontend/src/content/docs/app-host/executable-resources.mdx b/src/frontend/src/content/docs/app-host/executable-resources.mdx
index b21858ce6e..649d84f9c7 100644
--- a/src/frontend/src/content/docs/app-host/executable-resources.mdx
+++ b/src/frontend/src/content/docs/app-host/executable-resources.mdx
@@ -281,6 +281,88 @@ Aspire 13.3 unified non-C# AppHost environment assignment behind a single `withE
When upgrading to Aspire 13.3, replace every earlier per-kind environment helper call with `withEnvironment(name, value)`. The 13.3 TypeScript SDK doesn't generate compatibility aliases for those helpers.
+## Declare required commands
+
+Executables depend on tools that must be installed on the developer's machine. Use to declare a command that a resource needs, and optionally a link to installation instructions. You can call it on any resource, not only executables, and call it more than once to declare several commands:
+
+
+
+```csharp title="AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var frontend = builder.AddExecutable("frontend", "vercel", ".", "dev")
+ .WithRequiredCommand("vercel", helpLink: "https://vercel.com/docs/cli");
+
+builder.Build().Run();
+```
+
+
+```typescript title="apphost.mts" twoslash
+import { createBuilder } from './.aspire/modules/aspire.mjs';
+
+const builder = await createBuilder();
+
+const frontend = await builder.addExecutable("frontend", "vercel", ".", ["dev"])
+ .withRequiredCommand("vercel", { helpLink: "https://vercel.com/docs/cli" });
+
+await builder.build().run();
+```
+
+
+
+Before the resource starts, Aspire checks that the command exists. A command that contains a directory separator is treated as a path to a file; otherwise Aspire searches the `PATH` (on Windows, `PATHEXT` extensions are also tried). If the command isn't found, Aspire:
+
+- Logs a warning that the resource may fail to start.
+- Shows a **Missing command** notification in the dashboard, with an **Installation instructions** link when you provide `helpLink`.
+- Still lets the resource attempt to start. The check never blocks startup.
+
+When several resources require the same command with the same validation, Aspire checks it and shows the notification only once per AppHost run.
+
+### Validate the resolved command
+
+To check more than whether the command exists, such as its version or install location, pass a validation callback. The callback runs only after the command is found and receives a `RequiredCommandValidationContext` with the resolved `ResolvedPath`, a `Services` provider, and a `CancellationToken`. Return `context.Success()` or `context.Failure(message)`. In TypeScript, use `withRequiredCommandValidation`:
+
+
+
+```csharp title="AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var worker = builder.AddExecutable("worker", "python", ".", "worker.py")
+ .WithRequiredCommand(
+ "python",
+ context => Task.FromResult(
+ context.ResolvedPath.Contains(".venv")
+ ? context.Success()
+ : context.Failure($"Activate the project's virtual environment. Found: {context.ResolvedPath}")),
+ helpLink: "https://docs.python.org/3/library/venv.html");
+
+builder.Build().Run();
+```
+
+
+```typescript title="apphost.mts" twoslash
+import { createBuilder } from './.aspire/modules/aspire.mjs';
+
+const builder = await createBuilder();
+
+const worker = await builder.addExecutable("worker", "python", ".", ["worker.py"])
+ .withRequiredCommandValidation(
+ "python",
+ async (context) => {
+ const resolvedPath = await context.resolvedPath();
+ return resolvedPath.includes(".venv")
+ ? context.success()
+ : context.failure(`Activate the project's virtual environment. Found: ${resolvedPath}`);
+ },
+ { helpLink: "https://docs.python.org/3/library/venv.html" });
+
+await builder.build().run();
+```
+
+
+
+A failed validation is reported the same way as a missing command: the warning and notification include your failure message, and the resource still attempts to start.
+
## Publishing with PublishAsDockerFile
For production deployment, executable resources need to be containerized. Use the method to specify how the executable should be packaged:
diff --git a/src/frontend/src/content/docs/dashboard/explore.mdx b/src/frontend/src/content/docs/dashboard/explore.mdx
index 34644d2ddf..bbad4d49d6 100644
--- a/src/frontend/src/content/docs/dashboard/explore.mdx
+++ b/src/frontend/src/content/docs/dashboard/explore.mdx
@@ -276,6 +276,8 @@ Select **Group resources** to group the list by tags, resource type, or state, o
+Some resources, such as the management containers of integrations, are hidden by default. To include them, select **View options** (**...**) in the resource list and then **Show hidden resources**. Hidden resources are marked with an eye-off icon in the resource list and graph, so you can tell them apart from resources that are normally visible.
+
### Resource display order
By default, the resource list is ordered by resource type and then by name. To change where a resource appears, call `WithDisplayOrder` in the AppHost. It's a relative sort key: resources with a higher value appear first, resources without a value count as `0`, and a negative value moves a resource after them. Resources with the same value are sorted by name. If you reorder resources in the dashboard, your saved order takes precedence.
@@ -319,6 +321,8 @@ In the preceding example, `api` appears before `worker`, and both appear before
The Graph view and the telemetry pages (Console logs, Structured logs, Traces, and Metrics) show a resource list sidebar. Drag the splitter between the sidebar and the content to resize it. Select **Collapse resource list** to hide it and give the content more room.
+When a resource has unviewed error logs, its row shows an error count badge. Select the badge to open the resource's [structured logs](#structured-logs-page) filtered to errors, without changing the current resource selection.
+
When the sidebar is collapsed, a resource drop-down replaces it. Select the drop-down to switch resources, and type in its **Filter** box to quickly find a resource.
diff --git a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
index c57c2c3485..eaf617e6d7 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
@@ -366,7 +366,7 @@ This first deploy serves plain HTTP only. Continue to the next step before expos
var certManager = aks.AddCertManager("cert-manager");
var letsencrypt = certManager.AddIssuer("letsencrypt-prod")
- .WithLetsEncryptProduction("ops@contoso.com")
+ .WithAcmeServer("https://acme-v02.api.letsencrypt.org/directory", "ops@contoso.com")
.WithHttp01Solver();
aks.AddGateway("storefront")
@@ -380,7 +380,10 @@ aks.AddGateway("storefront")
const certManager = await aks.addCertManager('cert-manager');
const letsencrypt = await certManager.addIssuer('letsencrypt-prod');
-await letsencrypt.withLetsEncryptProduction('ops@contoso.com');
+await letsencrypt.withAcmeServer(
+ 'https://acme-v02.api.letsencrypt.org/directory',
+ 'ops@contoso.com'
+);
await letsencrypt.withHttp01Solver();
const storefront = await aks.addGateway('storefront');
@@ -423,9 +426,79 @@ await storefront.withTls(letsencrypt, {
-Let's Encrypt's production endpoint enforces strict rate limits. While iterating on your AppHost, swap for so failed attempts don't cost you your weekly quota. Browsers will warn on staging certificates — flip back to production once everything works end-to-end.
+Let's Encrypt's production endpoint enforces strict rate limits. While iterating on your AppHost, pass the staging directory URL (`https://acme-staging-v02.api.letsencrypt.org/directory`) to so failed attempts don't cost you your weekly quota. Browsers will warn on staging certificates — flip back to production once everything works end-to-end.
+#### Choose the ACME directory per environment
+
+`WithAcmeServer` accepts the ACME directory URL and contact email either as two literal strings or as two parameters. Use parameters to select the directory per environment without changing the AppHost:
+
+
+
+```csharp title="AppHost.cs"
+var serverUrl = builder.AddParameter("acmeserver");
+var email = builder.AddParameter("acmeemail");
+
+var issuer = certManager.AddIssuer("acme")
+ .WithAcmeServer(serverUrl, email)
+ .WithHttp01Solver();
+```
+
+
+```typescript title="apphost.mts"
+const serverUrl = await builder.addParameter('acmeserver');
+const email = await builder.addParameter('acmeemail');
+
+const issuer = await certManager.addIssuer('acme');
+await issuer.withAcmeServer(serverUrl, email);
+await issuer.withHttp01Solver();
+```
+
+
+
+Set `Parameters__acmeserver` and `Parameters__acmeemail` before you run `aspire deploy`. You can't mix a literal URL with a parameter email; use two strings or two parameters.
+
+#### Use a certificate authority that requires External Account Binding
+
+Some ACME certificate authorities, such as ZeroSSL and Google Trust Services, require [External Account Binding (EAB)](https://www.rfc-editor.org/rfc/rfc8555.html#section-7.3.4) to link the ACME account cert-manager registers to your existing account with the provider. Get an EAB key ID and HMAC key from the provider, then call `WithExternalAccountBinding` after `WithAcmeServer`:
+
+
+
+```csharp title="AppHost.cs"
+var keyId = builder.AddParameter("acmeeabkeyid");
+var hmacKey = builder.AddParameter("acmeeabhmackey", secret: true);
+
+var zeroSsl = certManager.AddIssuer("zerossl")
+ .WithAcmeServer("https://acme.zerossl.com/v2/DV90", "ops@contoso.com")
+ .WithExternalAccountBinding(keyId, hmacKey)
+ .WithHttp01Solver();
+```
+
+
+```typescript title="apphost.mts"
+const keyId = await builder.addParameter('acmeeabkeyid');
+const hmacKey = await builder.addParameter('acmeeabhmackey', { secret: true });
+
+const zeroSsl = await certManager.addIssuer('zerossl');
+await zeroSsl.withAcmeServer('https://acme.zerossl.com/v2/DV90', 'ops@contoso.com');
+await zeroSsl.withExternalAccountBinding(keyId, hmacKey);
+await zeroSsl.withHttp01Solver();
+```
+
+
+
+Both EAB values must be parameters, and the HMAC key must be a secret parameter. Supply them from your pipeline's secret store as `Parameters__acmeeabkeyid` and `Parameters__acmeeabhmackey`, passing the provider's HMAC key text unchanged. At deploy time, Aspire stores the HMAC key in a Kubernetes Secret named `-eab` that cert-manager reads; the key isn't written to published artifacts, and `aspire destroy` removes the Secret. EAB only authorizes account registration—the HTTP-01 challenge still validates domain ownership.
+
+| Provider | ACME directory URL | EAB required |
+|---|---|---|
+| Let's Encrypt (production) | `https://acme-v02.api.letsencrypt.org/directory` | No |
+| Let's Encrypt (staging) | `https://acme-staging-v02.api.letsencrypt.org/directory` | No |
+| ZeroSSL | `https://acme.zerossl.com/v2/DV90` | Yes |
+| Google Trust Services (production) | `https://dv.acme-v02.api.pki.goog/directory` | Yes |
+| Google Trust Services (staging) | `https://dv.acme-v02.test-api.pki.goog/directory` | Yes |
+
+Some providers issue single-use or expiring EAB credentials. Aspire doesn't acquire or refresh them; supply a fresh pair when cert-manager needs to register a new ACME account. Existing accounts are reused.
+
#### How the certificate gets issued
cert-manager validates domain ownership using the **HTTP-01** challenge configured by — it asks the gateway to serve a token at `/.well-known/acme-challenge/` and verifies the response. There is no DNS API access required, so this works for the auto-assigned `*.alb.azure.com` FQDN out of the box.
@@ -671,13 +744,13 @@ Common causes:
- **DNS hasn't propagated yet** when using a custom domain — Let's Encrypt fetches `http:///.well-known/acme-challenge/...` and that has to resolve to the AGC frontend.
- **HTTP traffic is blocked** between Let's Encrypt and the gateway — HTTP-01 needs port 80 open. AGC keeps the HTTP listener that `AddGateway` generates open by default; don't remove it.
-- **Production rate limit hit** while iterating — switch the issuer to `WithLetsEncryptStaging` until everything else works, then flip back to production.
+- **Production rate limit hit** while iterating — point the issuer's `WithAcmeServer` call at the Let's Encrypt staging directory until everything else works, then flip back to production.
- **The contact email was rejected by ACME** — see [Let's Encrypt rejects the contact email](#lets-encrypt-rejects-the-contact-email).
- **The bootstrap TLS secret is missing** — see [Gateway HTTPS listener reports `InvalidCertificateRef`](#gateway-https-listener-reports-invalidcertificateref).
### Let's Encrypt rejects the contact email
-The first time you `aspire deploy` with `WithLetsEncryptProduction(email)` or `WithLetsEncryptStaging(email)`, cert-manager creates an ACME account using that email. Let's Encrypt validates the address and refuses to register accounts whose email uses a reserved or forbidden domain. The `ClusterIssuer` will report `Ready=False` and `kubectl describe clusterissuer ` will show one of:
+The first time you `aspire deploy` with `WithAcmeServer(serverUrl, email)` pointing at Let's Encrypt, cert-manager creates an ACME account using that email. Let's Encrypt validates the address and refuses to register accounts whose email uses a reserved or forbidden domain. The `ClusterIssuer` will report `Ready=False` and `kubectl describe clusterissuer ` will show one of:
- `Domain name does not end with a valid public suffix` — the TLD isn't a registered public suffix. Reserved TLDs from RFC 2606 (`.test`, `.example`, `.invalid`, `.localhost`) are common offenders.
- `contact email has forbidden domain example.com` — Let's Encrypt explicitly blocks the IANA example domains (`example.com`, `example.net`, `example.org`).
diff --git a/src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx b/src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx
index f4b96f192b..557a18198e 100644
--- a/src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx
@@ -15,7 +15,7 @@ import ApiReference from '@components/ApiReference.astro';
/>
:::note[Retired in Aspire 17.0]
-Starting with Aspire 17.0, the required-command validation APIs (the `WithRequiredCommand` overload that accepts a validation callback, `RequiredCommandAnnotation`, `IRequiredCommandValidator`, `RequiredCommandValidationContext`, and `RequiredCommandValidationResult`) are stable and no longer report `ASPIRECOMMAND001`. After you upgrade, remove any `ASPIRECOMMAND001` suppressions from _.editorconfig_ files, project files, and `#pragma warning` directives. The rest of this page describes the diagnostic as it applied to earlier versions.
+Starting with Aspire 17.0, the required-command validation APIs (the `WithRequiredCommand` overload that accepts a validation callback, `RequiredCommandAnnotation`, `IRequiredCommandValidator`, `RequiredCommandValidationContext`, and `RequiredCommandValidationResult`) are stable and no longer report `ASPIRECOMMAND001`. After you upgrade, remove any `ASPIRECOMMAND001` suppressions from _.editorconfig_ files, project files, and `#pragma warning` directives. For current usage, see [Declare required commands](/app-host/executable-resources/#declare-required-commands). The rest of this page describes the diagnostic as it applied to earlier versions.
:::
> Required command validation types and members are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed.
diff --git a/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx b/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx
index 7f1a790bae..f545480e68 100644
--- a/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx
+++ b/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx
@@ -1191,5 +1191,6 @@ Types that are **not** ATS-compatible include: interpolated string handlers and
## See also
- [Build your first app](/get-started/first-app/?lang=typescript) — Get started with a TypeScript AppHost
+- [Author hosting integrations in TypeScript](/extensibility/typescript-hosting-integrations/) — Write an integration in TypeScript instead of C# (experimental)
- [Custom resources](/extensibility/custom-resources/) — Creating custom resource types
- [Integrations overview](/integrations/overview/) — Available integrations
diff --git a/src/frontend/src/content/docs/extensibility/typescript-hosting-integrations.mdx b/src/frontend/src/content/docs/extensibility/typescript-hosting-integrations.mdx
new file mode 100644
index 0000000000..1027a1416f
--- /dev/null
+++ b/src/frontend/src/content/docs/extensibility/typescript-hosting-integrations.mdx
@@ -0,0 +1,207 @@
+---
+title: Author hosting integrations in TypeScript
+description: Write experimental Aspire hosting integrations in TypeScript with AspireExport and defineIntegration, then consume them as builder methods from polyglot AppHosts.
+---
+
+import { Steps } from '@astrojs/starlight/components';
+
+You can write a hosting integration in TypeScript instead of C#. The integration exports methods, such as `addNuxtApp`, that appear in the generated SDK of a consuming AppHost, just like the methods of a C# integration. Under the hood, Aspire runs your integration in its own Node.js process and routes each call to it, so your code configures the same resource model as a C# integration.
+
+:::caution[Experimental]
+Hosting integrations written in TypeScript are experimental and disabled by default. AppHosts that consume them must opt in, and the authoring APIs might change in future releases.
+:::
+
+To make a C# integration available to TypeScript AppHosts instead, see [Multi-language integrations](/extensibility/multi-language-integration-authoring/).
+
+## Choose a library or an exported integration
+
+You can share TypeScript AppHost code in two ways:
+
+- **Plain library**: An npm package that exports ordinary functions, such as `addKafka(builder, ...)`. A TypeScript AppHost imports and calls them directly. No opt-in is required, but the functions aren't added to the builder and AppHosts in other languages can't use them.
+- **Exported integration**: A package that marks its functions with `AspireExport` and runs as an integration host. Consuming AppHosts get fluent builder methods, such as `builder.addNuxtApp(...)`, in their generated SDK. This page describes this option.
+
+## Author an integration
+
+An integration is a library package, not an app. It has its own _aspire.config.json_ so that `aspire restore` can generate the typed Aspire SDK that your code builds on, and an entry point that starts the integration host.
+
+
+
+1. Create a package with an _aspire.config.json_ file that declares the TypeScript language and the hosting packages your integration uses. Don't set an AppHost path:
+
+ ```json title="aspire.config.json"
+ {
+ "appHost": {
+ "language": "typescript/nodejs"
+ },
+ "packages": {
+ "Aspire.Hosting.JavaScript": ""
+ }
+ }
+ ```
+
+1. Add a _package.json_ file. Aspire starts the integration host with `node --import tsx`, so include `tsx` as a dependency:
+
+ ```json title="package.json"
+ {
+ "name": "@contoso/aspire-nuxt",
+ "version": "0.1.0",
+ "type": "module",
+ "dependencies": {
+ "tsx": "^4.21.0",
+ "vscode-jsonrpc": "8.2.1"
+ }
+ }
+ ```
+
+1. Run `aspire restore` in the package directory. It generates the SDK in _.aspire/modules/_, including the `AspireExport`, `defineIntegration`, and `runIntegrationHost` helpers.
+
+1. Write your integration. Wrap each method with `AspireExport` and use the generated builder APIs to configure resources. The `projection` describes the method's target, parameters, and return type so that consuming AppHosts can generate a typed method for it. The `typeId` of each Aspire type matches the handle types in the generated _.aspire/modules/aspire.mts_ file. Finally, group the methods with `defineIntegration`:
+
+ ```typescript title="src/integration.ts"
+ import type {
+ DistributedApplicationBuilder,
+ JavaScriptAppResource,
+ } from '../.aspire/modules/aspire.mjs';
+ import {
+ AspireExport,
+ defineIntegration,
+ type AspireTypeRef,
+ } from '../.aspire/modules/base.mjs';
+
+ const builderType: AspireTypeRef = {
+ typeId: 'Aspire.Hosting/Aspire.Hosting.IDistributedApplicationBuilder',
+ category: 'Handle',
+ isInterface: true,
+ };
+ const appType: AspireTypeRef = {
+ typeId: 'Aspire.Hosting.JavaScript/Aspire.Hosting.JavaScript.JavaScriptAppResource',
+ category: 'Handle',
+ };
+ const stringType: AspireTypeRef = { typeId: 'string', category: 'Primitive' };
+
+ interface AddNuxtAppArgs {
+ builder: DistributedApplicationBuilder;
+ name: string;
+ appDirectory: string;
+ }
+
+ export const addNuxtApp = AspireExport(
+ {
+ id: '@contoso/aspire-nuxt/addNuxtApp',
+ method: 'addNuxtApp',
+ description: 'Adds a Nuxt application.',
+ projection: {
+ capabilityKind: 'Method',
+ targetTypeId: builderType.typeId,
+ targetType: builderType,
+ targetParameterName: 'builder',
+ returnsBuilder: true,
+ returnType: appType,
+ parameters: [
+ { name: 'name', type: stringType },
+ { name: 'appDirectory', type: stringType },
+ ],
+ },
+ },
+ async ({ builder, name, appDirectory }) => {
+ return await builder.addJavaScriptApp(name, appDirectory, { runScriptName: 'dev' })
+ .withHttpEndpoint({ env: 'PORT' })
+ .withEnvironment('HOST', '0.0.0.0');
+ },
+ );
+
+ export default defineIntegration({
+ name: 'NuxtIntegration',
+ capabilities: [addNuxtApp],
+ });
+ ```
+
+ Give each method a unique `id`. Consuming AppHosts call the method by its `method` name.
+
+1. Add an entry point that starts the integration host:
+
+ ```typescript title="src/host.ts"
+ import nuxtIntegration from './integration.js';
+ import { runIntegrationHost } from '../.aspire/modules/integration-host.mjs';
+
+ await runIntegrationHost({
+ packageName: '@contoso/aspire-nuxt',
+ integrations: [nuxtIntegration],
+ });
+ ```
+
+ `runIntegrationHost` handles the connection to the AppHost, registration, and dispatching calls to your methods.
+
+
+
+To distribute the integration, compile it and publish or pack it as an npm package. Include the compiled output and the generated _.aspire/modules/_ SDK, as the preview [`@aspire/nuxt`](https://github.com/microsoft/aspire/tree/release/17.0/src/Aspire.Hosting.Nuxt) package does.
+
+## Consume an integration
+
+
+
+1. Enable the feature in the AppHost directory:
+
+ ```bash title="Aspire CLI"
+ aspire config set features.experimentalHostingIntegrations true
+ ```
+
+ Without this setting, the CLI rejects AppHosts that reference npm hosting integrations and shows the command to enable them. Running the command adds the `features` setting shown in the next step to _aspire.config.json_.
+
+1. Install the integration package, and then add it to the `packages` section of the AppHost's _aspire.config.json_ file. Set `source` to `npm` and `path` to the integration's host entry point, relative to _aspire.config.json_:
+
+ ```json title="aspire.config.json"
+ {
+ "appHost": {
+ "path": "apphost.mts",
+ "language": "typescript/nodejs"
+ },
+ "features": {
+ "experimentalHostingIntegrations": true
+ },
+ "packages": {
+ "Aspire.Hosting.JavaScript": "",
+ "@contoso/aspire-nuxt": {
+ "source": "npm",
+ "path": "./node_modules/@contoso/aspire-nuxt/dist/src/host.js"
+ }
+ }
+ }
+ ```
+
+ During development, `path` can also point to a TypeScript entry point in a local folder, such as `./nuxt-integration/src/host.ts`.
+
+1. Run `aspire restore`. The CLI installs the integration's dependencies, starts its host, and adds its methods to the generated SDK.
+
+1. Call the methods from your AppHost like any other builder method:
+
+ ```typescript title="apphost.mts"
+ import { createBuilder } from './.aspire/modules/aspire.mjs';
+
+ const builder = await createBuilder();
+
+ const api = await builder.addJavaScriptApp('api', './api', { runScriptName: 'start' })
+ .withHttpEndpoint({ env: 'PORT' });
+
+ await builder.addNuxtApp('web', './web')
+ .withReference(api)
+ .waitFor(api);
+
+ await builder.build().run();
+ ```
+
+
+
+## Current limitations
+
+- TypeScript is the only supported language for authoring these integrations.
+- You write the `projection` metadata for each method by hand.
+- `aspire add` doesn't find npm integrations. Add them to _aspire.config.json_ manually.
+- The preview `@aspire/nuxt` integration isn't published to npm. To try it, build and pack it from the [Aspire repository](https://github.com/microsoft/aspire/tree/release/17.0/src/Aspire.Hosting.Nuxt).
+- If an integration host that registered callbacks stops unexpectedly, the AppHost stops and you need to start it again.
+
+## See also
+
+- [Multi-language integrations](/extensibility/multi-language-integration-authoring/): Export C# hosting integrations to TypeScript AppHosts.
+- [TypeScript AppHost](/app-host/typescript-apphost/): Build an AppHost in TypeScript.
+- [Custom resources](/extensibility/custom-resources/): Create custom resource types.
diff --git a/src/frontend/src/content/docs/fundamentals/external-parameters.mdx b/src/frontend/src/content/docs/fundamentals/external-parameters.mdx
index f7802a78db..a3b63c7db7 100644
--- a/src/frontend/src/content/docs/fundamentals/external-parameters.mdx
+++ b/src/frontend/src/content/docs/fundamentals/external-parameters.mdx
@@ -367,7 +367,11 @@ The manifest representation is as follows:
## Optional parameters
-By default, a parameter is required: if no value is configured, you're prompted for one when you run or publish the app, and publishing fails until a value is supplied. Some parameters don't need a value in every environment. Use `AsOptional` to mark a parameter as optional:
+By default, a parameter is required: if no value is configured, you're prompted for one when you run or publish the app, and publishing fails until a value is supplied. An empty string doesn't satisfy a required parameter either, including secret and connection-string parameters.
+
+When a required value is missing or empty during `aspire run`, the parameter shows a `ValueMissing` state, and the dashboard asks you to supply the value. When the dashboard can't prompt, such as in publish or non-interactive runs, initialization fails with a `MissingParameterValueException` that names the parameter.
+
+Some parameters don't need a value in every environment. Use `AsOptional` to mark a parameter as optional:
@@ -403,7 +407,9 @@ await builder.build().run();
-When an optional parameter has no configured value, you aren't prompted for it, and resources that depend on it don't wait for it. The parameter resolves to `null`, and a `null` value is omitted when it's used as an environment variable, so in the preceding example `MESSAGE_PREFIX` isn't set. If a value is configured, it's used just like a required parameter's value.
+When an optional parameter has no configured value, you aren't prompted for it, and resources that depend on it don't wait for it. The parameter resolves to `null`, and a `null` value is omitted when it's used as an environment variable, so in the preceding example `MESSAGE_PREFIX` isn't set. If a value is configured, it's used just like a required parameter's value, and an explicitly configured empty string stays `""`.
+
+Mark a parameter optional only when an absent or empty value is genuinely valid for your app. Don't make required credentials optional to avoid the missing-value check.
The manifest format generated by `aspire do publish-manifest` doesn't support optional parameter inputs. Publishing an optional parameter to the manifest throws a DistributedApplicationException.
diff --git a/src/frontend/src/content/docs/fundamentals/health-checks.mdx b/src/frontend/src/content/docs/fundamentals/health-checks.mdx
index 857b790016..e5c9322602 100644
--- a/src/frontend/src/content/docs/fundamentals/health-checks.mdx
+++ b/src/frontend/src/content/docs/fundamentals/health-checks.mdx
@@ -502,6 +502,49 @@ await frontend.waitFor(backend);
+### HTTP probes for deployment
+
+Use to declare startup, readiness, or liveness probes that deployment targets configure on the deployed resource. Pass a `ProbeType` (`Startup`, `Readiness`, or `Liveness`) and the path to probe. You can add one probe of each type to a container, executable, or project resource; adding another probe of the same type replaces it:
+
+
+
+
+```csharp title="AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var api = builder.AddContainer("api", "myregistry/api")
+ .WithHttpEndpoint(targetPort: 8080)
+ .WithHttpProbe(ProbeType.Readiness, "/health")
+ .WithHttpProbe(ProbeType.Liveness, "/alive", periodSeconds: 10);
+```
+
+
+
+
+```typescript title="apphost.mts" twoslash
+import { createBuilder, ProbeType } from './.aspire/modules/aspire.mjs';
+
+const builder = await createBuilder();
+
+const api = await builder.addContainer('api', 'myregistry/api')
+ .withHttpEndpoint({ targetPort: 8080 })
+ .withHttpProbe(ProbeType.Readiness, { path: '/health' })
+ .withHttpProbe(ProbeType.Liveness, { path: '/alive', periodSeconds: 10 });
+```
+
+
+
+
+By default, a probe targets the resource's first HTTP or HTTPS endpoint; set `endpointName` to choose another. The optional `initialDelaySeconds`, `periodSeconds`, `timeoutSeconds`, `failureThreshold`, and `successThreshold` parameters default to `5`, `5`, `1`, `3`, and `1`, and the path defaults to `/`. Each probe also adds an HTTP health check for the same endpoint and path, so `WaitFor` and the dashboard use it when you run locally.
+
+Deployment targets apply probes as follows:
+
+- **Azure Container Apps** and **Kubernetes**: Each probe becomes the matching startup, readiness, or liveness probe on the container's target port, with the configured timings.
+- **Azure App Service**: Only the path is used, as the site's health check path. The liveness probe is preferred; otherwise, the first probe is used.
+- **Azure Front Door**: An origin's health probe uses the path and scheme of the resource's liveness probe, or of its first probe when there's no liveness probe.
+
+Other deployment targets, such as Docker Compose, don't use probes.
+
### Custom resource health checks
You can create custom health checks for more complex readiness scenarios. Start by defining the health check in the AppHost's service collection, then associate it with resources:
diff --git a/src/frontend/src/content/docs/get-started/csharp-service-defaults.mdx b/src/frontend/src/content/docs/get-started/csharp-service-defaults.mdx
index 2de39c4136..81501bead5 100644
--- a/src/frontend/src/content/docs/get-started/csharp-service-defaults.mdx
+++ b/src/frontend/src/content/docs/get-started/csharp-service-defaults.mdx
@@ -271,14 +271,14 @@ The `MapDefaultEndpoints` method:
If the default service configuration provided by the project template is not sufficient for your needs, you have the option to create your own service defaults project. This is especially useful when your consuming project, such as a Worker project or WinForms project, cannot or does not want to have a `FrameworkReference` dependency on `Microsoft.AspNetCore.App`.
-To do this, create a new .NET 9.0 class library project and add the necessary dependencies to the project file, consider the following example:
+To do this, create a new .NET 10.0 class library project and add the necessary dependencies to the project file, consider the following example:
```xml
Library
- net9.0
+ net10.0
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/ai-compatibility-matrix.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/ai-compatibility-matrix.mdx
index a83ccb7b1f..83d7a58136 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/ai-compatibility-matrix.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/ai-compatibility-matrix.mdx
@@ -22,33 +22,32 @@ Aspire provides several AI hosting and client integrations that enable you to wo
The following table shows the compatibility between Aspire AI hosting and client integrations:
-| **Hosting Integration** | **Aspire.OpenAI** | **Aspire.Azure.AI.OpenAI** | **Aspire.Azure.AI.Inference** |
+| **Hosting Integration** | **Aspire.OpenAI** | **Aspire.Azure.AI.Extensions.OpenAI** | **Aspire.Azure.AI.Projects** |
|--|--|--|--|
-| `Aspire.Hosting.Foundry` | ⚠️ Partial — Foundry Local only (preferred) | ⚠️ Partial | ❗ Legacy |
+| `Aspire.Hosting.Foundry` | ⚠️ Partial — Foundry Local only (preferred) | ✅ Yes — deployments and projects (preferred) | ⚠️ Partial — projects only |
| `Aspire.Hosting.Azure.CognitiveServices` | ❌ No | ✅ Yes (preferred) | ❌ No |
-| `Aspire.Hosting.OpenAI` | ✅ Yes (preferred) | ✅ Yes | ❌ No |
+| `Aspire.Hosting.OpenAI` | ✅ Yes (preferred) | ⚠️ Partial — `AddOpenAIClientFromConfiguration` only | ❌ No |
- ✅ **Yes**: The client integration is compatible with the hosting integration.
- ⚠️ **Partial**: The client integration has limited model, API, or hosting-mode support.
- ❌ **No**: The client integration does not support the hosting environment.
-- ❗ **Legacy**: The client integration remains available for existing apps but is not recommended for this pairing.
- **(preferred)**: The recommended client integration for this hosting integration.
+:::note[Upgrading to Aspire 17?]
+`Aspire.Azure.AI.OpenAI` and `Aspire.Azure.AI.Inference` are discontinued. See [Migrate from Aspire.Azure.AI.Inference or Aspire.Azure.AI.OpenAI](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/#migrate-from-aspireazureaiinference-or-aspireazureaiopenai).
+:::
+
## Recommended pairings
-In general, use an Aspire client integration when one supports the resource and its authentication method. Use **Aspire.OpenAI** for OpenAI-compatible resources that provide an API key, including Foundry Local. For cloud-provisioned Microsoft Foundry resources, use the OpenAI SDK directly because they authenticate with managed identity.
+In general, use an Aspire client integration when one supports the resource and its authentication method. Use **Aspire.OpenAI** for OpenAI-compatible resources that provide an API key, including Foundry Local. For Azure OpenAI and cloud-provisioned Microsoft Foundry resources, which authenticate with Microsoft Entra ID, use **Aspire.Azure.AI.Extensions.OpenAI**.
### Microsoft Foundry
-For Foundry Local resources, use the **Aspire.OpenAI** client integration. It provides dependency injection and telemetry for the OpenAI-compatible endpoint and the API key that Foundry Local exposes. Cloud-provisioned Microsoft Foundry resources use managed identity, which **Aspire.OpenAI** does not support; use the OpenAI SDK directly for those resources.
-
-
- **Aspire.Azure.AI.Inference** wraps the Azure AI Inference SDK, which Microsoft has retired in favor of the OpenAI SDK for calling Azure AI Foundry Models. Retain it only for existing applications that have not migrated. For cloud Foundry resources, see [Connect to Azure AI Foundry](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/#connect-with-the-openai-sdk). See Microsoft's [migration guide](https://learn.microsoft.com/azure/foundry/how-to/model-inference-to-openai-migration) for details.
-
+For Foundry Local resources, use the **Aspire.OpenAI** client integration. It provides dependency injection and telemetry for the OpenAI-compatible endpoint and the API key that Foundry Local exposes. For cloud-provisioned Microsoft Foundry resources, use **Aspire.Azure.AI.Extensions.OpenAI**: `AddAzureOpenAIClient` for model deployments, or `AddAzureProjectOpenAIClient` for Foundry projects. Use **Aspire.Azure.AI.Projects** (`AddAzureAIProjectClient`) for project and agent-management operations.
For more information, see [Microsoft Foundry integration](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/).
@@ -110,11 +109,17 @@ api := builder.AddNodeApp("api", "./api", "index.js").
#### Client integration
-For Foundry Local, the [Aspire.OpenAI](https://www.nuget.org/packages/Aspire.OpenAI) package provides the recommended client integration. For its configuration sample, see [Connect with Aspire.OpenAI](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/#connect-with-aspireopenai-foundry-local). For cloud-provisioned Foundry resources that authenticate with managed identity, use the OpenAI SDK directly as shown on that page.
+For Foundry Local, the [Aspire.OpenAI](https://www.nuget.org/packages/Aspire.OpenAI) package provides the recommended client integration. For its configuration sample, see [Connect with Aspire.OpenAI](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/#connect-with-aspireopenai-foundry-local). For cloud-provisioned Foundry resources, the [Aspire.Azure.AI.Extensions.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.Extensions.OpenAI) package provides the client integration:
+
+```csharp title="Program.cs"
+builder.AddAzureOpenAIClient("chat").AddChatClient();
+```
+
+For Foundry projects and the [Aspire.Azure.AI.Projects](https://www.nuget.org/packages/Aspire.Azure.AI.Projects) package, see [Connect to a Foundry project](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/#connect-to-a-foundry-project).
### Azure Cognitive Services (Azure OpenAI)
-For Azure OpenAI resources, use the **Aspire.Azure.AI.OpenAI** client integration for full Azure-specific features and authentication support. For more information, see [Azure OpenAI integration](/integrations/cloud/azure/azure-openai/azure-openai-get-started/).
+For Azure OpenAI resources, use the **Aspire.Azure.AI.Extensions.OpenAI** client integration for Microsoft Entra ID and API-key authentication support. For more information, see [Azure OpenAI integration](/integrations/cloud/azure/azure-openai/azure-openai-get-started/).
#### Hosting integration
@@ -161,7 +166,7 @@ api := builder.AddNodeApp("api", "./api", "index.js").
#### Client integration
-The [Aspire.Azure.AI.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.OpenAI) package provides the client integration. In your service project:
+The [Aspire.Azure.AI.Extensions.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.Extensions.OpenAI) package provides the client integration. In your service project:
```csharp title="Program.cs"
builder.AddAzureOpenAIClient("openai");
@@ -276,29 +281,33 @@ Endpoint={Endpoint};Key={Key};Deployment={Deployment};Model={Model}
Uses either `Deployment` or `Model` (in that order). `Deployment` is set by `Aspire.Hosting.Azure.CognitiveServices` while `Model` is set by `Aspire.Hosting.OpenAI`.
-#### Aspire.Azure.AI.OpenAI
+#### Aspire.Azure.AI.Extensions.OpenAI
-Expects connection strings in the format:
+`AddAzureOpenAIClient` expects an HTTPS Azure OpenAI or Foundry account endpoint:
```
-Endpoint={Endpoint};Key={Key};Deployment={Deployment};Model={Model}
+Endpoint={Endpoint};Key={Key};Deployment={Deployment}
```
-Uses either `Deployment` or `Model` (in that order). `Deployment` is set by `Aspire.Hosting.Azure.CognitiveServices` while `Model` is set by `Aspire.Hosting.OpenAI`.
+`Key` is optional; without it, the client uses Microsoft Entra ID. A bare endpoint URI is also accepted. Chat and embedding helpers use either `Deployment` or `Model`, but not both.
+
+`AddAzureProjectOpenAIClient` expects a Foundry project endpoint and rejects `Key`:
+
+```
+Endpoint=https://{account}.services.ai.azure.com/api/projects/{project}
+```
-This integration is a superset of `Aspire.OpenAI` and supports `TokenCredential` and Azure-specific features.
+`AddOpenAIClientFromConfiguration` selects an Azure account, Foundry project, or OpenAI-compatible registration from the endpoint. Endpoints on Azure hosts are treated as Azure; use `IsAzure=true` or `IsAzure=false` to override detection.
-#### Aspire.Azure.AI.Inference
+#### Aspire.Azure.AI.Projects
-Expects connection strings in the format:
+Expects a Foundry project endpoint, either as a bare URI or in the format:
```
-Endpoint={Endpoint};EndpointAIInference={EndpointAIInference};Key={Key};Deployment={DeploymentName};Model={ModelName}
+Endpoint=https://{account}.services.ai.azure.com/api/projects/{project}
```
-Uses either `Deployment` or `Model` (in that order).
-
-Uses `EndpointAIInference` if available, otherwise `Endpoint`.
+`Key` isn't supported; the client uses Microsoft Entra ID.
## See also
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect.mdx
index ef97e7cfe8..9ee2ebb41a 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect.mdx
@@ -22,7 +22,7 @@ import ApiReference from '@components/ApiReference.astro';
This page describes how consuming apps connect to an Azure AI Foundry resource that's already modeled in your AppHost. For the AppHost API surface — adding a Foundry account, model deployments, Foundry projects, hosted agents, and more — see [Azure AI Foundry hosting integration](../azure-ai-foundry-host/).
-When you reference an Azure AI Foundry deployment resource from your AppHost, Aspire injects the connection information into the consuming app as environment variables. In C# apps running Foundry Local, use the Aspire OpenAI client integration for dependency injection and telemetry. Cloud-provisioned Foundry resources authenticate with a managed identity, which the Aspire OpenAI client integration doesn't support, so use the OpenAI SDK directly for those resources. The Python, Go, and TypeScript examples also use their OpenAI SDKs directly.
+When you reference an Azure AI Foundry deployment resource from your AppHost, Aspire injects the connection information into the consuming app as environment variables. In C# apps running Foundry Local, use the Aspire OpenAI client integration for dependency injection and telemetry. For cloud-provisioned Foundry resources, which authenticate with Microsoft Entra ID, use the `Aspire.Azure.AI.Extensions.OpenAI` client integration for model deployments and Foundry projects, or `Aspire.Azure.AI.Projects` for project and agent-management operations. The Python, Go, and TypeScript examples use their SDKs directly.
## Connection properties
@@ -73,7 +73,7 @@ CHAT_FORMAT=OpenAI
CHAT_VERSION=2025-06-01
```
-For .NET apps that consume the composed `ConnectionStrings:{name}` value (for example, via `AddAzureChatCompletionsClient(connectionName: "chat")`) instead of the individual properties above, the format is:
+For .NET apps that consume the composed `ConnectionStrings:{name}` value (for example, via `AddAzureOpenAIClient(connectionName: "chat")`) instead of the individual properties above, the format is:
```
Endpoint=https://my-foundry.services.ai.azure.com/;EndpointAIInference=https://my-foundry.services.ai.azure.com/models;Deployment=chat
@@ -124,7 +124,13 @@ Pick the language your consuming app is written in. Each example assumes your Ap
-For C# apps running Foundry Local, the recommended approach is the Aspire OpenAI client integration. It registers an `OpenAIClient` through dependency injection and can also register an [`IChatClient`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.ai.ichatclient) via `Microsoft.Extensions.AI`. Cloud-provisioned Foundry resources use managed identity, which the Aspire OpenAI integration does not support; use the OpenAI SDK directly for those resources.
+For C# apps, use an Aspire client integration that matches the resource you reference:
+
+- **Foundry Local:** [Aspire.OpenAI](#connect-with-aspireopenai-foundry-local) registers an `OpenAIClient` that uses Foundry Local's API key.
+- **Cloud model deployments:** [Aspire.Azure.AI.Extensions.OpenAI](#connect-to-a-model-deployment) registers an `OpenAIClient` that authenticates with Microsoft Entra ID.
+- **Foundry projects:** [Aspire.Azure.AI.Extensions.OpenAI](#connect-to-a-foundry-project) registers a `ProjectOpenAIClient` for models and agents, and [Aspire.Azure.AI.Projects](#manage-a-foundry-project-with-aiprojectclient) registers an `AIProjectClient` for project and agent-management operations.
+
+Each OpenAI-based integration can also register an [`IChatClient`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.ai.ichatclient) via `Microsoft.Extensions.AI`. To use the OpenAI SDK without a client integration, see [Connect with the OpenAI SDK](#connect-with-the-openai-sdk).
### Connect with Aspire.OpenAI (Foundry Local)
@@ -149,6 +155,78 @@ builder.AddOpenAIClient(
.AddChatClient();
```
+### Connect to a model deployment
+
+For cloud-provisioned Foundry deployments, install the [📦 Aspire.Azure.AI.Extensions.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.Extensions.OpenAI) NuGet package in the client-consuming project:
+
+
+
+The deployment's connection string includes the account endpoint and the `Deployment` name. Call `AddAzureOpenAIClient` to register an `OpenAIClient` for the account's `/openai/v1/` route, then `AddChatClient()` to register an `IChatClient` for that deployment:
+
+```csharp title="Program.cs"
+builder.AddAzureOpenAIClient("chat")
+ .AddChatClient();
+```
+
+The client authenticates with Microsoft Entra ID: Aspire uses a development credential locally and managed identity when deployed to Azure. Resolve `OpenAI.OpenAIClient` or `IChatClient` through dependency injection. Use `AddEmbeddingGenerator()` for embedding deployments, and `AddKeyedAzureOpenAIClient` for keyed registrations. For configuration and telemetry options, see [Connect to Azure OpenAI](/integrations/cloud/azure/azure-openai/azure-openai-connect/#configuration).
+
+
+ To use the same code for Foundry Local and cloud deployments, call `builder.AddOpenAIClientFromConfiguration("chat").AddChatClient()`. It reads the connection string and uses Foundry Local's API key or Microsoft Entra ID for Azure, without an application-side switch.
+
+
+### Connect to a Foundry project
+
+To call models or agents through a [Foundry project](../azure-ai-foundry-host/#add-a-foundry-project), reference both the Foundry resource and the project from the consuming app in your AppHost. The project reference supplies the project endpoint; the Foundry resource reference configures the app's identity and access. Then call `AddAzureProjectOpenAIClient` from [📦 Aspire.Azure.AI.Extensions.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.Extensions.OpenAI). It registers a `ProjectOpenAIClient` (also resolvable as `OpenAIClient`). The connection name matches the project resource name:
+
+```csharp title="Program.cs"
+var clientBuilder = builder.AddAzureProjectOpenAIClient("my-project");
+clientBuilder.AddChatClient("chat");
+clientBuilder.AddEmbeddingGenerator("embeddings");
+```
+
+Model names refer to deployments available to the project. To call a prompt agent, resolve `ProjectOpenAIClient`:
+
+```csharp title="AgentService.cs"
+using Azure.AI.Extensions.OpenAI;
+
+public class AgentService(ProjectOpenAIClient client)
+{
+ public async Task AskAsync(string prompt)
+ {
+ var responses = client.GetProjectResponsesClientForAgent(new AgentReference("my-agent"));
+ var response = await responses.CreateResponseAsync(prompt);
+ // Use response...
+ }
+}
+```
+
+Hosted agents use `GetProjectResponsesClientForAgentEndpoint("my-agent")` instead. The Responses APIs may require suppressing the `OPENAI001` experimental-API warning.
+
+Project clients authenticate with Microsoft Entra ID only; connection strings with a `Key` are rejected. Settings are read from the `Aspire:Azure:AI:Extensions:OpenAI` configuration section. Use `AddKeyedAzureProjectOpenAIClient` for keyed registrations.
+
+### Manage a Foundry project with AIProjectClient
+
+For project and agent-management operations — such as project connections, deployments, datasets, and agent administration — install the [📦 Aspire.Azure.AI.Projects](https://www.nuget.org/packages/Aspire.Azure.AI.Projects) NuGet package:
+
+
+
+Call `AddAzureAIProjectClient` to register an `AIProjectClient`:
+
+```csharp title="Program.cs"
+builder.AddAzureAIProjectClient("my-project");
+```
+
+```csharp title="ProjectService.cs"
+using Azure.AI.Projects;
+
+public class ProjectService(AIProjectClient projectClient)
+{
+ // Use projectClient...
+}
+```
+
+Use `AddKeyedAzureAIProjectClient` for keyed registrations. Settings are read from the `Aspire:Azure:AI:Projects` configuration section; set `DisableTracing` to `true` to turn off the `Azure.AI.Projects.*` traces. Like the project OpenAI client, it uses Microsoft Entra ID and rejects API keys. Neither project integration registers a health check.
+
### Install the OpenAI SDK
@@ -157,7 +235,7 @@ builder.AddOpenAIClient(
### Connect with the OpenAI SDK
-For cloud-provisioned Foundry resources, read the Aspire-injected connection properties in _Program.cs_ and construct a `ChatClient` authenticated with `DefaultAzureCredential`, pointing it at the Foundry endpoint's `openai/v1` route:
+If you'd rather not use a client integration with cloud-provisioned Foundry resources, read the Aspire-injected connection properties in _Program.cs_ and construct a `ChatClient` authenticated with `DefaultAzureCredential`, pointing it at the Foundry endpoint's `openai/v1` route:
```csharp title="Program.cs"
using Azure.Identity;
@@ -240,36 +318,19 @@ public class ExampleService(IChatClient chatClient)
}
```
-### Legacy: Azure AI Inference SDK
+### Migrate from Aspire.Azure.AI.Inference or Aspire.Azure.AI.OpenAI
-
- Microsoft has retired the Azure AI Inference SDK (`Azure.AI.Inference` / `ChatCompletionsClient`) in favor of the OpenAI SDK for calling Azure AI Foundry Models. For details, see Microsoft's [Azure AI Inference SDK to OpenAI SDK migration guide](https://learn.microsoft.com/azure/foundry/how-to/model-inference-to-openai-migration). The Aspire Azure AI Inference client integration below still works and provides dependency injection, health checks, and telemetry, but new code should use Aspire.OpenAI for Foundry Local or the OpenAI SDK for cloud-provisioned Foundry resources. Use this section only if you have an existing app you haven't migrated yet.
-
+The `Aspire.Azure.AI.Inference` and `Aspire.Azure.AI.OpenAI` client integrations are discontinued, and previously published versions remain on NuGet. Microsoft has also retired the Azure AI Inference SDK (`Azure.AI.Inference` / `ChatCompletionsClient`) in favor of the OpenAI SDK. To upgrade a Foundry app:
-Install the [📦 Aspire.Azure.AI.Inference](https://www.nuget.org/packages/Aspire.Azure.AI.Inference) NuGet package in the client-consuming project:
-
-
-
-In _Program.cs_, call `AddAzureChatCompletionsClient` on your `IHostApplicationBuilder` to register a `ChatCompletionsClient`:
-
-```csharp title="Program.cs"
-builder.AddAzureChatCompletionsClient(connectionName: "chat");
-```
-
-
-The `connectionName` must match the Foundry deployment resource name from the AppHost. For more information, see [Add a Foundry deployment resource](../azure-ai-foundry-host/#add-a-foundry-deployment-resource).
-
-
-Resolve the client through dependency injection:
-
-```csharp title="ExampleService.cs"
-public class ExampleService(ChatCompletionsClient client)
-{
- // Use client for chat completions...
-}
-```
+| Before | After |
+| ------ | ----- |
+| `Aspire.Azure.AI.Inference` or `Aspire.Azure.AI.OpenAI` package | `Aspire.Azure.AI.Extensions.OpenAI` package |
+| `AddAzureChatCompletionsClient("chat")` against a deployment | `AddAzureOpenAIClient("chat").AddChatClient()` |
+| `AddAzureChatCompletionsClient` or `AddAzureOpenAIClient` against a project | `AddAzureProjectOpenAIClient("my-project")` with the **project** endpoint |
+| Resolve `ChatCompletionsClient`, `EmbeddingsClient`, or `AzureOpenAIClient` | Resolve `OpenAIClient`, `ProjectOpenAIClient`, or `IChatClient` |
+| Project management through the inference endpoint | `Aspire.Azure.AI.Projects` and `AddAzureAIProjectClient` |
-For keyed clients, configuration options, health checks, and telemetry details for this legacy integration, see [Connect to Azure AI Inference](/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-connect/).
+Azure AI Inference SDK request and response types aren't interchangeable with OpenAI SDK types, so update calls accordingly. Project clients don't accept API keys; grant the app's identity the permissions it needs instead. For SDK-level differences, see Microsoft's [Azure AI Inference SDK to OpenAI SDK migration guide](https://learn.microsoft.com/azure/foundry/how-to/model-inference-to-openai-migration).
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-connect.mdx
index a4c5604d24..295fd98249 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-connect.mdx
@@ -23,7 +23,11 @@ import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png';
This page describes how consuming apps connect to an Azure AI Inference endpoint that's already registered as a connection string in your AppHost. For instructions on registering the connection, see [Get started with the Azure AI Inference integrations](../azure-ai-inference-get-started/).
-When you reference an Azure AI Inference connection from your AppHost, Aspire injects the connection string into the consuming app as an environment variable. Your app can either read the environment variable directly — the pattern works from any language — or, in C#, use the `Aspire.Azure.AI.Inference` client integration for automatic dependency injection, health checks, and telemetry.
+When you reference an Azure AI Inference connection from your AppHost, Aspire injects the connection string into the consuming app as an environment variable. Your app can read the environment variable directly — the pattern works from any language.
+
+:::note[Upgrading to Aspire 17?]
+The `Aspire.Azure.AI.Inference` client integration is discontinued, so the C# guidance on this page applies only to previously published versions. For C# apps, use `Aspire.Azure.AI.Extensions.OpenAI`. See [Migrate from Aspire.Azure.AI.Inference or Aspire.Azure.AI.OpenAI](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/#migrate-from-aspireazureaiinference-or-aspireazureaiopenai).
+:::
## Connection string
@@ -57,7 +61,7 @@ Pick the language your consuming app is written in. Each example assumes your Ap
-For C# apps, the recommended approach is the Aspire Azure AI Inference client integration. It registers a `ChatCompletionsClient` through dependency injection and adds health checks and telemetry automatically. If you'd rather read the connection string directly, see the [Read the connection string](#read-the-connection-string-in-c) section at the end of this tab.
+For C# apps that still use a previously published version, the Aspire Azure AI Inference client integration registers a `ChatCompletionsClient` through dependency injection and adds health checks and telemetry automatically. This package is discontinued; see the note at the top of this page. If you'd rather read the connection string directly, see the [Read the connection string](#read-the-connection-string-in-c) section at the end of this tab.
### Install the client integration
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx
index 96dc0b704c..5c59c5885c 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx
@@ -26,7 +26,10 @@ Adding an Azure AI Inference connection through Aspire — rather than hard-codi
- **Centralized credential management.** The API key and endpoint are stored once in the AppHost configuration and injected into each consuming app automatically.
- **Consistent connection info across languages.** Once you reference the connection from a consuming app, Aspire injects the connection string as an environment variable in a predictable format that works from C#, TypeScript, Python, Go, or any other language.
-- **A first-class C# client integration.** C# apps can use the `Aspire.Azure.AI.Inference` package for dependency injection, health checks, and OpenTelemetry, all wired up from the same connection name.
+
+:::note[Upgrading to Aspire 17?]
+The `Aspire.Azure.AI.Inference` C# client integration is discontinued. For C# apps, use [`Aspire.Azure.AI.Extensions.OpenAI`](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/#connect-to-a-model-deployment). See [Migrate from Aspire.Azure.AI.Inference](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/#migrate-from-aspireazureaiinference-or-aspireazureaiopenai).
+:::
## How the pieces fit together
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-host.mdx
index 2c609c411c..2ba9fafc5a 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-host.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-host.mdx
@@ -396,7 +396,7 @@ Available roles include: `AcrPull`, `AcrPush`, `AcrDelete`, `AcrImageSigner`, `A
## Schedule image cleanup with purge tasks
-Over time, container registries accumulate old images that consume storage. Use to add a scheduled [ACR purge task](https://learn.microsoft.com/azure/container-registry/container-registry-auto-purge) that automatically removes old or unused images:
+Over time, container registries accumulate old images that consume storage. Use to add a scheduled [ACR purge task](https://learn.microsoft.com/azure/container-registry/container-registry-auto-purge) that automatically removes old image tags and untagged manifests:
@@ -454,7 +454,17 @@ if err := app.Run(); err != nil {
-The preceding code creates a purge task that runs daily at 1:00 AM, removing images older than 7 days while keeping the 5 most recent images per repository. The C# `ago` parameter accepts a `TimeSpan`; the TypeScript `ago` option accepts milliseconds.
+The preceding code creates a purge task that runs daily at 1:00 AM. It removes tags that were last modified more than 7 days ago, while always keeping the 5 newest matching tags per repository. The C# `ago` parameter accepts a `TimeSpan`; the TypeScript `ago` option accepts milliseconds.
+
+The purge task applies these rules to repositories that match `filter` (all repositories and tags by default):
+
+- **`keep`** (default `3`) is a minimum, not a maximum. Tags newer than `ago` are also retained, so more than `keep` tags can remain.
+- **`ago`** defaults to zero, so without it every matching tag except the newest `keep` is eligible for removal.
+- **Untagged manifests** are always deleted, regardless of age. This includes manifests that the task just untagged and manifests that were already untagged, so removing tags actually reclaims storage. Locked artifacts and manifests that retained images depend on aren't deleted.
+
+
+ Deleting untagged manifests is irreversible. If you pull images by digest or roll back to earlier digests, those pulls can fail after the purge task runs. Use `filter` to limit the purge task to repositories where that's acceptable.
+
### Multiple purge tasks
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-front-door.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-front-door.mdx
index eae30951d9..084d4609f4 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-front-door.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-front-door.mdx
@@ -306,12 +306,26 @@ resource my_apiRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2025-06-01' = {
}
output my_api_endpointUrl string = 'https://${my_apiEndpoint.properties.hostName}'
+
+output my_api_endpointId string = my_apiEndpoint.id
```
Aspire passes the origin's hostname (resolved from the compute environment, not the full URL) into the `my_api_host` parameter so the Front Door origin points at the deployed backend.
The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly are overwritten, so make changes through the provisioning APIs to ensure they're reflected in the generated files.
+#### Reference endpoint outputs
+
+Each origin produces two outputs named after the origin resource (normalized to a Bicep identifier, such as `my_api`): `{originName}_endpointUrl` with the Front Door endpoint URL, and `{originName}_endpointId` with the endpoint's Azure resource ID. In C#, get references to them by passing the origin's resource name to `GetEndpointUrl` and `GetEndpointId` on the Front Door resource. Use the endpoint ID for resources that require it, such as Azure DNS alias records for an apex domain:
+
+```csharp title="AppHost.cs"
+var frontdoor = builder.AddAzureFrontDoor("frontdoor")
+ .WithOrigin(api);
+
+var endpointUrl = frontdoor.Resource.GetEndpointUrl("api");
+var endpointId = frontdoor.Resource.GetEndpointId("api");
+```
+
#### Customize provisioning infrastructure
For advanced scenarios such as upgrading to the Premium SKU, attaching a Web Application Firewall (WAF) policy, configuring caching, or tuning routes, use `ConfigureInfrastructure` (`configureInfrastructure` in TypeScript) to modify the generated Bicep model directly:
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-connect.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-connect.mdx
index ae2f561ecf..be8202fc91 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-connect.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-connect.mdx
@@ -21,7 +21,7 @@ import openaiIcon from '@assets/icons/azure-openai-icon.png';
This page describes how consuming apps connect to an Azure OpenAI resource that's already modeled in your AppHost. For the AppHost API surface — adding an Azure OpenAI account, deployment resources, managed identity, and infrastructure customization — see [Azure OpenAI hosting integration](../azure-openai-host/).
-When you reference an Azure OpenAI deployment from your AppHost, Aspire injects the connection information into the consuming app as environment variables. Your app can either read those environment variables directly — the pattern works the same from any language — or, in C#, use the Aspire Azure OpenAI client integration for automatic dependency injection, health checks, and telemetry.
+When you reference an Azure OpenAI deployment from your AppHost, Aspire injects the connection information into the consuming app as environment variables. Your app can either read those environment variables directly — the pattern works the same from any language — or, in C#, use the `Aspire.Azure.AI.Extensions.OpenAI` client integration for automatic dependency injection and telemetry.
## Connection properties
@@ -70,17 +70,21 @@ Pick the language your consuming app is written in. Each example assumes your Ap
-For C# apps, the recommended approach is the Aspire Azure OpenAI client integration. It registers an [`AzureOpenAIClient`](https://learn.microsoft.com/dotnet/api/azure.ai.openai.azureopenaiclient) through dependency injection and, optionally, registers an [`IChatClient`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.ai.ichatclient) via `Microsoft.Extensions.AI`. If you'd rather read environment variables directly, see the [Read environment variables](#read-environment-variables-in-c) section at the end of this tab.
+For C# apps, the recommended approach is the Aspire Azure AI Extensions OpenAI client integration. It registers an [`OpenAIClient`](https://github.com/openai/openai-dotnet) from the standard OpenAI SDK through dependency injection, configured for the account's `/openai/v1/` endpoint, and can also register an [`IChatClient`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.ai.ichatclient) or embedding generator via `Microsoft.Extensions.AI`. If you'd rather read environment variables directly, see the [Read environment variables](#read-environment-variables-in-c) section at the end of this tab.
+
+:::note[Upgrading to Aspire 17?]
+`Aspire.Azure.AI.OpenAI` is discontinued. Use `Aspire.Azure.AI.Extensions.OpenAI`, and see [Migrate from Aspire.Azure.AI.OpenAI](#migrate-from-aspireazureaiopenai).
+:::
### Install the client integration
-Install the [📦 Aspire.Azure.AI.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.OpenAI) NuGet package in the client-consuming project:
+Install the [📦 Aspire.Azure.AI.Extensions.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.Extensions.OpenAI) NuGet package in the client-consuming project:
-
+
### Add an Azure OpenAI client
-In _Program.cs_, call `AddAzureOpenAIClient` on your `IHostApplicationBuilder` to register an `AzureOpenAIClient`:
+In _Program.cs_, call `AddAzureOpenAIClient` on your `IHostApplicationBuilder` to register an `OpenAIClient`:
```csharp title="Program.cs"
builder.AddAzureOpenAIClient(connectionName: "chat");
@@ -93,7 +97,9 @@ The `connectionName` must match the Azure OpenAI deployment resource name from t
Resolve the client through dependency injection:
```csharp title="ExampleService.cs"
-public class ExampleService(AzureOpenAIClient client)
+using OpenAI;
+
+public class ExampleService(OpenAIClient client)
{
// Use client...
}
@@ -101,11 +107,11 @@ public class ExampleService(AzureOpenAIClient client)
### Add a chat client
-Call `AddChatClient` after `AddAzureOpenAIClient` to also register an `IChatClient` from `Microsoft.Extensions.AI`. The deployment name is passed as an argument:
+Call `AddChatClient` after `AddAzureOpenAIClient` to also register an `IChatClient` from `Microsoft.Extensions.AI`. When you reference a deployment resource, its connection string includes the deployment name, so you can omit the argument. Pass a deployment name to override it:
```csharp title="Program.cs"
builder.AddAzureOpenAIClient("chat")
- .AddChatClient("chat");
+ .AddChatClient();
```
Use `AddKeyedChatClient` to register a keyed `IChatClient`:
@@ -118,21 +124,30 @@ builder.AddAzureOpenAIClient("chat")
Resolve the `IChatClient` through dependency injection:
```csharp title="ExampleService.cs"
+using Microsoft.Extensions.AI;
+
public class ExampleService(IChatClient chatClient)
{
public async Task GetResponseAsync(string userMessage)
{
- var response = await chatClient.CompleteAsync(userMessage);
- return response.Message.Text ?? string.Empty;
+ var response = await chatClient.GetResponseAsync(userMessage);
+ return response.Text;
}
}
```
+To register an `IEmbeddingGenerator>`, call `AddEmbeddingGenerator` (or `AddKeyedEmbeddingGenerator`) instead:
+
+```csharp title="Program.cs"
+builder.AddAzureOpenAIClient("embeddings")
+ .AddEmbeddingGenerator();
+```
+
For more information on `IChatClient` and `Microsoft.Extensions.AI`, see [Unified AI Building Blocks for .NET](https://learn.microsoft.com/dotnet/core/extensions/artificial-intelligence).
### Add keyed Azure OpenAI clients
-To register multiple `AzureOpenAIClient` instances with different connection names, use `AddKeyedAzureOpenAIClient`:
+To register multiple `OpenAIClient` instances with different connection names, use `AddKeyedAzureOpenAIClient`:
```csharp title="Program.cs"
builder.AddKeyedAzureOpenAIClient(name: "chat");
@@ -143,8 +158,8 @@ Then resolve each instance by key:
```csharp title="ExampleService.cs"
public class ExampleService(
- [FromKeyedServices("chat")] AzureOpenAIClient chatClient,
- [FromKeyedServices("embeddings")] AzureOpenAIClient embeddingsClient)
+ [FromKeyedServices("chat")] OpenAIClient chatClient,
+ [FromKeyedServices("embeddings")] OpenAIClient embeddingsClient)
{
// Use clients...
}
@@ -152,7 +167,7 @@ public class ExampleService(
### Configuration
-The Aspire Azure OpenAI client integration offers multiple ways to provide configuration.
+The client integration offers multiple ways to provide configuration.
**Connection strings.** When using a connection string from the `ConnectionStrings` configuration section, pass the connection name to `AddAzureOpenAIClient`:
@@ -160,14 +175,14 @@ The Aspire Azure OpenAI client integration offers multiple ways to provide confi
builder.AddAzureOpenAIClient("chat");
```
-The connection string is resolved from the `ConnectionStrings` section. Two formats are supported:
+The connection string is resolved from the `ConnectionStrings` section. The endpoint must be an HTTPS account endpoint; Aspire normalizes it to the account's `/openai/v1/` route. Two authentication formats are supported:
-- **Managed identity (recommended):** The endpoint URI only.
+- **Microsoft Entra ID (recommended):** The endpoint, optionally with a default `Deployment`. A bare endpoint URI is also accepted.
```json title="appsettings.json"
{
"ConnectionStrings": {
- "chat": "https://{account-name}.openai.azure.com/"
+ "chat": "Endpoint=https://{account-name}.openai.azure.com/;Deployment=chat"
}
}
```
@@ -182,7 +197,9 @@ The connection string is resolved from the `ConnectionStrings` section. Two form
}
```
-**Configuration providers.** The client integration supports `Microsoft.Extensions.Configuration`. It loads `AzureOpenAISettings` from _appsettings.json_ (or any other configuration source) using the `Aspire:Azure:AI:OpenAI` key:
+Without a key, the client authenticates with Microsoft Entra ID: Aspire uses a development credential locally and managed identity when deployed to Azure. The default token scope is `https://ai.azure.com/.default`; set `TokenScope` for other Azure clouds.
+
+**Configuration providers.** The client integration supports `Microsoft.Extensions.Configuration`. It loads `AzureOpenAISettings` from _appsettings.json_ (or any other configuration source) using the `Aspire:Azure:AI:OpenAI` key, followed by a connection-specific subsection:
```json title="appsettings.json"
{
@@ -190,7 +207,9 @@ The connection string is resolved from the `ConnectionStrings` section. Two form
"Azure": {
"AI": {
"OpenAI": {
- "DisableTracing": false
+ "DisableTracing": false,
+ "DisableMetrics": false,
+ "EnableSensitiveTelemetryData": false
}
}
}
@@ -198,71 +217,80 @@ The connection string is resolved from the `ConnectionStrings` section. Two form
}
```
-**Inline delegates.** Configure settings inline using an `Action`:
+**Inline delegates.** Configure settings inline using an `Action`, for example to supply a custom credential:
```csharp title="Program.cs"
+using Azure.Identity;
+
builder.AddAzureOpenAIClient(
"chat",
- settings => settings.DisableTracing = true);
+ settings => settings.Credential = new AzureCliCredential());
```
-To configure the `AzureOpenAIClientOptions` inline:
+To configure the `OpenAIClientOptions` inline:
```csharp title="Program.cs"
+using Microsoft.Extensions.Azure;
+
builder.AddAzureOpenAIClient(
connectionName: "chat",
configureClientBuilder: clientBuilder =>
{
clientBuilder.ConfigureOptions(options =>
{
- options.UserAgentApplicationId = "MyApp";
+ options.NetworkTimeout = TimeSpan.FromSeconds(60);
});
});
```
-### Add Azure OpenAI client from configuration
+### Add an OpenAI client from configuration
-Use `AddOpenAIClientFromConfiguration` to register an `OpenAIClient` or `AzureOpenAIClient` based on the connection string value:
+Use `AddOpenAIClientFromConfiguration` (or `AddKeyedOpenAIClientFromConfiguration`) when the same app might run against Azure OpenAI or another OpenAI-compatible endpoint. It always registers an `OpenAIClient` and picks the registration based on the connection string value:
```csharp title="Program.cs"
-builder.AddOpenAIClientFromConfiguration("chat");
+builder.AddOpenAIClientFromConfiguration("chat")
+ .AddChatClient();
```
-The method selects the client type according to these rules:
+| Connection string example | Registration |
+| ------------------------- | ------------ |
+| `https://{account}.openai.azure.com/` | Azure OpenAI account, Microsoft Entra ID |
+| `Endpoint=https://{account}.openai.azure.com/;Key={key}` | Azure OpenAI account, API key |
+| `Endpoint=https://{account}.services.ai.azure.com/api/projects/{project}` | Foundry project (see [Connect to Azure AI Foundry](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/)) |
+| `Endpoint=https://{account}.openai.azure.com/;Key={key};IsAzure=false` | OpenAI-compatible endpoint, API key |
+| `Endpoint=https://localhost:18889;Key={key}` | OpenAI-compatible endpoint, API key |
-| Connection string example | Registered client type |
-| ------------------------- | ---------------------- |
-| `https://{account}.openai.azure.com/` | `AzureOpenAIClient` |
-| `Endpoint=https://{account}.openai.azure.com/;Key={key}` | `AzureOpenAIClient` |
-| `Endpoint=https://{account}.openai.azure.com/;Key={key};IsAzure=false` | `OpenAIClient` |
-| `Endpoint=https://localhost:18889;Key={key}` | `OpenAIClient` |
+Endpoints on Azure hosts (such as `*.azure.com`) are treated as Azure. Use `IsAzure=true` or `IsAzure=false` to override detection, for example for custom domains.
### Client integration health checks
-Aspire client integrations enable health checks by default. The Azure OpenAI client integration participates in the standard Aspire health check pipeline.
+The client integration doesn't register a health check, so it never makes billable inference calls to probe the service.
### Observability and telemetry
-The Aspire Azure OpenAI client integration automatically configures logging, tracing, and metrics through OpenTelemetry.
+The chat and embedding helpers register `Microsoft.Extensions.AI` tracing and metrics through OpenTelemetry, using these activity sources and meters:
-**Logging** categories:
+- `Experimental.Microsoft.Extensions.AI`
+- `Microsoft.Extensions.AI`
-- `Azure`
-- `Azure.Core`
-- `Azure.Identity`
-- `Azure.AI.OpenAI`
+Use `DisableTracing` and `DisableMetrics` to turn off each signal independently. Message content isn't captured unless you set `EnableSensitiveTelemetryData` to `true` (or set the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` environment variable to `true`). Calls you make directly on `OpenAIClient` use the OpenAI SDK's own diagnostics.
-**Tracing** activities:
+### Migrate from Aspire.Azure.AI.OpenAI
-- `Azure.AI.OpenAI.*`
-- `gen_ai.system` — generic AI system tracing
-- `gen_ai.operation.name` — operation names for AI calls
+To upgrade an app that uses the discontinued `Aspire.Azure.AI.OpenAI` package:
-**Metrics:**
+1. Replace the `Aspire.Azure.AI.OpenAI` package reference with `Aspire.Azure.AI.Extensions.OpenAI`.
+2. Keep your `AddAzureOpenAIClient`, `AddKeyedAzureOpenAIClient`, `AddOpenAIClientFromConfiguration`, `AddChatClient`, and `AddEmbeddingGenerator` calls. Settings stay under `Aspire:Azure:AI:OpenAI`.
+3. Update code that depends on the old types:
-The Aspire Azure OpenAI integration currently does not emit metrics by default due to limitations with the Azure SDK for .NET.
+ | Before (`Aspire.Azure.AI.OpenAI`) | After (`Aspire.Azure.AI.Extensions.OpenAI`) |
+ | --------------------------------- | ------------------------------------------- |
+ | Resolve `Azure.AI.OpenAI.AzureOpenAIClient` | Resolve `OpenAI.OpenAIClient` |
+ | `Aspire.Azure.AI.OpenAI.AzureOpenAISettings` | `Aspire.Azure.AI.Extensions.OpenAI.AzureOpenAISettings` |
+ | `configureClientBuilder` customizes `AzureOpenAIClientOptions` | `configureClientBuilder` customizes `OpenAIClientOptions` |
+ | Deployment-specific routes | `/openai/v1/` routes |
-Any of these telemetry features can be disabled through the configuration options above.
+The new package uses the standard OpenAI SDK's v1 API, so the registration pattern is compatible but the client types aren't. For API differences, see the [Azure OpenAI SDK migration guide](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/openai/Azure.AI.OpenAI/migration-guidance.md).
### Read environment variables in C\#
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx
index 73f124e5f6..a05044c850 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx
@@ -27,7 +27,7 @@ Adding Azure OpenAI through Aspire — rather than hard-coding endpoints and cre
- **Consistent connection info across languages.** Once you reference the deployment from a consuming app, Aspire injects connection properties as environment variables in a predictable format that works from C#, TypeScript, Python, Go, or any other language.
- **Declarative Bicep provisioning.** Aspire generates Bicep for the Azure Cognitive Services account and role assignments from your C# or TypeScript AppHost code — no hand-authoring required.
- **Dashboard observability.** The Azure OpenAI resource and its deployments show up in the Aspire dashboard with status and telemetry alongside your other services.
-- **A first-class C# client integration.** C# apps can use the `Aspire.Azure.AI.OpenAI` package for dependency injection, health checks, and OpenTelemetry, all wired up from the same resource name.
+- **A first-class C# client integration.** C# apps can use the `Aspire.Azure.AI.Extensions.OpenAI` package for dependency injection, `Microsoft.Extensions.AI` chat and embedding clients, and OpenTelemetry, all wired up from the same resource name. It replaces `Aspire.Azure.AI.OpenAI`, which is discontinued as of Aspire 17.0.
- **A path to existing Azure resources.** Point to an already-deployed Azure OpenAI account in your Azure subscription without re-provisioning anything.
## How the pieces fit together
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx
index f24ea0eb81..8e59e43358 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx
@@ -613,6 +613,72 @@ The preceding code maps the `emulator` endpoint to host port `7777`:
| ------------- | ------------------------------- |
| `emulator` | `5672:7777` |
+### Configure the emulator's SQL Server
+
+The emulator stores its state in a SQL Server resource that Aspire creates for it. In C# AppHosts, pass a callback to `WithSqlServer` to customize that resource with the regular [SQL Server hosting integration](/integrations/databases/sql-server/sql-server-host/) APIs, such as persisting state in a data volume:
+
+```csharp title="AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var serviceBus = builder.AddAzureServiceBus("messaging")
+ .RunAsEmulator(emulator =>
+ {
+ emulator.WithSqlServer(sql => sql
+ .WithDataVolume()
+ .WithContainerName("messaging-sql"));
+ });
+
+// After adding all resources, run the app...
+builder.Build().Run();
+```
+
+The emulator connects to the SQL Server through its `tcp` endpoint, so don't remove or rename that endpoint in the callback.
+
+To reuse a SQL Server resource that's already in your AppHost instead of creating a new one, pass it to `WithSqlServer`. The emulator waits for that SQL Server to be healthy before it starts:
+
+
+
+
+```csharp title="AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var sql = builder.AddSqlServer("sql");
+
+var serviceBus = builder.AddAzureServiceBus("messaging")
+ .RunAsEmulator(emulator =>
+ {
+ emulator.WithSqlServer(sql);
+ });
+
+// After adding all resources, run the app...
+builder.Build().Run();
+```
+
+
+
+
+```typescript title="apphost.mts"
+import { createBuilder } from './.aspire/modules/aspire.mjs';
+
+const builder = await createBuilder();
+
+const sql = await builder.addSqlServer("sql");
+
+const serviceBus = await builder.addAzureServiceBus("messaging")
+ .runAsEmulator({
+ configureContainer: async (emulator) => {
+ await emulator.withSqlServer(sql);
+ }
+ });
+
+await builder.build().run();
+```
+
+
+
+
+You can't combine the two forms: an emulator either customizes its own SQL Server or uses an existing one.
+
### Configure the emulator with a custom JSON file
The Service Bus emulator generates its configuration automatically from the resources you've added. To provide a fully custom configuration file instead, call :
diff --git a/src/frontend/src/content/docs/integrations/compute/kubernetes.mdx b/src/frontend/src/content/docs/integrations/compute/kubernetes.mdx
index 4c78dc984a..7ad56c6304 100644
--- a/src/frontend/src/content/docs/integrations/compute/kubernetes.mdx
+++ b/src/frontend/src/content/docs/integrations/compute/kubernetes.mdx
@@ -491,6 +491,51 @@ This example uses the C# workload resource model. The same typed CPU and memory
For quantity syntax and enforcement details, see [Resource management for pods and containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
+### Set environment variables from an init container's env file
+
+When a value is only known at pod startup—for example, a token or setting an init container fetches or computes—an init container can write it to an env file on an `emptyDir` volume, and the app container can read individual keys with `FileKeyRef`. The file isn't mounted into the app container, and you don't need to override the app's entrypoint.
+
+```csharp title="AppHost.cs"
+using Aspire.Hosting.Kubernetes.Resources;
+
+builder.AddContainer("myapp", "nginx:alpine")
+ .PublishAsKubernetesService(resource =>
+ {
+ var pod = resource.Workload!.PodTemplate.Spec;
+ pod.Volumes.Add(new VolumeV1 { Name = "generated-env", EmptyDir = new() });
+
+ pod.InitContainers.Add(new ContainerV1
+ {
+ Name = "prepare-env",
+ Image = "docker.io/library/busybox:1.37",
+ Command = { "sh", "-ec" },
+ Args = { "printf \"SOURCE_KEY='generated-value'\\n\" > /out/app.env" },
+ VolumeMounts = { new VolumeMountV1 { Name = "generated-env", MountPath = "/out" } }
+ });
+
+ pod.Containers[0].Env.Add(new EnvVarV1
+ {
+ Name = "APP_VALUE",
+ ValueFrom = new EnvVarSourceV1
+ {
+ FileKeyRef = new FileKeySelectorV1
+ {
+ VolumeName = "generated-env",
+ Path = "app.env",
+ Key = "SOURCE_KEY",
+ Optional = false
+ }
+ }
+ });
+ });
+```
+
+`FileKeySelectorV1` selects `Key` from the file at `Path`, relative to the root of the `emptyDir` volume named by `VolumeName`. When `Optional` is `true`, a missing file or key leaves the variable unset; otherwise, the container doesn't start. The value is read once when the container starts, so later changes to the file don't update a running container. Init-container images must be pullable by the cluster.
+
+:::note
+`FileKeyRef` requires Kubernetes 1.34 or later with the `EnvFiles` feature gate enabled; it's on by default starting with Kubernetes 1.35. This C# resource-model API isn't exposed to TypeScript AppHosts.
+:::
+
## Add custom Kubernetes manifests
Within a `PublishAsKubernetesService` callback, you can attach arbitrary Kubernetes manifests — such as [cert-manager](https://cert-manager.io/) `Certificate` definitions, additional `ConfigMap` objects, or any other Kubernetes resource — to the generated Helm chart alongside your service.
diff --git a/src/frontend/src/content/docs/integrations/frameworks/rust/rust-get-started.mdx b/src/frontend/src/content/docs/integrations/frameworks/rust/rust-get-started.mdx
index 255eef1ba8..e9dbedcd1b 100644
--- a/src/frontend/src/content/docs/integrations/frameworks/rust/rust-get-started.mdx
+++ b/src/frontend/src/content/docs/integrations/frameworks/rust/rust-get-started.mdx
@@ -44,7 +44,7 @@ Adding Rust apps through Aspire — rather than starting each `cargo run` by han
- The [Aspire CLI](/get-started/install-cli/), along with the other [Aspire prerequisites](/get-started/prerequisites/).
:::note
-A C# or TypeScript AppHost can host Rust apps without turning on any experimental features. Writing the AppHost itself in Rust is a separate, experimental scenario that you turn on with the `features.experimentalPolyglot:rust` [configuration setting](/reference/cli/configuration/).
+A C# or TypeScript AppHost can host Rust apps without turning on any experimental features. Writing the AppHost itself in Rust is a separate, experimental scenario that you turn on with the `features.experimentalPolyglotRust` [configuration setting](/reference/cli/configuration/).
:::
## How the pieces fit together
diff --git a/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/client-credentials.mdx b/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/client-credentials.mdx
index b2feb6b51f..feae45d0fe 100644
--- a/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/client-credentials.mdx
+++ b/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/client-credentials.mdx
@@ -206,7 +206,7 @@ const tenantId = await builder.addParameter("entra-tenant-id");
const webClientId = await builder.addParameter("entra-web-client-id");
const webSecret = await builder.addParameter("entra-web-secret", { secret: true });
-const entraWeb = await builder.addExistingEntraApplication("entra-web", tenantId, webClientId);
+const entraWeb = await builder.addExistingEntraIdApplication("entra-web", tenantId, webClientId);
await entraWeb.withClientSecret(webSecret);
await builder.build().run();
@@ -222,7 +222,7 @@ var tenantId = builder.AddParameter("entra-tenant-id");
var webClientId = builder.AddParameter("entra-web-client-id");
var webSecret = builder.AddParameter("entra-web-secret", secret: true);
-var entraWeb = builder.AddExistingEntraApplication("entra-web", tenantId, webClientId)
+var entraWeb = builder.AddExistingEntraIdApplication("entra-web", tenantId, webClientId)
.WithClientSecret(webSecret);
// After adding all resources, run the app...
@@ -242,7 +242,7 @@ Reference a Key Vault that you model in the AppHost instead of hard-coding its U
```typescript title="apphost.mts"
const vault = await builder.addAzureKeyVault("vault");
-const entraWeb = await builder.addExistingEntraApplication("entra-web", tenantId, webClientId)
+const entraWeb = await builder.addExistingEntraIdApplication("entra-web", tenantId, webClientId)
.withCertificateFromKeyVault(vault, "MyCert");
const web = await builder.addDotnetProject("web", "../Web/Web.csproj");
@@ -255,7 +255,7 @@ await web.withReference(entraWeb);
```csharp title="AppHost.cs"
var vault = builder.AddAzureKeyVault("vault");
-var entraWeb = builder.AddExistingEntraApplication("entra-web", tenantId, webClientId)
+var entraWeb = builder.AddExistingEntraIdApplication("entra-web", tenantId, webClientId)
.WithCertificateFromKeyVault(vault, "MyCert");
builder.AddDotnetProject("web", "../Web/Web.csproj")
diff --git a/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/existing-registrations.mdx b/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/existing-registrations.mdx
index f2b8e5fda4..0b3af891ed 100644
--- a/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/existing-registrations.mdx
+++ b/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/existing-registrations.mdx
@@ -10,7 +10,7 @@ Many teams manage app registrations outside the AppHost, for example because a c
## Reference an existing registration
-You supply the **Directory (tenant) ID** and the **Application (client) ID** from the registration's **Overview** page. Use `AddExistingEntraApplication` when you don't want Aspire to set up Azure provisioning for the registration. You can mix existing registrations with registrations that Aspire creates in the same AppHost.
+You supply the **Directory (tenant) ID** and the **Application (client) ID** from the registration's **Overview** page. Use `AddExistingEntraIdApplication` when you don't want Aspire to set up Azure provisioning for the registration. You can mix existing registrations with registrations that Aspire creates in the same AppHost.
@@ -23,7 +23,7 @@ const builder = await createBuilder();
const tenantId = await builder.addParameter("entra-tenant-id");
const apiClientId = await builder.addParameter("entra-api-client-id");
-const entraApi = await builder.addExistingEntraApplication("entra-api", tenantId, apiClientId);
+const entraApi = await builder.addExistingEntraIdApplication("entra-api", tenantId, apiClientId);
const api = await builder.addDotnetProject("api", "../Api/Api.csproj");
await api.withReference(entraApi);
@@ -40,7 +40,7 @@ var builder = DistributedApplication.CreateBuilder(args);
var tenantId = builder.AddParameter("entra-tenant-id");
var apiClientId = builder.AddParameter("entra-api-client-id");
-var entraApi = builder.AddExistingEntraApplication("entra-api", tenantId, apiClientId);
+var entraApi = builder.AddExistingEntraIdApplication("entra-api", tenantId, apiClientId);
builder.AddDotnetProject("api", "../Api/Api.csproj")
.WithReference(entraApi);
@@ -61,7 +61,7 @@ Each ID accepts a literal value or a parameter. In TypeScript, you can mix them:
const clientId = await builder.addParameter("entra-client-id");
const clientSecret = await builder.addParameter("entra-secret", { secret: true });
-const entraApi = await builder.addExistingEntraApplication(
+const entraApi = await builder.addExistingEntraIdApplication(
"entra-api", "aaaabbbb-0000-cccc-1111-dddd2222eeee", clientId)
.withClientSecret(clientSecret);
@@ -75,7 +75,7 @@ await builder.addExecutable("worker", "node", ".", ["worker.mjs"])
```csharp title="AppHost.cs"
var clientSecret = builder.AddParameter("entra-secret", secret: true);
-var entraApi = builder.AddExistingEntraApplication(
+var entraApi = builder.AddExistingEntraIdApplication(
"entra-api",
tenantId: "aaaabbbb-0000-cccc-1111-dddd2222eeee",
clientId: "00001111-aaaa-2222-bbbb-3333cccc4444")
@@ -102,7 +102,7 @@ You can also convert an `AddEntraIdApplication` resource with `AsExistingApplica
| Approach | Azure provisioning | Use it when |
|----------|--------------------|-------------|
-| `AddExistingEntraApplication` | Not enabled | The AppHost needs only the registration's settings. It needs no Azure or Microsoft Graph access. |
+| `AddExistingEntraIdApplication` | Not enabled | The AppHost needs only the registration's settings. It needs no Azure or Microsoft Graph access. |
| `AddEntraIdApplication(...).AsExistingApplication(...)` | Kept | You start with a created registration and later point it at an existing one. |
`AsExistingApplication` keeps the Azure setup that `AddEntraIdApplication` adds, so deployment can still require Azure authentication and provisioning configuration. Other Azure resources in the same AppHost keep their normal provisioning behavior in both approaches.
@@ -158,7 +158,7 @@ To reference an existing API's scopes, pass the URI that the registration alread
```typescript title="apphost.mts"
-const entraApi = await builder.addExistingEntraApplication("entra-api", tenantId, apiClientId)
+const entraApi = await builder.addExistingEntraIdApplication("entra-api", tenantId, apiClientId)
.withApplicationIdUri({ applicationIdUri: "api://contoso-orders" })
.withScope("Weather.Read", "Allows the app to read weather forecasts.", {
id: "5d1f7b84-3c2e-4a6e-9a1d-0b8f2c3d4e5f",
@@ -172,7 +172,7 @@ await entraWeb.withApiPermissions(entraApi, ["Weather.Read"]);
```csharp title="AppHost.cs"
-var entraApi = builder.AddExistingEntraApplication("entra-api", tenantId, apiClientId)
+var entraApi = builder.AddExistingEntraIdApplication("entra-api", tenantId, apiClientId)
.WithApplicationIdUri("api://contoso-orders")
.WithScope("Weather.Read", "Allows the app to read weather forecasts.", scope =>
{
diff --git a/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/index.mdx b/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/index.mdx
index 40f4e388d3..0cbb5a8693 100644
--- a/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/index.mdx
+++ b/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/index.mdx
@@ -98,7 +98,7 @@ The registration appears in the dashboard as a resource:
- When it's ready, it reports **Running**, links to the tenant's OpenID Connect discovery document, and shows its tenant ID, client ID, and other settings as properties. In the Azure public cloud and national clouds, it also links to the app registration in the Azure portal.
- If a setting is invalid, it reports **Failed to start**, and its console logs explain why. If Azure provisioning isn't configured, it reports **Missing subscription configuration**. To resolve these and other errors, see [Troubleshoot Entra ID errors](/integrations/security/microsoft-entra-id/lifecycle-and-permissions/#troubleshoot-entra-id-errors).
-If tenant policy prevents creating registrations, use [`AddExistingEntraApplication`](/integrations/security/microsoft-entra-id/existing-registrations/) for a configuration-only reference.
+If tenant policy prevents creating registrations, use [`AddExistingEntraIdApplication`](/integrations/security/microsoft-entra-id/existing-registrations/) for a configuration-only reference.
## Settings that apps receive
diff --git a/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/lifecycle-and-permissions.mdx b/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/lifecycle-and-permissions.mdx
index 3531affab5..cd786d286f 100644
--- a/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/lifecycle-and-permissions.mdx
+++ b/src/frontend/src/content/docs/integrations/security/microsoft-entra-id/lifecycle-and-permissions.mdx
@@ -71,7 +71,7 @@ var entraApi = builder.AddEntraIdApplication("entra-api")
-Changing the name or the suffix targets a different registration and leaves the previous application and service principal in place. To keep using a registration that has a different `uniqueName`, reference it with `AddExistingEntraApplication`, or [clean it up](/integrations/security/microsoft-entra-id/lifecycle-and-permissions/#clean-up-registrations).
+Changing the name or the suffix targets a different registration and leaves the previous application and service principal in place. To keep using a registration that has a different `uniqueName`, reference it with `AddExistingEntraIdApplication`, or [clean it up](/integrations/security/microsoft-entra-id/lifecycle-and-permissions/#clean-up-registrations).
Use separate registrations for development and production, especially with the [local developer certificate](/integrations/security/microsoft-entra-id/client-credentials/#local-developer-certificate).
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx
index 6f17bf0c27..b6f63a6694 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx
@@ -96,8 +96,11 @@ The following options are available:
cache Redis Running Healthy tcp://localhost:63122
webfrontend Project Running Healthy https://localhost:17015, http://localhost:15099
apiservice Project Running Healthy https://localhost:17016, http://localhost:15100
+ migrations Project Finished (exit code: 0) - -
```
+ For resources in the `Finished` or `Exited` state, the **State** column includes the exit code when it's available, such as `Finished (exit code: 0)`. A nonzero exit code is shown in red so that failed resources stand out.
+
- Show details for a specific resource:
```bash title="Aspire CLI"
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx
index 3142643144..45229351b9 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx
@@ -151,6 +151,18 @@ The following options are available:
The programming language for the AppHost, such as `csharp`, `typescript`, or `go`. When you don't pass a template, `aspire new` offers only the templates that support the language.
+- **`--template-path `**
+
+ Path to an unpacked .NET template package directory. When you also specify `--template-repository`, the path is relative to the repository root, and it defaults to the root. You can't combine this option with a template command, `--source`, `--version`, `--channel`, or `--language`.
+
+- **`--template-repository `**
+
+ Clone a Git repository that contains templates, and choose a template from it without registering a [template source](#configure-template-sources). Requires Git on your `PATH`. The same restrictions as `--template-path` apply.
+
+- **`--template-repository-ref [`**
+
+ The branch, tag, or full commit SHA of the template repository to use. Requires `--template-repository`. Defaults to the repository's default branch.
+
- **`--use-config-source [true|false]`**
Accept a Git configuration source that's available for the project, or pass `false` to use standard Aspire configuration instead. Specify this option to respond to the configuration source prompt in non-interactive mode.
@@ -254,6 +266,24 @@ The `aspire-go-starter` template scaffolds a Go API (`api/`), a Vite and React f
aspire new aspire-starter --name myapp --agents all --skills aspire --scope project --non-interactive
```
+- Create a project from templates in a local, unpacked template package directory:
+
+ ```bash title="Aspire CLI"
+ aspire new --template-path ./my-templates
+ ```
+
+- Create a project from templates in a Git repository:
+
+ ```bash title="Aspire CLI"
+ aspire new --template-repository https://github.com/Azure/aspire-templates
+ ```
+
+- Create a project from a template in a subdirectory of a specific branch of a Git repository:
+
+ ```bash title="Aspire CLI"
+ aspire new --template-repository https://github.com/example-org/aspire-templates --template-repository-ref custom-starter --template-path templates
+ ```
+
## Troubleshooting
### Language support not found
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-delete.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-delete.mdx
index b81e86d70b..77adacb378 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-delete.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-delete.mdx
@@ -17,7 +17,7 @@ aspire secret delete ] [options]
## Description
-The `aspire secret delete` command deletes a user secret from the secrets store for an Aspire AppHost.
+The `aspire secret delete` command deletes a secret from the secrets file for the selected environment (`Development` by default) of an Aspire AppHost.
@@ -43,6 +43,10 @@ The following options are available:
The path to the Aspire AppHost project file.
+- **`-e, --environment `**
+
+ The AppHost environment whose secrets file is used. Names are case-insensitive. The default is `Development`. For storage details, see [Environment-specific secrets](../aspire-secret/#environment-specific-secrets).
+
-
-
@@ -68,3 +72,9 @@ The following options are available:
```bash title="Aspire CLI"
aspire secret delete Parameters:rabbitmq-password --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj
```
+
+- Delete a secret from the `Production` environment:
+
+ ```bash title="Aspire CLI"
+ aspire secret delete Parameters:postgres-password -e Production
+ ```
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-get.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-get.mdx
index 3a896d2375..f294c64e3b 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-get.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-get.mdx
@@ -17,7 +17,7 @@ aspire secret get [options]
## Description
-The `aspire secret get` command retrieves a user secret value for an Aspire AppHost.
+The `aspire secret get` command retrieves a secret value for an Aspire AppHost from the secrets file for the selected environment (`Development` by default).
@@ -43,6 +43,10 @@ The following options are available:
The path to the Aspire AppHost project file.
+- **`-e, --environment `**
+
+ The AppHost environment whose secrets file is used. Names are case-insensitive. The default is `Development`. For storage details, see [Environment-specific secrets](../aspire-secret/#environment-specific-secrets).
+
-
-
@@ -68,3 +72,9 @@ The following options are available:
```bash title="Aspire CLI"
aspire secret get Parameters:rabbitmq-password --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj
```
+
+- Get a secret from the `Production` environment:
+
+ ```bash title="Aspire CLI"
+ aspire secret get Parameters:postgres-password -e Production
+ ```
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-list.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-list.mdx
index 4779297496..6c21420868 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-list.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-list.mdx
@@ -17,7 +17,7 @@ aspire secret list [options]
## 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 secret list` command lists the secrets stored for an Aspire AppHost in the selected environment (`Development` by default). Use `--all` to list secrets from every environment. By default, secrets are displayed in a table format sorted alphabetically by key. If no secrets are configured, the command displays "No secrets configured."
@@ -33,6 +33,14 @@ The following options are available:
The path to the Aspire AppHost project file.
+- **`-e, --environment `**
+
+ The AppHost environment whose secrets file is used. Names are case-insensitive. The default is `Development`. For storage details, see [Environment-specific secrets](../aspire-secret/#environment-specific-secrets).
+
+- **`--all`, `--all-environments`**
+
+ List secrets from all of the AppHost's environment secrets files. The table output adds an `Environment` column, and the JSON output groups secrets by environment name. You can't combine `--all` with `--environment`.
+
-
-
@@ -64,3 +72,15 @@ The following options are available:
```bash title="Aspire CLI"
aspire secret list --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj
```
+
+- List secrets for the `Production` environment:
+
+ ```bash title="Aspire CLI"
+ aspire secret list --environment Production
+ ```
+
+- List secrets for every environment:
+
+ ```bash title="Aspire CLI"
+ aspire secret list --all
+ ```
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-path.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-path.mdx
index 3b1ea68f07..9cca1b0320 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-path.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-path.mdx
@@ -17,7 +17,7 @@ aspire secret path [options]
## 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 secret path` command displays the full file path to the secrets file for the selected environment (`Development` by default) of an Aspire AppHost, such as `~/.aspire/secrets//Development.json`. The file might not exist until a secret is set. This is useful when you need to directly inspect or edit the secrets file, or when troubleshooting secrets resolution.
@@ -29,6 +29,10 @@ The following options are available:
The path to the Aspire AppHost project file.
+- **`-e, --environment `**
+
+ The AppHost environment whose secrets file is used. Names are case-insensitive. The default is `Development`. For storage details, see [Environment-specific secrets](../aspire-secret/#environment-specific-secrets).
+
-
-
@@ -54,3 +58,9 @@ The following options are available:
```bash title="Aspire CLI"
aspire secret path --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj
```
+
+- Show the secrets file path for the `Production` environment:
+
+ ```bash title="Aspire CLI"
+ aspire secret path --environment Production
+ ```
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-set.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-set.mdx
index be570bc182..82f4651423 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-set.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret-set.mdx
@@ -17,7 +17,7 @@ aspire secret set [] [options]
## 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 secret set` command sets a secret value for an Aspire AppHost in the secrets file for the selected environment (`Development` by default). The file is created if it doesn't exist. For a C# AppHost without a `UserSecretsId`, setting a `Development` secret also initializes one so the AppHost can locate its secrets.
@@ -41,6 +41,10 @@ The following options are available:
The path to the Aspire AppHost project file.
+- **`-e, --environment `**
+
+ The AppHost environment whose secrets file is used. Names are case-insensitive. The default is `Development`. For storage details, see [Environment-specific secrets](../aspire-secret/#environment-specific-secrets).
+
- **`--envvar `**
Read the secret value from the named environment variable instead of a positional value. The variable must be set in the CLI process environment; an empty value is accepted. You can't combine `--envvar` with a positional `value`.
@@ -71,6 +75,12 @@ The following options are available:
aspire secret set Parameters:rabbitmq-password Pass123 --apphost ./src/MyApp.AppHost/MyApp.AppHost.csproj
```
+- Set a secret for the `Production` environment:
+
+ ```bash title="Aspire CLI"
+ aspire secret set Parameters:postgres-password --environment Production --envvar POSTGRES_PASSWORD
+ ```
+
- Enter a secret at a masked prompt, keeping the value out of shell history:
```bash title="Aspire CLI"
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret.mdx
index 88efa2fbae..79ab781d00 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-secret.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-secret.mdx
@@ -1,13 +1,13 @@
---
title: aspire secret command
-description: Learn about the aspire secret command and its usage. This command is used to manage user secrets for an Aspire AppHost.
+description: Learn about the aspire secret command and its usage. This command is used to manage environment-specific secrets for an Aspire AppHost.
---
import Include from '@components/Include.astro';
## Name
-`aspire secret` - Manage AppHost user secrets.
+`aspire secret` - Manage AppHost secrets.
## Synopsis
@@ -17,12 +17,28 @@ aspire secret [command] [options]
## 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.
+The `aspire secret` command manages secrets for an Aspire AppHost project. Secrets provide a safe way to store sensitive configuration values—such as passwords, API keys, and connection strings—outside of your project files.
-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.
+Aspire uses 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 saves the generated password. On subsequent runs, the saved password is reused so that the resource retains its state.
+### Environment-specific secrets
+
+Each `aspire secret` subcommand accepts `--environment` (or `-e`) to select the AppHost environment whose secrets you manage. Environment names are case-insensitive, and the default is `Development`. Secrets for each environment are stored in a separate JSON file in your user profile:
+
+```text title="Secrets file location"
+~/.aspire/secrets//.json
+```
+
+The `` is the AppHost's `UserSecretsId` when it has one; otherwise, Aspire derives an ID from the AppHost file path. Use [`aspire secret path`](../aspire-secret-path/) to print the exact file for an environment.
+
+When the AppHost runs, it loads the secrets file for its environment—for example, `Development` for `aspire run`, or `Production` for `aspire publish`, `aspire deploy`, and `aspire do` unless you pass a different `--environment`. Values that a deployment prompts for are saved to the same file. Secrets override `appsettings.json` values, while environment variables and command-line arguments still take precedence.
+
+:::note[Upgrading to Aspire 17?]
+The first time the `Development` environment is used, Aspire imports existing .NET user secrets into `Development.json` if that file doesn't exist. After that, `aspire secret` reads and writes only the Aspire secrets file. Set secrets for other environments with `--environment`.
+:::
+
## Options
The following options are available:
@@ -63,6 +79,12 @@ The following commands are available:
aspire secret set Parameters:postgres-password MySecretPassword123
```
+- Set a secret for the `Production` environment from an environment variable:
+
+ ```bash title="Aspire CLI"
+ aspire secret set Parameters:postgres-password --environment Production --envvar POSTGRES_PASSWORD
+ ```
+
- List all secrets for a specific AppHost:
```bash title="Aspire CLI"
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source.mdx
index 5d2146c570..e06048fed5 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-template-source.mdx
@@ -23,6 +23,42 @@ When at least one source is configured, the interactive [`aspire new`](../aspire
Template sources require the `aspire.config.json` configuration format. If your global configuration still uses the legacy format, these commands fail and direct you to run `aspire config info` to migrate it.
+### Source display names
+
+In the `aspire new` picker, each source's templates are grouped under a heading that defaults to the source name. To show a friendlier heading, set the optional `displayName` key for the source:
+
+```bash title="Aspire CLI"
+aspire config set templateSources.company.displayName "Company templates" --global
+```
+
+The source name remains the source's identity, so sources with identical display names aren't merged. An empty or whitespace-only `displayName` falls back to the source name.
+
+### Project-derived prompt defaults
+
+Template authors can show a project-derived value as the default in an `aspire new` prompt. In the template's `.template.config/aspirecli.host.json` file (or `dotnetcli.host.json` if the Aspire-specific file doesn't exist), set `defaultValueSource` on an optional string parameter to the name of the `coalesce` symbol that consumes it:
+
+```json title=".template.config/aspirecli.host.json"
+{
+ "symbolInfo": {
+ "displayName": { "defaultValueSource": "displayNameValue" }
+ }
+}
+```
+
+```json title=".template.config/template.json (symbols)"
+{
+ "displayName": { "type": "parameter", "datatype": "string", "defaultValue": "" },
+ "displayNameValue": {
+ "type": "generated",
+ "generator": "coalesce",
+ "parameters": { "sourceVariableName": "displayName", "fallbackVariableName": "name" },
+ "replaces": "DISPLAY_NAME"
+ }
+}
+```
+
+With this configuration, the `displayName` prompt shows the project name as its default. The parameter must have an empty default, and its fallback can depend only on the project name through `regex` and `coalesce` symbols. Otherwise, `aspire new` reports an invalid prompt default.
+
## Options
The following options are available:
diff --git a/src/frontend/src/content/docs/reference/cli/configuration.mdx b/src/frontend/src/content/docs/reference/cli/configuration.mdx
index 6da5737874..291d3e964f 100644
--- a/src/frontend/src/content/docs/reference/cli/configuration.mdx
+++ b/src/frontend/src/content/docs/reference/cli/configuration.mdx
@@ -226,8 +226,7 @@ and their default values.
```
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:
+ Copy the key name exactly from `aspire config list --all`:
```bash title="Enable a user-scoped preview feature default"
aspire config set features. true --global
@@ -236,13 +235,9 @@ and their default values.
For example, consider the following that enables global support for Rust:
```bash title="Enable global Rust support"
- aspire config set features.experimentalPolyglot:rust true --global
+ aspire config set features.experimentalPolyglotRust 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 `.
diff --git a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md
index 92722f16a0..95e6cf0c39 100644
--- a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md
+++ b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md
@@ -11,9 +11,9 @@ title: Config Settings Table
| `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: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.experimentalPolyglotJava` | `false` | Enable or disable experimental Java AppHost support. |
+| `features.experimentalPolyglotPython` | `false` | Enable or disable experimental Python AppHost support. |
+| `features.experimentalPolyglotRust` | `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`. |
@@ -30,8 +30,6 @@ title: Config Settings Table
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:
+`aspire config set` treats every `.` and `:` in a key as a nesting separator, so it can't write keys whose names contain those characters. Package IDs such as `Aspire.Hosting.Redis` contain dots, so use `aspire add` to add packages, or edit the `packages` object by hand.
-- 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:rust": 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.
:::
diff --git a/src/frontend/src/content/docs/whats-new/aspire-17.mdx b/src/frontend/src/content/docs/whats-new/aspire-17.mdx
index 11c1af9163..ae4f8f44e6 100644
--- a/src/frontend/src/content/docs/whats-new/aspire-17.mdx
+++ b/src/frontend/src/content/docs/whats-new/aspire-17.mdx
@@ -3,8 +3,8 @@ title: "What's new in Aspire 17.0"
seoTitle: 'Aspire 17.0: New features, updates, and upgrade guidance'
description: 'Aspire 17.0 brings a redesigned dashboard, generally available Go AppHosts, a tray companion, stable Kubernetes deployment, and dozens of graduated APIs.'
resourceImage:
- light: '~/assets/whats-new/aspire-17/testshop-all-resources-light.png'
- dark: '~/assets/whats-new/aspire-17/testshop-all-resources.png'
+ light: '~/assets/whats-new/aspire-17/dashboard-overview-light.png'
+ dark: '~/assets/whats-new/aspire-17/dashboard-overview.png'
sidebar:
label: Aspire 17.0
order: 0
@@ -26,7 +26,7 @@ This release introduces:
- A CLI that adds shell completion, environment-specific secrets, team template, integration, and skill sources, plus a preview tray companion.
- Generally available Go AppHosts with templates, debugging, `aspire doctor` checks, and SDK export.
- AppHost updates including optional parameters, browser-origin references, TypeScript Azure Functions, and graduated APIs.
-- New Microsoft Entra ID and Azure API Management integrations.
+- New Microsoft Entra ID and Azure API Management integrations, plus Azure AI client packages built on the OpenAI SDK.
- Stable Kubernetes deployment with Helm 4, AKS Standard tier and OS SKU selection, and cert-manager External Account Binding.
- Integration updates for Azure Web PubSub, Azure Service Bus, Redis output caching, and Deno.
- Updated default container images, including MongoDB `9.0`, PostgreSQL `18.6`, and Redis `8.10`.
@@ -71,8 +71,12 @@ Once Aspire 17.0 is available on the stable channel, use the [`aspire update` co
import ThemeImage from '@components/ThemeImage.astro';
import testShopDashboard from '@assets/whats-new/aspire-17/testshop-dashboard.png';
import testShopDashboardLight from '@assets/whats-new/aspire-17/testshop-dashboard-light.png';
-import testShopAllResources from '@assets/whats-new/aspire-17/testshop-all-resources.png';
-import testShopAllResourcesLight from '@assets/whats-new/aspire-17/testshop-all-resources-light.png';
+import dashboardHome from '@assets/whats-new/aspire-17/dashboard-home.png';
+import dashboardHomeLight from '@assets/whats-new/aspire-17/dashboard-home-light.png';
+import dashboardOverview from '@assets/whats-new/aspire-17/dashboard-overview.png';
+import dashboardOverviewLight from '@assets/whats-new/aspire-17/dashboard-overview-light.png';
+import dashboardMetrics from '@assets/whats-new/aspire-17/dashboard-metrics.png';
+import dashboardMetricsLight from '@assets/whats-new/aspire-17/dashboard-metrics-light.png';
import testShopResource from '@assets/whats-new/aspire-17/testshop-resource.png';
import testShopResourceLight from '@assets/whats-new/aspire-17/testshop-resource-light.png';
import testShopTraces from '@assets/whats-new/aspire-17/testshop-traces.png';
@@ -82,8 +86,6 @@ import testShopTracesLight from '@assets/whats-new/aspire-17/testshop-traces-lig
Keep the resources you're investigating in view as you move between logs, traces, and metrics. The redesigned dashboard adds a shared resource pane with search, filters, and multi-selection, plus grouping by tags, resource type, or state.
-Metrics appear as cards with live sparklines. Pin instruments you want to return to instead of finding them again in the full instrument list.
-
The new experience is still evolving. You can switch to the previous dashboard from **Settings** when the previous experience is available in your dashboard distribution.
@@ -91,14 +93,32 @@ The new experience is still evolving. You can switch to the previous dashboard f
telemetry, and dashboard actions.
+### Resource table home page
+
+The dashboard opens to a full-width table of every resource. Select a row, **All resources**, or a tab to drill in. Select the application name in the header to return to the table. Error badges in the resource list now open that resource's structured logs filtered to errors.
+
+
+
+Resources also show friendly type labels such as **Redis** or **PostgreSQL Server** in the dashboard and in the **Type** column of `aspire describe`.
+
+
+ See [Filter and group
+ resources](/dashboard/explore/#filter-and-group-resources) to focus the
+ dashboard on the resources you're investigating.
+
+
### All resources
-Start with **All resources** to check resource states, incoming request rates, and the slowest endpoints. TestShop's overview below includes real catalog browsing, sample checkouts, and activity-generator traffic.
+Open **All resources** for a health summary of your whole app: resource states, live request activity, error rate, p95 latency, the slowest endpoints, and the busiest resources. Select **View all** to open recent errors or failed traces.
### Resource graph
@@ -131,17 +151,15 @@ Expand a trace to see the time spent in each service and dependency. This trace
alt="A populated TestShop trace waterfall in Aspire 17.0, with ten nested spans covering frontend, catalog, PostgreSQL, basket, and Redis calls."
/>
-### Resource table home page
+### Metrics
-The dashboard opens to a full-width table of every resource. Select a row, **All resources**, or a tab to drill in. Select the application name in the header to return to the table. Error badges in the resource list now open that resource's structured logs filtered to errors.
-
-Resources also show friendly type labels such as **Redis** or **PostgreSQL Server** in the dashboard and in the **Type** column of `aspire describe`.
+Metrics appear as cards with live sparklines. Group instruments by resource, meter, or instrument, and pin the ones you want to return to instead of finding them again in the full instrument list. Collapse the resource list to give the cards more room.
-
- See [Filter and group
- resources](/dashboard/explore/#filter-and-group-resources) to focus the
- dashboard on the resources you're investigating.
-
+
### Terminals page
@@ -332,6 +350,8 @@ Stop it with `aspire tray stop`. The tray companion requires a native Aspire CLI
- **Container tunnel base image**: Use a mirrored or customized tunnel image with `aspire config set containerTunnel.baseImage `.
- **Stricter `aspire destroy`**: The command rejects unknown arguments instead of ignoring them.
- **Clearer publish guidance**: `dotnet run --operation publish` fails fast and directs you to `aspire publish`.
+- **Exit codes in `aspire describe`**: The table output shows the exit code of finished resources and highlights nonzero codes.
+- **SDK migration hint**: When `aspire update --migrate` finds nothing to migrate automatically but your AppHost still uses `Aspire.AppHost.Sdk`, it points you to the [ASPIRE012 migration steps](#aspireapphostsdk-is-deprecated).
## 🐹 Go AppHost support
@@ -443,7 +463,7 @@ When you deploy, Docker Compose, Kubernetes, and Radius publishers turn these va
### Hosting integrations written in TypeScript
-You can now author hosting integrations in TypeScript and consume them from polyglot AppHosts, starting with the preview `@aspire/nuxt` package.
+You can now author hosting integrations in TypeScript and consume them from polyglot AppHosts, starting with the preview `@aspire/nuxt` package. See [TypeScript hosting integrations](/extensibility/typescript-hosting-integrations/) to opt in, author, and consume one.
### AppHost Server v2 (preview)
@@ -481,7 +501,7 @@ The following APIs are stable starting with Aspire 17.0 and no longer report the
| [ASPIREPROBES001](/diagnostics/aspireprobes001/) | `WithHttpProbe`, `ProbeType`, and related probe types |
| [ASPIREUSERSECRETS001](/diagnostics/aspireusersecrets001/) | `IUserSecretsManager` and `IDistributedApplicationBuilder.UserSecretsManager` |
-`ASPIRECOMPUTE002` still applies to the Kubernetes persistent volume APIs, but the compute environment endpoint-mapping contracts `GetHostAddressExpression` and `GetEndpointPropertyExpression` no longer report it. `ASPIRECSHARPAPPS001` is also retired because `AddCSharpApp` is now marked `[Obsolete]` and reports `CS0618` instead.
+`ASPIRECOMPUTE002` still applies to the Kubernetes persistent volume APIs, but the compute environment endpoint-mapping contracts `GetHostAddressExpression` and `GetEndpointPropertyExpression` no longer report it. Likewise, `WithTerminal` and `TerminalOptions` no longer report `ASPIRETERMINAL001`, while AppHost-owned terminals, `TerminalService`, and the terminal automation APIs remain experimental. TypeScript AppHosts can also pass a callback to `withTerminal` to set the terminal's columns and rows. `ASPIRECSHARPAPPS001` is also retired because `AddCSharpApp` is now marked `[Obsolete]` and reports `CS0618` instead.
See the [diagnostics overview](/diagnostics/overview/) for the full list of
@@ -496,6 +516,7 @@ The following APIs are stable starting with Aspire 17.0 and no longer report the
- **Idempotent bind mounts**: Repeating an identical `WithBindMount` call is a no-op, and a conflicting target throws.
- **`*.localhost` in containers**: Container references to `*.localhost` hosts are remapped so they resolve inside the container.
- **Interaction availability**: `IInteractionService.IsAvailable` returns `false` during `BeforeStart`, before the dashboard can show prompts.
+- **Blazor Gateway CLI**: During `aspire run`, standalone Blazor WebAssembly apps added with `AddBlazorGateway` are served by the official ASP.NET Core Blazor Gateway CLI, which Aspire runs through `dotnet tool exec`. The first run needs access to a NuGet feed that provides `Microsoft.AspNetCore.Components.Gateway.Cli`.
### `Aspire.AppHost.Sdk` is deprecated
@@ -503,6 +524,21 @@ C# AppHosts that use the `Aspire.AppHost.Sdk` MSBuild SDK now get warning `ASPIR
## ✨ New integrations
+### Azure AI client packages
+
+Two new client integrations replace `Aspire.Azure.AI.OpenAI` and `Aspire.Azure.AI.Inference`, which are discontinued:
+
+- `Aspire.Azure.AI.Extensions.OpenAI` registers an `OpenAIClient` from the standard OpenAI SDK. Use `AddAzureOpenAIClient` for Azure OpenAI and Foundry model deployments, or `AddAzureProjectOpenAIClient` to call a Foundry project, including its agents.
+- `Aspire.Azure.AI.Projects` registers an `AIProjectClient` with `AddAzureAIProjectClient` for managing a Foundry project.
+
+```csharp title="Program.cs"
+builder.AddAzureOpenAIClient(connectionName: "chat");
+```
+
+
+ See [Connect to Azure OpenAI](/integrations/cloud/azure/azure-openai/azure-openai-connect/) and [Connect to Microsoft Foundry](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/) for registration, configuration, and migration steps.
+
+
### Microsoft Entra ID
Model application registrations alongside the services that use them with the new preview `Aspire.Hosting.Azure.EntraId` integration. You can provision registrations and service principals, or reference registrations you already manage.
@@ -549,12 +585,14 @@ Azure Front Door can connect to Aspire-provisioned Azure Container Apps and App
- **External account binding**: Use ACME providers that require external account binding (EAB) by calling `WithExternalAccountBinding` after `WithAcmeServer`. The HMAC key must be a secret parameter, and it isn't written to published artifacts.
- **File-based environment variables**: Generated manifests support Kubernetes `fileKeyRef` environment variable sources.
+- **Persistent volume claims**: Customize the generated `PersistentVolumeClaim` with `WithConfiguration`, or claim an existing volume with `WithPersistentVolumeName` and `WithoutStorageClass`. These APIs remain experimental and report `ASPIRECOMPUTE002`. See [Persistent volumes](/deployment/kubernetes/persistent-volumes/).
- **Container registries in Helm charts**: Published charts honor the container registry configured for each image. See [Configure a container registry](/deployment/kubernetes/clusters/#configure-a-container-registry).
- **Structured manifest fields**: Polyglot AppHosts can pass structured values to `withField` when customizing Kubernetes manifests.
### More deployment improvements
- **Dashboard telemetry**: Dashboards in generated Docker Compose files and Helm charts opt out of dashboard usage telemetry with `ASPIRE_DASHBOARD_TELEMETRY_OPTOUT=true`. Your application's OpenTelemetry data isn't affected. See [Deployed dashboards](/dashboard/microsoft-collected-dashboard-telemetry/#deployed-dashboards) for the opt-out policy.
+- **Front Door endpoint IDs**: `AzureFrontDoorResource.GetEndpointId` returns an origin endpoint's Azure resource ID, which Azure DNS alias records for apex domains require.
- **Registry cleanup**: The Azure Container Registry `WithPurgeTask` also deletes untagged manifests. See [Schedule image cleanup with purge tasks](/integrations/cloud/azure/azure-container-registry/azure-container-registry-host/#schedule-image-cleanup-with-purge-tasks) to configure cleanup. Thanks to @codebytes for this improvement.
@@ -624,18 +662,31 @@ MongoDB moves to a new major version. Review the MongoDB 9.0 release notes befor
-| Change | Migration |
-| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `ResourceUrlAnnotation.DisplayOrder` changed from a field to a property | Rebuild assemblies that use the field. |
-| Legacy `Aspire.RabbitMQ.Client.v6` and `Aspire.MongoDB.Driver.v2` packages removed | Switch to `Aspire.RabbitMQ.Client` and `Aspire.MongoDB.Driver`, and migrate to the 7.x and 3.x client libraries. |
-| Azure Cosmos DB `configureClientOptions` now receives `IServiceProvider` | Add the service-provider parameter to callbacks and rebuild binaries that call these methods. |
-| Docker Swarm `UpdateConfig.MaxFailureRatio` changed from `string?` to `double?` | Assign a number such as `0.3` instead of a string such as `"0.3"`. |
-| `AddCSharpApp` is obsolete and reports `CS0618` instead of `ASPIRECSHARPAPPS001` | Add `Aspire.Hosting.Dotnet` and replace calls with `AddDotnetProject`. |
+| Change | Migration |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `ResourceUrlAnnotation.DisplayOrder` changed from a field to a property | Rebuild assemblies that use the field. |
+| Legacy `Aspire.RabbitMQ.Client.v6` and `Aspire.MongoDB.Driver.v2` packages removed | Switch to `Aspire.RabbitMQ.Client` and `Aspire.MongoDB.Driver`, and migrate to the 7.x and 3.x client libraries. |
+| `Aspire.Azure.AI.OpenAI` and `Aspire.Azure.AI.Inference` packages discontinued | Switch to `Aspire.Azure.AI.Extensions.OpenAI` or `Aspire.Azure.AI.Projects`. |
+| Azure Cosmos DB `configureClientOptions` now receives `IServiceProvider` | Add the service-provider parameter to callbacks and rebuild binaries that call these methods. |
+| Docker Swarm `UpdateConfig.MaxFailureRatio` changed from `string?` to `double?` | Assign a number such as `0.3` instead of a string such as `"0.3"`. |
+| `AddCSharpApp` is obsolete and reports `CS0618` instead of `ASPIRECSHARPAPPS001` | Add `Aspire.Hosting.Dotnet` and replace calls with `AddDotnetProject`. |
+| `Aspire.AppHost.Sdk` is obsolete (`ASPIRE012`) | Switch to `Microsoft.NET.Sdk` with explicit Aspire package references. |
+| `TerminalOptions.ShowTerminalHost` removed | Remove the assignment; terminal hosts are always hidden. |
+| Polyglot feature keys renamed | Use `experimentalPolyglotJava`, `experimentalPolyglotPython`, or `experimentalPolyglotRust`; Go needs no flag. |
+| Let's Encrypt cert-manager shortcuts removed | Call `WithAcmeServer` with the ACME directory URL. |
+| AKS clusters use user-assigned identities | Plan for node pool updates and reapply custom permissions. |
+| Polyglot `addNodePool` takes a callback | Configure the node pool in a callback instead of an options object. |
+| SQL Server REPL no longer discovers older `sqlcmd` paths | Select `SqlServerReplCommand.Version17` for images with only the older client. |
+| OpenTelemetry 1.18 halves the default maximum OTLP request size to 64 MiB | Set `OtlpExporterOptions.MaxRequestSizeBytes` if your app exports larger batches. |
+| Required parameters reject empty values | Supply a nonempty value, or mark the parameter optional with `AsOptional` when an empty value is valid. |
+
### `ResourceUrlAnnotation.DisplayOrder` is now a property
`DisplayOrder` changed from an obsolete public field to a read/write property. Its behavior is unchanged: higher values display higher in the dashboard URL list.
-Rebuild assemblies that access the field. Typical C# reads and assignments need no changes.
+Rebuild assemblies that access the field: binaries compiled against an earlier version throw `MissingFieldException` until they're rebuilt. Hosting integration authors who set `DisplayOrder`, for example in a `WithUrlForEndpoint` callback, need to ship a version built against Aspire 17.0.
+
+Typical C# reads, assignments, and object initializers need no changes, and you can remove `CS0618` suppressions that existed only for `DisplayOrder`. Passing `DisplayOrder` by `ref` or `out` no longer compiles; use a local variable and assign it to the property. Reflection code must use `Type.GetProperty` instead of `Type.GetField`.
### Legacy RabbitMQ and MongoDB client packages removed
@@ -658,6 +709,17 @@ The service registration calls, `AddRabbitMQClient` and `AddMongoDBClient`, rema
current client setup guidance.
+### Azure AI OpenAI and Inference client packages discontinued
+
+Starting in Aspire 17.0, new releases no longer include `Aspire.Azure.AI.OpenAI` or `Aspire.Azure.AI.Inference`. Previously published versions remain available on NuGet.
+
+| Discontinued package | Replacement |
+| ---------------------------- | ---------------------------------------------------------------------------------------------- |
+| `Aspire.Azure.AI.OpenAI` | `Aspire.Azure.AI.Extensions.OpenAI`, which registers an `OpenAIClient` instead of `AzureOpenAIClient` |
+| `Aspire.Azure.AI.Inference` | `Aspire.Azure.AI.Extensions.OpenAI` for chat and embeddings, or `Aspire.Azure.AI.Projects` for `AIProjectClient` |
+
+Update code that resolves `AzureOpenAIClient` or Azure AI Inference clients. See [Migrate from Aspire.Azure.AI.OpenAI](/integrations/cloud/azure/azure-openai/azure-openai-connect/#migrate-from-aspireazureaiopenai) and [Migrate from Aspire.Azure.AI.Inference or Aspire.Azure.AI.OpenAI](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/#migrate-from-aspireazureaiinference-or-aspireazureaiopenai) for method mappings.
+
### Azure Cosmos DB client options callback receives a service provider
The `configureClientOptions` parameter on the Azure Cosmos DB client integration now has the type `Action` instead of `Action`. This change applies to the client, container, and database registration methods, including their keyed variants.
@@ -673,7 +735,7 @@ builder.AddAzureCosmosClient(
});
```
-The callback runs when the `CosmosClient` is first resolved from dependency injection, not during service registration. An exception in the callback therefore occurs when the client is resolved. Rebuild applications compiled against an earlier version: calls to these methods from older binaries throw `MissingMethodException`, even when they don't pass a callback.
+The callback runs when the `CosmosClient` is first resolved from dependency injection, not during service registration. An exception in the callback therefore occurs when the client is resolved. Similarly, `AddKeyedContainer` on a database builder no longer creates the `CosmosClient` during registration, so missing connection information is reported when the container is first resolved. Rebuild applications compiled against an earlier version: calls to these methods from older binaries throw `MissingMethodException`, even when they don't pass a callback.
### Docker Swarm `MaxFailureRatio` now requires a number
@@ -705,3 +767,87 @@ builder.AddDotnetProject("api", "./api/api.cs");
[microsoft/aspire#20825](https://github.com/microsoft/aspire/pull/20825).
+### `Aspire.AppHost.Sdk` is obsolete
+
+Projects that use `Aspire.AppHost.Sdk` get warning `ASPIRE012`. Follow the migration steps in [`Aspire.AppHost.Sdk` is deprecated](#aspireapphostsdk-is-deprecated), or temporarily set `SuppressAspireAppHostSdkObsoleteWarning` to `true`.
+
+### `TerminalOptions.ShowTerminalHost` removed
+
+Terminal host resources are always hidden from the dashboard, so the `ShowTerminalHost` option was removed. Delete any assignments to it.
+
+### Polyglot feature keys renamed
+
+The experimental polyglot feature flags no longer use a colon-separated suffix. Update `aspire.config.json` and any `aspire config set` scripts:
+
+| Before | After |
+| ----------------------------- | ---------------------------- |
+| `experimentalPolyglot:java` | `experimentalPolyglotJava` |
+| `experimentalPolyglot:go` | Remove the flag |
+| `experimentalPolyglot:python` | `experimentalPolyglotPython` |
+| `experimentalPolyglot:rust` | `experimentalPolyglotRust` |
+
+Go AppHosts no longer need a feature flag.
+
+### Let's Encrypt cert-manager shortcuts removed
+
+`WithLetsEncryptProduction` and `WithLetsEncryptStaging` were removed, along with the `WithAcmeServer` overload that mixed a literal server URL with a parameter email. Call `WithAcmeServer` with the ACME directory URL and contact email, using either two literals or two parameters. For Let's Encrypt production, the directory URL is `https://acme-v02.api.letsencrypt.org/directory`.
+
+### AKS clusters use user-assigned identities
+
+Aspire-provisioned AKS clusters now use separate user-assigned identities for the control plane and kubelet. When you redeploy an existing cluster, Azure may update its node pools, which can disrupt running workloads. Permissions you granted manually to the previous identities aren't transferred; grant them to the new identities.
+
+### Polyglot `addNodePool` takes a callback
+
+In polyglot AppHosts, `addNodePool` configures the pool through a callback instead of an options object. C# AppHosts are unchanged.
+
+
+
+
+```typescript title="apphost.mts"
+await aks.addNodePool('workers', async (pool) => {
+ pool.osSku = 'AzureLinux';
+});
+```
+
+
+
+
+```go title="apphost.go"
+aks.AddNodePool("workers", func(pool *aspire.AksNodePoolConfig) {
+ pool.OsSku = aspire.StringPtr("AzureLinux")
+})
+```
+
+
+
+
+Python AppHosts use camelCase keys for node pool settings.
+
+### SQL Server REPL no longer discovers older `sqlcmd` paths
+
+The SQL Server dashboard REPL now launches `/opt/mssql-tools18/bin/sqlcmd` directly. For images that only include the older `/opt/mssql-tools/bin/sqlcmd` client, use `WithRepl` to set the REPL options' `Command` to `SqlServerReplCommand.Version17`.
+
+The default image and parameterless `WithRepl` call are unaffected.
+
+### Default maximum OTLP request size is 64 MiB
+
+Aspire 17.0 updates its OpenTelemetry dependencies to 1.18, and new ServiceDefaults projects reference the same versions. OpenTelemetry 1.18 lowers the OTLP exporter's default maximum request size from 128 MiB to 64 MiB, and drops a batch that exceeds the limit. Existing ServiceDefaults projects keep their package versions until you update them.
+
+If your app exports very large telemetry batches, restore the previous limit in your ServiceDefaults project:
+
+```csharp title="Extensions.cs"
+builder.Services.Configure(options =>
+ options.MaxRequestSizeBytes = 128 * 1024 * 1024);
+```
+
+### Required parameters reject empty values
+
+Parameters are required by default, and in Aspire 17.0 an explicit empty string no longer satisfies a required value. This applies to ordinary, secret, and connection-string parameters.
+
+- Supply a nonempty value. During `aspire run`, a missing or empty required value puts the parameter in the `ValueMissing` state, and the dashboard prompts for it. Without dashboard interaction, initialization fails with a `MissingParameterValueException` that names the parameter.
+- Mark a parameter optional only when an empty or absent value is valid. Call `AsOptional()` in C# and Go, or `asOptional()` in TypeScript. An explicitly configured empty optional value stays `""`, and an unset optional value resolves to `null` and is omitted from environment variables. Don't make required credentials optional just to avoid the check.
+- The manifest publisher doesn't support optional parameters, so supply values for required deployment parameters instead.
+
+
+ See [Optional parameters](/fundamentals/external-parameters/#optional-parameters) for required and optional parameter behavior.
+
diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json
index 232240ee47..21451c88b9 100644
--- a/src/frontend/src/data/integration-docs.json
+++ b/src/frontend/src/data/integration-docs.json
@@ -1,4 +1,8 @@
[
+ {
+ "match": "Aspire.Azure.AI.Extensions.OpenAI",
+ "href": "/integrations/cloud/azure/azure-openai/azure-openai-get-started/"
+ },
{
"match": "Aspire.Azure.AI.Inference",
"href": "/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started/"
@@ -7,6 +11,10 @@
"match": "Aspire.Azure.AI.OpenAI",
"href": "/integrations/cloud/azure/azure-openai/azure-openai-get-started/"
},
+ {
+ "match": "Aspire.Azure.AI.Projects",
+ "href": "/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/"
+ },
{
"match": "Aspire.Azure.Data.Tables",
"href": "/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started/"
diff --git a/src/frontend/tests/unit/typescript-apphost-sdk-imports.vitest.test.ts b/src/frontend/tests/unit/typescript-apphost-sdk-imports.vitest.test.ts
index f06afbb7ff..13dde875e2 100644
--- a/src/frontend/tests/unit/typescript-apphost-sdk-imports.vitest.test.ts
+++ b/src/frontend/tests/unit/typescript-apphost-sdk-imports.vitest.test.ts
@@ -5,6 +5,8 @@ import { describe, expect, test } from 'vitest';
const frontendRoot = join(import.meta.dirname, '../..');
const docsRoot = join(frontendRoot, 'src/content/docs');
const currentSdkImport = './.aspire/modules/aspire.mjs';
+// Files nested in a package, such as src/integration.ts, reach the same layout through ../.
+const currentSdkLayout = /^(?:\.\/|(?:\.\.\/)+)\.aspire\/modules\/aspire\.mjs$/;
function docs(directory: string, files: string[] = []) {
for (const entry of readdirSync(directory, { withFileTypes: true })) {
@@ -36,7 +38,7 @@ function legacySdkImports(source: string) {
for (const [, specifier] of fence.body.matchAll(
/\bfrom\s+['"]([^'"]*modules\/aspire\.m?js)['"]/g
)) {
- if (specifier !== currentSdkImport) problems.push(`line ${fence.line}: ${specifier}`);
+ if (!currentSdkLayout.test(specifier)) problems.push(`line ${fence.line}: ${specifier}`);
}
if (fence.body.includes(currentSdkImport) && /title="[^"]*\bapphost\.ts\b/.test(fence.info)) {
problems.push(`line ${fence.line}: title names apphost.ts`);
@@ -57,6 +59,9 @@ describe('TypeScript AppHost SDK imports', () => {
'```typescript title="apphost.mts"',
"import { createBuilder } from './.aspire/modules/aspire.mjs';",
'```',
+ '```typescript title="src/integration.ts"',
+ "import type { DistributedApplicationBuilder } from '../.aspire/modules/aspire.mjs';",
+ '```',
].join('\n');
expect(legacySdkImports(source)).toEqual([