Appsettings

Every application needs a way to manage its configuration—the settings that change between different environments, such as database connection strings, API keys, and feature flags. Hardcoding these values is not an option, as it would require a code change and redeployment for every minor adjustment.

This is the crucial role of the appsettings.json file. It is the central control panel for your SliceFlow application, providing a flexible and powerful way to manage all its configuration from one place.

The Power of Environment-Specific Settings

An application behaves differently on a developer’s laptop than it does in a live production environment. In development, you might want to connect to a local database, allow requests from any origin for easy testing, and redirect all emails to your personal inbox. In production, you need to connect to the production database, enforce strict security policies, and send emails to real users.

SliceFlow leverages .NET’s built-in configuration system to handle this gracefully. The primary configuration is in appsettings.json, but you can create environment-specific overrides. The most common is appsettings.Development.json.

When you run your application in a development environment, any settings in appsettings.Development.json will automatically override the corresponding settings in the base appsettings.json file. This allows you to keep your production-safe defaults in the main file while easily customizing your local setup.

For example, to allow any frontend to connect to your API during development, your appsettings.Development.json might look like this:

{
  "Cors": {
    "AllowedOrigins": ["*"]
  },
  "Email": {
    "EmailDebugOverrideRecipient": "developer@example.com"
  }
}

From JSON to C#: Strongly-Typed Settings

While JSON is flexible, working with it directly in your code can be error-prone. A simple typo in a string ("ConnectionString" vs "Connectionstring") can lead to runtime errors that are hard to track down.

SliceFlow solves this by embracing the Options pattern. The entire appsettings.json structure is mapped to a set of strongly-typed C# classes, typically located in a Settings folder.

EmailSettings.cs

public class EmailSettings
{
    public const string SectionName = "Email";

    public SmtpSettings Smtp { get; init; } = new();
    public string EmailDebugOverrideRecipient { get; init; } = string.Empty;
    public bool EmailsEnabled { get; init; } = true;
}

This means you never have to guess at configuration keys. You can inject these settings objects directly into your services and endpoints with full type safety and IntelliSense.

// In an endpoint or service
public class MyService(IOptions<EmailSettings> emailSettings)
{
    private readonly EmailSettings _settings = emailSettings.Value;

    public void DoSomething()
    {
        if (_settings.EmailsEnabled)
        {
            // ...
        }
    }
}

Fail Fast: Validation on Startup

A misconfigured application can cause unpredictable behavior or, even worse, fail silently at runtime when a specific feature is used. SliceFlow is designed to prevent this by validating your entire configuration when the application starts.

This is achieved by decorating the properties in your strongly-typed settings classes with standard Data Annotation attributes, just like you would for an API request.

// Example: SmtpSettings.cs with validation attributes
public class SmtpSettings
{
    public const string SectionName = "Email:Smtp";

    [Required]
    public string Host { get; init; } = string.Empty;

    [Range(1, 65535)]
    public int Port { get; init; } = 587;

    [Required, EmailAddress]
    public string FromEmail { get; init; } = string.Empty;
}

In Program.cs, a special extension method, BindAppSettings, is called. This method not only binds the JSON to your C# classes but also validates them.

// In Program.cs
builder.BindAppSettings();

// Inside the extension method...
app.Services.AddOptions<SmtpSettings>()
    .Bind(app.Configuration.GetSection(SmtpSettings.SectionName))
    .ValidateDataAnnotations() // Ensures rules on the C# class are met
    .ValidateOnStart();      // Performs the validation at startup

The .ValidateOnStart() call is your safety net. If a critical setting is missing from appsettings.json or is in an invalid format, your application will fail to start, immediately telling you exactly what is wrong. This “fail-fast” approach is invaluable for catching configuration errors early, long before they can cause problems in a live environment.

A Tour of appsettings.json

The appsettings.json file in SliceFlow is organized into logical sections, each corresponding to a feature of the framework. Each of these sections is mapped to a dedicated, strongly-typed C# class within the Settings folder, ensuring type safety and enabling validation. Here are the primary sections:

• Company (CompanySettings): General company information, like the company name used in documentation.
• Cors (CorsSettings): Defines your Cross-Origin Resource Sharing policy, controlling which domains can access your API.
• ConnectionStrings (ConnectionStringSettings): Holds the connection strings for all your data stores, like the primary Default PostgreSQL database and the Redis cache.
• Auth (AuthSettings): The parent section for authentication.
  • Jwt (JwtSettings): Contains the settings for your external identity provider, such as the Authority and Audience for JWT validation.
• Email (EmailSettings): The parent section for email configuration, including the global toggle and debug override recipient.
  • Smtp (SmtpSettings): Contains your specific SMTP server details for sending emails.
• Frontend (FrontendSettings): Contains settings related to the frontend application, such as its base URL.
• Messaging (MessagingSettings): The parent section for the messaging system.
  • RabbitMq (RabbitMqSettings): Contains the connection details for your RabbitMQ server, which powers the background job and email systems.
• Serilog: While not mapped to a settings class in the same way, this section configures all aspects of structured logging, including the log levels and the destinations (sinks) like the console and Grafana Loki.

By combining a flexible, environment-based file structure with a robust, type-safe, and validated C# mapping, SliceFlow’s configuration system gives you a secure and reliable foundation for managing your application’s settings.