Table of Contents

DotEnvSerializer Class

Definition

Namespace
Bodu.Text.DotEnv
Assembly
Bodu.Text.DotEnv.dll
Package
Bodu.Text.DotEnv 1.3.0
Source
DotEnvSerializer.Binder.cs

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

source Stream

The source stream.

options DotEnvSerializerOptions

The serializer options, or null to use the defaults.

cancellationToken CancellationToken

A token that cancels the stream copy.

Returns

ValueTask<T>

A task that yields the deserialized value.

Type Parameters

T

The target type.

Exceptions

ArgumentNullException

Thrown when source is null.

DotEnvFormatException

Thrown when the content is not valid DotEnv.

DotEnvSerializationException

Thrown when the document cannot be mapped to T, including when T is 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

source Stream

The source stream.

options DotEnvSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The target type.

Exceptions

ArgumentNullException

Thrown when source is null.

DotEnvFormatException

Thrown when the content is not valid DotEnv.

DotEnvSerializationException

Thrown when the document cannot be mapped to T, including when T is 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

utf8DotEnv ReadOnlySpan<byte>

The DotEnv source bytes.

options DotEnvSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The target type.

Exceptions

DotEnvFormatException

Thrown when the bytes are not valid DotEnv.

DotEnvSerializationException

Thrown when the document cannot be mapped to T, including when T is 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

text string

The DotEnv source text.

options DotEnvSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The target type.

Exceptions

ArgumentNullException

Thrown when text is null.

DotEnvFormatException

Thrown when the text is not valid DotEnv.

DotEnvSerializationException

Thrown when the document cannot be mapped to T, including when T is 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

destination Stream

The destination stream.

value T

The value to serialize.

options DotEnvSerializerOptions

The serializer options, or null to use the defaults.

cancellationToken CancellationToken

A token that cancels the final stream write.

Returns

ValueTask

A task that completes when the DotEnv has been written.

Type Parameters

T

The type of value to serialize.

Exceptions

ArgumentNullException

Thrown when destination is null.

DotEnvSerializationException

Thrown when T cannot 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

destination IBufferWriter<byte>

The buffer writer that receives the DotEnv bytes.

value T

The value to serialize.

options DotEnvSerializerOptions

The serializer options, or null to use the defaults.

Type Parameters

T

The type of value to serialize.

Exceptions

ArgumentNullException

Thrown when destination is null.

DotEnvSerializationException

Thrown when T cannot 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

value T

The value to serialize.

options DotEnvSerializerOptions

The serializer options, or null to use the defaults.

Returns

string

The DotEnv text.

Type Parameters

T

The type of value to serialize.

Exceptions

DotEnvSerializationException

Thrown when T cannot 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

ProductVersions
.NET8, 10