Envilder 0.4.0

Envilder .NET SDK

Securely load environment variables from AWS SSM Parameter Store or Azure Key Vault directly into your .NET application. Zero vendor lock-in — secrets stay in your cloud.

Part of the Envilder project.

Prerequisites

• .NET Standard 2.0 compatible runtime (.NET 6+, .NET Framework 4.6.1+, and any netstandard2.0-compatible target)
• AWS provider: AWS credentials configured (CLI, environment variables, or IAM role)
• Azure provider: Azure credentials via az login, managed identity, or environment variables

Install

dotnet add package Envilder

Quick Start

One-liner — resolve + inject

using Envilder;

// Resolve secrets from the map file and inject into Environment
Env.Load("envilder.json");

// Access via standard environment variable API
var dbPassword = Environment.GetEnvironmentVariable("DB_PASSWORD");

Resolve without injecting

using Envilder;

var secrets = Env.ResolveFile("envilder.json");
var dbPassword = secrets["DB_PASSWORD"];

Async variants

Every method has an async counterpart:

using Envilder;

await Env.LoadAsync("envilder.json");
var secrets = await Env.ResolveFileAsync("envilder.json");

Fluent builder (with overrides)

Override the map file's $config at runtime — useful for switching providers, profiles, or vault URLs per environment:

using Envilder;

// Override provider + vault URL
var secrets = Env.FromMapFile("envilder.json")
    .WithProvider(SecretProviderType.Azure)
    .WithVaultUrl("https://my-vault.vault.azure.net")
    .Resolve();

// Override AWS profile and inject
Env.FromMapFile("envilder.json")
    .WithProfile("staging")
    .Inject();

// Async versions
var secrets = await Env.FromMapFile("envilder.json")
    .WithProvider(SecretProviderType.Azure)
    .WithVaultUrl("https://my-vault.vault.azure.net")
    .ResolveAsync();

await Env.FromMapFile("envilder.json")
    .WithProfile("staging")
    .InjectAsync();

Environment-based loading

Route secret loading based on your current environment. Each environment maps to its own secrets file (or null to skip loading):

using Envilder;

var env = Environment.GetEnvironmentVariable("APP_ENV") ?? "development";

// Resolve + inject
Env.Load(env, new Dictionary<string, string?>
{
    ["production"] = "prod-secrets.json",
    ["development"] = "dev-secrets.json",
    ["test"] = null,  // no secrets loaded
});

Resolve without injecting:

var secrets = Env.ResolveFile(env, new Dictionary<string, string?>
{
    ["production"] = "prod-secrets.json",
    ["development"] = "dev-secrets.json",
    ["test"] = null,
});

Behaviour:

• If the environment maps to a file path, secrets are loaded from that file.
• If the environment maps to null or is not in the mapping, an empty dictionary is returned silently.
• Empty or whitespace-only environment names throw ArgumentException.

Secret validation

Opt-in validation ensures all resolved secrets have non-empty values:

using Envilder;

var secrets = Env.ResolveFile("envilder.json");
secrets.ValidateSecrets(); // throws SecretValidationException if any value is empty

ValidateSecrets() is an extension method on IReadOnlyDictionary<string, string> that:

• Throws SecretValidationException when the dictionary is empty
• Throws SecretValidationException listing the keys whose values are null, empty, or whitespace
• Passes silently when all values are present

Via IConfiguration (ASP.NET)

using Microsoft.Extensions.Configuration;

var config = new ConfigurationBuilder()
    .AddEnvilder("envilder.json")
    .Build();

var dbPassword = config["DB_PASSWORD"];

Secrets with / in their paths are normalized to configuration sections:

{
  "Database/ConnectionString": "/app/prod/db-connection",
  "Database/Password": "/app/prod/db-password"
}

var dbSettings = config.GetSection("Database");
var connString = dbSettings["ConnectionString"];

Via IServiceCollection (ASP.NET DI)

services.AddEnvilder("envilder.json");

With runtime overrides (IConfiguration)

Pass EnvilderOptions to override the map file's $config from code:

using Envilder;
using Microsoft.Extensions.Configuration;

var config = new ConfigurationBuilder()
    .AddEnvilder("envilder.json", new EnvilderOptions
    {
        Provider = SecretProviderType.Azure,
        VaultUrl = "https://my-vault.vault.azure.net",
    })
    .Build();

API Reference

Static facade (Env)

Fluent builder (EnvilderBuilder)

Validation (SecretValidationExtensions)

IConfiguration integration

Dependency injection

Map File Format

{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": {
    "provider": "aws",
    "profile": "my-profile"
  },
  "DB_PASSWORD": "/app/prod/db-password",
  "API_KEY": "/app/prod/api-key"
}

Supported providers: aws (default), azure.

For Azure, add vaultUrl:

{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "DB_PASSWORD": "db-password",
  "API_KEY": "api-key"
}

Links

• Changelog
• Official Website

License

MIT