diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-6.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-6.mdx index 6b648f80d..158d90749 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-6.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-6.mdx @@ -37,18 +37,14 @@ We'd love to hear what you think. Drop by [ -These APIs use `ASPIRETERMINAL001`. An AppHost-owned terminal belongs to its creator: closing a viewer isn't a general substitute for disposing the terminal, and stopping the AppHost stops its owned terminals. Resource terminals configured with `WithTerminal` remain separate from AppHost-owned dock tabs. +These APIs use `ASPIRETERMINAL001`. An AppHost-owned terminal belongs to its creator: closing a viewer isn't a general substitute for disposing the terminal, and stopping the AppHost stops its owned terminals. Resource terminals configured with `WithTerminal` remain separate from AppHost-owned dock tabs. For example, the following AppHost gives a Python REPL its own resource terminal: + + + + +```typescript title="apphost.mts" twoslash +import { createBuilder } from './.aspire/modules/aspire.mjs'; + +const builder = await createBuilder(); + +await builder + .addExecutable('repl', 'python3', '.', ['-i', '-q']) + .withTerminal(); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +#pragma warning disable ASPIRETERMINAL001 +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddExecutable("repl", "python3", ".", "-i", "-q") + .WithTerminal(); + +builder.Build().Run(); +``` + + + #### Database and cache REPLs -Opt into `WithRepl` / `withRepl` on [PostgreSQL](/integrations/databases/postgres/postgres-host/#add-postgresql-resource-with-a-repl-command), [MySQL](/integrations/databases/mysql/mysql-host/#add-mysql-resource-with-a-repl-command), [MongoDB](/integrations/databases/mongodb/mongodb-host/#add-mongodb-resource-with-a-repl-command), [SQL Server](/integrations/databases/sql-server/sql-server-host/#add-sql-server-resource-with-a-repl-command), [Redis](/integrations/caching/redis/redis-host/#add-redis-resource-with-a-repl-command), or [Valkey](/integrations/caching/valkey/valkey-host/#add-valkey-resource-with-a-repl-command) to open the container's bundled client from a **REPL** dashboard command. No local database client installation is needed. +Opt into `WithRepl` / `withRepl` on [PostgreSQL](/integrations/databases/postgres/postgres-host/#open-an-interactive-repl), [MySQL](/integrations/databases/mysql/mysql-host/#open-an-interactive-repl), [MongoDB](/integrations/databases/mongodb/mongodb-host/#open-an-interactive-repl), [SQL Server](/integrations/databases/sql-server/sql-server-host/#open-an-interactive-repl), [Redis](/integrations/caching/redis/redis-host/#open-an-interactive-repl), or [Valkey](/integrations/caching/valkey/valkey-host/#open-an-interactive-repl) to open the container's bundled client from a **REPL** dashboard command. No local database client installation is needed. + + + + +```typescript title="apphost.mts" twoslash +import { createBuilder } from './.aspire/modules/aspire.mjs'; + +const builder = await createBuilder(); + +await builder.addRedis('cache').withRepl(); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddRedis("cache").WithRepl(); + +builder.Build().Run(); +``` + + + REPL commands are run-only and disabled unless you opt in. They use the resource's actual credentials and aren't read-only, so enable them only for trusted dashboard users. Exit the client explicitly before closing its terminal tab; closing the viewer alone can leave the client process running inside the container. - See [resource terminals](/app-host/with-terminal/) and the [AppHost-owned - terminal - lifecycle](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/docs/specs/with-terminal.md#apphost-owned-terminals). + See [resource terminals](/app-host/with-terminal/) and [interactive terminals + in the dashboard](/dashboard/explore/#interactive-terminals). #### More telemetry and independent dashboard sessions @@ -172,32 +225,106 @@ Other dashboard improvements include: [dashboard security considerations](/dashboard/security-considerations/). +#### Native AOT standalone dashboard and refreshed UI + +The standalone dashboard now publishes and runs as a **Native AOT** executable, shipping as a self-contained, dedicated bundle instead of routing through the managed `dashboard` subcommand. Existing `aspire dashboard run`, AppHost startup, and CLI profile-capture workflows select the right dashboard automatically, and older AppHosts keep a managed fallback, so no command-line changes are required. + +The dashboard also moves to **Fluent UI Blazor v5**. Resources, console logs, structured logs, traces, and metrics keep the same workflows, and the desktop navigation becomes a collapsible rail that you can expand to show page labels or collapse to icons. Your choice of mode persists across reloads. + ## ✨ New integrations Aspire 13.6 adds first-party hosting integrations for Java, Rust, Azure Connector Namespace, and Azure Container Apps Sandboxes. Java and Rust build on implementations that originated in the Aspire Community Toolkit. +:::note[Prerelease packages] +`Aspire.Hosting.Java`, `Aspire.Hosting.Rust`, `Aspire.Hosting.Azure.ConnectorNamespace`, and `Aspire.Hosting.Azure.Sandboxes` ship as prerelease (`-preview`) packages in Aspire 13.6. Their APIs may change in future releases. +::: + #### ☕ Java The new `Aspire.Hosting.Java` package supports executable JARs, Maven and Gradle wrappers, Spring Boot, Quarkus, and prebuilt Java container images. It can detect the target Java release from Maven or Gradle, generate a multi-stage Dockerfile for publishing, attach the OpenTelemetry Java agent, and run both Java resources and Java AppHosts under the Visual Studio Code debugger. The generated container path uses the repository's Maven or Gradle wrapper rather than a machine-global tool, rejects paths outside the build context, and runs the application as a non-root user. + + + +```typescript title="apphost.mts" twoslash +import { createBuilder } from './.aspire/modules/aspire.mjs'; + +const builder = await createBuilder(); + +const catalog = await builder.addSpringBootApp('catalog', '../catalog'); +await catalog.withExternalHttpEndpoints(); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddSpringBootApp("catalog", "../catalog") + .WithExternalHttpEndpoints(); + +builder.Build().Run(); +``` + + + + +`AddSpringBootApp` / `addSpringBootApp` detect Maven or Gradle from the build file, build the app, and declare an HTTP endpoint through `SERVER_PORT`. Use `AddJavaApp`, `AddQuarkusApp`, or `AddJavaContainer` for other application shapes. + See [Java hosting and Toolkit migration](/integrations/frameworks/java/java-host/). + #### 🦀 Rust The new `Aspire.Hosting.Rust` package models Cargo applications through `AddRustApp` / `addRustApp`. Configure the Cargo binary target, arguments, and features independently from application arguments, then let Aspire generate a multi-stage Dockerfile for publish and deploy. Visual Studio Code can discover, run, and debug both Rust resources and `apphost.rs` AppHosts. + + + +```typescript title="apphost.mts" twoslash +import { createBuilder } from './.aspire/modules/aspire.mjs'; + +const builder = await createBuilder(); + +await builder + .addRustApp('api', '../rust-api') + .withHttpEndpoint({ env: 'PORT' }) + .withExternalHttpEndpoints(); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddRustApp("api", "../rust-api") + .WithHttpEndpoint(env: "PORT") + .WithExternalHttpEndpoints(); + +builder.Build().Run(); +``` + + + + The first-party package doesn't yet include the Community Toolkit integration's Bacon support. Custom build and runtime images also remain responsible for ABI and linker compatibility. See [Rust hosting and Toolkit migration](/integrations/frameworks/rust/rust-host/). -#### Azure Connector Namespace +#### 🔌 Azure Connector Namespace The preview `Aspire.Hosting.Azure.ConnectorNamespace` package lets you model connections to external services and expose selected operations through managed MCP server configurations. Configure explicit operation allow-lists and Microsoft Entra access policies in your AppHost rather than managing each connection separately. @@ -217,7 +344,7 @@ Use `PublishAsAzureSandbox` / `publishAsAzureSandbox` to choose one of five reso -```typescript title="apphost.mts" +```typescript title="apphost.mts" twoslash import { AzureSandboxAutoSuspendMode, AzureSandboxTier, @@ -280,10 +407,9 @@ Only endpoints marked external get a public HTTPS URL. Those URLs require Micros - Review the source changes for - [Java](https://github.com/microsoft/aspire/pull/18033), - [Rust](https://github.com/microsoft/aspire/pull/18906), and [Azure Container - Apps Sandboxes](https://github.com/microsoft/aspire/pull/19008). + See [Java hosting](/integrations/frameworks/java/java-host/), [Rust + hosting](/integrations/frameworks/rust/rust-host/), and [Deploy to Azure + Container Apps Sandboxes](/deployment/azure/sandboxes/). ## 🧩 App model and AppHost @@ -294,15 +420,44 @@ The `AddDotnetProject` / `addDotnetProject` APIs now coordinate compatible proje These resources also participate in .NET SDK container publishing. You can select launch profiles from either AppHost language and separate MSBuild inputs with `WithBuildEnvironment` / `withBuildEnvironment` from runtime environment variables. Build-only variables aren't supported for file-based apps and must not be used for secrets. + + + +```typescript title="apphost.mts" twoslash +import { createBuilder } from './.aspire/modules/aspire.mjs'; + +const builder = await createBuilder(); + +const api = await builder.addDotnetProject('api', '../Api/Api.csproj'); +await api.withBuildEnvironment('ContinuousIntegrationBuild', 'true'); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddDotnetProject("api", "../Api/Api.csproj") + .WithBuildEnvironment("ContinuousIntegrationBuild", "true"); + +builder.Build().Run(); +``` + + + + `AddDotnetProject`, `DotnetProjectResource`, and the related `WithBuildEnvironment` overloads no longer require `ASPIREDOTNETPROJECT001` suppression in 13.6. The package remains prerelease; the separate Dotnet project Blazor gateway retains its experimental diagnostics. Projects that depend on per-project restore hooks can opt into individual restore with `Aspire:Dotnet:RestoreProjectsIndividually` in the AppHost configuration. Aspire also enables MSBuild's multithreaded task execution (`-mt`) when the selected SDK supports it. Project and traversal builds require .NET SDK `11.0.100-rc.1` or later; file-based apps require `11.0.100-rtm.26473.104` or a stable `11.0.100` or later. Older or undetected SDKs keep the existing behavior. +To move an existing AppHost onto this model, the CLI bundles a Project V2 migration skill that guides AI coding agents through the conversion. + See [coordinated builds and - restore](/integrations/dotnet/project-resources/#coordinated-builds-and-restore) - and the [.NET hosting integration's publishing - guidance](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Dotnet/README.md#publishing). + restore](/integrations/dotnet/project-resources/#coordinated-builds-and-restore). #### Portable volume paths @@ -312,7 +467,7 @@ Applications often need a host filesystem path during local process execution an -```typescript title="apphost.mts" +```typescript title="apphost.mts" twoslash import { createBuilder } from './.aspire/modules/aspire.mjs'; const builder = await createBuilder(); @@ -360,7 +515,7 @@ TypeScript AppHosts now load the standard configuration stack from the directory Read the value through the generated builder API: -```typescript title="apphost.mts" +```typescript title="apphost.mts" twoslash import { createBuilder } from './.aspire/modules/aspire.mjs'; const builder = await createBuilder(); @@ -419,10 +574,16 @@ aspire sdk export --language typescript `aspire update` can update repository-local Aspire CLI references in npm and .NET tool manifests alongside AppHost packages, rather than replacing a globally installed CLI. For a lightweight C# AppHost, `aspire init --language csharp --file-based` creates `apphost.cs` in the current directory without discovering or modifying a solution. +A C# AppHost that enables the CLI bundle (`AspireUseCliBundle=true`) can also control which CLI `dotnet run` launches through `AspireCliInvocationMode`. With `Dnx`, the AppHost runs `Aspire.Cli` through DNX without a version, so DNX honors an in-scope `.config/dotnet-tools.json` manifest or selects the latest package when no manifest applies. With `DnxPinned`, it runs the `Aspire.Cli` version paired with the AppHost's `Aspire.AppHost.Sdk`, ignoring any tool manifest. + +The `aspire new` and `aspire init` agent setup also changed. Both now preselect the recommended repository-local skills, including `aspireify`, while leaving the Aspire MCP server unselected. MCP configuration is strictly opt-in. + On Linux, certificate trust now includes Firefox NSS databases. Use the global `certificates.nssDbPaths` setting when browser profiles live outside the auto-discovered locations. - See [Aspire certificate configuration](/app-host/certificate-configuration/). + See [Aspire certificate configuration](/app-host/certificate-configuration/) + and [running an AppHost with `dotnet + run`](/get-started/aspire-sdk/#running-with-dotnet-run). #### Terminal tape playback @@ -432,9 +593,8 @@ On Linux, certificate trust now includes Firefox NSS databases. Use the global ` Terminal CLI commands no longer require the `features.terminalCommandsEnabled` flag in 13.6. AppHosts still need the `terminals.v1` capability, and the terminal hosting APIs remain experimental. A tape can send input to a real process; only run scripts you trust. - See the [`aspire terminal` command](/reference/cli/commands/aspire-terminal/) - and [tape - playback](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/docs/specs/with-terminal.md#tape-playback). + See the [`aspire terminal` + command](/reference/cli/commands/aspire-terminal/). #### More predictable updates and resource observation @@ -472,6 +632,7 @@ The Aspire extension brings more of the development lifecycle into the Aspire pa - **Agent-driven AppHosts.** Coding agents can start and stop AppHosts through the extension's lifecycle tools instead of spawning an unrelated CLI process. - **Deployment actions where you work.** AppHost items expose **Deploy**, **Publish**, **Run pipeline step**, and **Debug pipeline step** alongside run actions. The pane also adds **Create with Aspire...** for creating an app or adding Aspire to the current workspace. - **Multi-root and worktree awareness.** The Aspire pane discovers AppHosts from every workspace root. AppHost lifecycle operations are scoped to the current git worktree, and launch arguments survive extension delegation. +- **Outdated-CLI warning.** When an extension operation uses an Aspire CLI that's behind its installed release lane, the extension surfaces a one-click **Update Aspire CLI** action that updates that exact executable. **Don't Show Again** suppresses the warning for that specific path and version. - **Cleaner debugging.** AppHost logs appear once in the debug console with log-level color, and resources show setup guidance when their Visual Studio Code debugger extension is missing. - **Fewer disruptive prompts.** The C# Dev Kit Hot Reload advisory appears at most once per workspace and can be disabled. Reloading Visual Studio Code no longer forces the Aspire view into focus or restores a hidden Activity Bar entry. - **More reliable sessions.** Closing the window stops extension-owned CLI processes, browser launch no longer blocks startup completion, and Azure Functions and browser-debugging lifecycles report exits accurately. @@ -535,10 +696,12 @@ Azure Container Apps environments can opt into the Express preview with `AsExpre Existing integrations add new workflows and safer defaults: -- **Deno hosting.** `Aspire.Hosting.JavaScript` adds `AddDenoApp` / `addDenoApp`, with task and serve modes, permission controls, and runtime flags. Deno must be installed for local execution. See [Deno hosting](/integrations/frameworks/deno/deno-host/). +- **Docked database and cache REPLs.** Opt into `WithRepl()` / `withRepl()` on PostgreSQL, Redis, Valkey, MongoDB, MySQL, and SQL Server resources to open an interactive client for the resource in the dashboard terminal dock, using bundled clients and the resource's configured credentials. It's run-mode only and leaves existing apps unchanged unless you enable it. See [Database and cache REPLs](#database-and-cache-repls). +- **Deno hosting.** `Aspire.Hosting.JavaScript` adds experimental `AddDenoApp` / `addDenoApp`, which runs a script from an app directory, with task and serve modes, permission controls, and runtime flags. These APIs report `ASPIREDENO001`, and Deno must be installed for local execution. The first-party API differs from the Community Toolkit's [Deno integration](/integrations/frameworks/deno/deno-host/). - **MongoDB replica sets.** Experimental `WithReplicaSet` / `withReplicaSet` configures and initializes a single-member replica set, enabling transactions and change streams after readiness. A separate `AddMongoDBReplicaSet` API supports multi-member local scenarios. Both paths are local-run-only and reject publishing; see [MongoDB replica sets](/integrations/databases/mongodb/mongodb-host/#enable-transactions-and-change-streams-with-a-single-member-replica-set). - **MongoDB automatic TLS.** Local MongoDB resources now use Aspire's shared certificate configuration, including standalone servers. Existing plaintext clients should review the [TLS migration guidance](#mongodb-now-uses-automatic-tls-during-local-runs). - **Microsoft Foundry Toolboxes.** `AddToolbox` / `addToolbox` bundles tools behind one MCP endpoint and manages immutable versions as tool configuration changes. MCP approval policies are discovery metadata that the consuming application must enforce. See the [Toolbox walkthrough](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#add-a-toolbox). +- **Remote Foundry Local services.** `RunAsFoundryLocal` / `runAsFoundryLocal` now accepts an endpoint, so an AppHost, including one on WSL2 or Linux, can observe a Foundry Local service already running on another host (for example, a Windows GPU box) without starting, stopping, or downloading models on it. The integration also handles the newer `foundry server` CLI generation. See [Connect to a remote Foundry Local service](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/#connect-to-a-remote-foundry-local-service). - **Blazor WebAssembly debugging.** Standalone and hosted WebAssembly apps can expose dashboard commands for starting and stopping an Edge or Chrome debugging session during local runs. The related Dotnet project gateway APIs are also available to polyglot AppHosts and participate in publishing, but remain experimental. See [Blazor gateway hosting](/integrations/dotnet/blazor-hosting/#add-a-blazor-gateway-for-a-c-project-resource). - **Dev Tunnel discovery and expiration.** Tunnel, inspect, and local endpoint URLs appear as highlighted resource properties, and a **Show tunnel URLs** command surfaces them through the dashboard Interaction Service. `WithExpiration` / `withExpiration` also configures idle expiration for new or reused tunnels, in whole hours from one hour through 30 days. - **Radius recipe configuration.** Experimental APIs configure recipe parameters and required secrets globally or per resource from the AppHost. The integration now recommends [Radius v0.60.2](https://github.com/radius-project/radius/releases/tag/v0.60.2); v0.60.0 remains the minimum supported control-plane version. @@ -554,6 +717,64 @@ Existing integrations add new workflows and safer defaults: - **Front Door origin identity.** Generated origin names now include the origin's backend hostname, so switching backends creates a distinct origin instead of reusing the previous origin's Azure identity. Review the [breaking-change guidance](#breaking-changes) before upgrading. - **GitHub Models integration removed.** [GitHub Models was retired for all customers on July 30, 2026](https://github.blog/changelog/2026-07-30-github-models-is-now-retired/). `Aspire.Hosting.GitHub.Models` was deprecated in Aspire 13.5 and its source, tests, and playground sample are removed from the repository in 13.6. The final `13.5.x` package stays published for apps that already reference it. `Aspire.Hosting.GitHub.Models` is hidden from `aspire add`. Migrate to the [Microsoft Foundry integration](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/); see [Migrate Aspire apps from GitHub Models](/integrations/ai/github-models/github-models-get-started/) for guidance. +The following AppHost combines two of these additions: a first-party Deno app that can only reach one host, and a Foundry Toolbox that a project references: + + + + +```typescript title="apphost.mts" twoslash +import { + createBuilder, + DenoPermissionKind, +} from './.aspire/modules/aspire.mjs'; + +const builder = await createBuilder(); + +const deno = await builder.addDenoApp('deno-api', '../deno-api', 'main.ts'); +await deno.withDenoAllow(DenoPermissionKind.Net, ['api.example.com']); + +const foundry = await builder.addFoundry('foundry'); +const project = await foundry.addProject('project'); +const toolbox = await project.addToolbox('field-tools'); +await toolbox.withWebSearchTool({ + name: 'web-search', + description: 'Search the public web.', +}); + +const api = await builder.addProject('api', '../Api/Api.csproj'); +await api.withReference(toolbox); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +using Aspire.Hosting.Foundry; +using Aspire.Hosting.JavaScript; + +var builder = DistributedApplication.CreateBuilder(args); + +#pragma warning disable ASPIREDENO001 +builder.AddDenoApp("deno-api", "../deno-api", "main.ts") + .WithDenoAllow(DenoPermissionKind.Net, "api.example.com"); +#pragma warning restore ASPIREDENO001 + +var toolbox = builder.AddFoundry("foundry") + .AddProject("project") + .AddToolbox("field-tools") + .WithWebSearchTool("web-search", "Search the public web."); + +builder.AddProject("api") + .WithReference(toolbox); + +builder.Build().Run(); +``` + + + +