Add consolidated Aspire 13.x migration guide for 9.x upgrades

[Copilot]

Aspire 13.0/13.1 introduced breaking changes across packages, APIs, and behaviors. Existing what's-new documentation was comprehensive but not organized as an actionable upgrade path, causing compilation errors for users migrating from 9.x.

Changes

Consolidated migration guide at whats-new/aspire-13/#migration-guide covering:

• Quick checklist: 10-step upgrade path from CLI update through testing
• Package renames: Aspire.Hosting.NodeJs → Aspire.Hosting.JavaScript
• JavaScript API migrations:
  • AddNpmApp() removed → AddJavaScriptApp().WithRunScript()
  • AddNodeApp() refactored: absolute paths → appDirectory + relative scriptPath
• Lifecycle hooks → Events: IDistributedApplicationLifecycleHook → IDistributedApplicationEventingSubscriber
• Publishing callbacks → Pipeline steps: WithPublishingCallback() → WithPipelineStepFactory()
• Connection property renames (13.1): Model → ModelName, Database → DatabaseName across GitHub Models, OpenAI, Milvus, MongoDB, MySQL, Oracle
• Azure Redis rename (13.1): AddAzureRedisEnterprise() → AddAzureManagedRedis()
• Behavioral changes: EndpointReference.GetValueAsync() now waits for allocation instead of throwing immediately

Key migration examples

JavaScript apps:

// Before (9.x)
builder.AddNpmApp("frontend", "../frontend", scriptName: "dev");
builder.AddNodeApp("api", "/absolute/path/to/app.js", workingDirectory: "/absolute/path/to");

// After (13.0)
builder.AddJavaScriptApp("frontend", "../frontend").WithRunScript("dev");
builder.AddNodeApp("api", "../api", "app.js");

Lifecycle hooks:

// Before (9.x)
public class MyHook : IDistributedApplicationLifecycleHook { ... }
builder.Services.TryAddLifecycleHook<MyHook>();

// After (13.0)
public class MySubscriber : IDistributedApplicationEventingSubscriber { ... }
builder.Services.TryAddEventingSubscriber<MySubscriber>();

Screenshots

Quick migration checklist:

JavaScript API migrations:

Connection property renames (13.1):

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/CommunityToolkit/Aspire
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node ./scripts/update-github-stats.js (http block)
• https://api.github.com/repos/CommunityToolkit/Aspire/contributors
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build (http block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build git log �� %aE ���� --follow s/.bin/git udes/config-settgit --follow it git log �� %aE ���� --follow escript@5.9.3_/node_modules/@astrojs/starlight/node_modules/.bin/../../../../../../pagefind@1.4 udes/option-versgit --follow 0/x64/lib/node_m--pretty=format:������������ %H �� %aI �� %s �� %D �� %b �� %aN �� %aE ���� git (http block)
• https://api.github.com/repos/dotnet/aspire
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node ./scripts/update-github-stats.js (http block)
• https://api.github.com/repos/dotnet/aspire-samples
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node ./scripts/update-github-stats.js (http block)
• https://api.github.com/repos/dotnet/aspire-samples/contributors
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build (http block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build git log �� %aE ���� --follow s/.bin/git udes/config-settgit --follow it git log �� %aE ���� --follow escript@5.9.3_/node_modules/@astrojs/starlight/node_modules/.bin/../../../../../../pagefind@1.4 udes/option-versgit --follow 0/x64/lib/node_m--pretty=format:������������ %H �� %aI �� %s �� %D �� %b �� %aN �� %aE ���� git (http block)
• https://api.github.com/repos/dotnet/aspire/contributors
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build (http block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build git log �� %aE ���� --follow s/.bin/git udes/config-settgit --follow it git log �� %aE ���� --follow escript@5.9.3_/node_modules/@astrojs/starlight/node_modules/.bin/../../../../../../pagefind@1.4 udes/option-versgit --follow 0/x64/lib/node_m--pretty=format:������������ %H �� %aI �� %s �� %D �� %b �� %aN �� %aE ���� git (http block)
• https://api.github.com/repos/microsoft/aspire.dev
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node ./scripts/update-github-stats.js (http block)
• https://api.github.com/repos/microsoft/aspire.dev/contributors
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build (http block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build git log �� %aE ���� --follow s/.bin/git udes/config-settgit --follow it git log �� %aE ���� --follow escript@5.9.3_/node_modules/@astrojs/starlight/node_modules/.bin/../../../../../../pagefind@1.4 udes/option-versgit --follow 0/x64/lib/node_m--pretty=format:������������ %H �� %aI �� %s �� %D �� %b �� %aN �� %aE ���� git (http block)
• https://api.github.com/repos/microsoft/dcp
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node ./scripts/update-github-stats.js (http block)
• https://api.github.com/repos/microsoft/dcp/contributors
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build (http block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build git log �� %aE ���� --follow s/.bin/git udes/config-settgit --follow it git log �� %aE ���� --follow escript@5.9.3_/node_modules/@astrojs/starlight/node_modules/.bin/../../../../../../pagefind@1.4 udes/option-versgit --follow 0/x64/lib/node_m--pretty=format:������������ %H �� %aI �� %s �� %D �� %b �� %aN �� %aE ���� git (http block)
• learn.microsoft.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build (dns block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build git log �� %aE ���� --follow s/.bin/git udes/config-settgit --follow it git log �� %aE ���� --follow escript@5.9.3_/node_modules/@astrojs/starlight/node_modules/.bin/../../../../../../pagefind@1.4 udes/option-versgit --follow 0/x64/lib/node_m--pretty=format:������������ %H �� %aI �� %s �� %D �� %b �� %aN �� %aE ���� git (dns block)
• telemetry.astro.build
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build (dns block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js build git log �� %aE ���� --follow s/.bin/git udes/config-settgit --follow it git log �� %aE ���� --follow escript@5.9.3_/node_modules/@astrojs/starlight/node_modules/.bin/../../../../../../pagefind@1.4 udes/option-versgit --follow 0/x64/lib/node_m--pretty=format:������������ %H �� %aI �� %s �� %D �� %b �� %aN �� %aE ���� git (dns block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js preview git log %D �� %b �� %aN src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx --follow it udes/option-waitsh --follow modules/@npmcli/"pagefind" --site ../../../../../../dist git log %D �� %b �� %aN �� %aE ���� --follow /node-gyp-bin/node ference/cli/commsh --follow k/aspire.dev/nodpnpm --dir ./src/frontend run preview git (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[What's New Analysis] Create Aspire 13.x migration guide</issue_title>
<issue_description>## Summary

Aspire 13.0 and 13.1 have significant breaking changes that are only documented in what's-new. Need a dedicated migration guide.

Breaking Changes to Document

Package Renames

<!-- Before (9.x) -->
<PackageReference Include="Aspire.Hosting.NodeJs" Version="9.x.x" />

<!-- After (13.0) -->
<PackageReference Include="Aspire.Hosting.JavaScript" Version="13.0.0" />

API Signature Changes

AddNodeApp refactored:

// Before (9.x) - absolute scriptPath with optional workingDirectory
builder.AddNodeApp("frontend", "/absolute/path/to/app.js", 
    workingDirectory: "/absolute/path/to");

// After (13.0) - appDirectory with relative scriptPath
builder.AddNodeApp("frontend", "../frontend", "app.js");

AddNpmApp removed:

// Before (9.x)
builder.AddNpmApp("frontend", "../frontend", scriptName: "dev");

// After (13.0)
builder.AddJavaScriptApp("frontend", "../frontend")
    .WithRunScript("dev");

Lifecycle Hooks → Events

// Before (9.x)
public class MyHook : IDistributedApplicationLifecycleHook { ... }
builder.Services.TryAddLifecycleHook<MyHook>();

// After (13.0)
public class MySubscriber : IDistributedApplicationEventingSubscriber { ... }
builder.Services.TryAddEventingSubscriber<MySubscriber>();

Publishing Callbacks → Pipeline Steps

// Before (9.x)
.WithPublishingCallback(async (context, ct) => { ... });

// After (13.0)
.WithPipelineStepFactory(context => new PipelineStep() { ... });

Connection Property Renames (13.1)

Resource	Old	New
GitHub Models	Model	ModelName
OpenAI model	Model	ModelName
Milvus database	Database	DatabaseName
MongoDB database	Database	DatabaseName
MySQL database	Database	DatabaseName

Azure Redis Rename (13.1)

// Before
builder.AddAzureRedisEnterprise("cache");

// After
builder.AddAzureManagedRedis("cache");

Suggested Content

1. Quick migration checklist - package updates, API changes
2. Package rename mapping - old → new
3. API signature changes - with before/after examples
4. Lifecycle hooks migration - step-by-step
5. Publishing callbacks migration - step-by-step
6. Breaking behavior changes - EndpointReference.GetValueAsync now waits

Why It Matters

Users upgrading from 9.x hit compilation errors with no clear guidance. What's-new is comprehensive but not organized as a migration checklist.</issue_description>

<agent_instructions>Please update this https://aspire.dev/whats-new/aspire-13/#migration-guide</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [What's New Analysis] Create Aspire 13.x migration guide #345

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

Adds a consolidated “Migration guide” section to the Aspire 13 “What’s new” page to provide an actionable upgrade path from Aspire 9.x to 13.x, consolidating breaking changes from 13.0 and 13.1 into a checklist + focused migration subsections.

Changes:

• Introduces a 10-step quick migration checklist for upgrading CLI, packages, and key breaking changes.
• Adds structured migration subsections for package renames, JavaScript hosting API changes, lifecycle hooks → eventing, publishing callbacks → pipeline steps, connection property renames, Azure Redis rename, and EndpointReference.GetValueAsync() behavior.
• Provides before/after code examples and a connection property/environment variable rename table.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.