Quickstart: Create an ASP.NET Core app with Azure App Configuration

In this quickstart, you'll use Azure App Configuration to externalize storage and management of your app settings for an ASP.NET Core app. ASP.NET Core builds a single, key-value-based configuration object using settings from one or more configuration providers. App Configuration offers a .NET configuration provider library. Therefore, you can use App Configuration as an extra configuration source for your app. If you have an existing app, to begin using App Configuration, you'll only need a few small changes to your app startup code.

Prerequisites

• Azure subscription - Create a trial subscription
• .NET Core SDK

Add key-values

Add the following key-values to the 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.

Create an ASP.NET Core web app

Use the .NET Core command-line interface (CLI) to create a new ASP.NET Core web app project.

Run the following command to create an ASP.NET Core web app in a new TestAppConfig folder:

dotnet new webapp --output TestAppConfig --framework net6.0

Connect to the App Configuration store

Connect to your App Configuration store using Microsoft Entra ID (recommended), or a connection string.

1. Navigate into the project's directory TestAppConfig, and run the following command to add NuGet package references.

   • Microsoft Entra ID (recommended)
   • Connection string

   dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore
   dotnet add package Azure.Identity
   

2. Run the following command to restore packages for your project:

   dotnet restore
   

3. Create a user secret for the application by navigating into the TestAppConfig folder and running the following command.

   • Microsoft Entra ID (recommended)
   • Connection string

   The command uses Secret Manager to store a secret named Endpoints:AppConfiguration, which stores the endpoint for your App Configuration store. Replace the <your-App-Configuration-endpoint> placeholder with your App Configuration store's endpoint. You can find the endpoint in your App Configuration store's Overview blade in the Azure portal.

   dotnet user-secrets init
   dotnet user-secrets set Endpoints:AppConfiguration "<your-App-Configuration-endpoint>"
   

4. Open Program.cs and add the following namespaces:

   • Microsoft Entra ID (recommended)
   • Connection string

   using Microsoft.Extensions.Configuration;
   using Microsoft.Azure.AppConfiguration.AspNetCore;
   using Azure.Identity;
   

5. Connect to your App Configuration store by calling the AddAzureAppConfiguration method in the Program.cs file.

   • Microsoft Entra ID (recommended)
   • Connection string

   You use the DefaultAzureCredential to authenticate to your App Configuration store. Follow the instructions to assign your credential the App Configuration Data Reader role. Be sure to allow sufficient time for the permission to propagate before running your application.

   var builder = WebApplication.CreateBuilder(args); 
   
   // Load configuration from Azure App Configuration 
   builder.Configuration.AddAzureAppConfiguration(options =>
   {
       string endpoint = builder.Configuration.Get("Endpoints:AppConfiguration");
       options.Connect(new Uri(endpoint), new DefaultAzureCredential());
   });
   
    // The rest of existing code in program.cs
   // ... ...    
   

   This code loads all key-values that have no label from your App Configuration store. For more information on loading data from App Configuration, see the App Configuration provider API reference.

Read from the App Configuration store

In this example, you'll update a web page to display its content using the settings you configured in your App Configuration store.

1. Add a Settings.cs file at the root of your project directory. It defines a strongly typed Settings class for the configuration you're going to use. Replace the namespace with the name of your project.

   namespace TestAppConfig
   {
       public class Settings
       {
           public string BackgroundColor { get; set; }
           public long FontSize { get; set; }
           public string FontColor { get; set; }
           public string Message { get; set; }
       }
   }
   

2. Bind the TestApp:Settings section in configuration to the Settings object.

   Update Program.cs with the following code and add the TestAppConfig namespace at the beginning of the file.

   using TestAppConfig;
   
   // Existing code in Program.cs
   // ... ...
   
   builder.Services.AddRazorPages();
   
   // Bind configuration "TestApp:Settings" section to the Settings object
   builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));
   
   var app = builder.Build();
   
   // The rest of existing code in program.cs
   // ... ...
   

3. Open Index.cshtml.cs in the Pages directory, and update the IndexModel class with the following code. Add the using Microsoft.Extensions.Options namespace at the beginning of the file, if it's not already there.

   public class IndexModel : PageModel
   {
       private readonly ILogger<IndexModel> _logger;
   
       public Settings Settings { get; }
   
       public IndexModel(IOptionsSnapshot<Settings> options, ILogger<IndexModel> logger)
       {
           Settings = options.Value;
           _logger = logger;
       }
   }
   

4. Open Index.cshtml in the Pages directory, and update the content with the following code.

   @page
   @model IndexModel
   @{
       ViewData["Title"] = "Home page";
   }
   
   <style>
       body {
           background-color: @Model.Settings.BackgroundColor;
       }
   
       h1 {
           color: @Model.Settings.FontColor;
           font-size: @(Model.Settings.FontSize)px;
       }
   </style>
   
   <h1>@Model.Settings.Message</h1>
   

Build and run the app locally

1. To build the app using the .NET CLI, navigate to the root directory of your project. Run the following command in the command shell:

   dotnet build
   

2. After the build completes successfully, run the following command to run the web app locally:

   dotnet run
   

3. Open a browser and navigate to the URL the app is listening on, as specified in the command output. It looks like https://localhost:5001.

   The web page will look like this:

Clean up resources

If you don't want to continue using the resources created in this article, delete the resource group you created here to avoid charges.

1. Sign in to the Azure portal, and select Resource groups.
2. In the Filter by name box, enter the name of your resource group.
3. In the result list, select the resource group name to see an overview.
4. Select Delete resource group.
5. You're asked to confirm the deletion of the resource group. Enter the name of your resource group to confirm, and select Delete.

After a few moments, the resource group and all its resources are deleted.

Next steps

In this quickstart, you:

• Provisioned a new App Configuration store.
• Connected to your App Configuration store using the App Configuration provider library.
• Read your App Configuration store's key-values with the configuration provider library.
• Displayed a web page using the settings you configured in your App Configuration store.

To learn how to configure your ASP.NET Core web app to dynamically refresh configuration settings, continue to the next tutorial.