Table of Contents

IniSerializer Class

Definition

Namespace
Bodu.Text.Ini
Assembly
Bodu.Text.Ini.dll
Package
Bodu.Text.Ini 1.3.0
Source
IniSerializer.Binder.cs

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

source Stream

The source stream.

options IniSerializerOptions

The serializer options, or null to use the defaults.

cancellationToken CancellationToken

A token that cancels the stream copy.

Returns

ValueTask<T>

A task that yields the deserialized value.

Type Parameters

T

The target type.

Exceptions

ArgumentNullException

Thrown when source is null.

IniFormatException

Thrown when the content is not valid INI.

IniSerializationException

Thrown when the document cannot be mapped to T, including when T, or the type of a section it is read into, is abstract or has no public parameterless constructor, or when T has 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

utf8Ini ReadOnlySpan<byte>

The INI source bytes.

sectionName string

The section name, or an empty string to bind the document's global keys.

factory IIniSectionFactory<TSection>

The section factory that binds the entries.

options IniSerializerOptions

The serializer options, or null to use the defaults.

Returns

TSection

The deserialized section.

Type Parameters

TSection

The section type.

Exceptions

ArgumentNullException

Thrown when sectionName or factory is 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

text string

The INI source text.

sectionName string

The section name, or an empty string to bind the document's global keys.

factory IIniSectionFactory<TSection>

The section factory that binds the entries.

options IniSerializerOptions

The serializer options, or null to use the defaults.

Returns

TSection

The deserialized section.

Type Parameters

TSection

The section type.

Exceptions

ArgumentNullException

Thrown when text, sectionName, or factory is 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

source Stream

The source stream.

options IniSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The target type.

Exceptions

ArgumentNullException

Thrown when source is null.

IniFormatException

Thrown when the content is not valid INI.

IniSerializationException

Thrown when the document cannot be mapped to T, including when T, or the type of a section it is read into, is abstract or has no public parameterless constructor, or when T has 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

utf8Ini ReadOnlySpan<byte>

The INI source bytes.

options IniSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The 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 when T, or the type of a section it is read into, is abstract or has no public parameterless constructor, or when T has 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

text string

The INI source text.

options IniSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The target type.

Exceptions

ArgumentNullException

Thrown when text is null.

IniFormatException

Thrown when the text is not valid INI.

IniSerializationException

Thrown when the document cannot be mapped to T, including when T, or the type of a section it is read into, is abstract or has no public parameterless constructor, or when T has 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

destination Stream

The destination stream.

value T

The value to serialize.

options IniSerializerOptions

The serializer options, or null to use the defaults.

cancellationToken CancellationToken

A token that cancels the final stream write.

Returns

ValueTask

A task that completes when the INI has been written.

Type Parameters

T

The type of value to serialize.

Exceptions

ArgumentNullException

Thrown when destination is null.

IniSerializationException

Thrown when T cannot be mapped to an INI document, including when the type of value has 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 when value maps 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

destination IBufferWriter<byte>

The buffer writer that receives the INI bytes.

sectionName string

The section name, or an empty string to write the entries as global keys.

value TSection

The section value to serialize.

factory IIniSectionFactory<TSection>

The section factory that supplies the entries.

options IniSerializerOptions

The serializer options, or null to use the defaults.

Type Parameters

TSection

The section type.

Exceptions

ArgumentNullException

Thrown when destination, sectionName, value, or factory is 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

sectionName string

The section name, or an empty string to write the entries as global keys.

value TSection

The section value to serialize.

factory IIniSectionFactory<TSection>

The section factory that supplies the entries.

options IniSerializerOptions

The serializer options, or null to use the defaults.

Returns

string

The INI text.

Type Parameters

TSection

The section type.

Exceptions

ArgumentNullException

Thrown when sectionName, value, or factory is 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

destination IBufferWriter<byte>

The buffer writer that receives the INI bytes.

value T

The value to serialize.

options IniSerializerOptions

The serializer options, or null to use the defaults.

Type Parameters

T

The type of value to serialize.

Exceptions

ArgumentNullException

Thrown when destination is null.

IniSerializationException

Thrown when T cannot be mapped to an INI document, including when the type of value has 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 when value maps 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

value T

The value to serialize.

options IniSerializerOptions

The serializer options, or null to use the defaults.

Returns

string

The INI text.

Type Parameters

T

The type of value to serialize.

Exceptions

IniSerializationException

Thrown when T cannot be mapped to an INI document, including when the type of value has 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 when value maps 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

ProductVersions
.NET8, 10