TomlSerializer Class

Definition

Namespace

Bodu.Text.Toml

Assembly

Bodu.Text.Toml.dll

Package

Bodu.Text.Toml 1.0.0

Source

TomlSerializer.cs

Provides static methods for serializing values to normalized TOML text and deserializing TOML back into values, mapping plain CLR objects to and from the format through configurable converters.

public static class TomlSerializer

Inheritance

object

TomlSerializer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

string text = TomlSerializer.Serialize(new ServerConfig { Host = "localhost", Port = 8080 });
ServerConfig config = TomlSerializer.Deserialize<ServerConfig>(text);

Remarks

A TOML document's root is always a table, so the type serialized at the document root must map to an object or a string-keyed dictionary; serializing a top-level scalar or array throws TomlSerializationException. Scalars map to the corresponding TOML kinds; enumerations to strings; a byte array to an array of integers or a Base64 string per ByteArrayHandling; and TOML has no null, so a null member is omitted by default and a null array element is rejected.

TOML has no representation for an object reference, so reference identity is not preserved: a value reachable by more than one path is written once per path, by value, and a reference cycle is rejected with TomlSerializationException rather than serialized.

Each entry point accepts an optional TomlSerializerOptions. When none is supplied a default instance is used. Reusing a single configured options object across many calls is the efficient pattern, because resolved converters and type metadata are cached on it.

Methods

DeserializeAsync<T>(Stream, TomlSerializerOptions?, CancellationToken)

Asynchronously deserializes a value of type T by reading a stream of UTF-8 TOML bytes to its end.

[RequiresUnreferencedCode("TOML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("TOML serialization and deserialization construct converters for collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static ValueTask<T> DeserializeAsync<T>(Stream source, TomlSerializerOptions? options = null, CancellationToken cancellationToken = default)

Parameters

source Stream

The readable stream containing the UTF-8 TOML bytes.

options TomlSerializerOptions

The serializer options, or null to use the defaults.

cancellationToken CancellationToken

A token that can be used to cancel the read.

Returns

ValueTask<T>

A task that yields the deserialized value.

Type Parameters

T

The type to deserialize.

Remarks

The stream is copied to an in-memory buffer in full before parsing begins: the method buffers the complete input rather than parsing incrementally, so peak memory includes the entire document. Cancellation applies to reading the stream, not to the parse and bind that follow.

Exceptions

ArgumentNullException

Thrown when source is null.

ArgumentException

Thrown when source does not support reading.

TomlFormatException

Thrown when the stream contents are not a valid TOML document.

TomlSerializationException

Thrown when the document cannot be bound to T.

Deserialize<T>(Stream, TomlSerializerOptions?)

Deserializes a value of type T by reading a stream of UTF-8 TOML bytes to its end.

[RequiresUnreferencedCode("TOML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("TOML serialization and deserialization construct converters for collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static T Deserialize<T>(Stream source, TomlSerializerOptions? options = null)

Parameters

source Stream

The readable stream containing the UTF-8 TOML bytes.

options TomlSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

Remarks

The stream is read to its end into an in-memory buffer before parsing begins: the method buffers the complete input rather than parsing incrementally, so peak memory includes the entire document.

Exceptions

ArgumentNullException

Thrown when source is null.

ArgumentException

Thrown when source does not support reading.

TomlFormatException

Thrown when the stream contents are not a valid TOML document.

TomlSerializationException

Thrown when the document cannot be bound to T.

Deserialize<T>(ReadOnlySpan<byte>, TomlSerializerOptions?)

Deserializes a value of type T from the supplied UTF-8 TOML bytes.

[RequiresUnreferencedCode("TOML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("TOML serialization and deserialization construct converters for collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static T Deserialize<T>(ReadOnlySpan<byte> utf8Toml, TomlSerializerOptions? options = null)

Parameters

utf8Toml ReadOnlySpan<byte>

The UTF-8 TOML bytes to read.

options TomlSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

Exceptions

TomlFormatException

Thrown when the bytes are not a valid TOML document.

TomlSerializationException

Thrown when the document cannot be bound to T.

Deserialize<T>(string, TomlSerializerOptions?)

Deserializes a value of type T from the supplied TOML text.

[RequiresUnreferencedCode("TOML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("TOML serialization and deserialization construct converters for collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static T Deserialize<T>(string text, TomlSerializerOptions? options = null)

Parameters

text string

The TOML source text.

options TomlSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

Exceptions

ArgumentNullException

Thrown when text is null.

TomlFormatException

Thrown when the text is not a valid TOML document.

TomlSerializationException

Thrown when the document cannot be bound to T.

SerializeAsync<T>(Stream, T, TomlSerializerOptions?, CancellationToken)

Asynchronously serializes the specified value as UTF-8 TOML to the supplied stream.

[RequiresUnreferencedCode("TOML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("TOML serialization and deserialization construct converters for collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static ValueTask SerializeAsync<T>(Stream destination, T value, TomlSerializerOptions? options = null, CancellationToken cancellationToken = default)

Parameters

destination Stream

The stream that receives the UTF-8 TOML bytes.

value T

The value to serialize.

options TomlSerializerOptions

The serializer options, or null to use the defaults.

cancellationToken CancellationToken

A token that can be used to cancel the write.

Returns

ValueTask

A task that completes when the value has been written.

Type Parameters

T

The type of the value to serialize.

Remarks

The value is serialized into an in-memory buffer in full and then written to the stream in a single asynchronous operation: the method buffers the complete output rather than streaming it, so peak memory includes the entire rendered document. Cancellation applies to the final write, not to the serialization that precedes it.

Exceptions

ArgumentNullException

Thrown when destination is null.

ArgumentException

Thrown when destination does not support writing.

TomlSerializationException

Thrown when the value does not map to a table at the document root, or cannot be represented in TOML.

Serialize<T>(IBufferWriter<byte>, T, TomlSerializerOptions?)

Serializes the specified value as UTF-8 TOML to the supplied buffer writer.

[RequiresUnreferencedCode("TOML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("TOML serialization and deserialization construct converters for collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static void Serialize<T>(IBufferWriter<byte> destination, T value, TomlSerializerOptions? options = null)

Parameters

destination IBufferWriter<byte>

The buffer writer that receives the UTF-8 TOML bytes.

value T

The value to serialize.

options TomlSerializerOptions

The serializer options, or null to use the defaults.

Type Parameters

T

The type of the value to serialize.

Exceptions

ArgumentNullException

Thrown when destination is null.

NotSupportedException

Thrown when no converter is configured for a type that is encountered.

TomlSerializationException

Thrown when the value does not map to a table at the document root, or cannot be represented in TOML.

Serialize<T>(T, TomlSerializerOptions?)

Serializes the specified value to normalized TOML text.

[RequiresUnreferencedCode("TOML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("TOML serialization and deserialization construct converters for collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public static string Serialize<T>(T value, TomlSerializerOptions? options = null)

Parameters

value T

The value to serialize.

options TomlSerializerOptions

The serializer options, or null to use the defaults.

Returns

string

The TOML representation of value.

Type Parameters

T

The type of the value to serialize.

Exceptions

NotSupportedException

Thrown when no converter is configured for a type that is encountered.

TomlSerializationException

Thrown when the value does not map to a table at the document root, or cannot be represented in TOML.

Applies to

Product	Versions
.NET	8, 10