IniSerializer Class
Definition
Provides methods for serializing .NET objects to INI text and deserializing INI text into .NET objects, shaped after
System.Text.Json's JsonSerializer.
public static class IniSerializer
- Inheritance
-
IniSerializer
- Inherited Members
Remarks
INI models a two-level object-of-objects, so the serializer maps a root POCO (or string-keyed dictionary) whose scalar-convertible members become global keys and whose object-shaped members - section POCOs or IDictionary<TKey, TValue> values keyed by string - become sections. A section, or the root, may be a structure, and a Nullable<T> of a structure is read into the structure: a document without the section leaves such a member null, as it leaves a section of a class. A dictionary, whether the root or a section, that implements only that generic interface, and not the non-generic IDictionary, is written and read through it, as a Dictionary<TKey, TValue> is. A dictionary whose type is not keyed by string, such as a Hashtable or a Dictionary<TKey, TValue> keyed by int, is a collection rather than an object or a section, and is rejected with IniSerializationException, as the root or as a section, when written and when read. A dictionary entry that is not a section is one key, so its value must be null or a scalar, whatever the dictionary's value type: any other value, such as a list or a class with members of its own, is rejected with IniSerializationException naming the section and the key, rather than written as its ToString() text, which does not read back. A null entry of a dictionary root, which the ignore condition writes only when it is Never, has no value to decide by, so the dictionary's value type decides: a string-keyed dictionary type writes it as an empty section, a scalar or object as an empty key, and any other type, which no empty key reads back as, is rejected. A null entry of a dictionary written as a section, the reserved global section included, is decided in the same way, except that a string-keyed dictionary type, a third level, is rejected. Property names honor PropertyNamingPolicy and the PropertyNameAttribute family; the callback interfaces (IOnSerializing and its siblings) fire around the mapping. Each member name maps to one key or section, its most derived declaration: a property or field hidden with the new modifier is neither written nor read. A type that maps two members to one name is rejected with IniSerializationException before anything is read or written. A member declared with the C# required keyword is required, as one marked RequiredAttribute is: reading a document without its key or section throws.
A POCO root's type is checked whole, once per type and options instance, before the input is read or anything is written. A member declared as object, which could be a key or a section, a member whose type is a collection other than a string-keyed dictionary, and a member of a section type that is not a scalar, which would nest beyond the second level, are each rejected with IniSerializationException naming the member. The check is on the type's shape, not the instance: it covers every mapped member, whether it can be read, set or both, and the declared type of every section, whether or not the instance holds one, so a type is rejected in both directions or in neither, and reading rejects it whether or not the document has the section. A member left out with IgnoreAttribute is not checked. A string-keyed dictionary, as the root or as a section, is checked by its entries' values instead, as they are written.
Deserialization always routes through the normalized document model, applying the options' duplicate-section and duplicate-key policies, because duplicate-section merge declares structure out of source order. The asynchronous stream overloads buffer the entire document rather than streaming it; only the stream copy is asynchronous.
Methods
DeserializeAsync<T>(Stream, IniSerializerOptions?, CancellationToken)
Asynchronously deserializes the INI content of the supplied stream into a value of type
T.
[RequiresUnreferencedCode("Reflection-based INI serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based INI serialization may require runtime code generation.")]
public static ValueTask<T> DeserializeAsync<T>(Stream source, IniSerializerOptions? options = null, CancellationToken cancellationToken = default)
Parameters
sourceStreamThe source stream.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
cancellationTokenCancellationTokenA token that cancels the stream copy.
Returns
- ValueTask<T>
A task that yields the deserialized value.
Type Parameters
TThe target type.
Exceptions
- ArgumentNullException
Thrown when
sourceis null.- IniFormatException
Thrown when the content is not valid INI.
- IniSerializationException
Thrown when the document cannot be mapped to
T, including whenT, or the type of a section it is read into, is abstract or has no public parameterless constructor, or whenThas a member INI cannot represent, which is reported before the input is read.
DeserializeSection<TSection>(ReadOnlySpan<byte>, string, IIniSectionFactory<TSection>, IniSerializerOptions?)
Deserializes one section of the specified UTF-8 INI bytes using a section factory instead of reflection.
public static TSection DeserializeSection<TSection>(ReadOnlySpan<byte> utf8Ini, string sectionName, IIniSectionFactory<TSection> factory, IniSerializerOptions? options = null)
Parameters
utf8IniReadOnlySpan<byte>The INI source bytes.
sectionNamestringThe section name, or an empty string to bind the document's global keys.
factoryIIniSectionFactory<TSection>The section factory that binds the entries.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- TSection
The deserialized section.
Type Parameters
TSectionThe section type.
Exceptions
- ArgumentNullException
Thrown when
sectionNameorfactoryis null.- IniFormatException
Thrown when the bytes are not valid INI, or when a duplicate section, duplicate key, or global-key/section-name collision violates the configured policies.
- IniSerializationException
Thrown when the document does not contain a section named
sectionName, or when the factory cannot convert a value; the conversion error is then the inner exception.
DeserializeSection<TSection>(string, string, IIniSectionFactory<TSection>, IniSerializerOptions?)
Deserializes one section of the specified INI text using a section factory instead of reflection.
public static TSection DeserializeSection<TSection>(string text, string sectionName, IIniSectionFactory<TSection> factory, IniSerializerOptions? options = null)
Parameters
textstringThe INI source text.
sectionNamestringThe section name, or an empty string to bind the document's global keys.
factoryIIniSectionFactory<TSection>The section factory that binds the entries.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- TSection
The deserialized section.
Type Parameters
TSectionThe section type.
Exceptions
- ArgumentNullException
Thrown when
text,sectionName, orfactoryis null.- IniFormatException
Thrown when the text is not valid INI.
- IniSerializationException
Thrown when the document does not contain a section named
sectionName, or when the factory cannot convert a value; the conversion error is then the inner exception.
Deserialize<T>(Stream, IniSerializerOptions?)
Deserializes the INI content of the supplied stream into a value of type T.
[RequiresUnreferencedCode("Reflection-based INI serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based INI serialization may require runtime code generation.")]
public static T Deserialize<T>(Stream source, IniSerializerOptions? options = null)
Parameters
sourceStreamThe source stream.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- T
The deserialized value.
Type Parameters
TThe target type.
Exceptions
- ArgumentNullException
Thrown when
sourceis null.- IniFormatException
Thrown when the content is not valid INI.
- IniSerializationException
Thrown when the document cannot be mapped to
T, including whenT, or the type of a section it is read into, is abstract or has no public parameterless constructor, or whenThas a member INI cannot represent, which is reported before the input is read.
Deserialize<T>(ReadOnlySpan<byte>, IniSerializerOptions?)
Deserializes the specified UTF-8 INI bytes into a value of type T.
[RequiresUnreferencedCode("Reflection-based INI serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based INI serialization may require runtime code generation.")]
public static T Deserialize<T>(ReadOnlySpan<byte> utf8Ini, IniSerializerOptions? options = null)
Parameters
utf8IniReadOnlySpan<byte>The INI source bytes.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- T
The deserialized value.
Type Parameters
TThe target type.
Exceptions
- IniFormatException
Thrown when the bytes are not valid INI, or when a duplicate section, duplicate key, or global-key/section-name collision violates the configured policies.
- IniSerializationException
Thrown when the document cannot be mapped to
T, including whenT, or the type of a section it is read into, is abstract or has no public parameterless constructor, or whenThas a member INI cannot represent, which is reported before the input is read.
Deserialize<T>(string, IniSerializerOptions?)
Deserializes the specified INI text into a value of type T.
[RequiresUnreferencedCode("Reflection-based INI serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based INI serialization may require runtime code generation.")]
public static T Deserialize<T>(string text, IniSerializerOptions? options = null)
Parameters
textstringThe INI source text.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- T
The deserialized value.
Type Parameters
TThe target type.
Exceptions
- ArgumentNullException
Thrown when
textis null.- IniFormatException
Thrown when the text is not valid INI.
- IniSerializationException
Thrown when the document cannot be mapped to
T, including whenT, or the type of a section it is read into, is abstract or has no public parameterless constructor, or whenThas a member INI cannot represent, which is reported before the input is read.
SerializeAsync<T>(Stream, T, IniSerializerOptions?, CancellationToken)
Asynchronously serializes the specified value as INI to the supplied stream.
[RequiresUnreferencedCode("Reflection-based INI serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based INI serialization may require runtime code generation.")]
public static ValueTask SerializeAsync<T>(Stream destination, T value, IniSerializerOptions? options = null, CancellationToken cancellationToken = default)
Parameters
destinationStreamThe destination stream.
valueTThe value to serialize.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
cancellationTokenCancellationTokenA token that cancels the final stream write.
Returns
- ValueTask
A task that completes when the INI has been written.
Type Parameters
TThe type of value to serialize.
Exceptions
- ArgumentNullException
Thrown when
destinationis null.- IniSerializationException
Thrown when
Tcannot be mapped to an INI document, including when the type ofvaluehas a member INI cannot represent, which is reported before anything is written, when a dictionary entry that is not a section holds a value that is not a scalar, or whenvaluemaps to a key, section name or value that Utf8IniWriter refuses because it would not read back unchanged; the message then names the section and key, and the writer's ArgumentException is the inner exception.
SerializeSection<TSection>(IBufferWriter<byte>, string, TSection, IIniSectionFactory<TSection>, IniSerializerOptions?)
Serializes the specified value as one INI section to the supplied buffer writer using a section factory instead of reflection.
public static void SerializeSection<TSection>(IBufferWriter<byte> destination, string sectionName, TSection value, IIniSectionFactory<TSection> factory, IniSerializerOptions? options = null)
Parameters
destinationIBufferWriter<byte>The buffer writer that receives the INI bytes.
sectionNamestringThe section name, or an empty string to write the entries as global keys.
valueTSectionThe section value to serialize.
factoryIIniSectionFactory<TSection>The section factory that supplies the entries.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
Type Parameters
TSectionThe section type.
Exceptions
- ArgumentNullException
Thrown when
destination,sectionName,value, orfactoryis null.- IniSerializationException
Thrown when
sectionName, or a key or value the factory supplies, is one that Utf8IniWriter refuses because it would not read back unchanged; the message names the section and key, and the writer's ArgumentException is the inner exception.
SerializeSection<TSection>(string, TSection, IIniSectionFactory<TSection>, IniSerializerOptions?)
Serializes the specified value as one INI section using a section factory instead of reflection.
public static string SerializeSection<TSection>(string sectionName, TSection value, IIniSectionFactory<TSection> factory, IniSerializerOptions? options = null)
Parameters
sectionNamestringThe section name, or an empty string to write the entries as global keys.
valueTSectionThe section value to serialize.
factoryIIniSectionFactory<TSection>The section factory that supplies the entries.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- string
The INI text.
Type Parameters
TSectionThe section type.
Exceptions
- ArgumentNullException
Thrown when
sectionName,value, orfactoryis null.- IniSerializationException
Thrown when
sectionName, or a key or value the factory supplies, is one that Utf8IniWriter refuses because it would not read back unchanged; the message names the section and key, and the writer's ArgumentException is the inner exception.
Serialize<T>(IBufferWriter<byte>, T, IniSerializerOptions?)
Serializes the specified value as INI to the supplied buffer writer.
[RequiresUnreferencedCode("Reflection-based INI serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based INI serialization may require runtime code generation.")]
public static void Serialize<T>(IBufferWriter<byte> destination, T value, IniSerializerOptions? options = null)
Parameters
destinationIBufferWriter<byte>The buffer writer that receives the INI bytes.
valueTThe value to serialize.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
Type Parameters
TThe type of value to serialize.
Exceptions
- ArgumentNullException
Thrown when
destinationis null.- IniSerializationException
Thrown when
Tcannot be mapped to an INI document, including when the type ofvaluehas a member INI cannot represent, which is reported before anything is written, when a dictionary entry that is not a section holds a value that is not a scalar, or whenvaluemaps to a key, section name or value that Utf8IniWriter refuses because it would not read back unchanged; the message then names the section and key, and the writer's ArgumentException is the inner exception.
Serialize<T>(T, IniSerializerOptions?)
Serializes the specified value to INI text.
[RequiresUnreferencedCode("Reflection-based INI serialization may require members that trimming cannot statically determine.")]
[RequiresDynamicCode("Reflection-based INI serialization may require runtime code generation.")]
public static string Serialize<T>(T value, IniSerializerOptions? options = null)
Parameters
valueTThe value to serialize.
optionsIniSerializerOptionsThe serializer options, or null to use the defaults.
Returns
- string
The INI text.
Type Parameters
TThe type of value to serialize.
Exceptions
- IniSerializationException
Thrown when
Tcannot be mapped to an INI document, including when the type ofvaluehas a member INI cannot represent, which is reported before anything is written, when a dictionary entry that is not a section holds a value that is not a scalar, or whenvaluemaps to a key, section name or value that Utf8IniWriter refuses because it would not read back unchanged; the message then names the section and key, and the writer's ArgumentException is the inner exception.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |