DotEnv.Core
3.1.0
dotnet add package DotEnv.Core --version 3.1.0
NuGet\Install-Package DotEnv.Core -Version 3.1.0
<PackageReference Include="DotEnv.Core" Version="3.1.0" />
paket add DotEnv.Core --version 3.1.0
#r "nuget: DotEnv.Core, 3.1.0"
// 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.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
- Basic Concepts
- Installation
- Overview
- Copying .env file to the publish directory
- Extensions
- Samples
- File Format
- Frequently Answered Questions
- Contribution
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 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;
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:
- DotEnv.Example
- DotEnv.Example.SharedSettings
- DotEnv.Example.RequiredKeys
- DotEnv.Example.Parsing
- DotEnv.Example.Binding
- DotEnv.Example.OptionsPattern
- DotEnv.Example.ConfigurationApi
- DotEnv.Example.NetFramework
- DotEnv.Example.AspNetFramework
- DotEnv.Example.AspNetCore
- DotEnv.Extensions.Microsoft.DependencyInjection
- DotEnv.Extensions.Microsoft.Configuration
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:
- 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
Product | Versions 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. |
-
.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 |