DotEnvSerializer Class
Definition
- Assembly
- Bodu.Text.DotEnv.dll
- Package
- Bodu.Text.DotEnv 1.3.0
Provides methods for serializing .NET objects to DotEnv text and deserializing DotEnv text into .NET objects, shaped
after System.Text.Json's JsonSerializer.
public static class DotEnvSerializer
- Inheritance
-
DotEnvSerializer
- Inherited Members
Remarks
DotEnv models a flat, ordered object of string-valued keys, so the serializer maps a POCO (or an
IDictionary<TKey, TValue> keyed by string) whose members are strings or types
convertible from a string. A dictionary that implements only that generic interface, and not the non-generic
IDictionary, is written and read through it, as a
Dictionary<TKey, TValue> is. Each member or entry is one value, so its type must be a scalar: a
string or character, a number, a bool, an enumeration, a date, time or time span, a
Guid or a Uri, or object holding one. A type with a member of any other
type, such as a dictionary or a class with members of its own, whether the member is readable, writable or both, is
rejected with DotEnvSerializationException by Serialize and Deserialize alike, before
anything is written or read, whatever the member holds and whatever the ignore condition; a dictionary entry of such
a type, and a member declared as object holding such a value, are rejected when they are written.
Neither is written as the value's ToString() text, which does not read back. A dictionary whose
type is not keyed by string, such as a Hashtable or a
Dictionary<TKey, TValue> keyed by int, is a collection rather than an object, and is
rejected with DotEnvSerializationException when written and when read. Property names honor
PropertyNamingPolicy and the
PropertyNameAttribute family; the callback interfaces (IOnSerializing
and its siblings) fire around the mapping. Each member name maps to one key, its most derived declaration: a
property or field hidden with the new modifier is neither written nor read. A type that maps two
members to one key is rejected with DotEnvSerializationException before anything is read or written.
A member declared with the C# required keyword is required, as one marked
RequiredAttribute is: reading a document without its key throws.
The asynchronous stream overloads buffer the entire document rather than streaming it; only the stream copy is asynchronous.
Methods
DeserializeAsync<T>(Stream, DotEnvSerializerOptions?, CancellationToken)
Asynchronously deserializes the DotEnv content of the supplied stream into a value of type
T.
[RequiresUnreferencedCode("Reflection-based DotEnv serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based DotEnv serialization may require runtime code generation.")]
public static ValueTask<T> DeserializeAsync<T>(Stream source, DotEnvSerializerOptions? options = null, CancellationToken cancellationToken = default)
Parameters
sourceStreamThe source stream.
optionsDotEnvSerializerOptionsThe serializer options, or null to use the defaults.
cancellationTokenCancellationTokenA token that cancels the stream copy.
Returns
- ValueTask<T>
A task that yields the deserialized value.
Type Parameters
TThe target type.
Exceptions
- ArgumentNullException
Thrown when
sourceis null.- DotEnvFormatException
Thrown when the content is not valid DotEnv.
- DotEnvSerializationException
Thrown when the document cannot be mapped to
T, including whenTis abstract or has no public parameterless constructor, or has a member whose type is not a scalar, which is reported before the input is read.
Deserialize<T>(Stream, DotEnvSerializerOptions?)
Deserializes the DotEnv content of the supplied stream into a value of type T.
[RequiresUnreferencedCode("Reflection-based DotEnv serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based DotEnv serialization may require runtime code generation.")]
public static T Deserialize<T>(Stream source, DotEnvSerializerOptions? options = null)
Parameters
sourceStreamThe source stream.
optionsDotEnvSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- T
The deserialized value.
Type Parameters
TThe target type.
Exceptions
- ArgumentNullException
Thrown when
sourceis null.- DotEnvFormatException
Thrown when the content is not valid DotEnv.
- DotEnvSerializationException
Thrown when the document cannot be mapped to
T, including whenTis abstract or has no public parameterless constructor, or has a member whose type is not a scalar, which is reported before the input is read.
Deserialize<T>(ReadOnlySpan<byte>, DotEnvSerializerOptions?)
Deserializes the specified UTF-8 DotEnv bytes into a value of type T.
[RequiresUnreferencedCode("Reflection-based DotEnv serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based DotEnv serialization may require runtime code generation.")]
public static T Deserialize<T>(ReadOnlySpan<byte> utf8DotEnv, DotEnvSerializerOptions? options = null)
Parameters
utf8DotEnvReadOnlySpan<byte>The DotEnv source bytes.
optionsDotEnvSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- T
The deserialized value.
Type Parameters
TThe target type.
Exceptions
- DotEnvFormatException
Thrown when the bytes are not valid DotEnv.
- DotEnvSerializationException
Thrown when the document cannot be mapped to
T, including whenTis abstract or has no public parameterless constructor, or has a member whose type is not a scalar, which is reported before the input is read.
Deserialize<T>(string, DotEnvSerializerOptions?)
Deserializes the specified DotEnv text into a value of type T.
[RequiresUnreferencedCode("Reflection-based DotEnv serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based DotEnv serialization may require runtime code generation.")]
public static T Deserialize<T>(string text, DotEnvSerializerOptions? options = null)
Parameters
textstringThe DotEnv source text.
optionsDotEnvSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- T
The deserialized value.
Type Parameters
TThe target type.
Exceptions
- ArgumentNullException
Thrown when
textis null.- DotEnvFormatException
Thrown when the text is not valid DotEnv.
- DotEnvSerializationException
Thrown when the document cannot be mapped to
T, including whenTis abstract or has no public parameterless constructor, or has a member whose type is not a scalar, which is reported before the input is read.
SerializeAsync<T>(Stream, T, DotEnvSerializerOptions?, CancellationToken)
Asynchronously serializes the specified value as DotEnv to the supplied stream.
[RequiresUnreferencedCode("Reflection-based DotEnv serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based DotEnv serialization may require runtime code generation.")]
public static ValueTask SerializeAsync<T>(Stream destination, T value, DotEnvSerializerOptions? options = null, CancellationToken cancellationToken = default)
Parameters
destinationStreamThe destination stream.
valueTThe value to serialize.
optionsDotEnvSerializerOptionsThe serializer options, or null to use the defaults.
cancellationTokenCancellationTokenA token that cancels the final stream write.
Returns
- ValueTask
A task that completes when the DotEnv has been written.
Type Parameters
TThe type of value to serialize.
Exceptions
- ArgumentNullException
Thrown when
destinationis null.- DotEnvSerializationException
Thrown when
Tcannot be mapped to a DotEnv object, including when a member's type is not a scalar; when a dictionary entry that is written is not a scalar, or a member declared as object holds a value that is not, and the message then names the key; or when a member name or dictionary key is not a key the reader reads back (one matching[A-Za-z_][A-Za-z0-9_]*), and the message then names the key, with the writer's ArgumentException as the inner exception.
Serialize<T>(IBufferWriter<byte>, T, DotEnvSerializerOptions?)
Serializes the specified value as DotEnv to the supplied buffer writer.
[RequiresUnreferencedCode("Reflection-based DotEnv serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based DotEnv serialization may require runtime code generation.")]
public static void Serialize<T>(IBufferWriter<byte> destination, T value, DotEnvSerializerOptions? options = null)
Parameters
destinationIBufferWriter<byte>The buffer writer that receives the DotEnv bytes.
valueTThe value to serialize.
optionsDotEnvSerializerOptionsThe serializer options, or null to use the defaults.
Type Parameters
TThe type of value to serialize.
Exceptions
- ArgumentNullException
Thrown when
destinationis null.- DotEnvSerializationException
Thrown when
Tcannot be mapped to a DotEnv object, including when a member's type is not a scalar; when a dictionary entry that is written is not a scalar, or a member declared as object holds a value that is not, and the message then names the key; or when a member name or dictionary key is not a key the reader reads back (one matching[A-Za-z_][A-Za-z0-9_]*), and the message then names the key, with the writer's ArgumentException as the inner exception.
Serialize<T>(T, DotEnvSerializerOptions?)
Serializes the specified value to DotEnv text.
[RequiresUnreferencedCode("Reflection-based DotEnv serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based DotEnv serialization may require runtime code generation.")]
public static string Serialize<T>(T value, DotEnvSerializerOptions? options = null)
Parameters
valueTThe value to serialize.
optionsDotEnvSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- string
The DotEnv text.
Type Parameters
TThe type of value to serialize.
Exceptions
- DotEnvSerializationException
Thrown when
Tcannot be mapped to a DotEnv object, including when a member's type is not a scalar; when a dictionary entry that is written is not a scalar, or a member declared as object holds a value that is not, and the message then names the key; or when a member name or dictionary key is not a key the reader reads back (one matching[A-Za-z_][A-Za-z0-9_]*), and the message then names the key, with the writer's ArgumentException as the inner exception.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |