YamlSerializer Class
Definition
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
utf8YamlReadOnlySpan<byte>The UTF-8 encoded YAML source.
returnTypeTypeThe target type.
optionsYamlSerializerOptionsThe serializer options, or null for the defaults.
Returns
- object
The deserialized value.
Exceptions
- ArgumentNullException
returnTypeis 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
sourceStreamThe readable stream containing the UTF-8 YAML bytes.
optionsYamlSerializerOptionsThe serializer options, or null for the defaults.
cancellationTokenCancellationTokenA token that can be used to cancel the read.
Returns
- ValueTask<T>
A task that yields the deserialized value.
Type Parameters
TThe 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
sourceis null.- ArgumentException
Thrown when
sourcedoes 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
sourceStreamThe readable stream containing the UTF-8 YAML bytes.
optionsYamlSerializerOptionsThe serializer options, or null for the defaults.
Returns
- T
The deserialized value.
Type Parameters
TThe 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
sourceis null.- ArgumentException
Thrown when
sourcedoes 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
utf8YamlReadOnlySpan<byte>The UTF-8 encoded YAML source.
optionsYamlSerializerOptionsThe serializer options, or null for the defaults.
Returns
- T
The deserialized value.
Type Parameters
TThe 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
yamlstringThe YAML source.
optionsYamlSerializerOptionsThe serializer options, or null for the defaults.
Returns
- T
The deserialized value.
Type Parameters
TThe target type.
Exceptions
- ArgumentNullException
yamlis 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
valueobjectThe value to serialize.
inputTypeTypeThe declared type of the value.
optionsYamlSerializerOptionsThe serializer options, or null for the defaults.
Returns
- string
The YAML representation of
value.
Exceptions
- ArgumentNullException
inputTypeis 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
destinationStreamThe stream that receives the UTF-8 YAML bytes.
valueTThe value to serialize.
optionsYamlSerializerOptionsThe serializer options, or null for the defaults.
cancellationTokenCancellationTokenA token that can be used to cancel the write.
Returns
- ValueTask
A task that completes when the value has been written.
Type Parameters
TThe 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
destinationis null.- ArgumentException
Thrown when
destinationdoes 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
destinationIBufferWriter<byte>The buffer writer that receives the UTF-8 YAML bytes.
valueTThe value to serialize.
optionsYamlSerializerOptionsThe serializer options, or null for the defaults.
Type Parameters
TThe type of the value.
Exceptions
- ArgumentNullException
Thrown when
destinationis 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
valueTThe value to serialize.
optionsYamlSerializerOptionsThe serializer options, or null for the defaults.
Returns
- string
The YAML representation of
value.
Type Parameters
TThe 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
| Product | Versions |
|---|---|
| .NET | 8, 10 |