title	Quickstart for Azure App Configuration with Aspire
description	Create an Aspire solution with Azure App Configuration to centralize storage and management of application settings.
services	azure-app-configuration
author	zhiyuanliang-ms
ms.service	azure-app-configuration
ms.devlang	csharp
ms.custom	devx-track-csharp, mode-other
ms.topic	quickstart
ms.date	12/3/2025
zone_pivot_groups	appconfig-aspire
ms.author	zhiyuanliang

Quickstart: Create an Aspire solution with Azure App Configuration

In this quickstart, you'll use Azure App Configuration to externalize storage and management of your app settings for an Aspire project. You will use Azure App Configuration Aspire integration libraries to provision an App Configuration resource and use App Configuration in each distributed app.

Prerequisites

An Azure account with an active subscription. Create one for free.
Set up the development environment for Aspire.
Create a new Aspire solution using the Aspire Starter template.
An OCI compliant container runtime, such as Docker Desktop.

Test the app locally

The Aspire Starter template includes a frontend web app that communicates with a Minimal API project. The API project is used to provide fake weather data to the frontend. The frontend app is configured to use service discovery to connect to the API project. There is also an AppHost project which orchestrates all distributed applications in the Aspire solution.

Run the AppHost project. You see the Aspire dashboard in your browser.

:::image type="content" source="media/aspire/dashboard.png" alt-text="Screenshot of the Aspire dashboard with web frontend and API service resources." lightbox="media/aspire/dashboard.png":::
Click the URL of the web frontend. You see a page with a welcome message.

:::image type="content" source="media/aspire/web-app.png" alt-text="Screenshot of a web app with a welcome message." lightbox="media/aspire/web-app.png":::

:::zone target="docs" pivot="azure"

Add Azure App Configuration to the Aspire solution

Navigate into to the AppHost project's directory. Run the following command to add the Aspire.Hosting.Azure.AppConfiguration Nuget package.
```
dotnet add package Aspire.Hosting.Azure.AppConfiguration
```
Open the AppHost.csproj file to verify packages. You should see a package named Aspire.Hosting.AppHost being referenced. Ensure that the Aspire.Hosting.AppHost package version is at least as high as the version of Aspire.Hosting.Azure.AppConfiguration that was installed.
Open the AppHost.cs file and add the following code.
```
var builder = DistributedApplication.CreateBuilder(args);

// Add an Azure App Configuration resource
var appConfiguration = builder.AddAzureAppConfiguration("appconfiguration");
```
[!IMPORTANT] When you call AddAzureAppConfiguration, you instruct the app to generate Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local Azure provisioning. If you are using the latest Aspire SDK, you can configure the subscription information through the Aspire dashboard. :::image type="content" source="media/aspire/azure-subscription.png" alt-text="Screenshot of Aspire dashboard asking for Azure Subscription information." lightbox="media/aspire/azure-subscription.png":::

[!NOTE] You must have either the Owner or User Access Administrator role assigned on the Azure subscription. These roles are required to create role assignments as part of the provisioning process.

[!TIP] You can reference existing App Configuration resources by chaining a call RunAsExisting() on builder.AddAzureAppConfiguration("appconfig"). For more information, go to Use existing Azure resources.

Add the reference of App Configuration resource and configure the webfrontend project to wait for it.

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(apiService)
    .WaitFor(apiService)
    .WithReference(appConfiguration) // reference the App Configuration resource
    .WaitFor(appConfiguration); // wait for the App Configuration resource to enter the Running state before starting the resource

Run the AppHost project. You see the Azure App Configuration resource is provisioning.

:::image type="content" source="media/aspire/resource-provisioning.png" alt-text="Screenshot of Aspire dashboard provisioning Azure App Configuration resource." lightbox="media/aspire/resource-provisioning.png":::
Wait for a few minutes and you see the Azure App Configuration resource is provisioned and is running.

:::image type="content" source="media/aspire/resource-provisioned.png" alt-text="Screenshot of Aspire dashboard with Azure App Configuration resource running." lightbox="media/aspire/resource-provisioned.png":::
Go to the Azure portal by clicking the deployment URL on the Aspire dashboard. You see the deployment is complete and you can go to your Azure App Configuration resource.

:::image type="content" source="media/aspire/deployment-complete.png" alt-text="Screenshot of Azure portal showing the App Configuration deployment is complete." lightbox="media/aspire/deployment-complete.png":::

Add a key-value

Add the following key-value to your App Configuration store and leave Label and Content Type with their default values. For more information about how to add key-values to a store using the Azure portal or the CLI, go to Create a key-value.

Key	Value
TestApp:Settings:Message	Hello from Azure App Configuration!

:::zone-end

:::zone target="docs" pivot="emulator"

Add Azure App Configuration to the Aspire solution

Navigate into to the AppHost project's directory. Run the following command to add the Aspire.Hosting.Azure.AppConfiguration Nuget package.
```
dotnet add package Aspire.Hosting.Azure.AppConfiguration
```
Open the AppHost.csproj. Make sure that the Aspire.Hosting.AppHost package version is not earlier than the version you installed. Otherwise, you need to upgrade the Aspire.Hosting.AppHost package.
Open the AppHost.cs file and add the following code.
```
var builder = DistributedApplication.CreateBuilder(args);

// Add an Azure App Configuration resource
var appConfiguration = builder.AddAzureAppConfiguration("appconfiguration")
    .RunAsEmulator(emulator => { // use the App Configuration emulator
        emulator.WithDataBindMount();
    });
```
[!IMPORTANT] When you call RunAsEmulator, it pulls the App Configuration emulator image and runs a container as the App Configuration resource. Make sure that you have an OCI compliant container runtime on your machine. For more information, go to Aspire Container Runtime.

[!TIP] You can call WithDataBindMount or WithDataVolume to configure the emulator resource for persistent container storage so that you don't need to recreate key values each time.

Add the reference of App Configuration resource and configure the webfrontend project to wait for it.

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(apiService)
    .WaitFor(apiService)
    .WithReference(appConfiguration) // reference the App Configuration resource
    .WaitFor(appConfiguration); // wait for the App Configuration resource to enter the Running state before starting the resource

Start your container runtime. In this tutorial, we use Docker Desktop.
Run the AppHost project. Go to the Aspire dashboard. You see the App Configuration emulator resource is running.

:::image type="content" source="media/aspire/dashboard-emulator.png" alt-text="Screenshot of the Aspire dashboard showing the App Configuration emulator resource." lightbox="media/aspire/dashboard-emulator.png":::

A container is started to run the App Configuration emulator.

:::image type="content" source="media/aspire/docker.png" alt-text="Screenshot of the docker desktop running a container." lightbox="media/aspire/docker.png":::

Add a key-value

Click the URL of the appconfiguration resource. You see the App Configuration emulator UI.
Click the Create button on the upper-right corner.

:::image type="content" source="media/aspire/emulator-ui.png" alt-text="Screenshot of the App Configuration emulator UI.":::
Add the following key-value.

Key Value

TestApp:Settings:Message Hello from Azure App Configuration!
Click the Save button.

:::image type="content" source="media/aspire/emulator-create-key.png" alt-text="Screenshot of the App Configuration emulator UI of creating a new key value." lightbox="media/aspire/emulator-create-key.png":::

:::zone-end

Use App Configuration in the web application

Navigate into to the Web project's directory. Run the following command to add the Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration Nuget package.
```
dotnet add package Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration
```

Open the Program.cs file and add the following code.

var builder = WebApplication.CreateBuilder(args);

// Use Azure App Configuration
builder.AddAzureAppConfiguration("appconfiguration"); // use the resource name defined in the AppHost project

Open the Components/Pages/Home.razor file and update it with the following code.

@page "/"

@inject IConfiguration Configuration

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

@if (!string.IsNullOrWhiteSpace(message))
{
    <div class="alert alert-info">@message</div>
}
else
{
    <div class="alert alert-info">Welcome to your new app.</div>
}

@code {
    private string? message;

    protected override void OnInitialized()
    {
        string msg = Configuration["TestApp:Settings:Message"];
        message = string.IsNullOrWhiteSpace(msg) ? null : msg;
    }
}

Restart the AppHost project. Go to the Aspire dashboard and click the URL of the web frontend.

:::image type="content" source="media/aspire/dashboard-updated.png" alt-text="Screenshot of Aspire dashboard showing resources." lightbox="media/aspire/dashboard-updated.png":::
You see a page with a welcome message from Azure App Configuration.

:::image type="content" source="media/aspire/web-app-message.png" alt-text="Screenshot of a web app with a welcome message from Azure App Configuration." lightbox="media/aspire/web-app-message.png":::

Next steps

In this quickstart, you:

Added an Azure App Configuration resource in an Aspire solution.
Read your key-values from Azure App Configuration with the App Configuration Aspire integration library.
Displayed a web page using the settings you configured in your App Configuration.

To learn how to configure your Aspire app to dynamically refresh configuration settings, continue to the next tutorial.

[!div class="nextstepaction"] Enable dynamic configuration

To learn how to use feature flags in your Aspire app, continue to the next tutorial.

[!div class="nextstepaction"] Use feature flags in Aspire

To learn more about the Azure App Configuration emulator, continue to the following document.

[!div class="nextstepaction"] Azure App Configuration emulator overview

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Quickstart: Create an Aspire solution with Azure App Configuration

Prerequisites

Test the app locally

Add Azure App Configuration to the Aspire solution

Add a key-value

Add Azure App Configuration to the Aspire solution

Add a key-value

Use App Configuration in the web application

Next steps

FilesExpand file tree

quickstart-aspire.md

Latest commit

History

quickstart-aspire.md

File metadata and controls

Quickstart: Create an Aspire solution with Azure App Configuration

Prerequisites

Test the app locally

Add Azure App Configuration to the Aspire solution

Add a key-value

Add Azure App Configuration to the Aspire solution

Add a key-value

Use App Configuration in the web application

Next steps