Chapter 10: Adding legacy apps to Aspire and working with AI agents

Introduction

The chapter introduction explains why existing applications and AI coding assistants matter to Aspire, while previewing migration and integration topics.

• Existing application onboarding: Explain that Aspire is not limited to newly built applications: tooling can help add existing .NET applications and their infrastructure components, such as databases and message brokers.
  Why it matters: Aspire can be considered for an application you already have, not just one you build from scratch.
• AI assistant development role: Explain why agentic coding assistants are relevant here: they can automate tedious development tasks so developers can focus on problem-solving, and Aspire has tools that work with assistants such as Claude Code.
  Why it matters: This gives a reason to connect Aspire development with coding assistants without assuming any integration mechanics yet.

Key terms: existing applications, infrastructure components, databases, message brokers, agentic coding assistants, AI coding assistants, Claude Code

10.1 Migrating old .NET Aspire projects

This section explains why teams may still use older Aspire versions and what the move to Aspire 13 signals about the platform.

• Older Aspire adoption: Explain why an organization might still run an older version of Aspire despite significant changes in newer versions.
  Why it matters: This explains why migrating an existing Aspire application is a realistic task, not just a hypothetical one.
• Aspire 13 naming changes: Describe the version-number jump to Aspire 13 and why the name no longer includes .NET.
  Why it matters: The version jump and shorter name help explain which Aspire releases and languages the chapter is discussing.

Key terms: cloud-first development, old version of Aspire, Aspire 13, evergreen, .NET-exclusive, JavaScript, Python

10.1.1 Migrating from .NET Aspire 8

Explains how to move a .NET Aspire 8 application to Aspire 9 as a manual first step toward Aspire 13.

• Aspire 8 upgrade path: Explain why an Aspire 8 application should be upgraded manually to Aspire 9 before upgrading to Aspire 13.
  Why it matters: It explains why an Aspire 8 project cannot follow the same direct upgrade route as an Aspire 9 project.
• Manual project update steps: Describe the project-file changes taught for the manual move to Aspire 9, including which package categories must be updated and the optional .NET version update.
  Why it matters: Updating the host and integration-related packages together brings the project onto the Aspire 9 version needed for the next upgrade.
• Orchestration file naming: Distinguish where startup and orchestration code resides in Aspire 8 from the file-name options in an Aspire 9 host project.
  Why it matters: It helps you find the orchestration code without assuming the host file must be renamed during this migration.

Key terms: .NET Aspire 8, Aspire 9, Aspire 13, built-in upgrade tools, .csproj, Project tag, Aspire.Hosting.AppHost, hosted integration packages, Aspire-specific client packages, Program.cs

10.1.2 Migrating from .NET Aspire 9 to Aspire 13

This subsection explains how to upgrade an Aspire 9 solution to Aspire 13, optionally simplify its project file, and choose a supported startup file.

• Aspire 13 upgrade paths: Describe the manual and CLI-assisted ways to upgrade an Aspire 9 solution to Aspire 13, including what the CLI update changes.
  Why it matters: It distinguishes a solution-wide CLI update from changing the Aspire versions yourself.
• Optional AppHost project modernization: Explain why an upgraded AppHost project can look different from a new Aspire 13 project, and describe the project-file changes that make it less verbose.
  Why it matters: It prevents a different-looking upgraded project file from being mistaken for a broken or incomplete migration.
• Startup file choice: State which startup code filenames Aspire 13 supports and the restriction on using them together.
  Why it matters: It clarifies that migration does not require one particular startup filename, but does require choosing one.

Key terms: Aspire 13, aspire CLI tool, SDK, host package, client packages, aspire update, IsAspireHost, Aspire.AppHost.Sdk, Aspire.Hosting.AppHost, Sdk attribute

10.2 Enrolling existing projects in Aspire orchestration

The section explains why enrolling existing .NET applications in Aspire helps local development and outlines how to add orchestration and shared service defaults without yet moving an external database.

• Benefits of Aspire enrollment: Explain how enrolling an existing distributed application in Aspire can improve local development.
  Why it matters: This is the practical reason to bring an existing system under Aspire orchestration.
• Existing application topology: Describe the example application's components and identify what remains outside Aspire after the setup steps.
  Why it matters: It clarifies which applications are being enrolled and prevents assuming that enrollment also moves the database.
• Existing project enrollment: Describe the available ways to aspirify an existing solution and how its application projects become part of the Aspire host.
  Why it matters: Adding a host alone is not enough: it must reference the existing applications it will orchestrate.
• Service defaults and health checks: Trace how the section adds shared Aspire capabilities and exposes health checks in enrolled services.
  Why it matters: Orchestration and shared service behavior require changes in the enrolled applications as well as the host.

Key terms: Aspire orchestration, service discovery, Blazor application, backend API, SQL Server, connection string, aspirification, Aspire Host, Aspire CLI, AppHost.cs

10.3 Reconfiguring the infrastructure components

Shows how to move an existing application's SQL Server setup into Aspire while keeping client changes small and preserving its production database connection.

• SQL Server host registration: Describe how the existing application's SQL Server database is brought into Aspire orchestration: install the SQL Server hosting package, create the SQL Server object and database in AppHost.cs, and pass the database reference to the API service.
  Why it matters: This puts the existing database dependency under Aspire orchestration.
• Minimal API connection update: Explain how the API service can use Aspire's SQL Server connection without an Aspire-specific client library by retaining its configuration-based connection lookup and changing the requested name from DefaultConnection to sqldb. Distinguish this minimal approach from using the full client integration library.
  Why it matters: An existing API can adopt the Aspire-hosted database without replacing its connection code or adding a client library.
• Local and production database routing: Explain how the host can use a SQL Server container for local runs while retaining an external production database, using an IsRunMode condition and AddConnectionString() with the same sqldb label. State why this does not require another API service change.
  Why it matters: The application can gain a local Aspire-managed database without losing its existing production database.

Key terms: Aspire.Hosting .SqlServer, AppHost.cs, database reference, API service, Full, Minimal, GetConnectionString(), ConnectionStrings, DefaultConnection, sqldb

10.4 Integrating Aspire with AI coding agents

The section explains why AI coding agents need current Aspire information and walks through preparing a solution and assistant for an MCP-enabled exercise.

• Current Aspire information for agents: Explain why coding agents use tool calling when working with Aspire and identify MCP as the way they obtain up-to-date Aspire information.
  Why it matters: Current information helps an agent avoid suggesting obsolete methods or invented calls.
• Agent exercise startup sequence: Describe how to prepare the existing application and .NET solution for the coding-agent exercise, including the commands to start the assistant and Aspire host.
  Why it matters: This sequence leaves the assistant and Aspire host ready for the subsequent MCP setup.

Key terms: tool calling, Model Context Protocol (MCP), coding agents, claude, aspire init, aspire run, Aspire dashboard

10.4.1 Configuring MCP in Aspire

This section explains how to configure Aspire’s MCP server for a coding assistant and what tools that configuration makes available in the repository.

• MCP server setup context: Describe where to begin configuring Aspire’s MCP server, how the setup targets a coding assistant, and when the assistant can use the configured tools.
  Why it matters: The assistant needs the MCP server configured for its environment before it can use Aspire’s tools.
• Resource and diagnostic tools: Explain how the configured tools let a coding assistant inspect hosted resources and diagnose the running Aspire setup.
  Why it matters: These tools give a coding assistant a view of what Aspire is running and how that setup is behaving.
• Integration and app host tools: Describe how MCP tools help a coding assistant find integration packages and work with the right Aspire app host.
  Why it matters: Package information and app-host selection help the assistant make changes in the intended Aspire context.

Key terms: MCP server, Aspire host project, coding assistant, repo folder, list_resources, execute_resource_command, list_console_logs, list_structured_logs, list_traces, list_trace_structured_logs

10.4.2 Using agentic AI to work with Aspire

This section shows how to use a coding agent to plan Aspire AppHost changes, review and implement them safely, and investigate a running Aspire app through MCP.

• Agent-led AppHost planning: Describe how to start a coding assistant in the solution folder and ask it to inspect the projects and dependencies before proposing an Aspire AppHost model and implementation order.
  Why it matters: Reviewing what the agent thinks is in the solution helps catch misunderstandings before it changes the AppHost.
• Review and controlled implementation: Explain why the agent’s AppHost proposal and generated changes need human verification, and distinguish guarded autonomous execution from making small, reviewed changes.
  Why it matters: A convincing agent proposal can still miss requirements, and the developer is responsible for the result.
• MCP-assisted local diagnostics: Describe the kinds of questions an agent can answer about a locally running Aspire application using information from the MCP server.
  Why it matters: These prompts let the agent help investigate concrete problems in the running Aspire stack.

Key terms: coding assistant, Aspire AppHost model, projects+dependencies, health-check endpoints, WaitFor(), guardrails, AppHost, MCP server, Aspire stack, resources

10.4.3 What are MCP and agentic tool calling?

This section explains how coding assistants use agentic tool calling to act on a development task and how MCP gives them a standard way to discover and use tools.

• Agentic tool calling loop: Explain how a coding assistant uses tools to do more than generate text: it chooses actions based on a request, observes their results, and adjusts its next step.
  Why it matters: This is why a coding assistant can inspect a project, run tests, and revise its work rather than merely suggest code.
• MCP tool contract: Explain what MCP standardizes for an AI agent and how a tool describes what the agent can send and receive.
  Why it matters: A consistent tool contract lets an agent discover and call available capabilities through a predictable interface.
• MCP client server exchange: Trace how an agent uses an MCP-exposed tool, from receiving the available capabilities to getting a tool result back.
  Why it matters: The exchange shows how a tool call becomes an executed action whose result the assistant can use.

Key terms: agentic tool calling, LLM, tool invocation, MCP, tools, resources, input schema, output schema, AI agent, MCP server

10.5 Closing thoughts

This closing section frames Aspire as a way to make distributed systems understandable and draws out three principles that apply beyond the framework.

• Distributed system as a whole: Explain how Aspire changes the way a developer thinks about an application: independent services and their infrastructure become parts of one system that can be run, observed, and reasoned about.
  Why it matters: This is the section’s central shift from thinking about a single application to thinking about a distributed system.
• Infrastructure as application code: Explain why the section says infrastructure is part of the application, including what it means to treat resources such as databases, queues, identity providers, and caches as part of the system.
  Why it matters: It keeps the components an application depends on within the developer’s view of the application.
• Visibility and realistic local development: Explain why the section treats observability as a feature and a realistic local setup as a source of production confidence.
  Why it matters: Seeing system behavior and testing it in a realistic setting supports confidence beyond local development.

Key terms: distributed systems, services, infrastructure, Infrastructure is code, resources declaratively, Observability is a feature, Local confidence enables production confidence

10.6 Summary