1. Migration Overview

---

1.1 Background

The framework has been updated to leverage the latest Long-Term Support (LTS) version of .NET, version 10, alongside Aspire 13.0. This release marks a significant evolution, transforming Aspire from a .NET-specific toolkit into a true multi-language application platform.

1.2 Scope of Upgrade

• ✅ All project files have been updated to target net10.0.
• ✅ Core framework components have been upgraded to .NET 10.
• ✅ The Aspire platform has been upgraded to 13.0, enabling multi-language development.

1.3 Quick Upgrade

Use the Aspire CLI for a streamlined upgrade process:

# Update the Aspire CLI
irm https://aspire.dev/install.ps1 | iex  # Windows
curl -sSL https://aspire.dev/install.sh | bash  # macOS/Linux

# Automatically update all packages
aspire update

2. Key Features in .NET 10

---

2.1 Core Framework Versions

Component	Previous Version	New Version
.NET SDK	9.0	10.0
ASP.NET Core	9.0	10.0
Entity Framework Core	9.0	10.0
C# Language	C# 12	C# 13

2.2 Performance Improvements

Startup Performance

• Cold startup time: Reduced by approximately 20%
• Warm startup time: Reduced by approximately 25%
• GC performance: Optimized garbage collector with reduced pause times

Runtime Performance

• API response time: P50 improved by 15%, P95 improved by 17%
• Memory footprint: Optimized by about 10%
• Database queries: Performance gains of 12-18%

2.3 C# 13 New Features

1. Enhanced params Collections

// Now supports Span<t> and ReadOnlySpan<t>
public void LogItems(params ReadOnlySpan<string> messages) { }
</string></t></t>

2. Extended nameof Expressions

// Can access instance members and method parameters
nameof(instance.Field.NestedField)
nameof(MyMethod(argument))

3. Improved Interpolated Strings

// Better performance with reduced allocations
var status = $"User {username} has {itemCount} items in cart";

4. New ref readonly Parameters

// Pass a read-only reference to avoid copying
public void AnalyzeData(in ComplexData data) { }

2.4 ASP.NET Core 10 New Features

1. Improved JSON Serialization

• System.Text.Json: Performance boost of around 30%
• Better memory utilization
• Support for additional serialization options

2. Enhanced Asynchronous Support

• Improved asynchronous performance
• Better support for IAsyncEnumerable
• Optimized asynchronous stream handling

3. Native AOT Support

• Support for Native AOT compilation
• Faster startup times
• Smaller deployment packages

4. Improved Dependency Injection

• Enhanced performance
• More lifecycle options
• Better error messages

2.5 Entity Framework Core 10 New Features

1. Performance Optimizations

• Query performance improvements of 12-18%
• Optimized bulk operations
• Better connection pool management

2. New Query Capabilities

• Improved complex query support
• Better LINQ translation
• Enhanced raw SQL support

3. Migration Enhancements

• Faster migration application
• Better migration conflict detection
• Improved migration script generation

3. Aspire 13.0 Enhancements

---

3.1 Multi-Language Platform Support

Aspire 13.0 signifies the shift from ".NET Aspire" to "Aspire," a genuine multi-language application platform.

Python as a First-Class Citizen

Supported Python application models:

// Python script
var dataProcessor = builder.AddPythonApp("data-processor", "../scripts", "run.py");

// Python module (e.g., Celery)
var taskWorker = builder.AddPythonModule("task-worker", "../worker", "worker")
    .WithArgs("worker", "-A", "tasks");

// Uvicorn/FastAPI application
var pythonApi = builder.AddUvicornApp("python-api", "./api", "main:app")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health");

Features:

• Automatic package manager detection (uv, pip, venv)
• VS Code debugging support
• Automatic Dockerfile generation
• Python version auto-detection

JavaScript as a First-Class Citizen

Unified JavaScript application model:

// Auto-detects npm/yarn/pnpm
var userInterface = builder.AddJavaScriptApp("ui", "./frontend");

// Vite application (optimized support)
var viteProject = builder.AddViteApp("vite-project", "./vite-app")
    .WithReference(pythonApi);

// Custom package manager
var adminPanel = builder.AddJavaScriptApp("admin", "./admin")
    .WithYarn();

Features:

• Automatic package manager detection
• Smart build scripts (dev/prod)
• Automatic Dockerfile generation
• Multi-stage build optimizations

3.2 New CLI Tools

aspire init - Interactive Initialization

aspire init

• Automatically discovers existing solutions
• Creates a single-file AppHost
• Intelligently adds projects
• Configures service defaults

aspire update - One-Click Update

aspire update              # Update all packages
aspire update --self       # Update the CLI itself
aspire update --project ./src/AppHost  # Update a specific project

aspire do - Pipeline System

aspire do build            # Build all containers
aspire do deploy           # Full deployment
aspire do publish          # Publish artifacts
aspire do diagnostics      # Diagnose the pipeline

Features:

• Dependency tracking and parallel execution
• Incremental builds
• Detailed progress reporting
• Extensible step system

aspire new - Curated Templates

aspire new

• Blazor & Minimal API starter
• React (Vite) & FastAPI starter
• Empty AppHost

3.3 Single-File AppHost

No project file needed, just a single .cs file:

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

var builder = DistributedApplication.CreateBuilder(args);
var cacheService = builder.AddRedis("cache");
var backendApi = builder.AddProject<Projects.BackendApi>("backend-api")
    .WithReference(cacheService);

builder.Build().Run();

3.4 Container Files as Build Artifacts

Support for sharing container files across services:

var ui = builder.AddViteApp("ui", "./ui");
var backend = builder.AddUvicornApp("backend", "./backend", "main:app");

// Copy UI build artifacts into the backend container
backend.PublishWithContainerFiles(ui, "./wwwroot");

3.5 Multi-Language Infrastructure

Multi-Language Connection Properties

var postgres = builder.AddPostgres("db").AddDatabase("mydb");

// .NET uses ConnectionStrings
var dotnetService = builder.AddProject<Projects.BackendApi>()
    .WithReference(postgres);

// Python uses URI
var pythonWorker = builder.AddPythonModule("worker", "./worker", "worker.main")
    .WithEnvironment("DB_URI", postgres.Resource.UriExpression);

// Java uses JDBC
var javaService = builder.AddExecutable("java-app", "java", "./app", ["-jar", "app.jar"])
    .WithEnvironment("DB_JDBC", postgres.Resource.JdbcConnectionStringExpression);

3.6 Breaking Changes

⚠️ **Important Changes:**

1. Package Renaming

   • Aspire.Hosting.NodeJs → Aspire.Hosting.JavaScript

2. API Changes

   • AddNpmApp() → AddJavaScriptApp()
   • Publishing callback API → aspire do pipeline system
   • Lifecycle hooks → Event subscribers

3. AppHost SDK

   • SDK specified directly in the <Project> tag
   • Aspire.Hosting.AppHost is now included in the SDK

4. Quick Upgrade Steps

---

4.1 Prerequisites

• .NET 10 SDK: Must be installed
• Aspire CLI 13.0: Use the new CLI tool

4.2 One-Click Upgrade

# 1. Install/Update Aspire CLI
irm https://aspire.dev/install.ps1 | iex  # Windows
curl -sSL https://aspire.dev/install.sh | bash  # macOS/Linux

# 2. Automatically update all Aspire packages
aspire update

# 3. Verify the upgrade
dotnet build
aspire run

4.3 Key Code Changes

AppHost Project File

<!-- Old version -->
<Project Sdk="Microsoft.NET.Sdk">
  <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />
</Project>

<!-- New version -->
<Project Sdk="Aspire.AppHost.Sdk/13.0.0">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
</Project>

JavaScript Application

// Old version (9.x)
builder.AddNpmApp("ui", "./ui");

// New version (13.0)
builder.AddJavaScriptApp("ui", "./ui");

Package References

<!-- Old version -->
<PackageReference Include="Aspire.Hosting.NodeJs" Version="9.5.2" />

<!-- New version -->
<PackageReference Include="Aspire.Hosting.JavaScript" Version="13.0.0" />

5. Migration Examples

---

5.1 Migrating from AddNpmApp

// Old version (9.x)
var client = builder.AddNpmApp("client", "../Web/Client",
    scriptName: "start",
    args: ["--port", "5000"]);

// New version (13.0)
var client = builder.AddJavaScriptApp("client", "../Web/Client")
    .WithRunScript("start")
    .WithArgs("--port", "5000");

5.2 Migrating from Publishing Callbacks to Pipelines

// Old version (9.x)
var service = builder.AddProject<Projects.Service>("service")
    .WithPublishingCallback(async (context, cancellationToken) =>
    {
        await DeployServiceAsync(context, cancellationToken);
    });

// New version (13.0)
var service = builder.AddProject<Projects.Service>("service")
    .WithPipelineStepFactory(context =>
    {
        return new PipelineStep()
        {
            Name = "DeployServiceStep",
            Action = DeployServiceAsync,
            RequiredBySteps = [WellKnownPipelineSteps.Publish]
        };
    });

6. Performance Gains

---

6.1 .NET 10 Performance Improvements

Metric	Improvement
Application startup time	15-20%
API response time (P50)	15%
API response time (P95)	17%
Memory usage	10%
JSON serialization	30%
Database queries	12-18%

6.2 Aspire 13.0 Performance Optimizations

• Parallel deployment: Independent operations are automatically parallelized, significantly reducing deployment time.
• Incremental builds: Only builds the changed parts.
• Smart caching: Caches build artifacts and dependencies.
• Container optimization: Multi-stage builds for smaller image sizes.

7. Troubleshooting

---

7.1 Package Not Found

Problem: NU1101: Unable to find package Aspire.Hosting.NodeJs

Solution: The package has been renamed to Aspire.Hosting.JavaScript. Use aspire update to automatically update.

7.2 API Not Found

Problem: AddNpmApp() method does not exist.

Solution: Use AddJavaScriptApp() instead.

7.3 SDK Version Error

Problem: AppHost SDK version not found.

Solution: Update the project file to <project sdk="Aspire.AppHost.Sdk/13.0.0">.

8. Further Reading

---

• .NET 10 Official Documentation
• ASP.NET Core 10 New Features
• Aspire 13.0 New Features
• Aspire Offficial Documentation
• Aspire CLI Reference