C# Serialization Guide
Apache Fory™ C# is a high-performance, cross-language serialization runtime for .NET. It provides object graph serialization, schema evolution, generic object payload 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+
Install from NuGet
Reference the single Apache.Fory package. It includes the runtime and the source generator for [ForyObject] types.
<ItemGroup>
<PackageReference Include="Apache.Fory" Version="0.16.0" />
</ItemGroup>
Basic Example
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 = "alice@example.com",
};
byte[] payload = fory.Serialize(user);
User decoded = fory.Deserialize<User>(payload);
Core API Surface
Serialize<T>(in T value)/Deserialize<T>(...)Serialize<object?>(...)/Deserialize<object?>(...)for dynamic payloadsRegister<T>(uint typeId)and namespace/name registration APIsRegister<T, TSerializer>(...)for custom serializers
Documentation
| Topic | Description |
|---|---|
| Configuration | Builder options and runtime modes |
| Basic Serialization | Typed and dynamic serialization APIs |
| Type Registration | Registering user types and custom serializers |
| Custom Serializers | Implementing Serializer<T> |
| Field Configuration | [Field] attribute and integer encoding options |
| References | Shared/circular reference handling |
| Schema Evolution | Compatible mode behavior |
| Cross-Language | Interoperability guidance |
| Supported Types | Built-in and generated type support |
| Thread Safety | Fory vs ThreadSafeFory usage |
| Troubleshooting | Common errors and debugging steps |