Utf8DotEnvWriter Struct
Definition
Provides a high-performance, forward-only writer that emits DotEnv text as UTF-8 bytes to an
IBufferWriter<T> or a Stream. The writer is a ref struct, so it
lives on the stack and cannot be boxed or captured.
public ref struct Utf8DotEnvWriter
- Inherited Members
Remarks
DotEnv is line-oriented, so the writer emits progressively: WritePropertyName(string) followed by
WriteString(string) produces one KEY=VALUE line, and WriteComment(string)
produces one # comment line. WriteStartObject() and WriteEndObject() frame the
document to mirror the reader's token stream but emit no bytes of their own.
A value is emitted unquoted when it is safe to do so; a value that is empty is left after the =, and a value
containing whitespace at its edges, an inline-comment sequence, a quote, a backslash, or a line break is
double-quoted with the necessary escape sequences so a subsequent read round-trips it exactly.
Constructors
Utf8DotEnvWriter(IBufferWriter<byte>)
Initializes a new instance of the Utf8DotEnvWriter struct that writes to the supplied buffer.
public Utf8DotEnvWriter(IBufferWriter<byte> output)
Parameters
outputIBufferWriter<byte>The destination buffer writer.
Exceptions
- ArgumentNullException
Thrown when
outputis null.
Utf8DotEnvWriter(IBufferWriter<byte>, DotEnvWriterOptions)
Initializes a new instance of the Utf8DotEnvWriter struct that writes to the supplied buffer using the supplied options.
public Utf8DotEnvWriter(IBufferWriter<byte> output, DotEnvWriterOptions options)
Parameters
outputIBufferWriter<byte>The destination buffer writer.
optionsDotEnvWriterOptionsThe writer options.
Exceptions
- ArgumentNullException
Thrown when
outputis null.
Utf8DotEnvWriter(Stream)
Initializes a new instance of the Utf8DotEnvWriter struct that writes to the supplied stream.
public Utf8DotEnvWriter(Stream stream)
Parameters
streamStreamThe destination stream.
Exceptions
- ArgumentNullException
Thrown when
streamis null.
Utf8DotEnvWriter(Stream, DotEnvWriterOptions)
Initializes a new instance of the Utf8DotEnvWriter struct that writes to the supplied stream using the supplied options.
public Utf8DotEnvWriter(Stream stream, DotEnvWriterOptions options)
Parameters
streamStreamThe destination stream.
optionsDotEnvWriterOptionsThe writer options.
Exceptions
- ArgumentNullException
Thrown when
streamis null.
Properties
BytesCommitted
Gets the number of bytes flushed to the destination.
public readonly long BytesCommitted { get; }
Property Value
- long
The committed byte count.
BytesPending
Gets the number of bytes written but not yet flushed to the destination.
public readonly long BytesPending { get; }
Property Value
- long
The pending byte count; always zero in direct buffer-writer mode.
Methods
Dispose()
Flushes any buffered bytes and releases the writer.
public void Dispose()
Flush()
Flushes any buffered bytes to the destination stream. This method is a no-op in direct buffer-writer mode.
public void Flush()
WriteComment(string)
Writes a comment as one comment line per line of its text, each prefixed with # and followed by a line
feed.
public void WriteComment(string text)
Parameters
textstringThe comment text, without the leading prefix.
Remarks
A carriage return, a line feed, or a carriage return followed by a line feed ends a line of the text, as it ends a line for Utf8DotEnvReader, so each line reads back as a comment of its own rather than as an entry; an empty line becomes an empty comment line.
Exceptions
- ArgumentNullException
Thrown when
textis null.
WriteEndObject()
Writes the document object end. DotEnv has no object delimiter, so this method emits no bytes; it exists to mirror the reader's token stream.
public readonly void WriteEndObject()
WritePropertyName(string)
Writes a key name, followed by the = assignment. Call WriteString(string) next to write
the value.
public void WritePropertyName(string name)
Parameters
namestringThe key name.
Remarks
The export prefix is emitted when WriteExportPrefix is set.
Exceptions
- ArgumentNullException
Thrown when
nameis null.- ArgumentException
Thrown when
nameis not a key the reader reads back: one that begins with an ASCII letter orand holds only ASCII letters, digits and.
WritePropertyName(string, bool)
Writes a key name with an explicit export decision, followed by the = assignment. Call
WriteString(string) next to write the value.
public void WritePropertyName(string name, bool export)
Parameters
Remarks
The writer accepts exactly the keys Utf8DotEnvReader reads, which match
[A-Za-z_][A-Za-z0-9_]*, so an empty name, or one holding =, #, white space, a line break or
any other character, is refused rather than written as text that does not read back.
Exceptions
- ArgumentNullException
Thrown when
nameis null.- ArgumentException
Thrown when
nameis not a key the reader reads back: one that begins with an ASCII letter orand holds only ASCII letters, digits and.
WriteStartObject()
Writes the document object start. DotEnv has no object delimiter, so this method emits no bytes; it exists to mirror the reader's token stream.
public readonly void WriteStartObject()
WriteString(string)
Writes a string value, quoting and escaping it when required, followed by a line feed.
public void WriteString(string value)
Parameters
valuestringThe value to write.
Exceptions
- ArgumentNullException
Thrown when
valueis null.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |