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

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.

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

    Screenshot of the Aspire dashboard with web frontend and API service resources.

  2. Click the URL of the web frontend. You see a page with a welcome message.

    Screenshot of a web app with a welcome message.

Add Azure App Configuration to the Aspire solution

  1. 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

  2. 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.

  3. 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. Screenshot of Aspire dashboard asking for Azure Subscription information.

    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.

  4. 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

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

    Screenshot of Aspire dashboard provisioning Azure App Configuration resource.

  6. Wait for a few minutes and you see the Azure App Configuration resource is provisioned and is running.

    Screenshot of Aspire dashboard with Azure App Configuration resource running.

  7. 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.

    Screenshot of Azure portal showing the App Configuration deployment is complete.

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!

Add Azure App Configuration to the Aspire solution

  1. 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

  2. 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.

  3. 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.

  4. 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

  5. Start your container runtime. In this tutorial, we use Docker Desktop.

  6. Run the AppHost project. Go to the Aspire dashboard. You see the App Configuration emulator resource is running.

    Screenshot of the Aspire dashboard showing the App Configuration emulator resource.

    A container is started to run the App Configuration emulator.

    Screenshot of the docker desktop running a container.

Add a key-value

  1. Click the URL of the appconfiguration resource. You see the App Configuration emulator UI.

  2. Click the Create button on the upper-right corner.

    Screenshot of the App Configuration emulator UI.

  3. Add the following key-value.

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

  4. Click the Save button.

    Screenshot of the App Configuration emulator UI of creating a new key value.

Use App Configuration in the web application

  1. 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

  2. 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

  3. 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;
    }
}

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

    Screenshot of Aspire dashboard showing resources.

  5. You see a page with a welcome message from Azure App Configuration.

    Screenshot of a web app with a welcome message from Azure App Configuration.

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.

Enable dynamic configuration

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

Use feature flags in Aspire

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

Azure App Configuration emulator overview

  • Last updated on