Class SerializationSettings

Immutable configuration object that controls every aspect of a Scylla serialization or deserialization operation. Settings instances are created via the fluent SerializationSettings.Builder API obtained from CreateBuilder() or ToBuilder().

Inheritance

object

SerializationSettings

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.Serialization

Assembly: ScyllaCore.dll

Syntax

public sealed class SerializationSettings

Remarks

SerializationSettings is immutable after construction; all properties are set once by the SerializationSettings.Builder and cannot be modified thereafter. This makes settings instances safe to share and reuse across multiple concurrent serialization calls without additional synchronization.

Three pre-built singleton instances are provided for the most common scenarios:

• Default - JSON with all values included, reference preservation enabled, and no pretty-printing.
• CompactBinary - binary output with null and default values omitted for the smallest possible payload.
• ReadableJSON - JSON with pretty-printing enabled for human inspection during development and debugging.

For custom requirements, start from CreateBuilder() for a fresh configuration or from an existing instance's ToBuilder() to produce a modified copy without altering the original.

var settings = SerializationSettings.CreateBuilder()
    .WithFormat(SerializationFormat.JSON)
    .WithPrettyPrint(true)
    .WithReferenceHandling(ReferenceHandling.Preserve)
    .Build();

Fields

DEFAULT_INDENT

Default indentation string used when pretty-printing is enabled and no custom indent has been supplied via WithIndent(string). Defaults to a single tab character ("\t").

Declaration

public const string DEFAULT_INDENT = "\t"

Field Value

Type	Description
string

DEFAULT_MAX_DEPTH

Default maximum recursion depth used when no explicit depth is configured via WithMaxDepth(int). A value of 64 is sufficient for the vast majority of object graphs while still providing protection against deep or circular structures.

Declaration

public const int DEFAULT_MAX_DEPTH = 64

Field Value

Type	Description
int

Properties

CompactBinary

Gets a pre-built SerializationSettings instance optimized for the smallest possible payload size: binary format, null values omitted, and default values omitted.

Declaration

public static SerializationSettings CompactBinary { get; }

Property Value

Type	Description
SerializationSettings	A shared, immutable SerializationSettings singleton for compact binary serialization.

Remarks

Note that binary serialization is not yet natively implemented; until it is, the engine encodes binary output as UTF-8 JSON bytes. The null and default-value omission settings still reduce the JSON payload size in the interim.

CustomSerializers

Gets the per-operation custom type serializers registered via RegisterSerializer<T>(ITypeSerializer<T>). These take priority over globally registered serializers when the engine resolves a serializer for a specific type.

Declaration

public IReadOnlyDictionary<Type, ITypeSerializer> CustomSerializers { get; }

Property Value

Type	Description
IReadOnlyDictionary<Type, ITypeSerializer>	A read-only dictionary mapping target Type to ITypeSerializer. May be empty but never null.

See Also

GetSerializer(Type)

Default

Gets a pre-built SerializationSettings instance configured with all default values: JSON format, all values included (nulls and defaults), reference preservation, no pretty-printing, type and version metadata included, and a maximum depth of DEFAULT_MAX_DEPTH.

Declaration

public static SerializationSettings Default { get; }

Property Value

Type	Description
SerializationSettings	A shared, immutable SerializationSettings singleton for default use. Do not modify; create a customized copy with ToBuilder() if changes are needed.

DefaultValueHandling

Gets the policy governing how fields and properties whose value equals the type's default are emitted during serialization.

Declaration

public DefaultValueHandling DefaultValueHandling { get; }

Property Value

Type	Description
DefaultValueHandling	The configured DefaultValueHandling mode. Defaults to Include.

Format

Gets the output encoding format that the engine uses when writing serialized data and expects when reading it back.

Declaration

public SerializationFormat Format { get; }

Property Value

Type	Description
SerializationFormat	The configured SerializationFormat. Defaults to JSON.

IncludePrivateFields

Gets a value indicating whether private fields annotated with [ScyllaInclude] are included in serialization.

Declaration

public bool IncludePrivateFields { get; }

Property Value

Type	Description
bool	true to serialize opted-in private fields; false (the default) to serialize only public members.

IncludeTypeInfo

Gets a value indicating whether $type metadata is embedded in the serialized output to support polymorphic deserialization.

Declaration

public bool IncludeTypeInfo { get; }

Property Value

Type	Description
bool	true (the default) to include type metadata; false to omit it.

IncludeVersionInfo

Gets a value indicating whether $version metadata is embedded in the serialized output to support data migration between schema versions.

Declaration

public bool IncludeVersionInfo { get; }

Property Value

Type	Description
bool	true (the default) to include version metadata; false to omit it.

Indent

Gets the string prepended for each depth level when PrettyPrint is true.

Declaration

public string Indent { get; }

Property Value

Type	Description
string	The indentation string. Defaults to DEFAULT_INDENT ("\t").

MaxDepth

Gets the maximum object-graph nesting depth the engine is permitted to recurse into before throwing a SerializationException.

Declaration

public int MaxDepth { get; }

Property Value

Type	Description
int	A positive integer. Defaults to DEFAULT_MAX_DEPTH (64).

NullHandling

Gets the policy governing how null-valued fields and properties are emitted during serialization.

Declaration

public NullHandling NullHandling { get; }

Property Value

Type	Description
NullHandling	The configured NullHandling mode. Defaults to Include.

PrettyPrint

Gets a value indicating whether JSON output is formatted with newlines and indentation for human readability. Has no effect on binary output.

Declaration

public bool PrettyPrint { get; }

Property Value

Type	Description
bool	true to enable pretty-printing; false (the default) for compact single-line output.

ReadableJSON

Gets a pre-built SerializationSettings instance optimized for human-readable JSON output: JSON format and pretty-printing enabled. Intended for development, debugging, and configuration-file scenarios where readability is more important than output size.

Declaration

public static SerializationSettings ReadableJSON { get; }

Property Value

Type	Description
SerializationSettings	A shared, immutable SerializationSettings singleton for human-readable JSON output.

ReferenceHandling

Gets the strategy used when the engine encounters the same object reference more than once while traversing an object graph.

Declaration

public ReferenceHandling ReferenceHandling { get; }

Property Value

Type	Description
ReferenceHandling	The configured ReferenceHandling mode. Defaults to Preserve.

Methods

CreateBuilder()

Creates a new SerializationSettings.Builder pre-configured with all default values. Use the fluent With* methods on the returned builder to customize settings, then call Build() to obtain an immutable SerializationSettings instance.

Declaration

public static SerializationSettings.Builder CreateBuilder()

Returns

Type	Description
SerializationSettings.Builder	A new SerializationSettings.Builder instance with default settings applied.

ToBuilder()

Creates a new SerializationSettings.Builder pre-populated with all values from this SerializationSettings instance, including a copy of the custom serializer registrations. Use this method to derive a modified version of an existing settings object without altering the original.

Declaration

public SerializationSettings.Builder ToBuilder()

Returns

Type	Description
SerializationSettings.Builder	A new SerializationSettings.Builder whose initial state mirrors this settings instance. Modifying the builder will not affect this settings object.

Extension Methods

FileExtensions.SaveSecureToFileAsync<T>(T, string, string, CancellationToken)

FileExtensions.SaveSecureToFile<T>(T, string, string)

FileExtensions.SaveToFileAsync<T>(T, string, CancellationToken)

FileExtensions.SaveToFile<T>(T, string)

FileExtensions.SaveToFile<T>(T, string, SerializationSettings)

See Also

ScyllaSerialization

SerializationFormat

NullHandling

DefaultValueHandling

ReferenceHandling