BencodeSerializerOptions Class

Definition

Namespace

Bodu.Text.Bencode

Assembly

Bodu.Text.Bencode.dll

Package

Bodu.Text.Bencode 1.0.0

Source

BencodeSerializerOptions.cs

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.

public sealed class BencodeSerializerOptions

Inheritance

object

BencodeSerializerOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

// Configure once and reuse across calls; resolved converters are cached on the instance.
var options = new BencodeSerializerOptions
{
    PropertyNamingPolicy = NamingPolicy.SnakeCaseLower,
    DefaultIgnoreCondition = IgnoreCondition.WhenWritingDefault,
};
options.Converters.Add(new BencodeStringEnumConverter(NamingPolicy.SnakeCaseLower, allowIntegerValues: false));

byte[] bytes = BencodeSerializer.Serialize(value, options);

Remarks

An options instance becomes read-only the first time it is used to serialize or deserialize a value; subsequent attempts to change a setting throw. Resolved converters and type metadata are cached on the instance, so reusing one configured options object across many operations is the efficient pattern.

DefaultIgnoreCondition governs when a member is omitted on write. Because Bencode has no null token, a member whose value is null is omitted regardless of that setting.

Constructors

BencodeSerializerOptions()

Initializes a new instance of the BencodeSerializerOptions class with default (general-purpose) settings.

public BencodeSerializerOptions()

BencodeSerializerOptions(BencodeSerializerDefaults)

Initializes a new instance of the BencodeSerializerOptions class with a base set of defaults appropriate for the specified usage scenario.

public BencodeSerializerOptions(BencodeSerializerDefaults defaults)

Parameters

defaults BencodeSerializerDefaults

The base defaults to apply.

Remarks

Web selects camel-case property naming and case-insensitive property-name matching; General leaves the defaults unchanged.

Exceptions

ArgumentOutOfRangeException

Thrown when defaults is not a defined BencodeSerializerDefaults value.

Fields

DefaultMaxDepth

The default maximum nesting depth.

public const int DefaultMaxDepth = 64

Field Value

int

Properties

AllowDuplicateKeys

Gets or sets a value indicating whether deserialization accepts dictionaries carrying more than one entry for the same key.

public bool AllowDuplicateKeys { get; set; }

Property Value

bool

true to accept duplicate keys; otherwise false. The default is false, rejecting duplicate keys with BencodeFormatException.

Remarks

When enabled, repeated keys bind last-wins: the final occurrence of a key determines the member or dictionary entry value. The option affects reading only; the writer always rejects duplicate keys because canonical Bencode forbids them.

Exceptions

InvalidOperationException

Thrown when the options are read-only.

AllowUnsortedKeys

Gets or sets a value indicating whether deserialization accepts dictionaries whose keys are not in ascending bytewise order.

public bool AllowUnsortedKeys { get; set; }

Property Value

bool

true to accept unsorted keys; otherwise false. The default is false, rejecting unsorted keys with BencodeFormatException.

Remarks

BEP 3 requires keys sorted by raw byte order, but documents produced by older encoders occasionally violate this. The option affects reading only; output is always written in canonical key order.

Exceptions

InvalidOperationException

Thrown when the options are read-only.

Converters

Gets the list of user-registered converters, consulted in order before the built-in converters.

public IList<BencodeConverter> Converters { get; }

Property Value

IList<BencodeConverter>

The mutable converter list while the options are mutable.

DefaultIgnoreCondition

Gets or sets the default condition that determines when a member is omitted on write, applied to every member that does not carry its own IgnoreAttribute.

public IgnoreCondition DefaultIgnoreCondition { get; set; }

Property Value

IgnoreCondition

The default ignore condition; Never by default.

Remarks

Because Bencode has no null token, a member whose value is null is omitted from the output regardless of this setting, so Never behaves like WhenWritingNull for null values specifically.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is undefined, or when it is Always, which is not a valid default.

InvalidOperationException

Thrown when the options are read-only.

IncludeFields

Gets or sets a value indicating whether public fields are surfaced as serializable members alongside properties.

public bool IncludeFields { get; set; }

Property Value

bool

true to serialize and deserialize public fields; otherwise false. The default is false.

Remarks

A public field annotated with IncludeAttribute participates regardless of this setting. Fields honor the property naming policy, name and order attributes, ignore conditions, and required-member enforcement exactly like properties; a readonly field is written but never assigned on read.

Exceptions

InvalidOperationException

Thrown when the options are read-only.

IsReadOnly

Gets a value indicating whether the options have become read-only.

public bool IsReadOnly { get; }

Property Value

bool

true once the options have been used or frozen; otherwise false.

MaxDepth

Gets or sets the maximum container nesting depth permitted while serializing or deserializing.

public int MaxDepth { get; set; }

Property Value

int

The maximum depth; DefaultMaxDepth when set to zero.

Remarks

The limit bounds how deeply lists and dictionaries may nest. It is reached when serializing an object graph - or deserializing a document - whose containers nest more levels deep than the effective limit, for example a chain of objects each holding the next, a dictionary of dictionaries, or lists within lists. Crossing it is reported as a catchable failure: BencodeSerializationException while serializing, or BencodeFormatException while deserializing.

Although any non-negative value is accepted here, the effective limit is clamped to the hard ceiling, Bodu.Text.Bencode.BencodeLimits.AbsoluteMaxDepth (64); setting a larger value - even MaxValue - does not raise it. The ceiling exists because the serializer recurses one call-stack frame per nested container, so an unbounded depth on hostile or malformed input would exhaust the call stack and terminate the process with an uncatchable StackOverflowException. Clamping converts that into the catchable exceptions above.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is negative.

InvalidOperationException

Thrown when the options are read-only.

PreferredObjectCreationHandling

Gets or sets the serializer-wide preference for whether a member's value is replaced with a freshly created instance or populated when reading, applied to every type and member that does not carry its own ObjectCreationHandlingAttribute.

public ObjectCreationHandling PreferredObjectCreationHandling { get; set; }

Property Value

ObjectCreationHandling

The preferred object-creation handling; Replace by default.

Remarks

Populate applies only to collection and dictionary members whose existing value is non-null; in every other case the serializer replaces the value.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is undefined.

InvalidOperationException

Thrown when the options are read-only.

PropertyNameCaseInsensitive

Gets or sets a value indicating whether property-name matching ignores case when reading.

public bool PropertyNameCaseInsensitive { get; set; }

Property Value

bool

true to match case-insensitively; otherwise false. The default is true.

Remarks

The default is deliberately lenient: Bencode wire keys are raw bytes with no prescribed casing convention, so reads tolerate casing variation by default. The option affects reading only; written keys always use the resolved wire name unchanged.

Exceptions

InvalidOperationException

Thrown when the options are read-only.

PropertyNamingPolicy

Gets or sets the policy that translates member names to their serialized dictionary-key form.

public NamingPolicy? PropertyNamingPolicy { get; set; }

Property Value

NamingPolicy

The naming policy, or null to use member names unchanged.

Exceptions

InvalidOperationException

Thrown when the options are read-only.

UnmappedMemberHandling

Gets or sets the serializer-wide handling for a dictionary key that maps to no member of the target type when reading, applied to every type that does not carry its own UnmappedMemberHandlingAttribute.

public UnmappedMemberHandling UnmappedMemberHandling { get; set; }

Property Value

UnmappedMemberHandling

The unmapped-member handling; Skip by default.

Remarks

A type that declares an extension-data member captures unmapped keys into that member, which takes precedence over this setting, so a key absorbed by extension data never triggers Disallow.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is undefined.

InvalidOperationException

Thrown when the options are read-only.

Methods

GetConverter(Type)

Resolves the converter that handles the specified type, applying the type-level converter attribute, the registered converters, and finally the built-in converters, in that order.

public BencodeConverter GetConverter(Type typeToConvert)

Parameters

typeToConvert Type

The type to resolve a converter for.

Returns

BencodeConverter

The concrete converter for the type.

Exceptions

ArgumentNullException

Thrown when typeToConvert is null.

NotSupportedException

Thrown when no converter handles the type.

MakeReadOnly()

Freezes the options so their settings can no longer change, capturing the converter list. Called automatically before the first serialization or deserialization.

public void MakeReadOnly()

Applies to

Product	Versions
.NET	8, 10