Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
256 changes: 256 additions & 0 deletions src/frontend/src/content/docs/whats-new/aspire-17.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,262 @@ Once Aspire 17.0 is available on the stable channel, use the [`aspire update` co
CLI](/get-started/install-cli/).
</LearnMore>

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 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';
import testShopTracesLight from '@assets/whats-new/aspire-17/testshop-traces-light.png';

## 📊 Dashboard updates

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.

For the redesign and its ongoing feedback, see [microsoft/aspire#21412](https://github.com/microsoft/aspire/pull/21412).

### 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.

<ThemeImage
dark={testShopAllResources}
light={testShopAllResourcesLight}
alt="TestShop's All resources overview in Aspire 17.0, showing running resources, live request activity, and slowest endpoints."
/>

### Resource graph

Switch to the graph to see how TestShop's services and infrastructure are connected.

<ThemeImage
dark={testShopDashboard}
light={testShopDashboardLight}
alt="TestShop running in the Aspire 17.0 dashboard, with its resource list and dependency graph shown side by side."
/>

### Resource details

Select a resource to bring its health, endpoints, logs, and telemetry into one view. Here, `frontend` is the store used to browse the catalog and check out.

<ThemeImage
dark={testShopResource}
light={testShopResourceLight}
alt="TestShop's frontend resource in Aspire 17.0, showing healthy status, its store endpoint, console output, structured logs, and trace counts."
/>

### Distributed traces

Expand a trace to see the time spent in each service and dependency. This trace follows TestShop's activity generator through the frontend, catalog service, basket service, PostgreSQL, and Redis.

<ThemeImage
dark={testShopTraces}
light={testShopTracesLight}
alt="A populated TestShop trace waterfall in Aspire 17.0, with ten nested spans covering frontend, catalog, PostgreSQL, basket, and Redis calls."
/>

## 🛠️ CLI updates

### Shell completion

Complete Aspire commands and options in Bash, Fish, PowerShell, and Zsh. Generate a completion script with `aspire completions script`, specifying `bash`, `fish`, `pwsh`, or `zsh` when you want to select the shell explicitly.

For example, generate and load a Bash completion script for your current shell session:

```bash title="Aspire CLI — Generate Bash completions"
aspire completions script bash > aspire-completion.bash
source ./aspire-completion.bash
```

For installation details, see [microsoft/aspire#20026](https://github.com/microsoft/aspire/pull/20026).

### Environment-specific secrets

Keep deployment secrets separate by using `--environment` or `-e` with the `aspire secret` commands.

Run the secret commands from your AppHost directory. You can set a secret without putting its value in the command line: omit the value to enter it at a masked interactive prompt, or use `--envvar` to read an environment variable:

```bash title="Aspire CLI — Set a deployment secret from an environment variable"
aspire secret set Parameters:database-password --environment production --envvar DATABASE_PASSWORD
```

Set `DATABASE_PASSWORD` in your environment before running this command. Non-interactive calls must supply a value or `--envvar`; they don't open an input prompt.

For details, see [microsoft/aspire#20135](https://github.com/microsoft/aspire/pull/20135) and [microsoft/aspire#20984](https://github.com/microsoft/aspire/pull/20984).

### Custom templates, integrations, and skills

Bring your team's project scaffolding, hosting packages, and agent guidance into the Aspire CLI. Named sources let you reuse these across apps without replacing Aspire's built-in choices. Use sources you trust: templates and agent plugins can contain executable code.

#### Custom templates

Try templates directly from a Git repository without registering a source. For example, browse the Azure-focused templates in [Azure/aspire-templates](https://github.com/Azure/aspire-templates):

```bash title="Aspire CLI — Try Azure templates"
aspire new --template-repository https://github.com/Azure/aspire-templates
```

Fork the repository and customize a template for your team. Push your changes to a branch, then use `--template-repository-ref` to test it before merging:

```bash title="Aspire CLI — Test a template branch"
aspire new --template-repository https://github.com/example-org/aspire-templates \
--template-repository-ref custom-starter
```

Replace `example-org` with your fork's owner and `custom-starter` with your branch. The ref can also be a tag or full commit SHA; omitting it uses the repository's default branch. Use `--template-path` to select a directory within the repository.

When you want to reuse a source, add a persistent reference in your global Aspire settings:

```bash title="Aspire CLI — Save a template source"
aspire template source add azure --repository https://github.com/Azure/aspire-templates
aspire new
```

The CLI asks you to confirm that you trust the source before registering it. Use `--path` for a template directory within the repository and `--ref` to pin a branch, tag, or full commit SHA.

<LearnMore>
See [`aspire new`](/reference/cli/commands/aspire-new/) for project creation.
TODO: Add complete documentation for authoring templates and managing named template sources.
</LearnMore>

#### Custom integrations

Make your hosting integrations discoverable from a NuGet server. Add an `integrationSources` entry to `aspire.config.json`; optional package patterns limit which packages the source offers:

```json title="aspire.config.json — Discover team integrations"
{
"integrationSources": {
"team": {
"source": "https://nuget.example.com/v3/index.json",
"patterns": ["Team.Hosting.*"]
}
}
}
```

Replace the illustrative feed URL with your NuGet server's service index and publish your `Team.Hosting.*` packages there. Matching integrations appear in discovery and the `aspire add` picker. The built-in source remains enabled unless you set `integrationSources.default.enabled` to `false`.

<LearnMore>
See [Create hosting integrations](/integrations/custom-integrations/hosting-integrations/)
for integration authoring. TODO: Add complete documentation for named integration sources and package filtering.
</LearnMore>

#### Custom skills

Configure your team's agent plugins through `skillSources` in `aspire.config.json`. For example, point GitHub Copilot or Claude Code at your team's marketplace and select its plugin:

```json title="aspire.config.json — Configure a team plugin"
{
"skillSources": {
"team": {
"repository": "example-org/team-skills",
"marketplace": "team-skills",
"plugins": ["platform"]
}
}
}
```

Replace the repository, marketplace, and plugin names with your own. Run `aspire agent init --skills aspire` from your project to apply the enabled sources to your selected agents. OpenCode uses skill catalog URLs instead of marketplace plugins.

<LearnMore>
See [Configure AI agent plugins and skill sources](/reference/cli/configuration/#configure-ai-agent-plugins-and-skill-sources)
for agent-specific settings, catalog URLs, and source defaults.
</LearnMore>

#### Init source mechanism

Offer a shared starting configuration to everyone creating or initializing an app. Set **`ASPIRE_INIT_SOURCE_URL`** to a Git repository containing an `aspire.config.json` file:

```bash title="Aspire CLI — Offer a shared initialization source"
ASPIRE_INIT_SOURCE_URL=https://github.com/example-org/aspire-init.git \
aspire init
```

Replace the URL with your configuration repository. The variable proposes a source; it doesn't silently apply it. The CLI displays the source and asks for consent. Use `--use-config-source` to accept explicitly or `--use-config-source false` to decline, including in non-interactive runs.

After acceptance, Aspire copies the source's `integrationSources` and `skillSources` into the project's local configuration and records its source binding. During template discovery, an explicitly configured URL can also supply `templateSources` without copying them into the project file. These are optional defaults, not enforced organizational policy.

Use `ASPIRE_INIT_SOURCE_PATH` to select a different configuration file within the repository, or `ASPIRE_INIT_SOURCE_REF` to select a branch or pin a full commit SHA. If you don't set a URL, the CLI normally offers no source, although detected internal Microsoft environments can supply an organizational default. Refresh an adopted configuration with `aspire update --config-source`.

<LearnMore>
See [`aspire init`](/reference/cli/commands/aspire-init/) and
[`aspire update`](/reference/cli/commands/aspire-update/) for adoption and refresh commands.
TODO: Add a complete guide to shared configuration sources and their activation environment variables.
</LearnMore>

## 🧩 AppHost updates

Aspire 17.0 raises its minimum supported .NET version to **.NET 10**. Review your AppHost and Aspire package target frameworks before updating. This requirement doesn't mean every workload orchestrated by Aspire must target .NET 10. For details, see [microsoft/aspire#20614](https://github.com/microsoft/aspire/pull/20614).

The `Aspire.Hosting.Dotnet` integration now follows stable package versioning for .NET projects added by path. The older `AddProject` APIs are deprecated, not removed. Use the path-based project model when updating your AppHost; see [microsoft/aspire#21360](https://github.com/microsoft/aspire/pull/21360) for migration details.

<LearnMore>
Follow the [17.0 project migration guide on GitHub](https://github.com/microsoft/aspire/blob/a509f094e0ee87d17dc0e1cc9bca84f7ca2623da/docs/migrate-from-addproject.md)
for project paths, launch profiles, and scenarios that retain the legacy model.
</LearnMore>

## ✨ New integrations

### 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.

References supply identity configuration to your workloads. They don't install authentication middleware or protect application routes; configure authentication and authorization in the consuming application.

Thanks to @jmprieur for the initial integration proposal in [microsoft/aspire#14668](https://github.com/microsoft/aspire/pull/14668).

<LearnMore>
See the [Microsoft Entra ID integration](/integrations/security/microsoft-entra-id/)
for registration, credential, and workload configuration.
</LearnMore>

### Azure API Management

Define an API gateway in your AppHost with the new preview `Aspire.Hosting.Azure.ApiManagement` integration. Model APIs, backends, and policies, and import OpenAPI documents from files or reachable deployed workload endpoints.

API Management is a deployment-only resource: it isn't provisioned during `aspire run`. Your local workloads can still run without an API Management service.

Thanks to @tommasodotNET for [microsoft/aspire#19664](https://github.com/microsoft/aspire/pull/19664).

<LearnMore>
See [Azure API Management](/integrations/cloud/azure/azure-api-management/azure-api-management-get-started/)
for setup and gateway configuration.
</LearnMore>

## 🚀 Deployment updates

The `Aspire.Hosting.Kubernetes` and `Aspire.Hosting.Azure.Kubernetes` packages graduate to stable releases. Some APIs, including persistent-volume APIs, remain experimental. Helm-based deployment requires **Helm 4.0.0 or later**.

You can also target an existing Azure Kubernetes Service cluster rather than provisioning a new one. See [microsoft/aspire#20921](https://github.com/microsoft/aspire/pull/20921).

Azure Front Door can connect to Aspire-provisioned Azure Container Apps and App Service environments through Private Link. This API remains experimental, and the private endpoint connection must be approved before Front Door can reach the workloads. See [microsoft/aspire#21228](https://github.com/microsoft/aspire/pull/21228) and [microsoft/aspire#21396](https://github.com/microsoft/aspire/pull/21396).

<LearnMore>
See [Deploy to Kubernetes clusters](/deployment/kubernetes/clusters/),
[Azure Container Apps](/deployment/azure/container-apps/), and
[Azure App Service](/deployment/azure/app-service/) for deployment guidance.
</LearnMore>

## 📦 Integration updates

- Run Azure Web PubSub locally with its emulator using `RunAsEmulator`. Thanks to @vicancy for [microsoft/aspire#20956](https://github.com/microsoft/aspire/pull/20956).
- Reuse a SQL Server resource for the Azure Service Bus emulator instead of creating a separate instance. Thanks to @thomhurst for [microsoft/aspire#17885](https://github.com/microsoft/aspire/pull/17885).
- Use Deno hosting APIs without their previous experimental designation. See [microsoft/aspire#22159](https://github.com/microsoft/aspire/pull/22159).

<LearnMore>
See the [Web PubSub emulator README on GitHub](https://github.com/microsoft/aspire/blob/a509f094e0ee87d17dc0e1cc9bca84f7ca2623da/src/Aspire.Hosting.Azure.WebPubSub/README.md#run-locally-with-the-emulator)
and [Service Bus emulator README on GitHub](https://github.com/microsoft/aspire/blob/a509f094e0ee87d17dc0e1cc9bca84f7ca2623da/src/Aspire.Hosting.Azure.ServiceBus/README.md#emulator-usage)
for local configuration, and the [core Deno hosting README on GitHub](https://github.com/microsoft/aspire/blob/a509f094e0ee87d17dc0e1cc9bca84f7ca2623da/src/Aspire.Hosting.JavaScript/README.md#deno-runtime-and-publishing)
for Deno guidance.
</LearnMore>

## 🐹 Go AppHost documentation

<span id="go-apphost-docs"></span>
Expand Down
Loading