Dotnet Configuration

Installation

Mon, 01 Jan 0001 00:00:00 +0000

NuGet CLI

nuget install ArturRios.Configuration

Dotnet CLI

dotnet add package ArturRios.Configuration

PackageReference

<ItemGroup>
 <PackageReference Include="ArturRios.Configuration" Version="x.y.z" />
</ItemGroup>

Git submodule (alternative)

git submodule add https://github.com/artur-rios/dotnet-configuration.git external/dotnet-configuration

Then add a project reference:

<ItemGroup>
 <ProjectReference Include="external/dotnet-configuration/src/ArturRios.Configuration.csproj" />
</ItemGroup>

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Load environment variables from .env and appsettings JSON for a given environment:

using ArturRios.Configuration.Loaders;
using Microsoft.Extensions.Configuration;

// Choose your environment name: Local, Development, Staging, Production
var environmentName = "Development";

// Load environment variables from Environments/.env.<environment> (falls back to .env.local)
var envLoader = new ConfigurationLoader(environmentName);
envLoader.LoadEnvironment();

// Build appsettings for the environment from Settings/appsettings.<environment>.json (falls back to appsettings.local.json)
var builder = new ConfigurationBuilder();
var settingsLoader = new ConfigurationLoader(builder, environmentName);
settingsLoader.LoadAppSettings();

var configuration = builder.Build();
var connectionString = configuration["ConnectionStrings:Default"];

Use SettingsProvider to read typed values from configuration:

using ArturRios.Configuration.Providers;

var settings = new SettingsProvider(configuration);
var retries = settings.GetInt("Http:Retries");
var featureEnabled = settings.GetBool("Features:NewUX");
var apiKey = settings.GetString("Api:Key");

Read values from OS environment variables with EnvironmentProvider:

Advanced usage

Mon, 01 Jan 0001 00:00:00 +0000

Folder conventions

Conventions used by the loader, relative to the application’s base directory (AppDomain.CurrentDomain.BaseDirectory) unless you pass a basePath to the constructor:

.env files under Environments/.env.<EnvironmentName>, fallback to Environments/.env.local.
appsettings JSON under Settings/appsettings.<EnvironmentName>.json, fallback to Settings/appsettings.local.json.

The files must therefore be copied to the build output (for example with CopyToOutputDirectory) when the default base directory is used.

File names are matched without regard to case, so .env.Development and .env.development — or appsettings.Local.json and appsettings.local.json — are equally acceptable on every platform. Matching on exact case only resolved on Windows and silently found nothing on a case-sensitive file system.

API overview

Mon, 01 Jan 0001 00:00:00 +0000

ConfigurationLoader (in src/Loaders/ConfigurationLoader.cs): LoadEnvironment() loads the .env file into the process environment, and LoadAppSettings() adds appsettings.<env>.json to the IConfigurationBuilder passed to the constructor, both following the folder conventions.
EnvironmentProvider (in src/Providers/EnvironmentProvider.cs): read and parse OS environment variables to bool/int/string/object.
SettingsProvider (in src/Providers/SettingsProvider.cs): read and parse configuration values to bool/int/string/object. An object is deserialized from a JSON string value, not bound from a section; bind sections with configuration.GetSection(key).Get<T>().
Enums (in src/Enums/):
- ConfigurationSourceType, DataFormatType, DataSource, EnvironmentType, OutputType.

Extensibility

Mon, 01 Jan 0001 00:00:00 +0000

Create a custom source or provider:

Define a new provider class that implements IConfigurationProvider (in src/Providers/Interfaces/).
Add further sources to the same IConfigurationBuilder you passed to ConfigurationLoader; the loader does not expose the builder, so extend the builder rather than the loader.
Respect precedence by adding sources in order.

Example sketch:

public static class ConfigurationBuilderExtensions
{
 public static IConfigurationBuilder AddMySource(this IConfigurationBuilder builder, string endpoint)
 {
 // fetch data from endpoint and add it as a source, e.g. builder.AddInMemoryCollection(values)
 // ...
 return builder;
 }
}