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,\vand\$, 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= # notereads as an empty value, whileKEY=#noteandURL=http://host/#topkeep 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 inKEY="a"borKEY='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
- Streams and token-level I/O for the
Utf8DotEnvReadertoken loop. - Using INI for sectioned configuration.