Configuration

ASP.NET Core uses the built-in configuration mechanism to store application settings. Bulletcode.NET extends this mechanism and makes it possible to use it also in desktop applications.

Configuration sources

Application settings are stored in appsettings.json and appsettings.ENV.json files, where ENV is the name of the environment, such as Production or Development. Those files are stored in source code repository and shouldn’t contain any sensitive information, such as passwords and keys used in production.

To make it easier to modify the application settings during development, Bulletcode.NET also uses a third settings file called appsettings.local.json. This file should be added to .gitignore to make sure that it’s not added to the source repository. It should be copied to the output directory when building the application, but it shouldn’t be included when publishing. In order to do that, the following section should be added to the .csproj file:

<ItemGroup>
    <Content Remove="appsettings.local.json" />
    <None Include="appsettings.local.json" Condition="Exists('appsettings.local.json')"
        CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="Never" />
</ItemGroup>

In desktop applications, the appsettings.local.json is automatically registered by the application builder, but in web applications it should be added manually:

builder.Configuration.AddJsonFile( "appsettings.local.json", optional: true, reloadOnChange: true );

The appsettings.local.json file can also be used in production to store application settings which are not included in the base appsettings.json file, to make sure that they are not overwritten when a new version of the application is installed. In case of web applications published as Azure App Services, a better solution is to use the environment variables to override application settings, because they can be easily modified using the Azure Portal.

During development, a launchSettings.json file can be used to configure launch profiles for running a project from Visual Studio. In web applications, the ASPNETCORE_ENVIRONMENT variable can be used to set the environment to Development. It is also possible to change the local port on which the application runs and enable hot reload when the application is recompiled. In case of desktop applications, the DOTNET_ENVIRONMENT variable can be used to set the environment to Development.

Built-in configuration sections

In addition to standard sections of the appsettings.json file, such as ConnectionStrings and Logging, Bulletcode.NET also defines various custom sections which can be used to override the default framework settings.

The following sections can be used in both web and desktop applications:

CatalogProviderOptions — the location of .mo files; see Internationalization
LanguageOptions — the default language and available translations; see Internationalization

The following sections can be used in web applications:

AssetBundles — Vite and development asset bundles; see Assets
Authentication — cookie, token and API key authentication providers; see Authentication
SqlSessionOptions — session options; see Session
ServerOptions — base server URL used for composing emails; see Mail
MailOptions — SMTP server for sending emails; see Mail
StorageOptions — file storage service; see Storage

The following sections are available in desktop applications:

ApiClientOptions — to configure API client options; see API Client

Custom configuration sections

The application can define custom configuration sections by calling ConfigureSection(). For example:

services.Configure<MyOptions>( options => {
    options.Text = "hello";
    options.Number = 123;
    options.Boolean = true;
} );

services.ConfigureSection<MyOptions>();

The MyOptions object is initialized with default values, and the appsettings.json section with the same name can be used to override selected properties, for example:

{
  "MyOptions": {
    "Number": 42
  }
}

The IOptions<MyOptions> service can then be used by the application to retrieve the options object.

By default, the name of the section is the same as the name of the class containing the options, but a custom name can be passed to ConfigureSection().

The ConfigureSubsection() method works in a similar way, but the options are read from the given subsection of the appsettings.json file instead.

In web applications, the AddConfiguration() extension method must be called to make the root IConfiguration object available for ConfigureSection() and ConfigureSubsection(). In desktop application, this method is automatically called by the application builder.