Documentation on 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:

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

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.

Precedence

When building IConfiguration, sources are added in the order you call them on the same IConfigurationBuilder. JSON files added later override earlier ones.

API overview

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

ConfigurationLoader (in src/Loaders/ConfigurationLoader.cs): fluent-style helpers to add .env and appsettings.<env>.json using folder conventions, backing IConfigurationBuilder.
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.
Enums (in src/Enums/):
- ConfigurationSourceType, DataFormatType, EnvironmentType, OutputType.

Extensibility

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

Create a custom source or provider:

Define a new provider class (see src/Providers/Interfaces/ for guidance).
Extend your configuration loader or builder with additional sources as needed.
Respect precedence by adding sources in order.

Example sketch:

public static class ConfigurationLoaderExtensions
{
 public static ConfigurationLoader AddMySource(this ConfigurationLoader loader, string endpoint)
 {
 // fetch data from endpoint, add it to the underlying IConfigurationBuilder
 // ...
 return loader;
 }
}

Project info

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

Acknowledgements

Built on Microsoft.Extensions.Configuration
Uses DotNetEnv for .env support
Thanks to the .NET OSS community

Testing

The test suite is xUnit, and every test is named with the Given / When / Then pattern. Every test class carries a Category trait, so the two kinds can be run — and reported — separately:

dotnet test src/ArturRios.Configuration.sln --filter "Category=Unit"
dotnet test src/ArturRios.Configuration.sln --filter "Category=Functional"

Unit tests exercise the code in isolation against test doubles. Functional tests drive the loader over real .env and appsettings files written to a temporary directory on disk. CI runs the two as separate jobs, and both must pass before a pull request can be merged.