Skip to content

configuration.md

Latest commit

 

History

History
209 lines (154 loc) · 6.51 KB

configuration.md

File metadata and controls

209 lines (154 loc) · 6.51 KB
Raw
title Configuration
sidebar_position 4
id configuration
license Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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:

Option Default Description
TrackRef false Reference tracking disabled
Compatible true Compatible schema-evolution metadata enabled
CheckStructVersion false Struct schema hash checks disabled
MaxDepth 20 Max dynamic nesting depth
MaxGraphMemoryBytes 134217728 Approximate graph-memory gate per root read
MaxUnbackedContainerItems 8192 Unbacked collection/map work per root read
MaxTypeFields 512 Max fields in one received struct metadata body
MaxTypeMetaBytes 4096 Max encoded bytes in one received metadata body
MaxSchemaVersionsPerType 10 Max remote metadata versions for one logical type
MaxAverageSchemaVersionsPerType 3 Average 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.

MaxGraphMemoryBytes(long value)

Sets an approximate graph-memory gate for one root deserialization. The estimate mainly covers materialized collections, maps, arrays, structs, and objects. It skips leaf values such as strings, binary data, primitive scalars, and dense primitive arrays, so actual process memory can be higher than this value.

Fory fory = Fory.Builder()
    .MaxGraphMemoryBytes(64L * 1024 * 1024)
    .Build();

The default limit is a fixed 128 MiB for all root input forms. A positive value overrides the default. Explicit non-positive values are rejected when the Fory instance is created. Skipped leaf values are still gated by remaining input bytes: if the unread input does not contain enough bytes, Fory will not read or create that leaf value.

MaxUnbackedContainerItems(long value)

Limits collection elements and map entries whose repeated read bodies do not consume proportional input during one root deserialization. The default is 8192; zero is a strict limit.

Fory fory = Fory.Builder()
    .MaxUnbackedContainerItems(8192)
    .Build();

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

See C# Security for trust boundaries, safe reader configuration, and verification.

Related Topics