DOCSEARCHbyAlgolia
Submit Docs

.NET Aspire Documentation

repository·main·Indexed 41 days ago

https://github.com/dotnet/docs-aspire

Archived documentation for .NET Aspire, featuring compatibility guides and migration paths for versions 9.0 and 13.0. Includes details on DefaultAzureCredential behavior changes, Azure.Hosting API renames, Python resource updates (AddPythonApp), and pipeline activity reporter migrations.

Tokens
38.9K
Snippets
102
Records
165
Agent score
51%

What's inside .NET Aspire

  2. What is forward compatibility?

    main

    Forward compatibility is the ability of an existing consumer of an API to run against an older version of the API while exhibiting the same behavior.

    Maintaining forward compatibility is extremely difficult because any new features or changes added to a newer version prevent a consumer targeting that version from running on an older version. Maintaining forward compatibility is not a goal of Aspire.

  3. What is source compatibility and how is it broken?

    main

    Source compatibility is the ability for existing consumers of an API to recompile their code against a newer version of the API without needing to modify their source code.

    A source incompatible change occurs when a developer is forced to modify their existing source code in order to achieve a successful build against a newer version of the API.

  4. What is backwards compatibility?

    main

    Backwards compatibility is the ability of an existing consumer of an API to run against a new version of that API while behaving in the same way.

    Backwards compatibility is affected by both behavioral changes and binary compatibility changes. If a consumer behaves differently or fails to run when using a newer version of the API, the API is considered backwards incompatible. In the .NET ecosystem, changes that break backwards compatibility are generally discouraged.

  5. What is binary compatibility and how is it broken?

    main

    Binary compatibility is the ability for a consumer of an API to use that API on a newer version without needing to recompile their own application.

    Compatible changes include:

    • Adding new methods.
    • Adding a new interface implementation to an existing type.

    Incompatible changes (Binary Incompatible) include:

    • Removing public signatures.
    • Altering public signatures so consumers can no longer access the same interface exposed by the assembly.

  7. Use OllamaModelResource for model management in Aspire 9.0

    main

    In Aspire Community Toolkit 9.0, models are now treated as first-class resources using OllamaModelResource. Instead of adding models as metadata to the main Ollama resource, you can now pass an OllamaModelResource as a reference to clients. This allows clients to automatically discover which model to use via the connection string.

    Key changes in 9.0:

    • Models as resources: Use OllamaModelResource to provide connection information about specific models.
    • Connection String Format: The connection string now follows a standard format: Endpoint=<...>;Model=<...>. The Model component is automatically included when an OllamaModelResource is passed as a reference.

  8. Breaking change: DefaultAzureCredential behavior on ACA and App Service in Aspire 13.0

    main

    Starting with Aspire 13.0, when deploying to Azure Container Apps (ACA) or Azure App Service, DefaultAzureCredential no longer uses the full chain of identity providers by default. Instead, it is configured to only use ManagedIdentityCredential.

    This is achieved by Aspire automatically setting the AZURE_TOKEN_CREDENTIALS environment variable during deployment. This change enforces deterministic credential resolution, which improves security, reliability, and performance in production environments by following Azure SDK best practices.

    Previous Behavior: DefaultAzureCredential would attempt multiple providers (e.g., EnvironmentCredential, WorkloadIdentityCredential) before reaching ManagedIdentityCredential.

    New Behavior: DefaultAzureCredential only uses ManagedIdentityCredential because the presence of AZURE_TOKEN_CREDENTIALS restricts the credential chain.

  9. Understand observability and telemetry in Aspire integrations

    main

    Aspire integrations automatically configure the three pillars of observability: Logging, Tracing, and Metrics.

    When using an Aspire integration, these telemetry features are set up for you by default. However, support for these features depends on the specific backing service being used. For instance, an integration might support logging and tracing but lack support for metrics.

    If you need to turn off these features, you can do so using the configuration techniques described in the Aspire configuration documentation.

  10. How `azd` integrates with Aspire projects

    main

    The Azure Developer CLI (azd) uses the Aspire manifest to automate the provisioning and deployment of resources to Azure Container Apps. The workflow follows these steps:

    1. Manifest Generation: azd runs the Aspire AppHost project with a special command (dotnet run --project AppHost.csproj --output-path manifest.json --publisher manifest) to generate an Aspire manifest file.
    2. Infrastructure Provisioning: The azd provision command interrogates the manifest to generate Bicep files (in-memory by default) and uses Azure's ARM APIs to provision the required resources.
    3. Container Building: During deployment, azd calls dotnet publish using .NET's built-in container publishing support to create container images.
    4. Image Registry: azd pushes the generated images to the Azure Container Registry (ACR) created during provisioning.
    5. Deployment: The azd deploy command uses the manifest to update the Azure resources (like Container Apps) to use the new container image versions.

  11. Standard Aspire project directory structure

    main

    A typical .NET Aspire solution follows a multi-project structure designed to separate orchestration, service logic, shared defaults, and frontend components. The core components include:

    • AppHost Project: The orchestration project (e.g., AspireSample.AppHost) that defines how services are started and how they interact. It contains the AppHost.cs file.
    • ServiceDefaults Project: A shared project (e.g., AspireSample.ServiceDefaults) containing common configuration, telemetry, and resilience settings used by all services in the solution.
    • Service Projects: Individual microservices or APIs (e.g., AspireSample.ApiService) that contain the actual business logic.
    • Frontend/Web Project: The user interface project (e.g., AspireSample.Web) that consumes the services defined in the AppHost.
    Directory
└───📂 AspireSample
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── AppHost.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── MainLayout.razor
     │    │    │    ├─── MainLayout.razor.css
     │    │    │    ├─── NavMenu.razor
     │    │    │    └─── NavMenu.razor.css
     │    │    ├───📂 Pages
     │    │    │    ├─── Counter.razor
     │    │    │    ├─── Error.razor
     │    │    │    ├─── Home.razor
     │    │    │    └─── Weather.razor
     │    │    ├─── _Imports.razor
     │    │    ├─── App.razor
     │    │    └─── Routes.razor
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───📂 bootstrap
     │    │    │    ├─── bootstrap.min.css
     │    │    │    └─── bootstrap.min.css.map
     │    │    ├─── app.css
     │    │    └─── favicon.png
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

  12. Understand binary and source compatibility definitions

    main

    When reviewing breaking changes in .NET Aspire, compatibility is categorized into two types:

    • Binary compatible: Your existing compiled binaries will load and execute successfully without needing to be recompiled. The runtime behavior remains unchanged.
    • Source compatible: Your existing source code will compile successfully without any modifications when you target the new runtime, use the new SDK, or switch to the new component.