Skip to main content
Version: dev

Configuration

This page covers ForyBuilder options and default configuration values for Apache Fory™ C#. Config is an immutable configuration snapshot created by ForyBuilder.

Build a Fory Instance​

using Apache.Fory;

Fory fory = Fory.Builder().Build();
ThreadSafeFory threadSafe = Fory.Builder().BuildThreadSafe();

Default Configuration​

Fory.Builder().Build() uses:

OptionDefaultDescription
TrackReffalseReference tracking disabled
CompatibletrueCompatible schema-evolution metadata enabled
CheckStructVersionfalseStruct schema hash checks disabled
MaxDepth20Max dynamic nesting depth
MaxTypeFields512Max fields in one received struct metadata body
MaxTypeMetaBytes4096Max encoded bytes in one received metadata body
MaxSchemaVersionsPerType10Max remote metadata versions for one logical type
MaxAverageSchemaVersionsPerType3Average remote metadata versions across types

Builder Options​

C# always uses xlang-compatible framing, so ForyBuilder does not expose a mode toggle.

TrackRef(bool enabled = false)​

Enables reference tracking for shared/circular object graphs.

Fory fory = Fory.Builder()
    .TrackRef(true)
    .Build();

Compatible(bool enabled = false)​

Enables schema evolution mode. C# uses the xlang wire format only, so compatible mode is enabled by default for independently deployed peers. Use .Build() without calling this method for the default compatible mode. Passing false, or calling Compatible() without an argument, opts into same-schema payloads. Use that only when every reader and writer always uses the same schema and you want faster serialization and smaller size. For cross-language payloads, call Compatible(false) only after verifying that every peer uses the same schema, or when native types are generated from Fory schema IDL.

Fory fory = Fory.Builder()
    .Compatible(false)
    .Build();

CheckStructVersion(bool enabled = false)​

Checks the schema hash when you intentionally use same-schema payloads.

Fory fory = Fory.Builder()
    .Compatible(false)
    .CheckStructVersion(true)
    .Build();

MaxDepth(int value)​

Sets max nesting depth for dynamic object graphs.

Fory fory = Fory.Builder()
    .MaxDepth(32)
    .Build();

value must be greater than 0.

MaxTypeFields(int value)​

Sets the maximum fields accepted in one received remote struct metadata body.

Fory fory = Fory.Builder()
    .MaxTypeFields(512)
    .Build();

MaxTypeMetaBytes(int value)​

Sets the maximum encoded body bytes accepted for one received TypeMeta body, excluding the 8-byte header and any extended-size varint.

Fory fory = Fory.Builder()
    .MaxTypeMetaBytes(4096)
    .Build();

MaxSchemaVersionsPerType(int value)​

Sets the maximum accepted remote metadata versions for one logical type.

Fory fory = Fory.Builder()
    .MaxSchemaVersionsPerType(10)
    .Build();

MaxAverageSchemaVersionsPerType(int value)​

Sets the average accepted remote metadata versions across accepted remote types. The effective global floor is 8192 schemas.

Fory fory = Fory.Builder()
    .MaxAverageSchemaVersionsPerType(3)
    .Build();

Common Configurations​

Compatible service​

Fory fory = Fory.Builder()
    .TrackRef(true)
    .Build();

Same-schema optimization​

Use this only when every reader and writer always uses the same schema.

Fory fory = Fory.Builder()
    .Compatible(false)
    .Build();

Thread-safe service instance​

ThreadSafeFory fory = Fory.Builder()
    .TrackRef(true)
    .BuildThreadSafe();

Security​

Security-related configuration:

  • Register only the expected types before deserializing untrusted payloads.
  • Use CheckStructVersion(true) with Compatible(false) for intentional same-schema payloads.
  • Set MaxDepth(...) to reject unexpectedly deep dynamic object graphs.
  • Keep the remote schema metadata limits at their defaults unless the data is not malicious and a trusted peer sends larger metadata or many schema versions.
  • Prefer generated or registered concrete models over broad dynamic fields for untrusted input.