mbcrocci / dotnet-env

A .NET library to load environment variables from .env files

dotnet-env

A .NET library to load environment variables from .env files. Supports .NET Core and .NET Framework

Installation

Available on NuGet

Visual Studio:

PM> Install-Package DotNetEnv

.NET Core CLI:

dotnet add package DotNetEnv

Usage

Load env file

Load() will automatically look for a .env file in the current directory

DotNetEnv.Env.Load();

Or you can specify the path to the .env file

DotNetEnv.Env.Load("./path/to/.env");

It's also possible to load the (text) file as a Stream

using (var stream = File.OpenRead("./path/to/.env"))
{
    DotNetEnv.Env.Load(stream);
}

Accessing environment variables

The variables in the .env can then be accessed through the System.Environment class

System.Environment.GetEnvironmentVariable("IP");

Or through on of the helper methods:

DotNetEnv.Env.GetString("A_STRING");
DotNetEnv.Env.GetBool("A_BOOL");
DotNetEnv.Env.GetInt("AN_INT");
DotNetEnv.Env.GetDouble("A_DOUBLE");

The helper methods also has a optional second argument which specifies what value to return if the variable is not found:

DotNetEnv.Env.GetString("THIS_DOES_NOT_EXIST", "Variable not found");

Additional arguments

You can also pass a LoadOptions object arg to all DotNetEnv.Env.Load variants to affect the Load/Parse behavior:

new DotNetEnv.Env.LoadOptions(
    trimWhitespace: false,
    isEmbeddedHashComment: false,
    unescapeQuotedValues: false,
    clobberExistingVars: false
)

All parameters default to true, which means:

1. trimWhitespace, first arg: true in order to trim leading and trailing whitespace from keys and values such that

  KEY  =  value

Would then be available as

"value" == System.Environment.GetEnvironmentVariable("KEY")
null == System.Environment.GetEnvironmentVariable("  KEY  ")

False would mean:

"  value" == System.Environment.GetEnvironmentVariable("  KEY  ")
null == System.Environment.GetEnvironmentVariable("KEY")

2. isEmbeddedHashComment, second arg: true in order to allow inline comments

KEY=value  # comment

Would then be available as

"value" == System.Environment.GetEnvironmentVariable("KEY")

False would mean:

"value  # comment" == System.Environment.GetEnvironmentVariable("KEY")

Which is most useful when you want to do something like:

KEY=value#moreValue#otherValue#etc

3. unescapeQuotedValues, third arg: true in order to unescape/parse quoted (single or double) values as being strings with escaped chars such as newline ("\n"), but also handles unicode chars (e.g. "\u00ae" and "\U0001F680") -- note that you can always include unescaped unicode chars anyway (e.g. "日本") if your .env is in UTF-8. Also note that there is no need to escape quotes inside.

KEY="quoted\n\tvalue"

Would then be available as

"quoted
    value" == System.Environment.GetEnvironmentVariable("KEY")

False would mean:

"\"quoted\\n\\tvalue\"" == System.Environment.GetEnvironmentVariable("KEY")

4. clobberExistingVars, fourth arg: false to avoid overwriting existing environment variables

KEY=value

System.Environment.SetEnvironmentVariable("KEY", "really important value, don't overwrite");
DotNetEnv.Env.Load(
    new DotNetEnv.Env.LoadOptions(
        clobberExistingVars: false
    )
)
"really important value, don't overwrite" == System.Environment.GetEnvironmentVariable("KEY")  // not "value" from the .env file

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section.

Contributing

Run dotnet test test/DotNetEnv.Tests to run all tests.

src/DotNetEnvEnv/Env.cs is the entry point for all behavior.

Open a PR on Github if you have some changes, or an issue if you want to discuss some proposed changes before creating a PR for them.

License

This project is licensed under the MIT license. See the LICENSE file for more info.