YamlStringEnumConverter Class
Definition
Produces a converter that serializes any enumeration as a YAML string holding its member name, applying an optional naming policy and honoring StringEnumMemberNameAttribute on individual members.
public sealed class YamlStringEnumConverter : YamlConverterFactory
- Inheritance
-
YamlStringEnumConverter
- Inherited Members
- Extension Methods
Examples
var options = new YamlSerializerOptions();
options.Converters.Add(new YamlStringEnumConverter(NamingPolicy.SnakeCaseLower, allowIntegerValues: false));
// Status.OnHold now serializes as the YAML scalar on_hold.
Remarks
Register the factory on Converters to apply it to every enumeration, or use the generic YamlStringEnumConverter<TEnum> with ConverterAttribute to apply it to a single enumeration. Two constructors are provided: a parameterless form that applies no naming policy and accepts integers on read, and a form that takes an explicit naming policy and integer-handling flag. The produced converter writes the member name regardless of WriteEnumsAsStrings. An integer accepted on read must lie within the range of the enumeration's underlying type; 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: a quoted "2" or " +2 ", !!str 2, a plain integer beyond the 64-bit range, which YAML
resolves as a string, or a list such as Read, 2. Each is rejected rather than bound as the integer, as
System.Text.Json's JsonStringEnumConverter rejects a numeric string from .NET 9. The wire names are matched
first, so a member named 1 through StringEnumMemberNameAttribute still reads from a string
scalar. 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 class that applies no naming policy and accepts integers on read.
public YamlStringEnumConverter()
YamlStringEnumConverter(NamingPolicy?, bool)
Initializes a new instance of the YamlStringEnumConverter class with the specified naming policy and integer-handling behavior.
public YamlStringEnumConverter(NamingPolicy? namingPolicy, bool allowIntegerValues)
Parameters
namingPolicyNamingPolicyThe naming policy applied to member names, or null to use member names unchanged.
allowIntegerValuesboolWhether 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
typeToConvertTypeThe type to test.
Returns
CreateConverter(Type, YamlSerializerOptions)
Creates a converter for the specified type.
public override YamlConverter CreateConverter(Type typeToConvert, YamlSerializerOptions options)
Parameters
typeToConvertTypeThe closed type to create a converter for.
optionsYamlSerializerOptionsThe serializer options in effect.
Returns
- YamlConverter
A converter that handles
typeToConvert.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |