Application settings

This document provides a comprehensive guide to configuring TheExampleApp using the appsettings.json files and other configuration sources. Understanding this configuration is essential for local development, deployment, and maintenance. The application leverages the standard ASP.NET Core configuration system, which provides a flexible, hierarchical approach to managing settings.

For a guide on setting up your local environment, please refer to the Local Setup Guide.

appsettings.json

The primary configuration is managed through a set of JSON files. The base file, appsettings.json, contains default settings and configuration values that are common across all environments. It serves as the foundation upon which environment-specific settings are layered.

The root appsettings.json file defines the default logging level and the primary Contentful space credentials.

{
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "ContentfulOptions": {
    "DeliveryApiKey": "df2a18b8a5b4426741408fc95fa4331c7388d502318c44a5b22b167c3c1b1d03",
    "PreviewApiKey": "10145c6d864960fdca694014ae5e7bdaa7de514a1b5d7fd8bd24027f90c49bbc",
    "SpaceId": "qz0n5cdakyl9",
    "UsePreviewApi": false
  }
}

Configuration structure

The configuration is organized into logical sections within the JSON files. The two primary sections are Logging and ContentfulOptions.

Logging configuration

The Logging section controls the verbosity of application logs. The configuration in appsettings.json sets the default log level to Warning, which is suitable for a production environment to avoid excessive log noise.

"Logging": {
  "IncludeScopes": false,
  "LogLevel": {
    "Default": "Warning"
  }
}

During development, this is overridden in appsettings.Development.json to provide more detailed output for debugging purposes.

ContentfulOptions section

This section contains all the necessary settings to connect to the Contentful headless CMS, which serves as the application's primary data source. These settings are bound to a configuration object and used by the contentful.aspnetcore SDK.

The configuration is registered with the dependency injection container in Startup.cs:

// File: TheExampleApp/Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddContentful(Configuration);
    // ...
}

The ContentfulOptions object has the following properties:

Key	Type	Description
DeliveryApiKey	string	The API key for accessing published content from the Contentful Delivery API. This is the standard key for production use.
PreviewApiKey	string	The API key for accessing unpublished, draft content from the Contentful Preview API.
SpaceId	string	The unique identifier for the Contentful space that holds the application's content.
UsePreviewApi	boolean	A flag that, when set to true, instructs the SDK to use the PreviewApiKey and connect to the Preview API endpoint. This is useful for staging environments or for previewing content changes before they are published.

For more details on acquiring these keys and setting up a Contentful space, see the Contentful Setup Guide.

Environment-specific settings

ASP.NET Core's configuration system is environment-aware. The application will load a specific appsettings.{Environment}.json file based on the ASPNETCORE_ENVIRONMENT environment variable (e.g., Development, Staging, Production). Settings in these files will override the values from the base appsettings.json.

appsettings.Development.json

For the Development environment, the configuration is optimized for debugging. The logging level is increased to Debug to provide maximum insight into the application's behavior.

// File: TheExampleApp/appsettings.Development.json
{
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

Note: This file only overrides the Logging section. The ContentfulOptions are inherited from the base appsettings.json file for local development.

appsettings.Staging.json

The Staging environment uses a completely separate Contentful space, as defined in appsettings.Staging.json. This allows for testing with a dedicated dataset that mirrors production without affecting live content.

// File: TheExampleApp/appsettings.Staging.json
{
  "Logging": {
    // ... same as Development
  },
  "ContentfulOptions": {
    "DeliveryApiKey": "3048cf48001c0a5f2d0cdd2135f4fa7b80f93e36452381a0a32b0f81c8ca8063",
    "PreviewApiKey": "d477447bd0ba58db88009e5eae6d033d524730a700010952f30300d7810b861a",
    "SpaceId": "9leupbwh43vu",
    "UsePreviewApi": false
  }
}

Environment variable overrides

Environment variables are a critical part of the configuration, especially for production and CI/CD environments. They can override any setting from the appsettings.*.json files. This is the recommended practice for handling secrets like API keys, as it avoids committing them to source control.

For more information, see the guide on Environment Variables in Deployment.

A specific example of an environment variable being used is found in Startup.cs for the Staging environment:

// File: TheExampleApp/Startup.cs

if (CurrentEnvironment.IsStaging())
{
    var host = Environment.GetEnvironmentVariable("StagingHost");
    if (!string.IsNullOrEmpty(host))
    {
        services.AddSingleton((ip) =>
        {
            var stagingHandler = new StagingMessageHandler
            {
                StagingHost = host
            };
            return new HttpClient(stagingHandler);
        });
    }
}

The StagingHost environment variable is used to redirect API calls from contentful to a different host, likely a proxy or mock server, via a custom StagingMessageHandler. This demonstrates how environment variables can be used for advanced configuration scenarios beyond simple key-value pairs.

Configuration loading

The loading and composition of configuration settings is handled automatically by the ASP.NET Core host.

How ASP.NET Core loads configuration

The process is initiated in Program.cs by WebHost.CreateDefaultBuilder(args).

// File: TheExampleApp/Program.cs

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .Build();

The CreateDefaultBuilder method sets up a default chain of configuration providers. The resulting IConfiguration object, which represents the merged view of all configuration sources, is then made available to the application via dependency injection. It is injected into the Startup class constructor, ready for use.

// File: TheExampleApp/Startup.cs

public class Startup
{
    public Startup(IConfiguration configuration, IHostingEnvironment env)
    {
        Configuration = configuration;
        CurrentEnvironment = env;
    }

    public IConfiguration Configuration { get; }
    // ...
}

Configuration precedence

ASP.NET Core loads configuration from multiple sources in a specific order. Each subsequent source overrides the values from the previous ones. The default order for this application is:

1. appsettings.json: The base configuration file.
2. appsettings.{Environment}.json: The environment-specific file (e.g., appsettings.Development.json). This is the primary method used in this project to differentiate environments.
3. User Secrets: Loaded only in the Development environment. (Not explicitly used in this project's provided files, but part of the default builder).
4. Environment Variables: High-priority source, ideal for secrets and deployment-specific settings.
5. Command-line Arguments: The highest-priority source, useful for ad-hoc changes.

This layered approach provides a powerful and secure way to manage settings, allowing developers to maintain base settings in source control while keeping sensitive data and environment-specific overrides separate.