Add Aspire 13.0 upgrade documentation and remove obsolete 9.5.2 guide

[Copilot]

Summary

Adds comprehensive upgrade guide for Aspire 13.0, documenting the new CLI-first upgrade workflow and simplified AppHost project structure. Removes the obsolete Aspire 9.5.2 upgrade documentation and consolidates all necessary upgrade instructions into a single guide.

Changes

• New documentation: docs/get-started/upgrade-to-aspire-13.md

  • CLI upgrade workflow using aspire update command
  • AppHost project template migration (9.x → 13.0): simplified SDK declaration, implicit Aspire.Hosting.AppHost inclusion, net10.0 target
  • Single-file AppHost support with #:package directives (includes note about Visual Studio limitations)
  • Breaking changes guidance and Upgrade Assistant instructions
  • Workload removal instructions (consolidated from 9.x guide)

• Removed: docs/get-started/upgrade-to-aspire-9.md (no longer needed)

• Table of contents: Updated to reference only the Aspire 13.0 upgrade guide

• Redirects: Added redirect from old 9.x upgrade URL to new 13.0 guide

Key structural changes in 13.0

Before (9.x):

<Project Sdk="Microsoft.NET.Sdk">
  <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />
  <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />

After (13.0):

<Project Sdk="Aspire.AppHost.Sdk/13.0.0">
  <!-- Aspire.Hosting.AppHost now implicit -->

Single-file alternative (not supported in Visual Studio):

#:sdk Aspire.AppHost.Sdk@13.0.0
#:package Aspire.Hosting.Redis@13.0.0

var builder = DistributedApplication.CreateBuilder(args);
// No project file required

Original prompt

Update the "upgrade-to-aspire-9" document to upgrade to aspire 13. Take content from here:

🆙 Upgrade to Aspire 13.0
Caution

Aspire 13.0 is a major version release with breaking changes. Please review the Breaking changes section before upgrading.

The easiest way to upgrade to Aspire 13.0 is using the aspire update command:

Update the Aspire CLI to the latest version:

Bash
PowerShell
Terminal window
curl -sSL https://aspire.dev/install.sh | bash

Update your Aspire project using the aspire update command:

Aspire CLI — Update all Aspire packages
aspire update

This command will:

Update the Aspire.AppHost.Sdk version in your AppHost project.
Update all Aspire NuGet packages to version 13.0.
Handle dependency resolution automatically.
Support both regular projects and Central Package Management (CPM).
Update your Aspire templates:

Terminal window
dotnet new install Aspire.ProjectTemplates

Note

If you’re upgrading from Aspire 8.x, follow the upgrade guide first to upgrade to 9.x, then upgrade to 13.0.

🧩 AppHost template updates
Aspire 13.0 introduces a simplified AppHost project template structure. The SDK now encapsulates the Aspire.Hosting.AppHost package, resulting in cleaner project files.

Before (9.x):

Exe net9.0 enable enable 1bf2ca25-7be4-4963-8782-c53a74e10ad9

After (13.0):

Exe net10.0 enable enable 1bf2ca25-7be4-4963-8782-c53a74e10ad9

Key changes:

Simplified SDK declaration: The SDK is now specified directly in the tag with its version: Sdk="Aspire.AppHost.Sdk/13.0.0".
No explicit Aspire.Hosting.AppHost reference: The SDK now automatically includes this package, reducing boilerplate.
Cleaner structure: Removed the separate element and the Microsoft.NET.Sdk base SDK.
Target framework: Updated from net9.0 to net10.0.
The aspire update command automatically handles this migration when upgrading from 9.x to 13.0.

Tip

For an even simpler setup, Aspire 13.0 also supports single-file AppHosts that don’t require a project file at all. Single-file AppHosts are perfect for quick prototypes and learning scenarios.

The same project as a file-based AppHost:

apphost.cs
#:sdk Aspire.AppHost.Sdk@13.0.0
#:package Aspire.Hosting.Redis@13.0.0

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");
var api = builder.AddProject("apiservice", "../MyApi");
.WithReference(cache);

builder.Build().Run();

No project file needed - just a single .cs file with package references declared using #:package directives.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/get-started/upgrade-to-aspire-13.md	docs/get-started/upgrade-to-aspire-13
docs/toc.yml	docs/toc

[davidfowl]

@copilot We don't need the 9.5.2 upgrade doc anymore.

[Copilot]

@copilot We don't need the 9.5.2 upgrade doc anymore.

Removed upgrade-to-aspire-9.md and consolidated the workload removal instructions into the upgrade-to-aspire-13.md document. Added a redirect from the old URL to the new upgrade guide. (10af2cd)

[davidfowl]

cc @IEvangelist

[Copilot]

Pull Request Overview

This PR updates the Aspire upgrade documentation to reflect version 13.0, introducing a new CLI-first upgrade workflow and simplified project structure. The update removes the obsolete Aspire 9.5.2 documentation and consolidates upgrade instructions into a comprehensive guide for version 13.0.

Key changes:

• New Aspire CLI-based upgrade workflow using the aspire update command
• Simplified AppHost SDK declaration syntax (Sdk="Aspire.AppHost.Sdk/13.0.0")
• Documentation of single-file AppHost support with #:package directives
• Updated references from net9.0 to net10.0 target framework

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
docs/toc.yml	Updates table of contents to reference the new Aspire 13.0 upgrade guide instead of the 9.5.2 version
docs/get-started/upgrade-to-aspire-13.md	New comprehensive upgrade guide covering CLI workflow, AppHost template changes, single-file AppHosts, manual upgrade steps, breaking changes, and workload removal
.openpublishing.redirection.json	Adds redirect from the old upgrade-to-aspire-9.md URL to the new upgrade-to-aspire-13 guide

Comments suppressed due to low confidence (5)

docs/get-started/upgrade-to-aspire-13.md:116

• The target framework net10.0 refers to .NET 10.0, which does not exist as of my knowledge cutoff in January 2025. If this is a hypothetical future version, it should be verified. The latest stable .NET version as of my knowledge is .NET 9.0. Please verify that net10.0 is the correct target framework for Aspire 13.0.
  docs/get-started/upgrade-to-aspire-13.md:139
• The description mentions updating from net9.0 to net10.0. However, net10.0 refers to .NET 10.0, which does not exist as of my knowledge cutoff in January 2025. Please verify that net10.0 is the correct target framework for Aspire 13.0 or if this should reference a different version.
  docs/get-started/upgrade-to-aspire-13.md:191
• The diff shows updating from net9.0 to net10.0. However, net10.0 refers to .NET 10.0, which does not exist as of my knowledge cutoff in January 2025. Please verify that net10.0 is the correct target framework for Aspire 13.0.
  docs/get-started/upgrade-to-aspire-13.md:29
• This heading uses a gerund ("Upgrade using..."), which violates the Aspire documentation guidelines. According to the style guide, headings should use sentence case with no gerunds. Change this to "Upgrade with the Aspire CLI" or "Aspire CLI upgrade".
  docs/get-started/upgrade-to-aspire-13.md:6
• According to the Aspire documentation guidelines, if this Markdown file was generated by AI (as indicated by the Copilot coding agent involvement in the PR), you need to add an ai-usage: ai-generated key/value pair to the frontmatter to disclose AI assistance.