EnvGuard 0.1.0

EnvGuard

Strongly-typed, validated environment variables for .NET. Fail fast at startup, not in production.

The Problem

// Scattered across your codebase, crashes at runtime:
var connStr = Environment.GetEnvironmentVariable("DATABASE_URL"); // null in prod = 💥
var timeout = int.Parse(config["HttpClient:TimeoutSeconds"]!);    // "thirty" = FormatException
var apiKey = config["OpenAI:ApiKey"];                               // empty string = silent failure

You deploy, everything looks fine, then 10 minutes later a request hits a code path with a missing config value. Boom.

The Solution

using EnvGuard;

public class AppConfig
{
    [EnvVar("DATABASE_URL", Required = true)]
    public string DatabaseUrl { get; set; } = "";

    [EnvVar("OPENAI_API_KEY", Required = true, Description = "OpenAI API key")]
    public string OpenAiApiKey { get; set; } = "";

    [EnvVar("HTTP_TIMEOUT_SECONDS", Default = "30")]
    public int HttpTimeoutSeconds { get; set; }

    [EnvVar("ENABLE_CACHE", Default = "true")]
    public bool EnableCache { get; set; }

    [EnvVar("LOG_LEVEL", Default = "Information")]
    public LogLevel LogLevel { get; set; }

    [EnvVar("ALLOWED_ORIGINS")]  // Optional
    public string? AllowedOrigins { get; set; }
}

Startup — Fail Fast

// Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEnvGuard<AppConfig>(); // validates ALL vars at startup

If DATABASE_URL or OPENAI_API_KEY are missing, your app won't start:

EnvGuardException: 2 required environment variables are missing or invalid:
  DATABASE_URL — Required, not set
  OPENAI_API_KEY — Required, not set (OpenAI API key)

All errors at once. Not one at a time. Not at runtime.

Usage — Inject anywhere

app.MapGet("/health", (AppConfig config) => new {
    timeout = config.HttpTimeoutSeconds,  // int, not string
    cache = config.EnableCache,           // bool, not string
    level = config.LogLevel               // enum, not string
});

Installation

dotnet add package EnvGuard

Features

Type Coercion

Bool Parsing

Accepts: true/false, 1/0, yes/no, on/off (case-insensitive).

Defaults

[EnvVar("PORT", Default = "8080")]
public int Port { get; set; }  // Uses 8080 if PORT is not set

Description in Errors

[EnvVar("OPENAI_API_KEY", Required = true, Description = "Get one at platform.openai.com")]
public string ApiKey { get; set; } = "";

// Error: OPENAI_API_KEY — Required, not set (Get one at platform.openai.com)

Check Without Throwing

var errors = EnvGuardValidator.Check<AppConfig>();
if (errors.Count > 0)
    foreach (var err in errors)
        Console.WriteLine($"  ⚠ {err}");

Standalone Usage (No DI)

var config = EnvGuardValidator.Validate<AppConfig>();

Testing

var testEnv = new Dictionary<string, string>
{
    ["DATABASE_URL"] = "sqlite://test.db",
    ["API_KEY"] = "test-key"
};

var config = EnvGuardValidator.Validate<AppConfig>(
    name => testEnv.GetValueOrDefault(name));

Why Not IOptions<T>?

License

MIT