DontPanicLabs.Ifx.Configuration.Local 2.1.0

Local Configuration

This project supports four configuration sources:

• The appsettings.json file
• The appsettings.{env}.json file
• The .NET User Secrets store
• Environment variables

appsettings.json

First the Config class loads the appsettings.json file, if included in the project. Values from appsettings.json will be overriden by values loaded from appsettings.{env}.json, user secrets and environment variables.

appsettings.{env}.json

Next the Config class tries to get the DOTNET_ENVIRONMENT or the ASPNETCORE_ENVIRONMENT variable, in that respective order, and adds the appsettings.{env}.json if it exists. Values from appsettings.{env}.json will be overriden by values loaded from user secrets and environment variables.

User Secrets

The recommended method for managing configuration in a development environment is to use User Secrets: https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets?view=aspnetcore-8.0&tabs=windows.

User secrets are stored outside of the project directory, so they are not checked into source control. The Config class will load user secrets after loading appsettings.json and the appsettings.{env}.json files.

In order to load user secrets, you must specify the secrets file name in the ifx section of the config:

{
  "appSettings": { },
  "ifx": { 
    "userSecretsId": "dpl.ifx.configuration.tests" 
  }
}

The user secrets file name is specified in the project file.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <UserSecretsId>dpl.ifx.configuration.tests</UserSecretsId>
</PropertyGroup>

Environment Variables

The Config class checks the appsettings.json file for the presence of the skipEnvironmentVariables entry. If this entry is found, and it is set to true, environment variables will not be loaded. Otherwise, environment variables will be loaded last, and will override any values loaded from the other configuration sources.

{
    "skipEnvironmentVariables": true,
    "ifx": {},
    "appsettings": {}
}

This setting is primarily intended to ensure consistent environment configuration for testing purposes.

Configuration Sections

ifx

The ifx section is intended for infrastructure items that do not directly relate to business operation of the application. Items such as connection strings, service endpoints, secret keys, etc.

appsettings

The appsettings section is intended for configuration items that affect the operation of the business/domain logic of the application. Items such as feature flags, business rules, etc.

Configuration Exceptions

When the config initializes, it requires the presence of the ifx and appsettings sections. If either of these sections are missing, the config will throw an exception.

Due to how the .NET configuration libraries work, the following will not result in a valid config file:

{
    "ifx": { },
    "appsettings": { }
}

The ifx and appsettings sections must contain at least one key-value pair. This will prevent the config from throwing an exception if no configuration has been specified for the application:

{
    "ifx": { 
        "_": "" 
    },
    "appsettings": { 
        "_": "" 
    }
}

Development Setup

In a development setting, the following is the recommended approach to managing configuration:

appsettings.json

{
    "ifx": {
        "userSecretsId": "location.specified.in.project.file"
    }
}

location.specified.in.project.file/secrets.json

{
    "ifx": {
        "Secret": "secret_value",
    },
    "appSettings": {
        "Application_Setting": "value",
        "Add more setting": "add some more"
    }
}