Class TypeMetadata

Represents all reflection metadata required to serialize and deserialize a single C# type within the Scylla serialization system.

Inheritance
object
TypeMetadata
Inherited Members
Namespace: Scylla.Core.Util.Serialization
Assembly: ScyllaCore.dll
Syntax
public sealed class TypeMetadata
Remarks

TypeMetadata is constructed once per type and stored in the global TypeMetadataCache. Construction performs all expensive reflection operations - attribute scanning, property and field discovery, migration method lookup, and factory delegate compilation - so that subsequent serialization operations can work from pre-computed data with minimal overhead.

Instances are immutable and thread-safe after construction. They are safe to share across concurrent serialization contexts.

Member discovery rules:

  • Public properties and fields are included by default unless decorated with ScyllaIgnoreAttribute.
  • Non-public properties and fields are included only when decorated with ScyllaIncludeAttribute.
  • Indexer properties and compiler-generated backing fields are always excluded.

Migration discovery rules: Static methods decorated with ScyllaMigrationAttribute that accept and return the declaring type are collected and indexed by version pair so the engine can apply them during deserialization of stale data.

Constructors

TypeMetadata(Type)

Initializes a new TypeMetadata instance by reflecting on all serialization-relevant aspects of the specified type.

Declaration
public TypeMetadata(Type type)
Parameters
Type Name Description
Type type

The Type to inspect. Must not be null. May be any type - primitive, value type, reference type, or generic. Types not decorated with ScyllaSerializableAttribute are still supported but will have IsExplicitlySerializable set to false and Version set to 0.
Exceptions
Type Condition
ArgumentNullException

Thrown if type is null.

Properties

HasDefaultConstructor

Gets whether this type has a parameterless constructor (public or non-public) that can be used to create instances during deserialization.

Declaration
public bool HasDefaultConstructor { get; }
Property Value
Type Description
bool

true if the type is a value type (which always supports default construction) or if a zero-argument constructor exists (regardless of access level); false if no such constructor exists, in which case CreateInstance() will throw InvalidOperationException.
See Also

IsExplicitlySerializable

Gets whether this type is explicitly annotated with ScyllaSerializableAttribute.

Declaration
public bool IsExplicitlySerializable { get; }
Property Value
Type Description
bool

true if ScyllaSerializableAttribute is present on the type; false if the type will be serialized implicitly (without versioning or alias support).

IsNullable

Gets whether this type is a Nullable<T> wrapper around a value type.

Declaration
public bool IsNullable { get; }
Property Value
Type Description
bool

true if GetUnderlyingType(Type) returns a non-null type; otherwise, false. When true, UnderlyingNullableType holds the wrapped value type.
See Also

IsPrimitive

Gets whether this type is a CLR primitive (e.g., int, float, bool, char).

Declaration
public bool IsPrimitive { get; }
Property Value
Type Description
bool

true if IsPrimitive is true for the described type; otherwise, false. Primitive types are serialized by dedicated primitive serializers rather than the reflection-based serializer.

IsValueType

Gets whether this type is a value type (struct, enum, or primitive).

Declaration
public bool IsValueType { get; }
Property Value
Type Description
bool

true if IsValueType is true for the described type; otherwise, false. Used by the serialization engine to decide whether null-checking and reference tracking apply.

Properties

Gets the ordered, read-only list of serializable PropertyMetadata entries discovered for this type.

Declaration
public IReadOnlyList<PropertyMetadata> Properties { get; }
Property Value
Type Description
IReadOnlyList<PropertyMetadata>

Members are sorted first by Order (ascending), then alphabetically by Name for members that share the same order value. The list is computed once during construction and is never modified afterwards.
See Also

PropertyLookup

Gets a read-only dictionary that maps each serialized property name to its PropertyMetadata, enabling O(1) lookup during deserialization.

Declaration
public IReadOnlyDictionary<string, PropertyMetadata> PropertyLookup { get; }
Property Value
Type Description
IReadOnlyDictionary<string, PropertyMetadata>

Keys are the serialized names (i.e., Name), compared with ordinal string equality. The dictionary is built from Properties and is never modified after construction.
See Also

Type

Gets the runtime Type that this metadata instance describes.

Declaration
public Type Type { get; }
Property Value
Type Description
Type

The same Type object passed to the constructor. Never null.

TypeAlias

Gets the short alias string used to identify this type in polymorphic serialization output.

Declaration
public string TypeAlias { get; }
Property Value
Type Description
string

The value of TypeAlias if one was specified on the type; otherwise, FullName. The alias is written to the $type property in JSON when IncludeTypeInfo is true, and used by ResolveAlias(string) during deserialization to recover the concrete type from the alias string.
See Also

UnderlyingNullableType

Gets the underlying value type if this type is Nullable<T>; otherwise, null.

Declaration
public Type UnderlyingNullableType { get; }
Property Value
Type Description
Type

The result of GetUnderlyingType(Type) for the described type, or null if IsNullable is false. For example, for Nullable<int> this property returns typeof(int).
See Also

Version

Gets the schema version declared on this type via ScyllaSerializableAttribute, or 0 if the type is not explicitly annotated.

Declaration
public int Version { get; }
Property Value
Type Description
int

A positive integer if the type carries ScyllaSerializableAttribute; 0 otherwise. The version is written into the serialized output (when IncludeVersionInfo is true) and used during deserialization to determine which ScyllaMigrationAttribute methods to invoke.
See Also

Methods

CreateInstance()

Creates and returns a new, zero-initialized instance of Type using the compiled factory delegate.

Declaration
public object CreateInstance()
Returns
Type Description
object

A freshly constructed object of Type. For value types, this is the default (zeroed) struct. For reference types, this is the object returned by invoking the parameterless constructor.
Exceptions
Type Condition
InvalidOperationException

Thrown if HasDefaultConstructor is false, meaning no parameterless constructor was found during metadata construction. Check HasDefaultConstructor before calling this method if the type's constructability is uncertain.

GetMigration(int, int)

Retrieves the static migration method that handles upgrading data from fromVersion to toVersion.

Declaration
public MethodInfo GetMigration(int fromVersion, int toVersion)
Parameters
Type Name Description
int fromVersion

The source schema version of the serialized data being deserialized.
int toVersion

The target schema version to migrate the data toward. This does not need to be the type's current Version; intermediate steps are valid.
Returns
Type Description
MethodInfo

The MethodInfo for the migration method decorated with [ScyllaMigration(fromVersion, toVersion)], or null if no direct migration exists for that exact version pair. Use HasMigrationPath(int, int) to check whether a step-by-step path exists before calling this method.
See Also

GetProperty(string)

Retrieves the PropertyMetadata for the member whose serialized name matches the specified string.

Declaration
public PropertyMetadata GetProperty(string name)
Parameters
Type Name Description
string name

The serialized property name (i.e., the key as it appears in the JSON output) to look up. The comparison is ordinal and case-sensitive.
Returns
Type Description
PropertyMetadata

The matching PropertyMetadata instance if found in PropertyLookup; otherwise, null.
See Also

HasMigrationPath(int, int)

Determines whether a complete migration path exists from fromVersion to toVersion using the available ScyllaMigrationAttribute- decorated methods.

Declaration
public bool HasMigrationPath(int fromVersion, int toVersion)
Parameters
Type Name Description
int fromVersion

The source schema version. If this is greater than or equal to toVersion, the method returns true immediately because no migration is necessary.
int toVersion

The target schema version to reach. Typically the type's current Version.
Returns
Type Description
bool

true if fromVersion is already at or above toVersion, or if a chain of registered migration methods covers the entire version gap without gaps; false if at least one intermediate version is not covered by any migration.
Remarks

The method first checks for a direct single-step migration. If none exists, it walks greedily through available migrations in ascending version order. The path is considered complete only if the walk reaches exactly toVersion without encountering an uncovered gap.

See Also

Extension Methods

See Also