YamlWriter Class

Namespace: Meziantou.Framework.Yaml.Serialization
Assembly: Meziantou.Framework.Yaml.dll
Package: Meziantou.Framework.Yaml 2.0.11
Source: YamlWriter.cs
Available in package assets: net10.0net11.0

Writes YAML tokens for use by YamlConverter implementations.

public sealed class YamlWriter : YamlReaderWriterBase

Inheritance: YamlReaderWriterBase YamlWriter

Nested types

Name	Description
YamlWriter.BlockSequenceItemStyleScope	Restores the block sequence item styles that were active before a `YamlWriter.PushBlockSequenceItemStyle` call.
YamlWriter.StringStyleScope	Restores the string style that was active before a `YamlWriter.PushStringStyle` call.

Constructors

Name	Description
YamlWriter(TextWriter, YamlSerializerOptions?)	Initializes a new instance of the `YamlWriter` class.
YamlWriter(StringBuilder, YamlSerializerOptions?)	Initializes a new instance of the `YamlWriter` class that writes directly to a `StringBuilder`.

YamlWriter overloads

YamlWriter(TextWriter, YamlSerializerOptions?)

YamlWriter.cs

Initializes a new instance of the YamlWriter class.

public YamlWriter(TextWriter writer, YamlSerializerOptions? options = null)

Parameters

writer TextWriter: The destination writer.
options YamlSerializerOptions?: The serializer options used for formatting.

Exceptions

ArgumentNullException: writer is null.

YamlWriter(StringBuilder, YamlSerializerOptions?)

YamlWriter.cs

Initializes a new instance of the YamlWriter class that writes directly to a StringBuilder.

public YamlWriter(StringBuilder stringBuilder, YamlSerializerOptions? options = null)

Parameters

stringBuilder StringBuilder: The destination string builder.
options YamlSerializerOptions?: The serializer options used for formatting.

Exceptions

ArgumentNullException: stringBuilder is null.

Properties

Name	Description
IsCollectingReferences	Gets a value indicating whether this writer only collects the object references of the value being serialized, and discards what it writes.

IsCollectingReferences

YamlWriter.cs

Gets a value indicating whether this writer only collects the object references of the value being serialized, and discards what it writes.

public bool IsCollectingReferences { get; }

Property value

bool

Remarks

With YamlReferenceHandling.PreserveMinimal, a value is written twice: a first pass finds the references that are shared or cyclic, and only those get an anchor when the value is actually written by the second pass. Converters are called in both passes, so a converter with side effects can check this property to run them once.

The IYamlOnSerialized.OnSerialized callback is not invoked by the first pass. See YamlWriter.ShouldInvokeOnSerializing for the IYamlOnSerializing.OnSerializing callback.

Methods

Name	Description
PushBlockSequenceItemStyle(YamlSequenceItemStyle, YamlSequenceItemStyle)	Temporarily overrides how nested block collections are emitted when they appear as items in block sequences.
PushStringStyle(ScalarStyle)	Temporarily overrides the style used to write string values.
ShouldInvokeOnSerializing(object)	Determines whether the `IYamlOnSerializing.OnSerializing` callback of `value` is invoked by this writer, so it runs once when the value is written by the two passes of `YamlReferenceHandling.PreserveMinimal`.
TryWriteReference(object?)	Attempts to preserve object references by writing an alias when `value` was previously anchored, or by writing an anchor for the next value when it is seen for the first time.
WriteAlias(string)	Writes a YAML alias value (a reference to an anchor).
WriteAnchor(string)	Writes a YAML anchor for the next node, which is a mapping key when `YamlWriter.WritePropertyName` is called next.
WriteDictionaryKey(object)	Writes a dictionary key the way the built-in dictionary converters write it.
WriteEndMapping()	Writes the end of a mapping.
WriteEndSequence()	Writes the end of a sequence.
WriteNullValue()	Writes a null scalar.
WritePropertyName(string)	Writes a mapping key.
WriteScalar(bool)	Writes a boolean scalar value.
WriteScalar(byte)	Writes an 8-bit unsigned integer scalar value.
WriteScalar(char)	Writes a character scalar value.
WriteScalar(DateOnly)	Writes a date-only scalar value using the round-trip format.
WriteScalar(DateTime)	Writes a date and time scalar value using the round-trip format.
WriteScalar(DateTimeOffset)	Writes a date and time with offset scalar value using the round-trip format.
WriteScalar(decimal)	Writes a decimal scalar value.
WriteScalar(double)	Writes a double-precision floating-point scalar value.
WriteScalar(Guid)	Writes a GUID scalar value.
WriteScalar(Half)	Writes a half-precision floating-point scalar value.
WriteScalar(Int128)	Writes a 128-bit signed integer scalar value.
WriteScalar(short)	Writes a 16-bit signed integer scalar value.
WriteScalar(int)	Writes a 32-bit signed integer scalar value.
WriteScalar(long)	Writes a 64-bit signed integer scalar value.
WriteScalar(nint)	Writes a platform-sized signed integer scalar value.
WriteScalar(BFloat16)	Writes a bfloat16 floating-point scalar value.
WriteScalar(Decimal128)	Writes a 128-bit IEEE 754 decimal floating-point scalar value.
WriteScalar(Decimal32)	Writes a 32-bit IEEE 754 decimal floating-point scalar value.
WriteScalar(Decimal64)	Writes a 64-bit IEEE 754 decimal floating-point scalar value.
WriteScalar(ReadOnlySpan<char>)	Writes a scalar value from a character span.
WriteScalar(sbyte)	Writes an 8-bit signed integer scalar value.
WriteScalar(float)	Writes a single-precision floating-point scalar value.
WriteScalar(string?)	Writes a scalar value.
WriteScalar(TimeOnly)	Writes a time-only scalar value using the round-trip format.
WriteScalar(TimeSpan)	Writes a time interval scalar value using the constant format.
WriteScalar(UInt128)	Writes a 128-bit unsigned integer scalar value.
WriteScalar(ushort)	Writes a 16-bit unsigned integer scalar value.
WriteScalar(uint)	Writes a 32-bit unsigned integer scalar value.
WriteScalar(ulong)	Writes a 64-bit unsigned integer scalar value.
WriteScalar(nuint)	Writes a platform-sized unsigned integer scalar value.
WriteScalar<T>(T)	Writes a scalar value for a span-formattable type using invariant culture formatting.
WriteStartMapping()	Writes the start of a mapping.
WriteStartSequence()	Writes the start of a sequence.
WriteString(string?)	Writes a CLR string value, quoting ambiguous YAML scalars when configured.
WriteTag(string)	Writes a YAML tag for the next node, which is a mapping key when `YamlWriter.WritePropertyName` is called next.

PushBlockSequenceItemStyle(YamlSequenceItemStyle, YamlSequenceItemStyle)

YamlWriter.cs

Temporarily overrides how nested block collections are emitted when they appear as items in block sequences.

public YamlWriter.BlockSequenceItemStyleScope PushBlockSequenceItemStyle(YamlSequenceItemStyle mappingStyle, YamlSequenceItemStyle sequenceStyle)

Parameters

mappingStyle YamlSequenceItemStyle: The mapping style override, or YamlSequenceItemStyle.Default to keep the current mapping style.
sequenceStyle YamlSequenceItemStyle: The sequence style override, or YamlSequenceItemStyle.Default to keep the current sequence style.

Returns

YamlWriter.BlockSequenceItemStyleScope A scope that restores the previous styles when disposed.

Exceptions

ArgumentOutOfRangeException: mappingStyle or sequenceStyle is not a defined YamlSequenceItemStyle.

PushStringStyle(ScalarStyle)

YamlWriter.cs

Temporarily overrides the style used to write string values.

public YamlWriter.StringStyleScope PushStringStyle(ScalarStyle style)

Parameters

style ScalarStyle: The style override, or ScalarStyle.Any to keep the current style.

Returns

YamlWriter.StringStyleScope A scope that restores the previous style when disposed.

Exceptions

ArgumentOutOfRangeException: style is not a defined ScalarStyle.

Remarks

The style applies to string values only. It is ignored for a value that cannot be represented in it, and for mapping keys.

ShouldInvokeOnSerializing(object)

YamlWriter.cs

Determines whether the IYamlOnSerializing.OnSerializing callback of value is invoked by this writer, so it runs once when the value is written by the two passes of YamlReferenceHandling.PreserveMinimal.

public bool ShouldInvokeOnSerializing(object value)

Parameters

value object: The value about to be written.

Returns

bool true when the callback must be invoked before writing value; otherwise false.

Exceptions

ArgumentNullException: value is null.

Remarks

The callback of an object runs in the first pass, before its references are collected, so the second pass writes the same references. The callback of a value type runs in the second pass: each pass writes its own copy of the value, so a change made to the copy of the first pass would be lost.

This method always returns true for other reference handling modes. It is intended for generated serializers and custom converters that invoke the serialization callbacks themselves. See YamlWriter.IsCollectingReferences.

TryWriteReference(object?)

YamlWriter.cs

Attempts to preserve object references by writing an alias when value was previously anchored, or by writing an anchor for the next value when it is seen for the first time.

public bool TryWriteReference(object? value)

Parameters

value object?: The value to track.

Returns

bool true when an alias was written and no further output for this value is required.

Remarks

This method is intended for use by generated serializers and custom converters. It is a no-op unless YamlSerializerOptions.ReferenceHandling is YamlReferenceHandling.Preserve or YamlReferenceHandling.PreserveMinimal.

WriteAlias(string)

YamlWriter.cs

Writes a YAML alias value (a reference to an anchor).

public void WriteAlias(string alias)

Parameters

alias string

WriteAnchor(string)

YamlWriter.cs

Writes a YAML anchor for the next node, which is a mapping key when YamlWriter.WritePropertyName is called next.

public void WriteAnchor(string anchor)

Parameters

anchor string

WriteDictionaryKey(object)

YamlWriter.cs

Writes a dictionary key the way the built-in dictionary converters write it.

public void WriteDictionaryKey(object key)

Parameters

key object: The key.

Exceptions

YamlException: key is null.
InvalidOperationException: The writer is not positioned within a mapping key.

Remarks

A string key is converted using YamlSerializerOptions.DictionaryKeyPolicy and is quoted when it would resolve to a null, a boolean, or a number, so it is read back as a string by an untyped reader. An enum key is written with the names of the enum converter, and the other keys use their invariant representation (true, 1.5, .inf, the round-trip format of dates, ...).

This is how the keys of a dictionary whose key type is Object are written.

WriteEndMapping()

YamlWriter.cs

Writes the end of a mapping.

public void WriteEndMapping()

WriteEndSequence()

YamlWriter.cs

Writes the end of a sequence.

public void WriteEndSequence()

WriteNullValue()

YamlWriter.cs

Writes a null scalar.

public void WriteNullValue()

WritePropertyName(string)

YamlWriter.cs

Writes a mapping key.

public void WritePropertyName(string name)

Parameters

name string: The key name.

Exceptions

InvalidOperationException: The writer is not positioned within a mapping key.

WriteScalar overloads

WriteScalar(bool)

YamlWriter.cs

Writes a boolean scalar value.

public void WriteScalar(bool value)

Parameters

value bool: The value to write.

WriteScalar(byte)

YamlWriter.cs

Writes an 8-bit unsigned integer scalar value.

public void WriteScalar(byte value)

Parameters

value byte: The value to write.

WriteScalar(char)

YamlWriter.cs

Writes a character scalar value.

public void WriteScalar(char value)

Parameters

value char: The value to write.

WriteScalar(DateOnly)

YamlWriter.cs

Writes a date-only scalar value using the round-trip format.

public void WriteScalar(DateOnly value)

Parameters

value DateOnly: The value to write.

WriteScalar(DateTime)

YamlWriter.cs

Writes a date and time scalar value using the round-trip format.

public void WriteScalar(DateTime value)

Parameters

value DateTime: The value to write.

WriteScalar(DateTimeOffset)

YamlWriter.cs

Writes a date and time with offset scalar value using the round-trip format.

public void WriteScalar(DateTimeOffset value)

Parameters

value DateTimeOffset: The value to write.

WriteScalar(decimal)

YamlWriter.cs

Writes a decimal scalar value.

public void WriteScalar(decimal value)

Parameters

value decimal: The value to write.

WriteScalar(double)

YamlWriter.cs

Writes a double-precision floating-point scalar value.

public void WriteScalar(double value)

Parameters

value double: The value to write.

WriteScalar(Guid)

YamlWriter.cs

Writes a GUID scalar value.

public void WriteScalar(Guid value)

Parameters

value Guid: The value to write.

WriteScalar(Half)

YamlWriter.cs

Writes a half-precision floating-point scalar value.

public void WriteScalar(Half value)

Parameters

value Half: The value to write.

WriteScalar(Int128)

YamlWriter.cs

Writes a 128-bit signed integer scalar value.

public void WriteScalar(Int128 value)

Parameters

value Int128: The value to write.

WriteScalar(short)

YamlWriter.cs

Writes a 16-bit signed integer scalar value.

public void WriteScalar(short value)

Parameters

value short: The value to write.

WriteScalar(int)

YamlWriter.cs

Writes a 32-bit signed integer scalar value.

public void WriteScalar(int value)

Parameters

value int: The value to write.

WriteScalar(long)

YamlWriter.cs

Writes a 64-bit signed integer scalar value.

public void WriteScalar(long value)

Parameters

value long: The value to write.

WriteScalar(nint)

YamlWriter.cs

Writes a platform-sized signed integer scalar value.

public void WriteScalar(nint value)

Parameters

value nint: The value to write.

WriteScalar(BFloat16)

YamlWriter.cs

Available in: net11.0(not available in the other target frameworks of the package)

Writes a bfloat16 floating-point scalar value.

public void WriteScalar(BFloat16 value)

Parameters

value BFloat16: The value to write.

WriteScalar(Decimal128)

YamlWriter.cs

Available in: net11.0(not available in the other target frameworks of the package)

Writes a 128-bit IEEE 754 decimal floating-point scalar value.

public void WriteScalar(Decimal128 value)

Parameters

value Decimal128: The value to write.

WriteScalar(Decimal32)

YamlWriter.cs

Available in: net11.0(not available in the other target frameworks of the package)

Writes a 32-bit IEEE 754 decimal floating-point scalar value.

public void WriteScalar(Decimal32 value)

Parameters

value Decimal32: The value to write.

WriteScalar(Decimal64)

YamlWriter.cs

Available in: net11.0(not available in the other target frameworks of the package)

Writes a 64-bit IEEE 754 decimal floating-point scalar value.

public void WriteScalar(Decimal64 value)

Parameters

value Decimal64: The value to write.

WriteScalar(ReadOnlySpan<char>)

YamlWriter.cs

Writes a scalar value from a character span.

public void WriteScalar(ReadOnlySpan<char> value)

Parameters

value ReadOnlySpan<char>: The scalar text.

Remarks

Text that a plain scalar would resolve to null, such as null or ~, is quoted.

WriteScalar(sbyte)

YamlWriter.cs

Writes an 8-bit signed integer scalar value.

public void WriteScalar(sbyte value)

Parameters

value sbyte: The value to write.

WriteScalar(float)

YamlWriter.cs

Writes a single-precision floating-point scalar value.

public void WriteScalar(float value)

Parameters

value float: The value to write.

WriteScalar(string?)

YamlWriter.cs

Writes a scalar value.

public void WriteScalar(string? value)

Parameters

value string?

Remarks

A non-null value is never written as a null scalar: text such as null or ~, which a plain scalar would resolve to null, is quoted. Use YamlWriter.WriteNullValue to write a null.

WriteScalar(TimeOnly)

YamlWriter.cs

Writes a time-only scalar value using the round-trip format.

public void WriteScalar(TimeOnly value)

Parameters

value TimeOnly: The value to write.

WriteScalar(TimeSpan)

YamlWriter.cs

Writes a time interval scalar value using the constant format.

public void WriteScalar(TimeSpan value)

Parameters

value TimeSpan: The value to write.

WriteScalar(UInt128)

YamlWriter.cs

Writes a 128-bit unsigned integer scalar value.

public void WriteScalar(UInt128 value)

Parameters

value UInt128: The value to write.

WriteScalar(ushort)

YamlWriter.cs

Writes a 16-bit unsigned integer scalar value.

public void WriteScalar(ushort value)

Parameters

value ushort: The value to write.

WriteScalar(uint)

YamlWriter.cs

Writes a 32-bit unsigned integer scalar value.

public void WriteScalar(uint value)

Parameters

value uint: The value to write.

WriteScalar(ulong)

YamlWriter.cs

Writes a 64-bit unsigned integer scalar value.

public void WriteScalar(ulong value)

Parameters

value ulong: The value to write.

WriteScalar(nuint)

YamlWriter.cs

Writes a platform-sized unsigned integer scalar value.

public void WriteScalar(nuint value)

Parameters

value nuint: The value to write.

WriteScalar<T>(T)

YamlWriter.cs

Writes a scalar value for a span-formattable type using invariant culture formatting.

public void WriteScalar<T>(T value) where T : IFormattable

Type parameters

T: The value type to write.

Parameters

value T: The value to write.

WriteStartMapping()

YamlWriter.cs

Writes the start of a mapping.

public void WriteStartMapping()

Exceptions

YamlException: The configured maximum nesting depth was exceeded.

WriteStartSequence()

YamlWriter.cs

Writes the start of a sequence.

public void WriteStartSequence()

Exceptions

YamlException: The configured maximum nesting depth was exceeded.

WriteString(string?)

YamlWriter.cs

Writes a CLR string value, quoting ambiguous YAML scalars when configured.

public void WriteString(string? value)

Parameters

value string?: The string value to write.

WriteTag(string)

YamlWriter.cs

Writes a YAML tag for the next node, which is a mapping key when YamlWriter.WritePropertyName is called next.

public void WriteTag(string tag)

Parameters

tag string: The YAML tag, such as !dog.