DotEnv.Core 3.1.0

dotnet add package DotEnv.Core --version 3.1.0                
NuGet\Install-Package DotEnv.Core -Version 3.1.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.Core" Version="3.1.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add DotEnv.Core --version 3.1.0                
#r "nuget: DotEnv.Core, 3.1.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.Core as a Cake Addin
#addin nuget:?package=DotEnv.Core&version=3.1.0

// Install DotEnv.Core as a Cake Tool
#tool nuget:?package=DotEnv.Core&version=3.1.0                

dotenv.core

dotenv-logo

dotenv.core dotenv.core PayPal-donate-button

DotEnv.Core downloads

DotEnv.Core.Props downloads

Dotenv.Microsoft.DI downloads

Dotenv.Microsoft.Config downloads

DotEnv.Core is a .NET library for reading and parsing .env files. It also provides a mechanism to retrieve the value of an environment variable in a simple and easy way.

The advantage of using this library is that you do not need to set the environment variable from the operating system shell (dotenv sets environment variables from an .env file).

Index

Features

  • It has a fluent interface, which makes it simple and easy to use.
  • Support for load multiple .env files.
  • Support to load the .env file depending on the environment (development, test, staging, or production).
  • Searches in parent directories when it does not find the .env file in the current directory.
  • You can set the base path for a set of .env files.
  • You can define which keys should be required by the application.
  • You can change the default .env file name, so it does not necessarily have to be .env.
  • Support for the variables interpolation.
  • And much more.

Don't forget to visit the official library website where you can find API documentation and articles.

Basic Concepts

What is a .env file?

A .env file or dotenv file is a simple text configuration file for controlling your Applications environment constants.

What do .env files look like?

.env files are line delimitated text files, meaning that each new line represents a single variable. By convention .env variable names are uppercase words separated by underscores. Variable names are followed directly by an = which, in turn is followed directly by the value, for example:

VARIABLE_NAME=value

What is environment variable?

An environment variable is a dynamic variable that can affect the behavior of running processes on a computer. They are part of the environment in which a process runs.

Installation

If you're want to install the package from Visual Studio, you must open the project/solution in Visual Studio, and open the console using the Tools > NuGet Package Manager > Package Manager Console command and run the install command:

Install-Package DotEnv.Core

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

dotnet add package DotEnv.Core

Overview

The first thing you need to do is create a .env file in the root directory of your project.

Load .env file

You must import the namespace types at the beginning of your class file:

using DotEnv.Core;

Then you can load the .env file with the Load method of the EnvLoader class:

new EnvLoader().Load();

By default, the Load method will search for a file called .env in the current directory and if it does not find it, it will search for it in the parent directories of the current directory. Generally, the current directory is where the executable (your application itself) with its dependencies is located.

Remember that if no encoding is specified to the Load method, the default will be UTF-8. Also, by default, the Load method does not overwrite the value of an existing environment variable.

You can also load your own .env file using the AddEnvFile method:

new EnvLoader()
   .AddEnvFile("config.env")
   .Load();

In this case, the Load method will search for a file called config.env instead of .env.

Accessing environment variables

After you have loaded the .env file with the Load method, you can access the environment variables using the EnvReader class:

var reader = new EnvReader();
string value = reader["CONNECTION_STRING"];
int dbPort = reader.GetIntValue("DB_PORT");

Or you can also access the environment variables using the static property Instance:

string value = EnvReader.Instance["CONNECTION_STRING"];
int dbPort = EnvReader.Instance.GetIntValue("DB_PORT");

If you don't want to use the EnvReader class to access environment variables, you can use the string class:

string value = "CONNECTION_STRING".GetEnv();
int dbPort = "DB_PORT".GetEnv<int>();

You can also use the Environment class or the Configuration API to access the environment variables.

Suggestion: It is recommended to use constants to avoid hard-coded keys in the application logic. A complete example can be found here.

Bind the model instance with the configuration keys

In case you do not want to use the EnvReader or Environment class, you can bind your own instance of the model with the keys of a .env file.

Create the model representing the setting class of the application:

class AppSettings
{
    [EnvKey("CONNECTION_STRING")]
    public string ConnectionString { get; set; }

    [EnvKey("SECRET_KEY")]
    public string SecretKey { get; set; }
}

The EnvKey attribute is used in case the key names do not match the properties and this is because the key names in a .env file usually follow this convention: KEY_NAME=VALUE (UpperCase + SnakeCase).

Note: As of version 2.3.0, it is no longer necessary to use the EnvKey attribute, because the binder performs an additional step: It converts the property name to UpperCaseSnakeCase and then checks if it exists in the environment. Note that this additional step only occurs if the EnvKey attribute is not used.

Then call the EnvBinder.Bind method to bind the AppSettings class with the configuration keys:

new EnvLoader().Load();
var settings = new EnvBinder().Bind<AppSettings>();
string key1 = settings.ConnectionString;
string key2 = settings.SecretKey;

Load .env file without altering the environment

You can load an .env file without having to modify the environment:

var envVars = new EnvLoader()
        .AvoidModifyEnvironment()
        .Load();

string key1 = envVars["KEY1"];
string key2 = envVars["KEY2"];

The Load method will return an instance that implements the IEnvironmentVariablesProvider interface and through this instance we can access the environment variables. In fact, the environment variables are obtained from a dictionary, instead of the current process.

Required Keys

You can specify which keys should be required by the application, in case they are missing, throw an error:

new EnvValidator()
    .SetRequiredKeys("SERVICE_APP_ID", "SERVICE_KEY", "SERVICE_SECRET")
    .Validate();

The Validate method will check if the keys "SERVICE_APP_ID", "SERVICE_KEY", "SERVICE_SECRET" are present in the application, otherwise it throws an exception.

Load .env file based on environment

You can load an .env file based on the environment (dev, test, staging or production) with the LoadEnv method. The environment is defined by the actual environment variable as DOTNET_ENV:

new EnvLoader().LoadEnv();

The LoadEnv method will search for these .env files in the following order:

  • .env.[environment].local (has the highest priority)
  • .env.local
  • .env.[environment]
  • .env (has the lowest priority)

The environment is specified by the actual environment variable DOTNET_ENV.

It should be noted that the default environment will be development or dev if the environment is never specified with DOTNET_ENV.

Parsing .env files

You can analyze key-value pairs from any data source (a .env file, a database, a web service, etc):

string myDataSource = @"
    SERVICE_APP_ID=1
    SERVICE_KEY=1234$
    SERVICE_SECRET=1234example$
";
new EnvParser().Parse(myDataSource);

Then you can access the environment variables with the EnvReader or System.Environment class.

Using DotEnv in ASP.NET Core

Open the Startup.cs file and add this code in the constructor:

new EnvLoader().Load();
Configuration = new ConfigurationBuilder()
          .AddEnvironmentVariables()
          .Build();

Once the environment variables have been set from an .env file, we call the AddEnvironmentVariables method to take care of adding the environment variables in the configuration object managed by ASP.NET Core. Then, the keys can be accessed with the IConfiguration interface, for example:

class HomeController
{
    public HomeController(IConfiguration configuration)
    {
        string key = configuration["KEY_NAME"];
    }
}

If you are using ASP.NET Core 6, you will not need to add anything in a Startup.cs file. Simply go to Program.cs and add the following code after the WebApplication.CreateBuilder method:

new EnvLoader().Load();
builder.Configuration.AddEnvironmentVariables();

For more information, see the articles.

Copying .env file to the publish directory

You can copy the .env file to the publish directory using the following package:

dotnet add package DotEnv.Core.Props

For more information, see the README.

If you do not want to use the previous package, add the following to your .csproj file:

<ItemGroup>
  <Content Include=".env" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

Note: Your .env file must be in the same directory as the .csproj file.

Extensions

Integration with Microsoft.Extensions.DependencyInjection

Install the package with this command:

dotnet add package Dotenv.Extensions.Microsoft.DependencyInjection

This package adds extension methods for Microsoft.Extensions.DependencyInjection, which can be accessed from the IServiceCollection interface.

For more information, see the documentation here.

Integration with Microsoft.Extensions.Configuration

Install the package with this command:

dotnet add package Dotenv.Extensions.Microsoft.Configuration

This package adds extension methods for Microsoft.Extensions.Configuration, which can be accessed from the IConfigurationBuilder interface.

For more information, see the documentation here.

Samples

You can find a complete and functional example in these projects:

File Format

  • Empty lines or lines with white-spaces will be ignored.
  • The key-value format must be as follows: KEY=VAL.
  • Single or double quotes in a value are removed.
  • If the value of a key is an empty string, it will be converted to a white-space.
  • White-spaces at both ends of the key and value are ignored.

Comments

Each line beginning with the # character is a comment. White-spaces at the beginning of each comment will be ignored.

Example:

# This is a comment without white-spaces
   # This is a comment with white-spaces
KEY=VALUE

A comment may begin anywhere on a line after a space (inline comments):

KEY=VALUE # This is an inline comment
VAR=VALUE    # This is another inline comment

Interpolating variables

Sometimes you will need to interpolate variables within a value, for example:

MYSQL_USER=root
MYSQL_ROOT_PASSWORD=1234
CONNECTION_STRING=username=${MYSQL_USER};password=${MYSQL_ROOT_PASSWORD};database=testdb;

If the variable embedded in the value is not set, the parser will throw an exception, for example:

MYSQL_ROOT_PASSWORD=1234
CONNECTION_STRING=username=${MYSQL_USER};password=${MYSQL_ROOT_PASSWORD};database=testdb;
MYSQL_USER=root

In the above example, the parser should throw an exception because the MYSQL_USER variable is not set.

Export variables

Lines can start with the export prefix, which has no effect on their interpretation.

export VAR=VALUE
export KEY=VALUE

The export prefix makes it possible to export environment variables from a file using the source command:

source .env

Multiline values

It is possible for single- or double-quoted values to span multiple lines. The following examples are equivalent:

KEY="first line
second line"

VAR='first line
second line'
KEY="first line\nsecond line"
VAR='first line\nsecond line'

Frequently Answered Questions

Can I use an .env file in a production environment?

Generally, you should not add sensitive data (such as passwords) to a .env file, as it would be unencrypted! Instead, you could use a secrets manager such as Azure Key Vault or AWS Secrets Manager.

If you are going to use .env files in production, make sure you have good security at the infrastructure level and also grant read/write permissions to a specific user (such as admin), so that not just anyone can access your .env file.

Should I commit my .env file?

Credentials should only be accessible on the machines that need access to them. Never commit sensitive information to a repository that is not needed by every development machine.

Why is it not overriding existing environment variables?

By default, it won't overwrite existing environment variables as dotenv assumes the deployment environment has more knowledge about configuration than the application does.

Contribution

Any contribution is welcome, the parser is still VERY dumb, so if you can improve it, do it.

Follow the steps below:

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
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 netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.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 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.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on DotEnv.Core:

Package Downloads
Dotenv.Extensions.Microsoft.DependencyInjection

Integrates DotEnv.Core package with Microsoft.Extensions.DependencyInjection

Dotenv.Extensions.Microsoft.Configuration

Integrates DotEnv.Core package with Microsoft.Extensions.Configuration

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on DotEnv.Core:

Repository Stars
ose-net/yesql.net
A class library for loading SQL statements from .sql files instead of writing SQL code in your C# source files
Version Downloads Last updated
3.1.0 45,017 6/29/2024
3.0.0 90,690 5/3/2023
2.3.2 10,025 1/21/2023
2.3.1 1,392 11/24/2022
2.3.0 571 11/17/2022
2.2.1 1,385 7/4/2022
2.2.0 424 6/30/2022
2.1.0 432 5/30/2022
2.1.0-alpha3 157 5/13/2022
2.1.0-alpha2 174 5/10/2022
2.1.0-alpha1 168 5/5/2022
2.0.1 4,923 4/30/2022
2.0.0 444 3/29/2022
1.1.3 291 1/3/2022
1.1.2 260 12/31/2021
1.0.2 267 12/24/2021
1.0.1 285 12/18/2021
1.0.0 315 12/16/2021