This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new 9a47fedadd π synced local 'docs/guide/' with remote 'docs/guide/'
9a47fedadd is described below
commit 9a47fedadd8cd19a4f15231e10c89e8952744714
Author: chaokunyang <[email protected]>
AuthorDate: Wed Feb 25 08:22:26 2026 +0000
π synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/csharp/basic-serialization.md | 131 ++++++++++++++++++++++++++++++
docs/guide/csharp/configuration.md | 133 +++++++++++++++++++++++++++++++
docs/guide/csharp/cross-language.md | 107 +++++++++++++++++++++++++
docs/guide/csharp/custom-serializers.md | 84 +++++++++++++++++++
docs/guide/csharp/field-configuration.md | 75 +++++++++++++++++
docs/guide/csharp/index.md | 94 ++++++++++++++++++++++
docs/guide/csharp/references.md | 72 +++++++++++++++++
docs/guide/csharp/schema-evolution.md | 90 +++++++++++++++++++++
docs/guide/csharp/supported-types.md | 97 ++++++++++++++++++++++
docs/guide/csharp/thread-safety.md | 73 +++++++++++++++++
docs/guide/csharp/troubleshooting.md | 92 +++++++++++++++++++++
docs/guide/csharp/type-registration.md | 82 +++++++++++++++++++
12 files changed, 1130 insertions(+)
diff --git a/docs/guide/csharp/basic-serialization.md
b/docs/guide/csharp/basic-serialization.md
new file mode 100644
index 0000000000..2188c912d3
--- /dev/null
+++ b/docs/guide/csharp/basic-serialization.md
@@ -0,0 +1,131 @@
+---
+title: Basic Serialization
+sidebar_position: 2
+id: basic_serialization
+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 typed and dynamic serialization APIs in Apache Foryβ’ C#.
+
+## Object Graph Serialization
+
+Use `[ForyObject]` on your classes/structs and register them before use.
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Address
+{
+ public string Street { get; set; } = string.Empty;
+ public int Zip { get; set; }
+}
+
+[ForyObject]
+public sealed class Person
+{
+ public long Id { get; set; }
+ public string Name { get; set; } = string.Empty;
+ public string? Nickname { get; set; }
+ public List<int> Scores { get; set; } = [];
+ public List<Address> Addresses { get; set; } = [];
+}
+
+Fory fory = Fory.Builder().Build();
+fory.Register<Address>(100);
+fory.Register<Person>(101);
+
+Person person = new()
+{
+ Id = 42,
+ Name = "Alice",
+ Nickname = null,
+ Scores = [10, 20, 30],
+ Addresses = [new Address { Street = "Main", Zip = 94107 }],
+};
+
+byte[] payload = fory.Serialize(person);
+Person decoded = fory.Deserialize<Person>(payload);
+```
+
+## Typed API
+
+### Serialize / Deserialize with byte arrays
+
+```csharp
+byte[] payload = fory.Serialize(value);
+MyType decoded = fory.Deserialize<MyType>(payload);
+```
+
+### Deserialize from `ReadOnlySpan<byte>`
+
+```csharp
+ReadOnlySpan<byte> span = payload;
+MyType decoded = fory.Deserialize<MyType>(span);
+```
+
+### Stream-style frame consumption
+
+```csharp
+using System.Buffers;
+
+ReadOnlySequence<byte> sequence = GetFramedSequence();
+MyType first = fory.Deserialize<MyType>(ref sequence);
+MyType second = fory.Deserialize<MyType>(ref sequence);
+```
+
+## Dynamic Object API
+
+Use object APIs when the compile-time type is unknown or heterogeneous.
+
+```csharp
+Dictionary<object, object?> value = new()
+{
+ ["k1"] = 7,
+ [2] = "v2",
+ [true] = null,
+};
+
+byte[] payload = fory.SerializeObject(value);
+object? decoded = fory.DeserializeObject(payload);
+```
+
+## Buffer Writer API
+
+Serialize directly into `IBufferWriter<byte>` targets.
+
+```csharp
+using System.Buffers;
+
+ArrayBufferWriter<byte> writer = new();
+fory.Serialize(writer, value);
+
+ArrayBufferWriter<byte> dynamicWriter = new();
+fory.SerializeObject(dynamicWriter, value);
+```
+
+## Notes
+
+- Reuse the same `Fory` or `ThreadSafeFory` instance for better performance.
+- Primitive types and collections do not require user registration.
+- User `[ForyObject]` and custom serializer types should be registered
explicitly.
+
+## Related Topics
+
+- [Type Registration](type-registration.md)
+- [Supported Types](supported-types.md)
+- [References](references.md)
diff --git a/docs/guide/csharp/configuration.md
b/docs/guide/csharp/configuration.md
new file mode 100644
index 0000000000..73a718e6e3
--- /dev/null
+++ b/docs/guide/csharp/configuration.md
@@ -0,0 +1,133 @@
+---
+title: Configuration
+sidebar_position: 1
+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#.
+
+## Build a Runtime
+
+```csharp
+using Apache.Fory;
+
+Fory fory = Fory.Builder().Build();
+ThreadSafeFory threadSafe = Fory.Builder().BuildThreadSafe();
+```
+
+## Default Configuration
+
+`Fory.Builder().Build()` uses:
+
+| Option | Default | Description
|
+| -------------------- | ------- |
---------------------------------------------- |
+| `Xlang` | `true` | Cross-language protocol mode
|
+| `TrackRef` | `false` | Reference tracking disabled
|
+| `Compatible` | `false` | Schema-consistent mode (no evolution
metadata) |
+| `CheckStructVersion` | `false` | Struct schema hash checks disabled
|
+| `MaxDepth` | `20` | Max dynamic nesting depth
|
+
+## Builder Options
+
+### `Xlang(bool enabled = true)`
+
+Controls cross-language mode.
+
+```csharp
+Fory fory = Fory.Builder()
+ .Xlang(true)
+ .Build();
+```
+
+### `TrackRef(bool enabled = false)`
+
+Enables reference tracking for shared/circular object graphs.
+
+```csharp
+Fory fory = Fory.Builder()
+ .TrackRef(true)
+ .Build();
+```
+
+### `Compatible(bool enabled = false)`
+
+Enables schema evolution mode.
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+```
+
+### `CheckStructVersion(bool enabled = false)`
+
+Enables strict schema hash validation for generated struct serializers.
+
+```csharp
+Fory fory = Fory.Builder()
+ .CheckStructVersion(true)
+ .Build();
+```
+
+### `MaxDepth(int value)`
+
+Sets max nesting depth for dynamic object graphs.
+
+```csharp
+Fory fory = Fory.Builder()
+ .MaxDepth(32)
+ .Build();
+```
+
+`value` must be greater than `0`.
+
+## Common Configurations
+
+### Fast schema-consistent service
+
+```csharp
+Fory fory = Fory.Builder()
+ .TrackRef(false)
+ .Compatible(false)
+ .Build();
+```
+
+### Compatible cross-language service
+
+```csharp
+Fory fory = Fory.Builder()
+ .Xlang(true)
+ .Compatible(true)
+ .TrackRef(true)
+ .Build();
+```
+
+### Thread-safe service instance
+
+```csharp
+ThreadSafeFory fory = Fory.Builder()
+ .Compatible(true)
+ .TrackRef(true)
+ .BuildThreadSafe();
+```
+
+## Related Topics
+
+- [Basic Serialization](basic-serialization.md)
+- [Schema Evolution](schema-evolution.md)
+- [Thread Safety](thread-safety.md)
diff --git a/docs/guide/csharp/cross-language.md
b/docs/guide/csharp/cross-language.md
new file mode 100644
index 0000000000..5a2af307ed
--- /dev/null
+++ b/docs/guide/csharp/cross-language.md
@@ -0,0 +1,107 @@
+---
+title: Cross-Language Serialization
+sidebar_position: 8
+id: cross_language
+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.
+---
+
+Apache Foryβ’ C# supports cross-language serialization with other Fory runtimes.
+
+## Enable Cross-Language Mode
+
+C# defaults to `Xlang(true)`, but it is good practice to configure it
explicitly in interoperability code.
+
+```csharp
+Fory fory = Fory.Builder()
+ .Xlang(true)
+ .Compatible(true)
+ .Build();
+```
+
+## Register with Stable IDs
+
+```csharp
+[ForyObject]
+public sealed class Person
+{
+ public string Name { get; set; } = string.Empty;
+ public int Age { get; set; }
+}
+
+Fory fory = Fory.Builder()
+ .Xlang(true)
+ .Compatible(true)
+ .Build();
+
+fory.Register<Person>(100);
+```
+
+Use the same ID mapping on all languages.
+
+## Register by Namespace/Type Name
+
+```csharp
+fory.Register<Person>("com.example", "Person");
+```
+
+## Cross-Language Example
+
+### C# (Serializer)
+
+```csharp
+Person person = new() { Name = "Alice", Age = 30 };
+byte[] payload = fory.Serialize(person);
+```
+
+### Java (Deserializer)
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true)
+ .build();
+
+fory.register(Person.class, 100);
+Person value = (Person) fory.deserialize(payloadFromCSharp);
+```
+
+### Python (Deserializer)
+
+```python
+import pyfory
+
+fory = pyfory.Fory(xlang=True, ref=True)
+fory.register_type(Person, type_id=100)
+value = fory.deserialize(payload_from_csharp)
+```
+
+## Type Mapping Reference
+
+See [xlang guide](../xlang/index.md) for complete mapping.
+
+## Best Practices
+
+1. Keep type IDs stable and documented.
+2. Enable `Compatible(true)` for rolling upgrades.
+3. Register all user types on both read/write peers.
+4. Validate integration with real payload round trips.
+
+## Related Topics
+
+- [Type Registration](type-registration.md)
+- [Schema Evolution](schema-evolution.md)
+- [Supported Types](supported-types.md)
diff --git a/docs/guide/csharp/custom-serializers.md
b/docs/guide/csharp/custom-serializers.md
new file mode 100644
index 0000000000..363e4ad82e
--- /dev/null
+++ b/docs/guide/csharp/custom-serializers.md
@@ -0,0 +1,84 @@
+---
+title: Custom Serializers
+sidebar_position: 4
+id: custom_serializers
+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.
+---
+
+Use custom serializers when a type is not generated with `[ForyObject]` or
requires specialized encoding.
+
+## Implement `Serializer<T>`
+
+```csharp
+using Apache.Fory;
+
+public sealed class Point
+{
+ public int X { get; set; }
+ public int Y { get; set; }
+}
+
+public sealed class PointSerializer : Serializer<Point>
+{
+ public override Point DefaultValue => new();
+
+ public override void WriteData(WriteContext context, in Point value, bool
hasGenerics)
+ {
+ context.Writer.WriteVarInt32(value.X);
+ context.Writer.WriteVarInt32(value.Y);
+ }
+
+ public override Point ReadData(ReadContext context)
+ {
+ return new Point
+ {
+ X = context.Reader.ReadVarInt32(),
+ Y = context.Reader.ReadVarInt32(),
+ };
+ }
+}
+```
+
+## Register the Serializer
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<Point, PointSerializer>(200);
+
+Point value = new() { X = 10, Y = 20 };
+byte[] payload = fory.Serialize(value);
+Point decoded = fory.Deserialize<Point>(payload);
+```
+
+## Serializer Behavior Notes
+
+- `WriteData` / `ReadData` only handle payload content.
+- Ref flags and type info are handled by base `Serializer<T>.Write` / `Read`
unless overridden.
+- `DefaultValue` is used for null/default fallback paths.
+
+## Best Practices
+
+1. Keep serializers deterministic and symmetric.
+2. Use varint/fixed/tagged encoding intentionally for integer-heavy payloads.
+3. Register custom serializers on all reader/writer peers.
+4. Prefer generated `[ForyObject]` serializers for normal domain models.
+
+## Related Topics
+
+- [Type Registration](type-registration.md)
+- [Field Configuration](field-configuration.md)
+- [Troubleshooting](troubleshooting.md)
diff --git a/docs/guide/csharp/field-configuration.md
b/docs/guide/csharp/field-configuration.md
new file mode 100644
index 0000000000..3fc502ee8e
--- /dev/null
+++ b/docs/guide/csharp/field-configuration.md
@@ -0,0 +1,75 @@
+---
+title: Field Configuration
+sidebar_position: 5
+id: field_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 field-level serializer configuration for C# generated
serializers.
+
+## `[ForyObject]` and `[Field]`
+
+Use `[ForyObject]` to enable source-generated serializers. Use `[Field]` to
override integer encoding for a specific field.
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Metrics
+{
+ // Fixed-width 32-bit encoding
+ [Field(Encoding = FieldEncoding.Fixed)]
+ public uint Count { get; set; }
+
+ // Tagged 64-bit encoding
+ [Field(Encoding = FieldEncoding.Tagged)]
+ public ulong TraceId { get; set; }
+
+ // Default (varint) encoding
+ public long LatencyMicros { get; set; }
+}
+```
+
+## Available Encodings
+
+| Encoding | Meaning |
+| ---------------------- | ----------------------------------------------- |
+| `FieldEncoding.Varint` | Variable-length integer encoding (default) |
+| `FieldEncoding.Fixed` | Fixed-width integer encoding |
+| `FieldEncoding.Tagged` | Tagged integer encoding (`long` / `ulong` only) |
+
+## Supported Field Types for Encoding Override
+
+`[Field(Encoding = ...)]` currently applies to:
+
+- `int`
+- `uint`
+- `long`
+- `ulong`
+
+Nullable value variants (for example `long?`) are also handled by generated
serializers.
+
+## Nullability and Reference Tracking
+
+- Field nullability comes from C# type nullability (`string?`, nullable value
types, etc.).
+- Reference tracking is controlled at runtime by `ForyBuilder.TrackRef(...)`.
+
+## Related Topics
+
+- [Configuration](configuration.md)
+- [Schema Evolution](schema-evolution.md)
+- [Supported Types](supported-types.md)
diff --git a/docs/guide/csharp/index.md b/docs/guide/csharp/index.md
new file mode 100644
index 0000000000..c12c5a32ea
--- /dev/null
+++ b/docs/guide/csharp/index.md
@@ -0,0 +1,94 @@
+---
+title: C# Serialization Guide
+sidebar_position: 0
+id: serialization_index
+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.
+---
+
+Apache Foryβ’ C# is a high-performance, cross-language serialization runtime
for .NET. It provides object graph serialization, schema evolution, dynamic
object support, and a thread-safe wrapper for concurrent workloads.
+
+## Why Fory C#?
+
+- High performance binary serialization for .NET 8+
+- Cross-language compatibility with Fory implementations in Java, Python, C++,
Go, Rust, and JavaScript
+- Source-generator-based serializers for `[ForyObject]` types
+- Optional reference tracking for shared and circular object graphs
+- Compatible mode for schema evolution
+- Thread-safe runtime (`ThreadSafeFory`) for multi-threaded services
+
+## Quick Start
+
+### Requirements
+
+- .NET SDK 8.0+
+- C# language version 12+
+
+### Basic Example
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class User
+{
+ public long Id { get; set; }
+ public string Name { get; set; } = string.Empty;
+ public string? Email { get; set; }
+}
+
+Fory fory = Fory.Builder().Build();
+fory.Register<User>(1);
+
+User user = new()
+{
+ Id = 1,
+ Name = "Alice",
+ Email = "[email protected]",
+};
+
+byte[] payload = fory.Serialize(user);
+User decoded = fory.Deserialize<User>(payload);
+```
+
+## Core API Surface
+
+- `Serialize<T>(in T value)` / `Deserialize<T>(...)`
+- `SerializeObject(object? value)` / `DeserializeObject(...)` for dynamic
payloads
+- `Register<T>(uint typeId)` and namespace/name registration APIs
+- `Register<T, TSerializer>(...)` for custom serializers
+
+## Documentation
+
+| Topic | Description
|
+| --------------------------------------------- |
------------------------------------------------ |
+| [Configuration](configuration.md) | Builder options and runtime
modes |
+| [Basic Serialization](basic-serialization.md) | Typed and dynamic
serialization APIs |
+| [Type Registration](type-registration.md) | Registering user types and
custom serializers |
+| [Custom Serializers](custom-serializers.md) | Implementing `Serializer<T>`
|
+| [Field Configuration](field-configuration.md) | `[Field]` attribute and
integer encoding options |
+| [References](references.md) | Shared/circular reference
handling |
+| [Schema Evolution](schema-evolution.md) | Compatible mode behavior
|
+| [Cross-Language](cross-language.md) | Interoperability guidance
|
+| [Supported Types](supported-types.md) | Built-in and generated type
support |
+| [Thread Safety](thread-safety.md) | `Fory` vs `ThreadSafeFory`
usage |
+| [Troubleshooting](troubleshooting.md) | Common errors and debugging
steps |
+
+## Related Resources
+
+- [Cross-language serialization
specification](../../specification/xlang_serialization_spec.md)
+- [Cross-language guide](../xlang/index.md)
+- [C# source directory](https://github.com/apache/fory/tree/main/csharp)
diff --git a/docs/guide/csharp/references.md b/docs/guide/csharp/references.md
new file mode 100644
index 0000000000..001f8a378c
--- /dev/null
+++ b/docs/guide/csharp/references.md
@@ -0,0 +1,72 @@
+---
+title: References
+sidebar_position: 6
+id: references
+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.
+---
+
+Apache Foryβ’ C# can preserve shared and circular references when
`TrackRef(true)` is enabled.
+
+## Enable Reference Tracking
+
+```csharp
+Fory fory = Fory.Builder()
+ .TrackRef(true)
+ .Build();
+```
+
+When enabled:
+
+- Shared object identity is preserved.
+- Circular object graphs can be serialized/deserialized safely.
+
+## Circular Reference Example
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Node
+{
+ public int Value { get; set; }
+ public Node? Next { get; set; }
+}
+
+Fory fory = Fory.Builder()
+ .TrackRef(true)
+ .Build();
+fory.Register<Node>(200);
+
+Node node = new() { Value = 7 };
+node.Next = node;
+
+byte[] payload = fory.Serialize(node);
+Node decoded = fory.Deserialize<Node>(payload);
+
+// The cycle is preserved.
+System.Diagnostics.Debug.Assert(object.ReferenceEquals(decoded, decoded.Next));
+```
+
+## When to Use `TrackRef(false)`
+
+`TrackRef(false)` can be faster for tree-like, acyclic data where reference
identity does not matter.
+
+## Related Topics
+
+- [Configuration](configuration.md)
+- [Basic Serialization](basic-serialization.md)
+- [Thread Safety](thread-safety.md)
diff --git a/docs/guide/csharp/schema-evolution.md
b/docs/guide/csharp/schema-evolution.md
new file mode 100644
index 0000000000..429abd2081
--- /dev/null
+++ b/docs/guide/csharp/schema-evolution.md
@@ -0,0 +1,90 @@
+---
+title: Schema Evolution
+sidebar_position: 7
+id: schema_evolution
+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.
+---
+
+Apache Foryβ’ C# supports schema evolution in `Compatible(true)` mode.
+
+## Compatible Mode
+
+```csharp
+Fory fory = Fory.Builder()
+ .Compatible(true)
+ .Build();
+```
+
+Compatible mode writes type metadata that allows readers and writers with
different struct definitions to interoperate.
+
+## Example: Add a Field
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class OneStringField
+{
+ public string? F1 { get; set; }
+}
+
+[ForyObject]
+public sealed class TwoStringField
+{
+ public string F1 { get; set; } = string.Empty;
+ public string F2 { get; set; } = string.Empty;
+}
+
+Fory fory1 = Fory.Builder().Compatible(true).Build();
+fory1.Register<OneStringField>(200);
+
+Fory fory2 = Fory.Builder().Compatible(true).Build();
+fory2.Register<TwoStringField>(200);
+
+byte[] payload = fory1.Serialize(new OneStringField { F1 = "hello" });
+TwoStringField evolved = fory2.Deserialize<TwoStringField>(payload);
+
+// F2 falls back to default value on reader side.
+System.Diagnostics.Debug.Assert(evolved.F1 == "hello");
+System.Diagnostics.Debug.Assert(evolved.F2 == string.Empty);
+```
+
+## Schema-Consistent Mode with Version Check
+
+If you want strict schema identity checks instead of evolution behavior:
+
+```csharp
+Fory strict = Fory.Builder()
+ .Compatible(false)
+ .CheckStructVersion(true)
+ .Build();
+```
+
+This mode throws on schema hash mismatches.
+
+## Best Practices
+
+1. Use `Compatible(true)` for independently deployed services.
+2. Keep stable type IDs across versions.
+3. Add new fields with safe defaults.
+4. Use `CheckStructVersion(true)` when strict matching is required.
+
+## Related Topics
+
+- [Configuration](configuration.md)
+- [Type Registration](type-registration.md)
+- [Troubleshooting](troubleshooting.md)
diff --git a/docs/guide/csharp/supported-types.md
b/docs/guide/csharp/supported-types.md
new file mode 100644
index 0000000000..8a89a3fab9
--- /dev/null
+++ b/docs/guide/csharp/supported-types.md
@@ -0,0 +1,97 @@
+---
+title: Supported Types
+sidebar_position: 9
+id: supported_types
+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 summarizes built-in and generated type support in Apache Foryβ’ C#.
+
+## Primitive Types
+
+| C# Type | Notes |
+| ---------------------------------------- | --------- |
+| `bool` | Supported |
+| `sbyte`, `short`, `int`, `long` | Supported |
+| `byte`, `ushort`, `uint`, `ulong` | Supported |
+| `float`, `double` | Supported |
+| `string` | Supported |
+| `byte[]` | Supported |
+| Nullable primitives (for example `int?`) | Supported |
+
+## Arrays
+
+- Primitive numeric arrays (`bool[]`, `int[]`, `ulong[]`, etc.)
+- `byte[]`
+- General arrays (`T[]`) through collection serializers
+
+## Collections
+
+### List-like
+
+- `List<T>`
+- `LinkedList<T>`
+- `Queue<T>`
+- `Stack<T>`
+
+### Set-like
+
+- `HashSet<T>`
+- `SortedSet<T>`
+- `ImmutableHashSet<T>`
+
+### Map-like
+
+- `Dictionary<TKey, TValue>`
+- `SortedDictionary<TKey, TValue>`
+- `SortedList<TKey, TValue>`
+- `ConcurrentDictionary<TKey, TValue>`
+- `NullableKeyDictionary<TKey, TValue>`
+
+## Time Types
+
+| C# Type | Wire Type |
+| ---------------- | ----------- |
+| `DateOnly` | `Date` |
+| `DateTime` | `Timestamp` |
+| `DateTimeOffset` | `Timestamp` |
+| `TimeSpan` | `Duration` |
+
+## User Types
+
+- `[ForyObject]` classes/structs/enums via source-generated serializers
+- Custom serializer types registered through `Register<T, TSerializer>(...)`
+- `Union` / `Union2<...>` typed union support
+
+## Dynamic Types
+
+Dynamic object APIs (`SerializeObject` / `DeserializeObject`) support:
+
+- Primitive/object values
+- Dynamic lists/sets/maps
+- Nested dynamic structures
+
+## Notes
+
+- User-defined types should be registered explicitly.
+- For cross-language usage, follow the [xlang guide](../xlang/index.md).
+
+## Related Topics
+
+- [Basic Serialization](basic-serialization.md)
+- [Type Registration](type-registration.md)
+- [Cross-Language](cross-language.md)
diff --git a/docs/guide/csharp/thread-safety.md
b/docs/guide/csharp/thread-safety.md
new file mode 100644
index 0000000000..e8c7e4149f
--- /dev/null
+++ b/docs/guide/csharp/thread-safety.md
@@ -0,0 +1,73 @@
+---
+title: Thread Safety
+sidebar_position: 10
+id: thread_safety
+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.
+---
+
+Apache Foryβ’ C# provides two runtime forms with different threading guarantees.
+
+## `Fory` (Single-Threaded Runtime)
+
+`Fory` is optimized for single-threaded reuse and must not be used
concurrently by multiple threads.
+
+```csharp
+Fory fory = Fory.Builder().Build();
+```
+
+Use one `Fory` instance per thread when managing thread affinity explicitly.
+
+## `ThreadSafeFory` (Concurrent Wrapper)
+
+`ThreadSafeFory` wraps one `Fory` instance per thread and exposes thread-safe
APIs.
+
+```csharp
+using Apache.Fory;
+
+using ThreadSafeFory fory = Fory.Builder()
+ .Compatible(true)
+ .TrackRef(true)
+ .BuildThreadSafe();
+
+fory.Register<MyType>(100);
+
+Parallel.For(0, 64, i =>
+{
+ byte[] payload = fory.Serialize(i);
+ int decoded = fory.Deserialize<int>(payload);
+});
+```
+
+## Registration Behavior
+
+- `ThreadSafeFory.Register(...)` stores registrations centrally.
+- Existing per-thread runtimes are updated.
+- New threads receive all previous registrations automatically.
+
+## Disposal
+
+`ThreadSafeFory` implements `IDisposable` and should be disposed when no
longer needed.
+
+```csharp
+using ThreadSafeFory fory = Fory.Builder().BuildThreadSafe();
+```
+
+## Related Topics
+
+- [Configuration](configuration.md)
+- [Type Registration](type-registration.md)
+- [References](references.md)
diff --git a/docs/guide/csharp/troubleshooting.md
b/docs/guide/csharp/troubleshooting.md
new file mode 100644
index 0000000000..f078627eee
--- /dev/null
+++ b/docs/guide/csharp/troubleshooting.md
@@ -0,0 +1,92 @@
+---
+title: Troubleshooting
+sidebar_position: 11
+id: troubleshooting
+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 common C# runtime issues and fixes.
+
+## `TypeNotRegisteredException`
+
+**Symptom**: `Type not registered: ...`
+
+**Cause**: A user type was serialized/deserialized without registration.
+
+**Fix**:
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<MyType>(100);
+```
+
+Ensure the same type-ID/name mapping exists on both write and read sides.
+
+## `InvalidDataException: xlang bitmap mismatch`
+
+**Cause**: Writer/reader disagree on `Xlang` mode.
+
+**Fix**: Use the same `Xlang(...)` value on both peers.
+
+```csharp
+Fory writer = Fory.Builder().Xlang(true).Build();
+Fory reader = Fory.Builder().Xlang(true).Build();
+```
+
+## Schema Version Mismatch in Strict Mode
+
+**Symptom**: `InvalidDataException` while deserializing generated struct types.
+
+**Cause**: `Compatible(false)` with `CheckStructVersion(true)` enforces exact
schema hashes.
+
+**Fix options**:
+
+- Enable `Compatible(true)` for schema evolution.
+- Keep writer/reader model definitions in sync.
+
+## Circular Reference Failures
+
+**Symptom**: Stack overflow-like recursion or graph reconstruction issues.
+
+**Cause**: Cyclic graphs with `TrackRef(false)`.
+
+**Fix**:
+
+```csharp
+Fory fory = Fory.Builder().TrackRef(true).Build();
+```
+
+## Concurrency Issues
+
+**Cause**: Sharing a single `Fory` instance across threads.
+
+**Fix**: Use `BuildThreadSafe()`.
+
+## Validation Commands
+
+Run C# tests from repo root:
+
+```bash
+cd csharp
+dotnet test Fory.sln -c Release
+```
+
+## Related Topics
+
+- [Configuration](configuration.md)
+- [Schema Evolution](schema-evolution.md)
+- [Thread Safety](thread-safety.md)
diff --git a/docs/guide/csharp/type-registration.md
b/docs/guide/csharp/type-registration.md
new file mode 100644
index 0000000000..9640c91ac8
--- /dev/null
+++ b/docs/guide/csharp/type-registration.md
@@ -0,0 +1,82 @@
+---
+title: Type Registration
+sidebar_position: 3
+id: type_registration
+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 how to register user types in Apache Foryβ’ C#.
+
+## Register by Numeric Type ID
+
+Use explicit IDs for compact and stable cross-service mapping.
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<User>(100);
+fory.Register<Order>(101);
+```
+
+## Register by Type Name
+
+Use namespace + type name registration when you prefer symbolic mappings.
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<User>("com.example", "User");
+```
+
+You can also use the short overload:
+
+```csharp
+fory.Register<User>("User");
+```
+
+## Register a Custom Serializer
+
+```csharp
+Fory fory = Fory.Builder().Build();
+fory.Register<MyType, MyTypeSerializer>(200);
+```
+
+Namespace-based custom serializer registration is also supported:
+
+```csharp
+fory.Register<MyType, MyTypeSerializer>("com.example", "MyType");
+```
+
+## Thread-Safe Registration
+
+`ThreadSafeFory` exposes the same registration APIs. Registrations are
propagated to all per-thread runtimes.
+
+```csharp
+using ThreadSafeFory fory = Fory.Builder().BuildThreadSafe();
+fory.Register<User>(100);
+fory.Register<Order>(101);
+```
+
+## Registration Rules
+
+- Register user-defined types on both writer and reader sides.
+- Keep ID/name mappings consistent across services and languages.
+- Register before high-volume serialization workloads to avoid runtime misses.
+
+## Related Topics
+
+- [Basic Serialization](basic-serialization.md)
+- [Custom Serializers](custom-serializers.md)
+- [Cross-Language](cross-language.md)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
