dotenv.net 3.2.0

dotnet add package dotenv.net --version 3.2.0                
NuGet\Install-Package dotenv.net -Version 3.2.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="dotenv.net" Version="3.2.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add dotenv.net --version 3.2.0                
#r "nuget: dotenv.net, 3.2.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install dotenv.net as a Cake Addin
#addin nuget:?package=dotenv.net&version=3.2.0

// Install dotenv.net as a Cake Tool
#tool nuget:?package=dotenv.net&version=3.2.0                

dotenv.net

CI - Build, Test & Coverage License: MIT Coverage Status NuGet Badge

project icon

dotenv.net is a group of projects that aim to make the process of reading .env files as simple and pain-free as possible in the dotnet ecosystem. It contains a core library that holds the env reading functionality and two libraries that add dependency injection (DI) support for two popular DI systems. If you have ideas or issues, feel free to create an issue.

Important

Version 3 is a huge departure from the previous system of accessing the library functionality. Deprecated methods from version 2.x have been removed as indicated. New functionality has been added but the reading and parsing logic has mostly stayed unchanged meaning at it's heart, is still the same ol' reliable.

Installation

If you are hardcore and want to go the manual route. Then add the following to your csproj file:

<PackageReference Include="dotenv.net" Version="3.0.0"/>

If you're using the Visual Studio package manager console, then run the following:

Install-Package dotenv.net

If you are making use of the dotnet CLI, then run the following in your terminal:

dotnet add package dotenv.net

Usage

Ensure you have declared the necessary namespace at the head of your class file:

using dotenv.net;

Load Environment Variables

Calling the Load() method with no parameters would locate and load the .env file in the same directory that the library is if one exists:

DotEnv.Load();

If you want to be notified of exceptions that occur in the process of loading env files then you can specify that via the configuration options:

DotEnv.Load(options: new DotEnvOptions(ignoreExceptions: false));

You can specify the env files to be loaded. One or more can be loaded. (NOTE: the order in which the env paths are provided is crucial. If there is a duplicate key and value specified in an env file specified later in the list, that value would overwrite the earlier values read). The default is .env:

DotEnv.Load(options: new DotEnvOptions(envFilePaths: new[] {"./path/to/env", "./path/to/second/env"}));

To search up from the executing library's directory for an env file. The directories would be searched upwards i.e given a directory path /path/to/var, The var directory would be searched first, then the to directory and then the path directory. The options allow for probing the directories as well as specifying how high up to search. The defaults are false and 4 directories up:

DotEnv.Load(options: new DotEnvOptions(probeForEnv: true, probeLevelsToSearch: 2)); // this would only search 2 directories up from the executing directory.

If the provided env files are not UTF-8 encoded, then the encoding to use in reading the files can be specified. The default is UTF-8:

using System.Text;
...
DotEnv.Load(options: new DotEnvOptions(encoding: Encoding.ASCII));

To trim extraneous whitespace from the values read from the file(s). The default is false:

DotEnv.Load(options: new DotEnvOptions(trimValues: true));

To skip overwriting an environment variable if it is set. The default is true:

DotEnv.Load(options: new DotEnvOptions(overwriteExistingVars: false));

<br>

Read Environment Variables

The Read() method returns a IDictionary<string, string> instance detailing the keys and associated values read from the env files provided. This hase the added advantage of not modifying your system environment variables. The same options as apply to the Load() method, apply to the Read() method as well.

var envVars = DotEnv.Read();
Console.WriteLine(envVars["KEY"]); // would print out whatever value was associated with the 'KEY'

Defining env variables

Environment variables can be defined in various ways:

  • # I am comment
  • hello=world
  • SINGLE_QUOTES='single'
  • DOUBLE_QUOTES="double"

Any variable starting with # will be ignored by the parser.

Any variable containing no quotes or single quotes will be read as a variable.

Any variable containing double quotes will be considered a multi-line variable, and can thus either be finished in the same line - or another line.

<br>

Fluent API

There is a fluent API analogue to the static methods documented above and can be terminated with a Read() or Load() call to return the env value or write to the environment variables .

// to load env vars with the specified options
DotEnv.Fluent()
    .WithExceptions()
    .WithEnvFiles("./path/to/env")
    .WithTrimValues()
    .WithEncoding()
    .WithOverwriteExistingVars()
    .WithProbeForEnv(probeLevelsToSearch: 6)
    .Load();

// to read the env vars with the specified options
var envVars = DotEnv.Fluent()
    .WithoutExceptions()
    .WithEnvFiles() // revert to the default .env file
    .WithoutTrimValues()
    .WithDefaultEncoding()
    .WithoutOverwriteExistingVars()
    .WithoutProbeForEnv()
    .Read();

<br>

Environment Variable Helpers

The Utilities namespace provides additional classes to aid in reading environment in a typed manner as well as other sundry assistive methods. Ensure you have declared the necessary namespace at the head of your class file:

using dotenv.net.Utilities;
...
var value = EnvReader.GetStringValue("KEY");
EnvReader Methods
Method Name Description Return Type Default (if applicable)
HasValue(string key) States whether the given key has a value set or not. bool N/A
GetStringValue(string key) Retrieve a value from the current environment by the given key and throws an exception if not found. string N/A
GetIntValue(string key) Retrieve a value from the current environment by the given key and throws an exception if not found. int N/A
GetDoubleValue(string key) Retrieve a value from the current environment by the given key and throws an exception if not found. double N/A
GetDecimalValue(string key) Retrieve a value from the current environment by the given key and throws an exception if not found. decimal N/A
GetBooleanValue(string key) Retrieve a value from the current environment by the given key and throws an exception if not found. bool N/A
TryGetStringValue(string key, out string value) A safer method to use when retrieving values from the environment as it returns a boolean value stating whether it successfully retrieved the value required. bool null
TryGetIntValue(string key, out int value) A safer method to use when retrieving values from the environment as it returns a boolean value stating whether it successfully retrieved the value required. bool 0
TryGetDoubleValue(string key, out double value) A safer method to use when retrieving values from the environment as it returns a boolean value stating whether it successfully retrieved the value required. bool 0.0
TryGetDecimalValue(string key, out decimal value) A safer method to use when retrieving values from the environment as it returns a boolean value stating whether it successfully retrieved the value required. bool 0.0m
TryGetBooleanValue(string key, out bool value) A safer method to use when retrieving values from the environment as it returns a boolean value stating whether it successfully retrieved the value required. bool false

<br>

Contributors

👏 👏 👏 Huge thanks to those who have contributed to these libraries.

@bolorundurowb @joliveros @vizeke @merqlove @tracker1 @NaturalWill @texyh @jonlabelle @Gounlaf @DTTerastar @Mondonno @caveman-d**k @VijoPlays

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp1.0 was computed.  netcoreapp1.1 was computed.  netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard1.6 is compatible.  netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen30 was computed.  tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (22)

Showing the top 5 NuGet packages that depend on dotenv.net:

Package Downloads
NetBricks

Commonly used tooling for dotnetcore, including configuration management, logging, etc.

CodeZero

CodeZero is a set of common implementations to help you implementing Clean Architecture, DDD, CQRS, Specification Patterns and another facilities for new modern web applications is an open-source project written in .NET Core.

Injector

Injects values into config files directly or via environment variables. Can inject app settings, connection strings, or WCF client endpoints.

CasAuth

The Comprehensive Authentication Solution (or CasAuth) was developed to provide an opinionated way to handle user and service authentication for APIs.

MCMS.Base

MCMS Base package

GitHub repositories (3)

Showing the top 3 popular GitHub repositories that depend on dotenv.net:

Repository Stars
Green-Software-Foundation/carbon-aware-sdk
Carbon-Aware SDK
redis/NRedisStack
Redis Stack .Net client
Azure/azure-sdk-tools
Tools repository leveraged by the Azure SDK team.
Version Downloads Last updated
3.2.0 23,177 6/22/2024
3.1.3 390,799 11/5/2023
3.1.2 1,544,514 11/25/2022
3.1.1 722,097 10/11/2021
3.1.0 103,065 7/11/2021
3.0.0 284,216 3/19/2021
2.1.3 205,241 1/18/2021
2.1.1 177,907 5/26/2020
2.1.0 119,913 4/1/2020
2.0.1 1,823 3/27/2020
2.0.0 1,078 3/25/2020
1.0.6 396,967 6/29/2019
1.0.5 1,247 6/27/2019
1.0.4 117,164 10/21/2018
1.0.3 23,812 2/17/2018
1.0.2 1,478 1/15/2018
1.0.1 1,569 12/31/2017
1.0.0 7,508 11/22/2017

- add multiline env var support