AutoDotEnv 1.0.0

AutoDotEnv

A minimal, AOT-first .env loader for .NET that loads automatically before Main.

Why AutoDotEnv?

Most .env libraries require a manual Env.Load() call at the start of your application. Forget it once and your app breaks in confusing ways. AutoDotEnv hooks into the module initializer system to load your .env file automatically, before any of your code runs.

• Zero boilerplate: Install the package, your .env is loaded
• Native AOT compatible: No reflection, no dynamic code generation at runtime
• Fast: ~150 microseconds to load and parse a typical .env file
• Lean: ~3.6 KB managed allocations per load, native memory freed immediately
• Familiar syntax: Implements the common subset of .env syntax (quotes, escapes, ${VAR} expansion, comments) that works across the major .env tools

Installation

dotnet add package AutoDotEnv

That's it. No code changes required. Your .env will be loaded automatically.

Usage

Create a .env file in your project's working directory:

APP_NAME=MyApp
DATABASE_URL=postgres://localhost/mydb
DEBUG=true

Access values normally via Environment.GetEnvironmentVariable:

var appName = Environment.GetEnvironmentVariable("APP_NAME");

The variables are available in Main and everywhere afterwards.

Supported Syntax

Basic key-value

KEY=value

Whitespace handling

• Whitespace around = is allowed and trimmed
• Leading and trailing whitespace in unquoted values is trimmed
• Whitespace inside quoted values is preserved

KEY    =    value
TRIMMED=  has spaces around  
QUOTED="  spaces preserved  "

Quoted values

Three styles, each with different rules:

DOUBLE="value with $expansion and \n escapes"
SINGLE='value literal, no $expansion or \n escapes'
UNQUOTED=value with $expansion but no escapes

Multi-line values

Both quote styles support multiple lines:

MULTILINE="line one
line two
line three"

Escape sequences (double quotes only)

Variable expansion

References to other variables work in unquoted and double-quoted values:

USER=admin
DATABASE_URL=postgres://${USER}@localhost/mydb
GREETING="Hello ${USER}"

Single-quoted values are taken literally:

LITERAL='${USER} stays as text'

If a referenced variable is not set, it expands to an empty string.

Comments

# Full-line comment
KEY=value # inline comment after value
URL=https://example.com/page#section  # hash without leading space stays in value
NO_COMMENT="this # is not a comment"  # hash inside quotes stays

A # only starts a comment when preceded by whitespace or at the start of a line.

Empty values

EMPTY_VALUE=

Sets the variable to an empty string.

Key naming rules

Keys must follow the POSIX convention:

• First character: letter (A-Z, a-z) or underscore (_)
• Following characters: letters, digits (0-9), or underscores

Invalid keys like MY-KEY or 9KEY will cause the parser to abort with an error (logged if logging is enabled).

Configuration

AutoDotEnv reads its own configuration from environment variables, set before your application starts:

Example: alternate file

AUTO_DOTENV_FILE=.env.production dotnet run

Example: enable error logging

AUTO_DOTENV_ERROR_LOG_ENABLED=1 dotnet run

If your .env has a syntax error, you'll find a log file with the line number and stack trace.

Example: disable for testing

AUTO_DOTENV_DISABLE=1 dotnet test

Useful in benchmarks or tests where you want a clean environment.

Setting log config inside the .env itself

AUTO_DOTENV_ERROR_LOG_ENABLED and AUTO_DOTENV_LOG_PATH are read at the moment an error occurs. This means you can set them inside your .env file directly:

AUTO_DOTENV_ERROR_LOG_ENABLED=1

# rest of your .env
APP_NAME=MyApp

For this to take effect on a parse error, the variable must be set on a line before the line where the error occurs. Note that AUTO_DOTENV_DISABLE and AUTO_DOTENV_FILE cannot be set this way, since they are evaluated before parsing begins.

Performance

Benchmark on a typical .env with 25 variables and 3 variable expansions:

Run on Intel Core i3-14100, .NET 10 Native AOT, Windows 11.

Design Decisions

Why a module initializer?

So you don't have to remember to call Env.Load(). Adding the package is enough. If you want explicit control, set AUTO_DOTENV_DISABLE=1 and call AutoDotEnv.Loader.Load() manually.

Why is silent error handling the default?

A misconfigured .env should not prevent your application from starting. Set AUTO_DOTENV_ERROR_LOG_ENABLED=1 to get diagnostic output when needed.

Why no support for .env.local, .env.development, etc.?

This lib loads exactly one file. Layered configurations are a framework concern (Next.js, Vite, Symfony do this on top of dotenv). If you need it, set AUTO_DOTENV_FILE based on your environment.

Limitations

• Files larger than int.MaxValue bytes (~2 GB) are not supported
• Variable names beyond POSIX rules are rejected
• 4-byte UTF-8 codepoints (e.g. emojis) in values are replaced with ?
• Browser/WebAssembly platform is not supported (no filesystem)

Compatibility

• .NET 10+
• Windows, Linux, macOS
• Native AOT
• Console apps, web apps, desktop apps

Not supported:

• .NET Framework 4.x
• Browser/WebAssembly

License

MIT