dotenv.core is a class library for read and parsing .env files in .NET Core and 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 a .env file).
- Features
- Basic Concepts
- Installation
- Overview
- Copying .env file to the output directory
- File Format
- Frequently Answered Questions
- Contribution
- 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, articles and diagrams.
A .env file or dotenv file is a simple text configuration file for controlling your Applications environment constants.
.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
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.
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
The first thing you need to do is create a .env
file in the root directory of your project.
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
.
After you have loaded the .env file with the Load
method, you can access the environment variables using the indexer of the EnvReader
class:
var reader = new EnvReader();
string key1 = reader["KEY1"];
string key2 = reader["KEY2"];
Or you can also access the environment variables using the static property Instance
:
string key1 = EnvReader.Instance["KEY1"];
string key2 = EnvReader.Instance["KEY2"];
If you don't want to use the EnvReader
class to access environment variables, you can use the System.Environment
class:
string key1 = System.Environment.GetEnvironmentVariable("KEY1");
string key2 = System.Environment.GetEnvironmentVariable("KEY2");
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 theEnvKey
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;
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.
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.
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
.
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.
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.
If you want to copy the .env file to the output directory, you have to add the following to your .csproj file:
<ItemGroup>
<Content Include=".env">
<CopyToOutputDirectory>Always</CopyToOutputDirectory>
</Content>
</ItemGroup>
NOTE: Your .env file must be in the same directory as the .csproj file.
- 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.
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
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.
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
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'
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.
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.
By default, it won't overwrite existing environment variables as dotenv assumes the deployment environment has more knowledge about configuration than the application does.
Any contribution is welcome, the parser is still VERY dumb, so if you can improve it, do it.
Follow the steps below:
- Fork it
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Added some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request