Class SerializationSettings.Builder

Fluent builder for constructing immutable SerializationSettings instances. Each With* method returns the same builder to enable method chaining. Call Build() when all options have been configured.

Inheritance

object

SerializationSettings.Builder

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.Builder

Remarks

Obtain a new builder via CreateBuilder() or a pre-populated builder via ToBuilder(). Builder instances are not thread-safe; use a separate builder per thread if settings are configured concurrently.

Methods

Build()

Constructs and returns the immutable SerializationSettings instance based on the current state of this builder.

Declaration

public SerializationSettings Build()

Returns

Type	Description
SerializationSettings	A new, immutable SerializationSettings instance. The builder can continue to be used after calling this method; further modifications will not affect already-built instances.

RegisterSerializer<T>(ITypeSerializer<T>)

Registers a custom type serializer that overrides the engine's default reflection-based handling for type T within operations that use the settings produced by this builder.

Declaration

public SerializationSettings.Builder RegisterSerializer<T>(ITypeSerializer<T> serializer)

Parameters

Type	Name	Description
ITypeSerializer<T>	serializer	The ITypeSerializer<T> implementation to register. Must not be null. Internally wrapped in a TypeSerializerAdapter<T> for non-generic dispatch.

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

Type Parameters

Name	Description
T	The type for which the serializer is registered. Any existing registration for the same type is replaced.

Exceptions

Type	Condition
ArgumentNullException	Thrown if serializer is null.

See Also

RegisterSerializer<T>(ITypeSerializer<T>)

WithDefaultValueHandling(DefaultValueHandling)

Sets how fields and properties whose value equals the type's default are treated during serialization.

Declaration

public SerializationSettings.Builder WithDefaultValueHandling(DefaultValueHandling handling)

Parameters

Type	Name	Description
DefaultValueHandling	handling	The DefaultValueHandling mode. Use Include (the default) to always emit default values, or Ignore to omit them and reduce output size.

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

WithEmitReferenceIDs(bool)

Sets whether the engine writes an explicit REF_ID_PROPERTY_NAME marker on a newly-tracked reference type. Only meaningful when ReferenceHandling is Preserve.

Declaration

public SerializationSettings.Builder WithEmitReferenceIDs(bool enabled = true)

Parameters

Type	Name	Description
bool	enabled	true (the default) to write an explicit $id so a $ref back- reference resolves correctly even when the reader traverses properties in a different order than the writer did; false to fall back to the older implicit-by-traversal-order behavior, kept for reading files written before this setting existed.

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

WithFormat(SerializationFormat)

Sets the output encoding format used by the engine when writing or reading data.

Declaration

public SerializationSettings.Builder WithFormat(SerializationFormat format)

Parameters

Type	Name	Description
SerializationFormat	format	The SerializationFormat to use. Defaults to JSON when the builder is created.

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

WithIndent(string)

Sets the string used for each level of indentation when pretty-printing is active. Only meaningful when WithPrettyPrint(bool) has been called with true.

Declaration

public SerializationSettings.Builder WithIndent(string indent)

Parameters

Type	Name	Description
string	indent	The indentation string to prepend for each depth level (e.g., "\t" for a tab or " " for two spaces). If null, the value reverts to DEFAULT_INDENT (a single tab).

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

WithMaxDepth(int)

Sets the maximum nesting depth the engine is permitted to recurse into before raising a SerializationException. This guards against stack overflows caused by unexpectedly deep or circular object graphs.

Declaration

public SerializationSettings.Builder WithMaxDepth(int maxDepth)

Parameters

Type	Name	Description
int	maxDepth	The maximum depth. Must be at least 1. The default is DEFAULT_MAX_DEPTH (64).

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if maxDepth is less than 1.

WithNullHandling(NullHandling)

Sets how null-valued fields and properties are treated during serialization.

Declaration

public SerializationSettings.Builder WithNullHandling(NullHandling handling)

Parameters

Type	Name	Description
NullHandling	handling	The NullHandling mode. Use Include (the default) to always emit null tokens, or Ignore to omit null fields entirely.

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

WithPrettyPrint(bool)

Sets whether JSON output should be formatted with newlines and indentation for human readability. Has no effect when the format is Binary.

Declaration

public SerializationSettings.Builder WithPrettyPrint(bool enabled = true)

Parameters

Type	Name	Description
bool	enabled	true to enable pretty-printing; false (the default) to produce compact single-line output. The indentation string can be customized via WithIndent(string).

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

WithPrivateFields(bool)

Sets whether non-public members are included in serialization. By default only public fields and properties, plus members annotated with [ScyllaInclude], are processed.

Declaration

public SerializationSettings.Builder WithPrivateFields(bool include = true)

Parameters

Type	Name	Description
bool	include	true to serialize every non-public field and every non-public property that has a getter and a setter; false (the default) to serialize only public members and members that carry [ScyllaInclude]. Non-public fields that hold a delegate, back an event, or are readonly are skipped even when this is true (unless marked with [ScyllaInclude]), and private members of base classes declared in Unity engine or .NET framework assemblies are never collected.

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

WithReferenceHandling(ReferenceHandling)

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

Declaration

public SerializationSettings.Builder WithReferenceHandling(ReferenceHandling handling)

Parameters

Type	Name	Description
ReferenceHandling	handling	The ReferenceHandling mode. Preserve (the default) assigns reference IDs and allows round-trips of graphs with shared or cyclic references. Error aborts if a cycle is detected. Ignore silently writes null for repeated references.

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

WithTypeInfo(bool)

Sets whether the engine writes a $type marker for every object, under the key Scylla.Core.Util.Serialization.SerializationSettings.TYPE_PROPERTY_NAME. The marker is the explicit TypeAlias when the type declares one, otherwise the assembly-qualified type name.

Declaration

public SerializationSettings.Builder WithTypeInfo(bool include = true)

Parameters

Type	Name	Description
bool	include	true (the default) to write a type marker for every object; false to suppress the marker for objects whose runtime type equals the declared type. A value whose runtime type differs from its declared type (a derived class in a base typed field, or any value in an object or interface field) always carries a marker, so disabling this flag never loses data on a round trip. When such a value is read back through an object or interface declaration, its type must be annotated with ScyllaSerializableAttribute or registered through RegisterAlias(string, Type).

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

WithVersionInfo(bool)

Sets whether the engine should embed $version metadata in the output to enable data migration between schema versions. When enabled, the engine writes the type's schema version under the key Scylla.Core.Util.Serialization.SerializationSettings.VERSION_PROPERTY_NAME.

Declaration

public SerializationSettings.Builder WithVersionInfo(bool include = true)

Parameters

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

Returns

Type	Description
SerializationSettings.Builder	This builder for method chaining.

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)