Table of Contents

Using DotEnv

Bodu.Text.DotEnv reads and writes .env files - a flat object of KEY=value entries with export prefixes, quoting, and comments. Values are deliberately literal: no ${VAR} interpolation happens at parse time.

Pattern 1 - query a document

using Bodu.Text.DotEnv.Document;

using DotEnvDocument env = DotEnvDocument.Parse(File.ReadAllBytes(".env"));
DotEnvElement root = env.RootElement;

string url = root.GetProperty("DATABASE_URL").GetString();
bool hasOptional = root.TryGetProperty("OPTIONAL_KEY", out DotEnvElement value);

foreach (DotEnvProperty property in root.EnumerateObject())
{
    Console.WriteLine($"{property.Name} = {property.Value.GetString()}");
}

Pattern 2 - typed settings via the serializer

The Web defaults apply the SCREAMING_SNAKE_CASE naming policy with case-insensitive matching, so conventional env keys bind onto PascalCase members:

using Bodu.Text.DotEnv;

sealed class Settings
{
    public string? AppEnv { get; set; }       // APP_ENV
    public int AppPort { get; set; }          // APP_PORT
    public string? DatabaseUrl { get; set; }  // DATABASE_URL
}

Settings settings = DotEnvSerializer.Deserialize<Settings>(
    envText, new DotEnvSerializerOptions(DotEnvSerializerDefaults.Web));

The root may be a class or a structure, nullable or not: a nullable structure is read into the structure and written as the structure is. Deserialize<Dictionary<string, string>> binds the whole file as a dictionary. Any type that implements IDictionary<string, TValue> binds the same way in both directions, whether or not it also implements the non-generic IDictionary. A dictionary whose type is not keyed by string, such as Hashtable, SortedList or Dictionary<int, string>, is a collection rather than an object: Serialize and Deserialize reject it with DotEnvSerializationException, as they reject a List<T>. Each member or dictionary entry is one value, so its type must be a scalar (a string or char, a number, bool, an enum, a date, time or time span, Guid or Uri) or object holding one. A type with a member of any other type, such as a nested dictionary or a class, is rejected whole by Serialize and Deserialize alike, with DotEnvSerializationException naming the key, before anything is written or read and whatever the member holds or the ignore condition; a dictionary entry of such a type, or an object member holding such a value, is rejected when it is written. No such value is written as its ToString() text, which does not read back. The write direction (Serialize) emits KEY=value lines; DotEnvSerializerOptions.WriteExportPrefix adds the export keyword.

Pattern 3 - author and round-trip with the mutable DOM

using Bodu.Text.DotEnv.Nodes;

DotEnvObject root = DotEnvNode.Parse(File.ReadAllBytes(".env"));
root["APP_PORT"] = new DotEnvValue("9090");
root.SetExport("APP_PORT", true);              // emit "export APP_PORT=9090"
File.WriteAllBytes(".env", root.ToUtf8Bytes());

The mutable DOM preserves each entry's export flag through the round trip.

Quoting rules

  • Double quotes delimit values and may span lines. They resolve the escapes \\, \', \", \a, \b, \f, \n, \r, \t, \v and \$, and a backslash before a line break continues the value on the next line; any other escape keeps its backslash, and octal escapes are not supported.
  • Single quotes delimit literal values.
  • Unquoted values are trimmed and end at an inline # comment, a # with whitespace before it: KEY= # note reads as an empty value, while KEY=#note and URL=http://host/#top keep their #.
  • An empty value (KEY=) is a real value, distinct from an absent key.
  • Whitespace is any Unicode whitespace character other than CR and LF, which end a line, so a form feed or a no-break space counts as well as a space or a tab. It may precede a key or a comment, follow export, and surround =, and it is trimmed from both ends of an unquoted value.
  • After a closing quote, only whitespace and a # comment may follow on the line; any other text, as in KEY="a"b or KEY='a' b, is malformed input.

DotEnvReaderOptions can disable the export prefix or inline comments (DisallowExportPrefix, DisallowInlineComments).

Exceptions

DotEnvFormatException for malformed input (unterminated quote, missing =), with line/offset. DotEnvSerializationException for binding failures.

When not to use it

Anything with sections or nesting (INI or TOML), and layered configuration (Bodu.Text.Configuration).

See also