[What's New Analysis] Create Aspire 13.x migration guide

[davidfowl]

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.