Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
219 lines (158 sloc) 8.8 KB
title description services documentationcenter author manager editor ms.assetid ms.service ms.devlang ms.topic ms.tgt_pltfrm ms.workload
Quickstart for Azure App Configuration with ASP.NET Core | Microsoft Docs
A quickstart for using Azure App Configuration with ASP.NET Core apps

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

In this quickstart, you incorporate Azure App Configuration into an ASP.NET Core app to centralize storage and management of application settings separate from your code. ASP.NET Core builds a single key-value-based configuration object by using settings from one or more data sources that are specified by an application. These data sources are known as configuration providers. Because App Configuration's .NET Core client is implemented as such a provider, the service appears like another data source.


Create an App Configuration store

[!INCLUDE azure-app-configuration-create]

  1. Select Configuration Explorer > + Create to add the following key-value pairs:

    Key Value
    TestApp:Settings:BackgroundColor White
    TestApp:Settings:FontSize 24
    TestApp:Settings:FontColor Black
    TestApp:Settings:Message Data from Azure App Configuration

    Leave Label and Content Type empty for now.

Create an ASP.NET Core web app

You use the .NET Core command-line interface (CLI) to create a new ASP.NET Core MVC web app project. The advantage of using the .NET Core CLI over Visual Studio is that it's available across the Windows, macOS, and Linux platforms.

  1. Create a new folder for your project. For this quickstart, name it TestAppConfig.

  2. In the new folder, run the following command to create a new ASP.NET Core MVC web app project:

        dotnet new mvc --no-https

Add Secret Manager

To use Secret Manager, add a UserSecretsId element to your .csproj file.

  • Open the .csproj file. Add a UserSecretsId element as shown here. You can use the same GUID, or you can replace this value with your own. Save the file.

    <Project Sdk="Microsoft.NET.Sdk.Web">
        <PackageReference Include="Microsoft.AspNetCore.App" />
        <PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.1.2" PrivateAssets="All" />

The Secret Manager tool stores sensitive data for development work outside of your project tree. This approach helps prevent the accidental sharing of app secrets within source code. For more information on Secret Manager, please see Safe storage of app secrets in development in ASP.NET Core

Connect to an App Configuration store

  1. Add a reference to the Microsoft.Azure.AppConfiguration.AspNetCore NuGet package by running the following command:

        dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore --version 2.0.0-preview-010060003-1250
  2. Run the following command to restore packages for your project:

        dotnet restore
  3. Add a secret named ConnectionStrings:AppConfig to Secret Manager.

    This secret contains the connection string to access your App Configuration store. Replace the value in the following command with the connection string for your App Configuration store.

    This command must be executed in the same directory as the .csproj file.

        dotnet user-secrets set ConnectionStrings:AppConfig <your_connection_string>

    [!IMPORTANT] Some shells will truncate the connection string unless it is enclosed in quotes. Ensure that the output of the dotnet user-secrets command shows the entire connection string. If it doesn't, rerun the command, enclosing the connection string in quotes.

    Secret Manager is used only to test the web app locally. When the app is deployed to Azure App Service, for example, you use an application setting Connection Strings in App Service instead of with Secret Manager to store the connection string.

    This secret is accessed with the configuration API. A colon (:) works in the configuration name with the configuration API on all supported platforms. See Configuration by environment.

  4. Open Program.cs, and add a reference to the .NET Core App Configuration provider.

    using Microsoft.Extensions.Configuration.AzureAppConfiguration;
  5. Update the CreateWebHostBuilder method to use App Configuration by calling the config.AddAzureAppConfiguration() method.

    [!IMPORTANT] CreateHostBuilder replaces CreateWebHostBuilder in .NET Core 3.0. Select the correct syntax based on your environment.

    Update CreateWebHostBuilder for .NET Core 2.x

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            .ConfigureAppConfiguration((hostingContext, config) =>
                var settings = config.Build();

    Update CreateHostBuilder for .NET Core 3.x

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        .ConfigureWebHostDefaults(webBuilder =>
        webBuilder.ConfigureAppConfiguration((hostingContext, config) =>
            var settings = config.Build();
  6. Open Index.cshtml in the Views > Home directory, and replace its content with the following code:

    @using Microsoft.Extensions.Configuration
    @inject IConfiguration Configuration
        body {
            background-color: @Configuration["TestApp:Settings:BackgroundColor"]
        h1 {
            color: @Configuration["TestApp:Settings:FontColor"];
            font-size: @Configuration["TestApp:Settings:FontSize"];
  7. Open _Layout.cshtml in the Views > Shared directory, and replace its content with the following code:

    <!DOCTYPE html>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>@ViewData["Title"] - hello_world</title>
        <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
        <link rel="stylesheet" href="~/css/site.css" />
        <div class="container body-content">
        <script src="~/lib/jquery/dist/jquery.js"></script>
        <script src="~/lib/bootstrap/dist/js/bootstrap.js"></script>
        <script src="~/js/site.js" asp-append-version="true"></script>
        @RenderSection("Scripts", required: false)

Build and run the app locally

  1. To build the app by using the .NET Core CLI, run the following command in the command shell:

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

        dotnet run
  3. Open a browser window, and go to http://localhost:5000, which is the default URL for the web app hosted locally.

Clean up resources

[!INCLUDE azure-app-configuration-cleanup]

Next steps

In this quickstart, you created a new App Configuration store and used it with an ASP.NET Core web app via the App Configuration provider. To learn how to configure your ASP.NET Core app to dynamically refresh configuration settings, continue to the next tutorial.

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

You can’t perform that action at this time.