Microsoft Aspire Documentation

The Polyglot AppHost feature allows developers to write Aspire app hosts in non-.NET languages. Instead of running a standalone guest process, guest language apphosts communicate with a .NET AppHost Server via JSON-RPC. This architecture allows non-.NET developers to leverage Aspire's 40+ hosting integrations and deployment publishers (like Bicep or Kubernetes YAML generation) while writing their orchestration logic in their preferred language.

Note: This feature is experimental and may change in future releases.

Aspire is a cloud-ready stack designed to streamline building, running, debugging, and deploying distributed applications. It uses a code-first approach where you define your services, databases, and front ends directly in code, providing type safety and version control for your application architecture.

Core Workflow:

1. Define: Specify services and their connections in an AppHost.
2. Run: Launch the entire distributed application locally with a single command.
3. Monitor: Use the Aspire Dashboard to observe your running services.
4. Deploy: Use the same architecture definition to deploy to Kubernetes, cloud providers, or custom servers.

The Aspire Bundle is a platform-specific, self-contained distribution package designed to provide everything needed to run Aspire applications without requiring large NuGet downloads or a global .NET SDK for polyglot app hosts.

It includes:

• Aspire CLI: A native AOT executable that handles commands like run, add, new, and publish, and includes native certificate management.
• Aspire Managed: A unified self-contained binary (aspire-managed) that provides the Dashboard, AppHost Server, and NuGet operations via subcommands.
• Developer Control Plane (DCP): The core runtime component for orchestration.

This bundle ensures version consistency between the CLI and runtime components and enables reliable offline development.

The release notes generation process is modularized into the following documentation components:

The Aspire CLI MCP (Model Context Protocol) Server is designed to provide AI agents and MCP clients with access to Aspire resources via a command-line interface.

Key architectural decisions include:

• Transport: Uses stdio transport to ensure compatibility with Node.js-based clients and agent environments like GitHub Copilot Chat (CCA).
• Connection Pattern: Employs a two-stage connection process. It uses a local Unix socket to securely obtain Dashboard credentials (endpoint and API token) from the running app host, then connects to the Dashboard MCP.
• Tooling Strategy: The CLI MCP acts as a proxy/forwarder for the existing Dashboard MCP tools. This allows the CLI to mirror the tool schemas and forward invocations directly to the Dashboard.
• Lifecycle: The API token lifetime is tied to the app host launch; the token is valid only while the app host is running.

The documentation search service is designed for high performance and zero external dependencies (no vector embeddings required). It uses weighted lexical search and eager indexing.

Key Features:

• Dynamic Fetching: Fetches documentation from https://aspire.dev/llms-full.txt using ETag-based caching to minimize bandwidth.
• Eager Indexing: Pre-indexes documentation on MCP server startup for fast query response.
• Weighted Lexical Search: Ranks results based on field importance (Title > Summary > Heading > Code > Body).
• Slug Matching: Provides significant scoring bonuses for exact or partial matches in document slugs (e.g., a query for "service discovery" will prioritize the service-discovery slug).

The Azure integration in Aspire utilizes Azure.Provisioning SDKs to manage infrastructure. During the publish phase, resources are transformed into Bicep files based on the following logic:

• AzureProvisioningInfrastructure: A collection representing all resources that will be included in the generated Bicep file.
• Existing Resources: Resources added to an AzureProvisioningInfrastructure instance using resource.AddAsExisting(infra) are represented in Bicep as resource "..." = existing {}.
• New Resources: Resources not marked as existing are treated as new infrastructure to be provisioned.
• BicepOutput: Represents a value that is pending and will be computed only when the Bicep deployment is executed.

Aspire uses a reconciliation process to coordinate Azure run-mode provisioning, cancellation, drift detection, and ARM (Azure Resource Manager) deployment reconciliation. This ensures that if the AppHost restarts or a command is cancelled, Aspire can reattach to existing ARM work instead of starting duplicate deployments.

Key concepts include:

• Azure intent: A typed operation request (e.g., provision, reprovision, delete, reset, cancel).
• Reconciliation: Treating cached Aspire state as a pointer to ARM, probing ARM as the source of truth, and adopting or clearing that state before a fresh deployment starts.
• Drift: A mismatch where Aspire has cached local state for a running Azure resource, but ARM no longer reports the target resource as existing.

The CLI MCP server uses two mechanisms to find and connect to Aspire app hosts:

1. Source Tree Scanning (Pre-launch): The server scans the working directory for .AppHost.csproj files to help agents discover and bootstrap new app hosts.
2. Dashboard Connection (Runtime): Once an app host is running, the CLI MCP server connects to a Unix socket located at $HOME/.aspire/mcp/backchannels/mcp.[hash].socket. It uses this JSON-RPC backchannel to retrieve the Dashboard MCP endpoint URL and the required API token, then forwards tool calls to the Dashboard via HTTPS.

Identity overrides via environment variables or the .aspire-install.json sidecar are local to the running process and have the following constraints:

• Sidecar Location: The sidecar is read from <binaryDir>/.aspire-install.json. It is never read from the current working directory (CWD), preventing local directory attacks.
• No NuGet Impact: Identity overrides do not change how NuGet resolves packages; NuGet configuration remains the source of truth.
• No Privilege Escalation: Overrides cannot bypass code signing or escalate process privileges.
• Process Isolation: Identity overrides are intended to be stripped at peer-process and AppHost-spawn boundaries to prevent accidental leakage.

Aspire client integrations are .NET NuGet packages designed as highly usable libraries for connecting to various technologies. They provide production-ready features including:

• Telemetry: Built-in observability.
• Health Checks: Readiness and liveness monitoring.
• Configurability: Easy setup via IConfiguration.
• Testability: Designed to work well in testing environments.

Each integration is typically a standalone NuGet package following the Aspire.<Technology> naming convention (e.g., Aspire.StackExchange.Redis).