跳到主要内容
版本：dev

C# 序列化指南

Apache Fory™ C# 是面向 .NET 的高性能跨语言序列化运行时。它提供对象图序列化、Schema 演进、泛型对象载荷支持，以及面向并发负载的线程安全封装。

为什么选择 Fory C#？​

  • 面向 .NET 8+ 的高性能二进制序列化
  • 与 Java、Python、C++、Go、Rust、JavaScript/TypeScript、Swift、Dart、Scala 和 Kotlin 中的 Fory 实现保持跨语言兼容
  • 基于 source generator 的 [ForyStruct] 类型序列化器，以及 [ForyEnum] 和 [ForyUnion] 类型注册
  • 为外部 class、struct 和 enum 目标生成序列化器
  • 可选引用跟踪，支持共享对象图和循环对象图
  • 面向 Schema 演进的兼容模式
  • 面向多线程服务的线程安全运行时 ThreadSafeFory

快速开始​

要求​

  • .NET SDK 8.0+
  • C# 语言版本 12+

从 NuGet 安装​

引用单个 Apache.Fory 包即可。它同时包含 Fory 库，以及用于 [ForyStruct]、[ForyEnum] 和 [ForyUnion] 类型的 source generator。

<ItemGroup>
  <PackageReference Include="Apache.Fory" Version="1.5.0" />
</ItemGroup>

基础示例​

using Apache.Fory;

[ForyStruct]
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);

核心 API​

  • Serialize<T>(in T value) / Deserialize<T>(...)
  • Serialize<object?>(...) / Deserialize<object?>(...)，用于动态载荷
  • Register<T>(uint typeId) 以及基于命名空间和名称的注册 API
  • Register<T, TSerializer>(...)，用于自定义序列化器

文档​

主题说明
配置构建器选项与模式设置
基础序列化强类型和动态序列化 API
Xlang 序列化互操作性指导
Schema 元数据[ForyField] ID 与 Schema 类型描述符
类型注册注册用户类型和自定义序列化器
外部类型第三方类型序列化器
自定义序列化器实现 Serializer<T>
引用共享引用与循环引用处理
Schema 演进兼容模式行为
支持的类型内置类型与生成类型支持
线程安全Fory 与 ThreadSafeFory 的用法
gRPC 支持生成由 Fory 支持的 gRPC service companion
故障排查常见错误与调试步骤

相关资源​