IniSerializer Class

Definition

Namespace

Bodu.Text.Ini

Assembly

Bodu.Text.Ini.dll

Package

Bodu.Text.Ini 1.0.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

object

IniSerializer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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 member nested beyond the second level is rejected. Property names honour PropertyNamingPolicy and the PropertyNameAttribute family; the callback interfaces (IOnSerializing and its siblings) fire around the mapping.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Applies to

Product	Versions
.NET	8, 10