Table of Contents

YamlSerializer Class

Definition

Namespace
Bodu.Text.Yaml
Assembly
Bodu.Text.Yaml.dll
Package
Bodu.Text.Yaml 1.3.0
Source
YamlSerializer.Read.cs

Provides static methods to serialize objects to YAML and deserialize YAML to objects, in the manner of System.Text.Json.JsonSerializer.

public static class YamlSerializer
Inheritance
YamlSerializer
Inherited Members

Remarks

The serializer maps public properties (and optionally fields) of plain CLR types, the built-in scalar and collection types, dictionaries keyed by string, a fixed-width integer type, an enumeration, Guid, bool, or char, and enumerations. Mapping is driven by converters resolved through GetConverter(Type) over the shared serialization metadata; custom behavior is supplied through YamlConverter<T> instances registered on YamlSerializerOptions.

Methods

Deserialize(ReadOnlySpan<byte>, Type, YamlSerializerOptions?)

Deserializes UTF-8 YAML to a value of the specified type.

[RequiresUnreferencedCode("YAML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("YAML serialization and deserialization construct converters for enumeration, integer, collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static object? Deserialize(ReadOnlySpan<byte> utf8Yaml, Type returnType, YamlSerializerOptions? options = null)

Parameters

utf8Yaml ReadOnlySpan<byte>

The UTF-8 encoded YAML source.

returnType Type

The target type.

options YamlSerializerOptions

The serializer options, or null for the defaults.

Returns

object

The deserialized value.

Exceptions

ArgumentNullException

returnType is null.

YamlFormatException

The source is not valid YAML.

YamlSerializationException

The source is valid YAML, but cannot be bound to returnType.

DeserializeAsync<T>(Stream, YamlSerializerOptions?, CancellationToken)

Asynchronously deserializes a value of type T by reading a stream of UTF-8 YAML bytes to its end.

[RequiresUnreferencedCode("YAML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("YAML serialization and deserialization construct converters for enumeration, integer, collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static ValueTask<T?> DeserializeAsync<T>(Stream source, YamlSerializerOptions? options = null, CancellationToken cancellationToken = default)

Parameters

source Stream

The readable stream containing the UTF-8 YAML bytes.

options YamlSerializerOptions

The serializer options, or null for the defaults.

cancellationToken CancellationToken

A token that can be used to cancel the read.

Returns

ValueTask<T>

A task that yields the deserialized value.

Type Parameters

T

The target type.

Remarks

The stream is copied to an in-memory buffer in full before parsing begins: the method buffers the complete input rather than parsing incrementally, so peak memory includes the entire document. Cancellation applies to reading the stream, not to the parse and bind that follow.

Exceptions

ArgumentNullException

Thrown when source is null.

ArgumentException

Thrown when source does not support reading.

YamlFormatException

The stream contents are not valid YAML.

YamlSerializationException

The stream contents are valid YAML, but cannot be bound to T.

Deserialize<T>(Stream, YamlSerializerOptions?)

Deserializes a value of type T by reading a stream of UTF-8 YAML bytes to its end.

[RequiresUnreferencedCode("YAML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("YAML serialization and deserialization construct converters for enumeration, integer, collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static T? Deserialize<T>(Stream source, YamlSerializerOptions? options = null)

Parameters

source Stream

The readable stream containing the UTF-8 YAML bytes.

options YamlSerializerOptions

The serializer options, or null for the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The target type.

Remarks

The stream is read to its end into an in-memory buffer before parsing begins: the method buffers the complete input rather than parsing incrementally, so peak memory includes the entire document.

Exceptions

ArgumentNullException

Thrown when source is null.

ArgumentException

Thrown when source does not support reading.

YamlFormatException

The stream contents are not valid YAML.

YamlSerializationException

The stream contents are valid YAML, but cannot be bound to T.

Deserialize<T>(ReadOnlySpan<byte>, YamlSerializerOptions?)

Deserializes UTF-8 YAML to a value of the specified type.

[RequiresUnreferencedCode("YAML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("YAML serialization and deserialization construct converters for enumeration, integer, collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static T? Deserialize<T>(ReadOnlySpan<byte> utf8Yaml, YamlSerializerOptions? options = null)

Parameters

utf8Yaml ReadOnlySpan<byte>

The UTF-8 encoded YAML source.

options YamlSerializerOptions

The serializer options, or null for the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The target type.

Exceptions

YamlFormatException

The source is not valid YAML.

YamlSerializationException

The source is valid YAML, but cannot be bound to T.

Deserialize<T>(string, YamlSerializerOptions?)

Deserializes YAML text to a value of the specified type.

[RequiresUnreferencedCode("YAML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("YAML serialization and deserialization construct converters for enumeration, integer, collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static T? Deserialize<T>(string yaml, YamlSerializerOptions? options = null)

Parameters

yaml string

The YAML source.

options YamlSerializerOptions

The serializer options, or null for the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The target type.

Exceptions

ArgumentNullException

yaml is null.

YamlFormatException

The source is not valid YAML.

YamlSerializationException

The source is valid YAML, but cannot be bound to T.

Serialize(object?, Type, YamlSerializerOptions?)

Serializes a value of the specified type to a YAML string.

[RequiresUnreferencedCode("YAML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("YAML serialization and deserialization construct converters for enumeration, integer, collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static string Serialize(object? value, Type inputType, YamlSerializerOptions? options = null)

Parameters

value object

The value to serialize.

inputType Type

The declared type of the value.

options YamlSerializerOptions

The serializer options, or null for the defaults.

Returns

string

The YAML representation of value.

Exceptions

ArgumentNullException

inputType is null.

ArgumentException

A string or key in the value contains an unpaired surrogate.

NotSupportedException

No converter is configured for a type that is encountered.

InvalidOperationException

A type maps more than one member to the same YAML key, or a converter attribute or converter factory is misconfigured.

YamlSerializationException

The value cannot be represented in YAML: it holds a reference cycle, nests deeper than MaxDepth, maps more than one dictionary or extension-data entry to the same key, or holds an enumeration value that its converter refuses to write.

SerializeAsync<T>(Stream, T, YamlSerializerOptions?, CancellationToken)

Asynchronously serializes a value as UTF-8 YAML to the supplied stream.

[RequiresUnreferencedCode("YAML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("YAML serialization and deserialization construct converters for enumeration, integer, collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static ValueTask SerializeAsync<T>(Stream destination, T value, YamlSerializerOptions? options = null, CancellationToken cancellationToken = default)

Parameters

destination Stream

The stream that receives the UTF-8 YAML bytes.

value T

The value to serialize.

options YamlSerializerOptions

The serializer options, or null for the defaults.

cancellationToken CancellationToken

A token that can be used to cancel the write.

Returns

ValueTask

A task that completes when the value has been written.

Type Parameters

T

The type of the value.

Remarks

The value is serialized into an in-memory buffer in full and then written to the stream in a single asynchronous operation: the method buffers the complete output rather than streaming it, so peak memory includes the entire rendered document. Cancellation applies to the final write, not to the serialization that precedes it.

Exceptions

ArgumentNullException

Thrown when destination is null.

ArgumentException

Thrown when destination does not support writing, or when a string or key in the value contains an unpaired surrogate.

NotSupportedException

No converter is configured for a type that is encountered.

InvalidOperationException

A type maps more than one member to the same YAML key, or a converter attribute or converter factory is misconfigured.

YamlSerializationException

The value cannot be represented in YAML: it holds a reference cycle, nests deeper than MaxDepth, maps more than one dictionary or extension-data entry to the same key, or holds an enumeration value that its converter refuses to write.

Serialize<T>(IBufferWriter<byte>, T, YamlSerializerOptions?)

Serializes a value as UTF-8 YAML to the supplied buffer writer.

[RequiresUnreferencedCode("YAML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("YAML serialization and deserialization construct converters for enumeration, integer, collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static void Serialize<T>(IBufferWriter<byte> destination, T value, YamlSerializerOptions? options = null)

Parameters

destination IBufferWriter<byte>

The buffer writer that receives the UTF-8 YAML bytes.

value T

The value to serialize.

options YamlSerializerOptions

The serializer options, or null for the defaults.

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

Thrown when destination is null.

ArgumentException

A string or key in the value contains an unpaired surrogate.

NotSupportedException

No converter is configured for a type that is encountered.

InvalidOperationException

A type maps more than one member to the same YAML key, or a converter attribute or converter factory is misconfigured.

YamlSerializationException

The value cannot be represented in YAML: it holds a reference cycle, nests deeper than MaxDepth, maps more than one dictionary or extension-data entry to the same key, or holds an enumeration value that its converter refuses to write.

Serialize<T>(T, YamlSerializerOptions?)

Serializes a value to a YAML string.

[RequiresUnreferencedCode("YAML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("YAML serialization and deserialization construct converters for enumeration, integer, collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static string Serialize<T>(T value, YamlSerializerOptions? options = null)

Parameters

value T

The value to serialize.

options YamlSerializerOptions

The serializer options, or null for the defaults.

Returns

string

The YAML representation of value.

Type Parameters

T

The type of the value.

Exceptions

ArgumentException

A string or key in the value contains an unpaired surrogate.

NotSupportedException

No converter is configured for a type that is encountered.

InvalidOperationException

A type maps more than one member to the same YAML key, or a converter attribute or converter factory is misconfigured.

YamlSerializationException

The value cannot be represented in YAML: it holds a reference cycle, nests deeper than MaxDepth, maps more than one dictionary or extension-data entry to the same key, or holds an enumeration value that its converter refuses to write.

Applies to

ProductVersions
.NET8, 10