Smp.Core.AzureAppConfiguration 1.0.2

Smp.Core.AzureAppConfiguration

A simplified Azure App Configuration provider for .NET applications. This package wraps Microsoft.Extensions.Configuration.AzureAppConfiguration with opinionated defaults, making it easy to load keys from one or more Azure App Configuration stores — with environment-label support and Azure Key Vault reference resolution — using a single appsettings.json block.

Table of Contents

• Installation
• How It Works
• Authentication Setup
• appsettings.json Configuration
• Usage by Project Type
  • ASP.NET Core (Web API / MVC / Minimal API)
  • Worker Service / Console (.NET Generic Host)
  • Azure Functions (Isolated Worker)
• Key Selection and Labels
• Multiple Stores

Installation

dotnet add package Smp.Core.AzureAppConfiguration

How It Works

The package exposes a single extension method on IConfigurationBuilder, living in the Microsoft.Extensions.Configuration.AzureAppConfiguration namespace so no extra using statement is required:

IConfigurationBuilder AddAppConfiguration(bool? addAppSettings = default, string? hostEnvironment = default)

The method reads the AppConfigurations array from the loaded configuration and connects to each Azure App Configuration endpoint via DefaultAzureCredential, selecting the specified keys. If no endpoints are configured it returns immediately without connecting to Azure.

Authentication Setup

This package uses DefaultAzureCredential, which resolves credentials in the following order:

1. Environment variables
2. Workload Identity (AKS)
3. Managed Identity (Azure-hosted apps)
4. Visual Studio credential
5. Azure CLI credential (az login)
6. Azure PowerShell credential

Local development: Sign in with az login or through Visual Studio → Tools → Options → Azure Service Authentication.

Deployed environments: Assign the application's Managed Identity the App Configuration Data Reader role on each Azure App Configuration resource. If keys reference Azure Key Vault secrets, also assign the Key Vault Secrets User role on the relevant vaults.

appsettings.json Configuration

Add an AppConfigurations array to appsettings.json. Each element targets one Azure App Configuration store.

{
  "AppConfigurations": [
    {
      "Endpoint": "https://<your-store-name>.azconfig.io",
      "Keys": [
        "*"
      ]
    }
  ]
}

Configuration Properties

Key Filter Examples

Usage by Project Type

ASP.NET Core (Web API / MVC / Minimal API)

WebApplication.CreateBuilder automatically loads appsettings.json and appsettings.{env}.json, so only hostEnvironment needs to be provided.

Modify Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddAppConfiguration(hostEnvironment: builder.Environment.EnvironmentName);

// ... register services

var app = builder.Build();

// ... configure pipeline

app.Run();

appsettings.json — add the AppConfigurations section alongside your existing configuration:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "AppConfigurations": [
    {
      "Endpoint": "https://<your-store-name>.azconfig.io",
      "Keys": [ "MyApp:*" ]
    }
  ]
}

Worker Service / Console (.NET Generic Host)

Both Host.CreateApplicationBuilder and Host.CreateDefaultBuilder automatically load appsettings.json and appsettings.{env}.json, so only hostEnvironment needs to be provided.

Using Host.CreateApplicationBuilder (.NET 8+)

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration
    .AddAppConfiguration(hostEnvironment: builder.Environment.EnvironmentName);

builder.Services.AddHostedService<Worker>();

var host = builder.Build();
host.Run();

Using Host.CreateDefaultBuilder

var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        config.AddAppConfiguration(hostEnvironment: context.HostingEnvironment.EnvironmentName);
    })
    .ConfigureServices(services =>
    {
        services.AddHostedService<Worker>();
    })
    .Build();

host.Run();

appsettings.json:

{
  "AppConfigurations": [
    {
      "Endpoint": "https://<your-store-name>.azconfig.io",
      "Keys": [ "MyWorker:*" ]
    }
  ]
}

Azure Functions (Isolated Worker)

new HostBuilder() does not load any JSON files automatically. Pass addAppSettings: true so the method loads appsettings.json before connecting to Azure.

In Program.cs:

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureAppConfiguration((context, config) =>
    {
        config.AddAppConfiguration(addAppSettings: true, hostEnvironment: context.HostingEnvironment.EnvironmentName);
    })
    .Build();

host.Run();

local.settings.json — used only for local development and not deployed:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
  }
}

appsettings.json — Azure Functions projects do not include this file by default. Create it at the project root:

{
  "AppConfigurations": [
    {
      "Endpoint": "https://<your-store-name>.azconfig.io",
      "Keys": [ "MyFunction:*" ]
    }
  ]
}

Because the Functions runtime reads files from the output directory, appsettings.json must be copied on every build. Add the following ItemGroup to your .csproj:

<ItemGroup>
  <Content Include="appsettings.json">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Content>
</ItemGroup>

Key Selection and Labels

When hostEnvironment is provided, keys are loaded in two passes:

1. No label (null) — loads the shared default value for each key.
2. Environment label — loads the environment-specific value (e.g., Development, Staging, Production), which overrides the default.

This means you can store a default value in Azure App Configuration with no label and then override it per environment by adding the same key with the appropriate label.

Example for key MyApp:ApiUrl:

When running in Production, the app receives https://api.example.com. In any other environment it falls back to https://api.default.example.com.

Multiple Stores

To pull keys from more than one Azure App Configuration store, add additional entries to the AppConfigurations array:

{
  "AppConfigurations": [
    {
      "Endpoint": "https://<shared-store>.azconfig.io",
      "Keys": [ "Shared:*" ]
    },
    {
      "Endpoint": "https://<app-store>.azconfig.io",
      "Keys": [ "MyApp:*" ]
    }
  ]
}

Stores are processed in array order. If the same key exists in multiple stores, the last store wins.