FriendlyEnvars 1.1.0

FriendlyEnvars

Simple, type-safe environment variable configuration for .NET

👀 Overview

Do you need to configure your .NET app purely via environment variables?

FriendlyEnvars lets you bind them directly to strongly typed configuration classes.

• Clean, explicit configuration mapping using the [Envar] attribute.
• Automatic type conversion, validation, and integration with the IOptions<T> pattern.
• Environment variables are bound once, at startup.

Ideal for: cloud-native apps, containerized deployments, microservices, or anywhere configuration comes from the environment.

📝 Why FriendlyEnvars?

• Type safety: Eliminates runtime configuration errors by mapping environment variables directly to typed properties.
• Built-in validation: Leverages data annotation attributes like [Required], [Range], etc. automatically.
• No boilerplate: No need to write manual parsing, error handling, or default value logic.
• Works with IOptions: Smooth experience for modern .NET dependency injection patterns.
• Explicit & Discoverable: Your configuration surface is crystal clear in the code.

🚀 Quick Start

1. Define Your Configuration Class

Annotate properties you want loaded from environment variables. Properties must have a setter (set or init):

public record DatabaseSettings
{
    [Envar("DB_HOST")]
    public string Host { get; init; } = string.Empty;

    [Envar("DB_PORT")]
    public int Port { get; init; }

    [Envar("DB_SSL_ENABLED")]
    public bool SslEnabled { get; init; } = true;

    [Envar("DB_CONNECTION_TIMEOUT")]
    public TimeSpan ConnectionTimeout { get; init; } = TimeSpan.FromSeconds(30);
}

2. Register in DI

Hook up configuration binding in your Startup.cs or DI setup:

services
    .AddOptions<DatabaseSettings>()
    .BindEnvars();

3. Add Validation (Optional)

Validate environment variables using standard data annotation attributes:

services
    .AddOptions<DatabaseSettings>()
    .BindEnvars()
    .ValidateDataAnnotations()
    .ValidateOnStart();

4. Inject and Use Your Config

public class MyService
{
    public MyService(IOptions<DatabaseSettings> settings)
    {
        var dbSettings = settings.Value;
    }
}

💡 Features

Supported Types:

• string, char, bool
• Numeric types: byte, sbyte, short, ushort, int, uint, long, ulong, float, double, decimal
• Guid, Uri, TimeSpan, DateTime, DateTimeOffset, DateOnly, TimeOnly
• Enum (case-insensitive, including [Flags] enums)
• Nullable versions of all above types
• Any type with a TypeConverter

Additional Features:

• Automatic conversion using invariant culture (by default) or custom culture.
• Custom parsing recipes via IEnvarPropertyBinder interface.
• Validation using familiar DataAnnotations attributes.

⚙️ Advanced Usage

Parsing with a Specific Culture

By default, conversions use CultureInfo.InvariantCulture for predictable parsing. To handle locale-specific formats:

using System.Globalization;

services.AddOptions<DatabaseSettings>()
    .BindEnvars(settings => {
        settings.UseCulture(CultureInfo.GetCultureInfo("en-US"));
    });

Custom Type Conversion

For complex types, implement IEnvarPropertyBinder to control parsing:

using System;
using System.Collections.Generic;
using System.Globalization;

public record ConnectionString
{
    public string Host { get; init; } = string.Empty;
    public int Port { get; init; }
    public string User { get; init; } = string.Empty;
    public string Password { get; init; } = string.Empty;
}

public class CustomEnvarPropertyBinder : IEnvarPropertyBinder
{
    private readonly DefaultEnvarPropertyBinder _defaultBinder = new();

    public object? Convert(string value, Type targetType, CultureInfo culture)
    {
        if (targetType == typeof(ConnectionString))
        {
            return ParseConnectionString(value);
        }

        return _defaultBinder.Convert(value, targetType, culture);
    }

    private static ConnectionString ParseConnectionString(string connectionString)
    {
        var pairs = connectionString.Split(';', StringSplitOptions.RemoveEmptyEntries);
        var values = new Dictionary<string, string>();

        foreach (var pair in pairs)
        {
            var parts = pair.Split('=', 2);
            if (parts.Length == 2)
            {
                values[parts[0].Trim()] = parts[1].Trim();
            }
        }

        return new ConnectionString
        {
            Host = values.GetValueOrDefault("Host", "localhost"),
            Port = int.Parse(values.GetValueOrDefault("Port", "5432")),
            User = values.GetValueOrDefault("User", ""),
            Password = values.GetValueOrDefault("Password", "")
        };
    }
}

Usage with environment variable CONNECTION_STRING=Host=localhost;Port=5432;User=Joe;Password=Joe12:

public record DatabaseSettings
{
    [Envar("CONNECTION_STRING")]
    public ConnectionString Connection { get; init; } = new();
}

Then, configure the binder:

services.AddOptions<DatabaseSettings>()
    .BindEnvars(settings =>
    {
        settings.UseCustomEnvarPropertyBinder(new CustomEnvarPropertyBinder());
    });

Working with IOptionsSnapshot and IOptionsMonitor

By default, IOptionsSnapshot<T> and IOptionsMonitor<T> are enabled and will always reflect the values from app startup. Environment variable configs do not refresh at runtime.

You can disable support for IOptionsSnapshot<T> and IOptionsMonitor<T> if you want to ensure only IOptions<T> is used:

services.AddOptions<DatabaseSettings>()
    .BindEnvars(settings =>
    {
        settings
            .BlockOptionsSnapshot()
            .BlockOptionsMonitor();
    });

⚠️ Breaking Changes

Empty Environment Variables (v2.x)

Previously, environment variables set to an empty string ("") were treated the same as unset variables — the property would retain its default value. Now, empty strings are passed to the binder. This means:

• string properties will be set to "" instead of keeping their default.
• Non-string properties (e.g., int, bool) will throw a FormatException wrapped in EnvarsException if the environment variable is empty.

If you relied on the old behavior of ignoring empty values, either unset the variable entirely or use a custom IEnvarPropertyBinder to handle empty strings.

⚠️ Limitations

• No runtime refresh: environment variables are read once on application startup.
• IOptionsSnapshot and IOptionsMonitor are enabled by default as read-only views, but can be disabled if needed.

With FriendlyEnvars, configuration is easy, explicit, and safe.