Table of Contents

Bodu.Text.Bencode Namespace

Package

Bodu.Text.Bencode

Purpose

Bodu.Text.Bencode is a Bencode (BEP 3) serializer for .NET 8. It maps plain CLR objects to and from Bencode - the BitTorrent metadata format - through a configurable converter model, over a low-level, forward-only token reader and writer, with both a mutable and a read-only document object model.

The public surface layers four tiers: a static BencodeSerializer for object mapping, the Utf8BencodeReader / Utf8BencodeWriter ref struct pair for forward-only token processing, a mutable BencodeNode DOM, and a read-only BencodeDocument DOM. The twin library Bodu.Text.Toml applies the identical shape to TOML.

Output is always canonical Bencode: dictionary entries are emitted in ascending bytewise key order. For binary-to-text encodings (Base16 / Base32 / Base64 / Base58 / Base85) that operate on flat byte sequences without a structural grammar, see the companion Bodu.Text.Encoding package.

Static documentation

Key types

Serializer (Bodu.Text.Bencode)

Low-level reader / writer

Document object models

Converters and attributes (Bodu.Text.Bencode.Serialization)

Example

using Bodu.Text.Bencode;

public sealed class TorrentInfo
{
    public string Name { get; set; } = "";
    public long Length { get; set; }
}

byte[] payload = BencodeSerializer.Serialize(new TorrentInfo { Name = "ubuntu.iso", Length = 1024 });
// d6:Lengthi1024e4:Name10:ubuntu.isoe   (dictionary keys in canonical order)

TorrentInfo info = BencodeSerializer.Deserialize<TorrentInfo>(payload);

// Edit a document without a model:
using Bodu.Text.Bencode.Nodes;
BencodeNode node = BencodeNode.Parse(payload)!;
byte[] back = node.ToByteArray();

Notes

  • Full serializer surface. The converter, attribute, callback, naming-policy, and enum-converter surfaces are all present.
  • Shared serialization core. The library references Bodu.Text.Serialization for the attribute family, the naming policies, the ignore / creation / unmapped-member enums, and the serialization callback interfaces, and compiles that package's shared metadata resolver and converter engine under its own format symbol; the reader, writer, DOMs, and format converters are Bencode-specific. Its twin, Bodu.Text.Toml, mirrors it type for type for TOML; Bodu.Text.Yaml shares the architecture with a YAML-tuned surface.
  • Canonical output. Bencode has exactly one canonical encoding for any value: integers use the shortest decimal representation with no padding and no + sign; dictionary keys are sorted by raw byte order; no whitespace is permitted. The serializer always produces canonical output, and the reader rejects every non-canonical input.
  • Value mapping. Strings, byte[], and memory-of-byte map to byte strings, the integer family - spanning the full long.MinValue through ulong.MaxValue range, with the 128-bit types confined to the 64-bit surfaces - to i…e, and enums to member-name byte strings. Collections (arrays, lists, sets, queues, stacks, and the concurrent collections) map to lists, with a Stack<T> round-trip reversing the stack (the writer emits pop order). Dictionaries map to canonical dictionaries; keys may be strings, integers, enums, Guid, bool, or char, stringified on the wire. An object-typed member writes its runtime type and reads back as a BencodeElement; the read-only DOM types participate directly. Types with no canonical Bencode form - Booleans, floating-point, and date-times - require a registered BencodeConverter<T>; a null member is omitted on write. Public fields participate via IncludeFields or [Include]. The full per-type list is in the built-in converter catalog.
  • Errors. Malformed bytes surface through BencodeFormatException; binding failures through BencodeSerializationException.
  • See also: the introduction, core concepts, and getting-started; the Using Bencode and writing converters guides; and the sibling TOML and YAML libraries.

Namespaces

Bodu.Text.Bencode.Document
Bodu.Text.Bencode.Nodes
Bodu.Text.Bencode.Reader
Bodu.Text.Bencode.Serialization
Bodu.Text.Bencode.Writer

Classes

BencodeFormatException

Represents an error that occurs when bencoded data is malformed.

BencodeSerializationException

The exception thrown when a value cannot be bound to or from a Bencode document during serialization - for example a type mismatch, a missing required member, or a value Bencode cannot represent.

BencodeSerializer

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.

BencodeSerializerOptions

Configures how values are serialized to and deserialized from Bencode: the converters to use, the property naming policy, the default ignore condition, and the maximum nesting depth.

Enums

BencodeSerializerDefaults

Specifies a base set of defaults applied when a BencodeSerializerOptions instance is created for a particular usage scenario.

BencodeTokenType

Identifies the kind of token a Utf8BencodeReader is positioned on.

BencodeValueKind

Identifies the kind of value a Bencode element represents.