YamlSerializerOptions Class
Definition
- Assembly
- Bodu.Text.Yaml.dll
- Package
- Bodu.Text.Yaml 1.3.0
Provides options that configure YamlSerializer, in the manner of JsonSerializerOptions.
public sealed class YamlSerializerOptions
- Inheritance
-
YamlSerializerOptions
- Inherited Members
- Extension Methods
Remarks
An options instance becomes read-only the first time it is used to serialize or deserialize, or when MakeReadOnly() is called. After that point its settable properties throw InvalidOperationException, which guarantees deterministic behavior when the same instance is shared across threads.
Constructors
YamlSerializerOptions()
Initializes a new instance of the YamlSerializerOptions class.
public YamlSerializerOptions()
YamlSerializerOptions(YamlSerializerDefaults)
Initializes a new instance of the YamlSerializerOptions class with a base set of defaults appropriate for the specified usage scenario.
public YamlSerializerOptions(YamlSerializerDefaults defaults)
Parameters
defaultsYamlSerializerDefaultsThe base defaults to apply.
Remarks
Web selects camel-case property naming and case-insensitive property-name matching; General leaves the defaults unchanged.
Exceptions
- ArgumentOutOfRangeException
Thrown when
defaultsis not a defined YamlSerializerDefaults value.
Properties
Converters
Gets the list of custom converters consulted before the built-in handling.
public IList<YamlConverter> Converters { get; }
Property Value
- IList<YamlConverter>
The converter collection.
DefaultIgnoreCondition
Gets or sets the serializer-wide default condition under which a member is omitted when writing, applied to every member that does not carry its own IgnoreCondition through an attribute.
public IgnoreCondition DefaultIgnoreCondition { get; set; }
Property Value
- IgnoreCondition
The default ignore condition; Never by default.
Exceptions
- InvalidOperationException
The options instance is read-only.
- ArgumentOutOfRangeException
Thrown when the value is undefined, or when it is Always, which is not a valid serializer-wide default.
DuplicateKeyBehavior
Gets or sets the policy applied when a mapping declares the same key more than once during deserialization.
public YamlDuplicateKeyBehavior DuplicateKeyBehavior { get; set; }
Property Value
- YamlDuplicateKeyBehavior
The duplicate-key policy; the default is Throw.
Exceptions
- InvalidOperationException
The options instance is read-only.
IncludeFields
Gets or sets a value indicating whether public fields are serialized in addition to properties.
public bool IncludeFields { get; set; }
Property Value
Exceptions
- InvalidOperationException
The options instance is read-only.
IsReadOnly
Gets a value indicating whether the options have become read-only.
public bool IsReadOnly { get; }
Property Value
MaxDepth
Gets or sets the maximum depth allowed when serializing an object graph and when parsing during deserialization.
public int MaxDepth { get; set; }
Property Value
- int
The maximum depth as set. A value of zero or less selects the default of 64, and a larger value is clamped to the hard ceiling of 64.
Remarks
The property returns the value as set, not the effective depth, so it reads 0 until it is set. Nesting
deeper than the effective depth throws YamlSerializationException while serializing and
YamlFormatException while deserializing.
Exceptions
- InvalidOperationException
The options instance is read-only.
MergeKeyBehavior
Gets or sets the policy applied to the YAML merge key (<<) during deserialization.
public YamlMergeKeyBehavior MergeKeyBehavior { get; set; }
Property Value
- YamlMergeKeyBehavior
The merge-key policy; the default is Expand.
Exceptions
- InvalidOperationException
The options instance is read-only.
NumberHandling
Gets or sets the policy applied when coercing numeric scalars to integral targets.
public YamlNumberHandling NumberHandling { get; set; }
Property Value
- YamlNumberHandling
The number-handling policy; the default is Strict.
Exceptions
- InvalidOperationException
The options instance is read-only.
PreferredObjectCreationHandling
Gets or sets the serializer-wide default for whether a member's value is replaced with a freshly created instance or populated into the value the member already holds during deserialization.
public ObjectCreationHandling PreferredObjectCreationHandling { get; set; }
Property Value
- ObjectCreationHandling
The preferred object-creation handling; the default is Replace.
Remarks
Populate reads a collection, dictionary, or object member into the value it already holds; when the member holds nothing that can be populated, the serializer replaces the value (see ObjectCreationHandling).
Exceptions
- InvalidOperationException
The options instance is read-only.
PropertyNameCaseInsensitive
Gets or sets a value indicating whether YAML keys are matched to members case-insensitively.
public bool PropertyNameCaseInsensitive { get; set; }
Property Value
Exceptions
- InvalidOperationException
The options instance is read-only.
PropertyNamingPolicy
Gets or sets the policy used to convert member names to YAML keys.
public NamingPolicy? PropertyNamingPolicy { get; set; }
Property Value
- NamingPolicy
The naming policy, or null to use member names verbatim.
Exceptions
- InvalidOperationException
The options instance is read-only.
SpecVersion
Gets or sets the YAML specification version applied when parsing during deserialization.
public YamlSpecVersion SpecVersion { get; set; }
Property Value
- YamlSpecVersion
The specification version; the default is V1_2.
Exceptions
- InvalidOperationException
The options instance is read-only.
UnmappedMemberHandling
Gets or sets the policy applied to a YAML key that does not map to any member of the target type.
public UnmappedMemberHandling UnmappedMemberHandling { get; set; }
Property Value
- UnmappedMemberHandling
The unmapped-member policy; the default is Skip.
Exceptions
- InvalidOperationException
The options instance is read-only.
WriteEnumsAsStrings
Gets or sets a value indicating whether enumerations are written as their string names.
public bool WriteEnumsAsStrings { get; set; }
Property Value
Remarks
The option governs the default enum handling. The enum converters ignore it: a converter that YamlStringEnumConverter or YamlStringEnumConverter<TEnum> produces writes names, and YamlNumberEnumConverter<TEnum> writes numeric values, whatever it says.
Exceptions
- InvalidOperationException
The options instance is read-only.
Methods
GetConverter(Type)
Resolves the converter that handles the specified type, applying the type-level converter attribute, the registered converters, and finally the built-in converters, in that order.
[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 YamlConverter GetConverter(Type typeToConvert)
Parameters
typeToConvertTypeThe type to resolve a converter for.
Returns
- YamlConverter
The concrete converter for the type.
Remarks
The first call makes the options read-only, as MakeReadOnly() does, so their settings and converter list can no longer change. The resolved converter is cached per type.
Exceptions
- ArgumentNullException
Thrown when
typeToConvertis null.- NotSupportedException
Thrown when no converter handles the type.
- InvalidOperationException
Thrown when a type-level converter attribute names a type that is not a converter or that has no public parameterless constructor, or when the converter a factory creates cannot convert the type.
MakeReadOnly()
Freezes the options so their settings can no longer change, capturing the converter list. Called automatically before the first serialization or deserialization.
public void MakeReadOnly()
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |