Skip to content

Latest commit

 

History

History
142 lines (102 loc) · 6.11 KB

index.md

File metadata and controls

142 lines (102 loc) · 6.11 KB
Raw

dotenv-logo

dotenv.core dotenv.core dotenv.core Nuget-Badges PayPal-donate-button

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

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

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.

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'

Extensions

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