Table of Contents

YamlStringEnumConverter<TEnum> Class

Definition

Namespace
Bodu.Text.Yaml.Serialization
Assembly
Bodu.Text.Yaml.dll
Package
Bodu.Text.Yaml 1.3.0
Source
YamlStringEnumConverter{T}.cs

Produces a converter that serializes the enumeration TEnum as a YAML string holding its member name, applying an optional naming policy and honoring StringEnumMemberNameAttribute on individual members.

public sealed class YamlStringEnumConverter<TEnum> : YamlConverterFactory where TEnum : struct, Enum

Type Parameters

TEnum

The enumeration type the produced converter handles.

Inheritance
YamlStringEnumConverter<TEnum>
Inherited Members
Extension Methods

Examples

[Converter(typeof(YamlStringEnumConverter<Status>))]
public enum Status
{
    Active,
    OnHold,
}

// Status.OnHold serializes as the YAML scalar OnHold.

Remarks

Unlike the non-generic YamlStringEnumConverter, this strongly typed factory can be referenced from a ConverterAttribute on a member, property, or the enumeration itself, because it exposes a public parameterless constructor and applies to a single enumeration type. Like the non-generic factory's, the produced converter writes the member name regardless of WriteEnumsAsStrings. An integer accepted on read must lie within the range of the underlying type of TEnum; one outside it throws YamlSerializationException rather than being narrowed into that type.

Names are matched as System.Text.Json's JsonStringEnumConverter matches them. A member's wire name, from StringEnumMemberNameAttribute or the naming policy, binds only in its own case; the CLR name of a member the attribute does not rename also binds, in any case, while a renamed member's CLR name does not. A combination of flags is written as the comma-separated wire names of its flags, in the order ToString() lists them, and is read from a list of names in any order, with a trailing comma tolerated; an integer binds, where integers are allowed, only as the whole text. A float scalar, even an integral one such as 2.0, never binds.

A converter that does not allow integers throws YamlSerializationException on an integer scalar, and at any other scalar that is not a member's wire name and whose text has an integer in any of its comma-separated parts, such as a quoted "2", !!str 2, or Read, 2, as System.Text.Json's JsonStringEnumConverter rejects a numeric string from .NET 9. A member whose wire name is an integer's text still reads from a string scalar, because the wire names are matched first. Such a converter also refuses to write a value that is neither a member nor a combination of defined flags, such as an undefined value or a flags value with an undefined bit, and throws YamlSerializationException rather than writing the decimal text it would reject on read.

Constructors

YamlStringEnumConverter()

Initializes a new instance of the YamlStringEnumConverter<TEnum> class that applies no naming policy and accepts integers on read.

public YamlStringEnumConverter()

YamlStringEnumConverter(NamingPolicy?, bool)

Initializes a new instance of the YamlStringEnumConverter<TEnum> class with the specified naming policy and integer-handling behavior.

public YamlStringEnumConverter(NamingPolicy? namingPolicy, bool allowIntegerValues)

Parameters

namingPolicy NamingPolicy

The naming policy applied to member names, or null to use member names unchanged.

allowIntegerValues bool

Whether integer values are allowed: read from a YAML integer scalar or a scalar whose text holds one, and written as the decimal text of a value that is neither a member nor a combination of flags.

Methods

CanConvert(Type)

Determines whether the converter can convert the specified type.

public override bool CanConvert(Type typeToConvert)

Parameters

typeToConvert Type

The type to test.

Returns

bool

true when the converter handles the type; otherwise false.

CreateConverter(Type, YamlSerializerOptions)

Creates a converter for the specified type.

public override YamlConverter CreateConverter(Type typeToConvert, YamlSerializerOptions options)

Parameters

typeToConvert Type

The closed type to create a converter for.

options YamlSerializerOptions

The serializer options in effect.

Returns

YamlConverter

A converter that handles typeToConvert.

Applies to

ProductVersions
.NET8, 10