BencodeSerializer Class

Definition

Namespace

Bodu.Text.Bencode

Assembly

Bodu.Text.Bencode.dll

Package

Bodu.Text.Bencode 1.0.0

Source

BencodeSerializer.cs

Provides static methods for serializing values to Bencode (BEP 3) bytes and deserializing Bencode bytes back into values, mapping plain CLR objects to and from the format through configurable converters.

public static class BencodeSerializer

Inheritance

object

BencodeSerializer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

byte[] bytes = BencodeSerializer.Serialize(new Torrent { Name = "demo", PieceLength = 262144 });
Torrent torrent = BencodeSerializer.Deserialize<Torrent>(bytes);

Remarks

Each entry point accepts an optional BencodeSerializerOptions that controls converters, the property naming policy, and the maximum nesting depth. When no options are 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.

Output is always canonical Bencode: dictionary entries are emitted in ascending bytewise key order regardless of the declaration order of the corresponding members.

Methods

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

Asynchronously deserializes a value of type T from the supplied stream.

public static ValueTask<T> DeserializeAsync<T>(Stream source, BencodeSerializerOptions? options = null, CancellationToken cancellationToken = default)

Parameters

source Stream

The stream to read the Bencode bytes from.

options BencodeSerializerOptions

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 buffered in full before parsing - the span-based reader requires the complete document in memory - so only the buffering copy is asynchronous; parsing and binding run synchronously once the copy completes.

Exceptions

ArgumentNullException

Thrown when source is null.

ArgumentException

Thrown when source does not support reading.

BencodeFormatException

Thrown when the bytes are not valid Bencode.

BencodeSerializationException

Thrown when the document cannot be bound to T.

Deserialize<T>(BencodeNode, BencodeSerializerOptions?)

Deserializes a value of type T from the supplied node tree.

public static T Deserialize<T>(BencodeNode node, BencodeSerializerOptions? options = null)

Parameters

node BencodeNode

The node tree to bind.

options BencodeSerializerOptions

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 node is null.

BencodeSerializationException

Thrown when the node tree cannot be bound to T, or contains a null entry, which has no Bencode representation.

NotSupportedException

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

Deserialize<T>(byte[], BencodeSerializerOptions?)

Deserializes a value of type T from the supplied Bencode byte array.

public static T Deserialize<T>(byte[] data, BencodeSerializerOptions? options = null)

Parameters

data byte[]

The Bencode bytes to read.

options BencodeSerializerOptions

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 data is null.

BencodeFormatException

Thrown when the bytes are not valid Bencode.

BencodeSerializationException

Thrown when the document cannot be bound to T.

NotSupportedException

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

Deserialize<T>(Stream, BencodeSerializerOptions?)

Deserializes a value of type T from the supplied stream.

public static T Deserialize<T>(Stream source, BencodeSerializerOptions? options = null)

Parameters

source Stream

The stream to read the Bencode bytes from.

options BencodeSerializerOptions

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 buffered in full before parsing - the span-based reader requires the complete document in memory - so the stream's length is bounded by the 2 GiB managed-array ceiling.

Exceptions

ArgumentNullException

Thrown when source is null.

ArgumentException

Thrown when source does not support reading.

BencodeFormatException

Thrown when the bytes are not valid Bencode.

BencodeSerializationException

Thrown when the document cannot be bound to T.

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

Deserializes a value of type T from the supplied Bencode bytes.

public static T Deserialize<T>(ReadOnlySpan<byte> data, BencodeSerializerOptions? options = null)

Parameters

data ReadOnlySpan<byte>

The Bencode bytes to read.

options BencodeSerializerOptions

The serializer options, or null to use the defaults.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

Exceptions

BencodeFormatException

Thrown when the bytes are not valid Bencode.

BencodeSerializationException

Thrown when the document cannot be bound to T.

NotSupportedException

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

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

Asynchronously serializes the specified value as Bencode to the supplied stream.

public static ValueTask SerializeAsync<T>(Stream destination, T value, BencodeSerializerOptions? options = null, CancellationToken cancellationToken = default)

Parameters

destination Stream

The stream that receives the Bencode bytes.

value T

The value to serialize.

options BencodeSerializerOptions

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.

Exceptions

ArgumentNullException

Thrown when destination is null.

ArgumentException

Thrown when destination does not support writing.

SerializeToDocument<T>(T, BencodeSerializerOptions?)

Serializes the specified value into a read-only BencodeDocument.

public static BencodeDocument SerializeToDocument<T>(T value, BencodeSerializerOptions? options = null)

Parameters

value T

The value to serialize.

options BencodeSerializerOptions

The serializer options, or null to use the defaults.

Returns

BencodeDocument

A document over the serialized value; dispose it when finished.

Type Parameters

T

The type of the value to serialize.

Exceptions

NotSupportedException

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

BencodeSerializationException

Thrown when a value cannot be represented in Bencode.

SerializeToNode<T>(T, BencodeSerializerOptions?)

Serializes the specified value into a mutable BencodeNode tree.

public static BencodeNode? SerializeToNode<T>(T value, BencodeSerializerOptions? options = null)

Parameters

value T

The value to serialize.

options BencodeSerializerOptions

The serializer options, or null to use the defaults.

Returns

BencodeNode

The root node of the serialized 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.

BencodeSerializationException

Thrown when a value cannot be represented in Bencode.

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

Serializes the specified value as Bencode to the supplied buffer writer.

public static void Serialize<T>(IBufferWriter<byte> destination, T value, BencodeSerializerOptions? options = null)

Parameters

destination IBufferWriter<byte>

The buffer writer that receives the Bencode bytes.

value T

The value to serialize.

options BencodeSerializerOptions

The serializer options, or null to use the defaults.

Type Parameters

T

The type of the value to serialize.

Remarks

The value is written through the buffer writer directly, with no intermediate array. Dictionary content is buffered internally until each dictionary closes (canonical key ordering requires it), so a serialization failure part-way through a root-level list may leave that list's already-emitted bytes in the destination.

Exceptions

ArgumentNullException

Thrown when destination is null.

NotSupportedException

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

BencodeSerializationException

Thrown when a value cannot be represented in Bencode.

Serialize<T>(Stream, T, BencodeSerializerOptions?)

Serializes the specified value as Bencode to the supplied stream.

public static void Serialize<T>(Stream destination, T value, BencodeSerializerOptions? options = null)

Parameters

destination Stream

The stream that receives the Bencode bytes.

value T

The value to serialize.

options BencodeSerializerOptions

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.

ArgumentException

Thrown when destination does not support writing.

NotSupportedException

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

BencodeSerializationException

Thrown when a value cannot be represented in Bencode.

Serialize<T>(T, BencodeSerializerOptions?)

Serializes the specified value to a new Bencode byte array.

public static byte[] Serialize<T>(T value, BencodeSerializerOptions? options = null)

Parameters

value T

The value to serialize.

options BencodeSerializerOptions

The serializer options, or null to use the defaults.

Returns

byte[]

The Bencode encoding 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.

BencodeSerializationException

Thrown when a value cannot be represented in Bencode.

Applies to

Product	Versions
.NET	8, 10