dotenv.net 4.0.2

dotenv.net

dotenv.net is a lightweight library for loading environment variables from .env files in .NET applications. It keeps sensitive configuration out of source code and supports a range of options to suit different project setups.

Installation

Install via NuGet using any of the following methods:

.NET CLI

dotnet add package dotenv.net

Package Manager Console

Install-Package dotenv.net

PackageReference

<PackageReference Include="dotenv.net" Version="4.x.x"/>

Quick Start

using dotenv.net;

// Load .env from the application directory into the system environment
DotEnv.Load();

// Read variables from .env without modifying the system environment
var envVars = DotEnv.Read();
Console.WriteLine(envVars["DATABASE_URL"]);

By default, both methods look for a .env file in the same directory as the application executable.

Configuration Options

Both Load() and Read() accept a DotEnvOptions instance to customise behaviour.

DotEnv.Load(options: new DotEnvOptions(
    ignoreExceptions: false,           // Throw on errors instead of silently failing (default: true)
    envFilePaths: ["./config/.env"],   // One or more paths to .env files (default: [".env"])
    encoding: Encoding.UTF8,           // File encoding (default: UTF-8)
    trimValues: true,                  // Strip whitespace from values (default: false)
    overwriteExistingVars: false,      // Skip vars already set in the environment (default: true)
    probeForEnv: true,                 // Search parent directories for a .env file (default: false)
    probeLevelsToSearch: 3,            // How many directory levels to ascend when probing (default: 4)
    supportExportSyntax: true          // Support `export KEY=VALUE` syntax (default: false)
));

Note: probeForEnv and envFilePaths are mutually exclusive. Setting both will throw an InvalidOperationException.

Loading multiple .env files

DotEnv.Load(options: new DotEnvOptions(
    envFilePaths: ["./config/.env", "./secrets/.env"]
));

When overwriteExistingVars is false, keys from earlier files take precedence over those in later files.

Fluent API

DotEnv.Fluent() returns a DotEnvOptions instance that exposes a chainable builder API, useful when you prefer an explicit, readable configuration style.

Loading variables:

DotEnv.Fluent()
    .WithExceptions()
    .WithEnvFiles("./config/.env")
    .WithTrimValues()
    .WithEncoding(Encoding.UTF8)
    .WithOverwriteExistingVars()
    .WithProbeForEnv(probeLevelsToSearch: 6)
    .WithSupportExportSyntax()
    .Load();

Reading variables without writing to the environment:

var envVars = DotEnv.Fluent()
    .WithoutExceptions()
    .WithEnvFiles()               // Defaults to .env
    .WithoutTrimValues()
    .WithEncoding(Encoding.UTF8)
    .WithoutOverwriteExistingVars()
    .WithoutProbeForEnv()
    .WithoutSupportExportSyntax()
    .Read();

Fluent builder methods

Reading Variables

DotEnv.Read() returns an IDictionary<string, string> of the parsed key-value pairs without writing anything to the system environment. This is useful for inspecting values or selectively applying them.

var envVars = DotEnv.Read();

if (envVars.TryGetValue("API_KEY", out var apiKey))
{
    // use apiKey
}

EnvReader Utility

The dotenv.net.Utilities namespace provides EnvReader, a helper class for reading strongly-typed values directly from the system environment (i.e., after calling DotEnv.Load()).

using dotenv.net.Utilities;

var host = EnvReader.GetStringValue("DB_HOST");
var port = EnvReader.GetIntValue("DB_PORT");
var enabled = EnvReader.GetBooleanValue("FEATURE_FLAG");

For non-throwing alternatives, use the TryGet* methods:

if (EnvReader.TryGetIntValue("DB_PORT", out var port))
{
    // port is valid
}

Available methods

Contributing

Contributions are welcome. If you have a bug report, feature request, or improvement in mind, please open an issue or submit a pull request.

To get started:

1. Fork the repository and create a feature branch.
2. Make your changes and ensure existing tests still pass.
3. Add tests for any new behaviour.
4. Open a pull request with a clear description of what was changed and why.

The project targets .NET and uses the standard dotnet CLI toolchain. Run the test suite with:

dotnet test

Contributors

Thanks to everyone who has contributed to dotenv.net:

@bolorundurowb @joliveros @vizeke @merqlove @tracker1 @NaturalWill @texyh @jonlabelle @Gounlaf @DTTerastar @Mondonno @caveman-dick @VijoPlays @bobbyg603

License

dotenv.net is licensed under the MIT License. See the LICENSE file for details.

Happy Coding! 🚀