Getting Started with `dotenv.core`

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

Usage

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

Loading .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.

Accessing 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.

Changing default name

You can also change the default name of the .env file using the SetDefaultEnvFileName method:

new EnvLoader()
    .SetDefaultEnvFileName(".env.dev")
    .Load();

Now the Load method will search for the .env.dev file in the current directory and in the parent directories if it is not found in the current directory.

Another case would be:

new EnvLoader()
    .SetDefaultEnvFileName(".env.dev")
    .AddEnvFiles("/foo/foo2", "/bar/bar2")
    .Load();

The Load method will search for two .env.dev files in the paths /foo/foo2 and /bar/bar2.

Specifying path absolute

You can also specify the absolute path to the .env file:

new EnvLoader()
    .AddEnvFile("/home/MyProject/App/src/.env.dev")
    .Load();

In this case the Load method will search for the .env.dev file in the path /home/MyProject/App/src/, if it does not find it, the method will search for the .env.dev file in the parent directories. In other words, the Load method will search for the file in the parent directories of src such as: App, MyProject, home.

It is recommended not to use absolute paths, instead use relative paths. Remember that an absolute path can be different in each operating system, so your application could lose portability.

Loading multiple .env files

You can also load multiple .env files in a single call:

new EnvLoader()
    .AddEnvFiles("env.example", "env.example2")
    .Load();

Or you can use the AddEnvFile method:

new EnvLoader()
    .AddEnvFile("env.example")
    .AddEnvFile("env.example2")
    .Load();

If you need to specify an encoding type for all .env files, you can do it like this:

new EnvLoader()
    .AddEnvFiles("env.example", "env.example2")
    // Or you can also use: SetEncoding("Unicode")
    .SetEncoding(Encoding.Unicode)
    .Load();

You can also specify an encoding type for each .env file using the AddEnvFile method:

new EnvLoader()
    .AddEnvFile("env.example",  Encoding.Unicode)
    .AddEnvFile("env.example2", Encoding.ASCII)
    .AddEnvFile("env.example3", "Unicode")
    .AddEnvFile("env.example4", "ASCII")
    .Load();

Optional .env files

You can indicate that the existence of an .env file is optional by means of the AddEnvFile method:

new EnvLoader()
    .AddEnvFile(".env.example", optional: true)
    .Load();

At the end the Load method will not generate any error in case the .env.example file is not in a directory, since it is optional.

You can also mark all .env files as optional using the AllowAllEnvFilesOptional method:

new EnvLoader()
    .AddEnvFile(".env.example1") 
    .AddEnvFile(".env.example2") 
    .AddEnvFile(".env.example3")
    .AllowAllEnvFilesOptional()
    .Load();

Specifying path relative

You can also specify a relative path using the AddEnvFile method:

new EnvLoader()
    .AddEnvFile("./dotenv/files")
    .Load();

In this case, the .env file is inside a directory, i.e. in files. The Load method will search for the file dotenv/files/.env in the current directory, if it does not find it, it will search for it in parent directories.

This is useful when the .env file is located in a different directory than the current one.

Specifying base path

You can specify one base path for all .env files:

new EnvLoader()
    .SetBasePath("./dotenv/files")
    .AddEnvFiles(".env.example", ".env.example2")
    .Load();

In this case, the Base Path is a relative path, so the .env.example and .env.example2 files are inside dotenv/files.

Error handling

By default, the Load method does not throw any exception if it does not found the .env file but you can change this behavior if you use the EnableFileNotFoundException method:

try 
{
    new EnvLoader()
        .EnableFileNotFoundException()
        .Load();
}
catch(FileNotFoundException ex)
{
    System.Console.WriteLine(ex.Message);
}

You can handle the error without throwing an exception by means of the EnvValidationResult class:

new EnvLoader()
    // To ignore the exception thrown by the parser.
    .IgnoreParserException()
    .Load(out EnvValidationResult result);

if(result.HasError())
{
    string msg = result.ErrorMessages;
    System.Console.WriteLine(msg);
    // Or you can also iterate over the errors.
    foreach(string errorMsg in result)
        System.Console.WriteLine(errorMsg); 
}
else 
{
    // Execute some action when there is no error.
}

Note: If you don't know what each class does, don't forget to check the API documentation.

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.

Getting Started with dotenv.core