T2FGame.CodeGen.Protocol 1.0.9

T2FGame.CodeGen.Protocol

协议源生成器 - 用于 protobuf-net 集成的增量源生成器。

功能

• 自动生成 protobuf-net RuntimeTypeModel 配置
• 从标记 [ProtoContract] 的类型生成 .proto 文件
• 自动生成错误码映射（C# 和 TypeScript）
• 支持构建后自动导出 .proto 文件

安装

<PackageReference Include="T2FGame.CodeGen.Protocol" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />

使用方法

1. 定义协议类

在 DTO 类上标记 [ProtoContract]：

[ProtoContract]
public class LoginRequest
{
    public string Username { get; set; }
    public string Password { get; set; }
}

可选使用 [ProtoOrder] 指定字段顺序：

[ProtoContract]
public class LoginRequest
{
    [ProtoOrder(1)]
    public string Username { get; set; }

    [ProtoOrder(2)]
    public string Password { get; set; }
}

2. 生成的文件

生成器将自动生成：

• GeneratedProtoConfig.g.cs - RuntimeTypeModel 配置
• Proto_*.g.cs - .proto 文件内容（作为嵌入资源）
• GeneratedErrorCodes.g.cs - 错误码映射
• GeneratedErrorCodes.ts.g.cs - TypeScript 错误码（作为嵌入资源）

导出 .proto 文件

方式一：使用 MSBuild 任务（推荐）

在项目文件中启用自动导出：

<PropertyGroup>
  
  <T2FGame_ExportProtoEnabled>true</T2FGame_ExportProtoEnabled>

  
  <T2FGame_ExportProtoPath>$(MSBuildProjectDirectory)\..\protos</T2FGame_ExportProtoPath>

  
  <T2FGame_ExportProtoClean>true</T2FGame_ExportProtoClean>
</PropertyGroup>

构建后会自动导出 .proto 文件到指定目录。

方式二：使用 CLI 工具

安装全局工具：

dotnet tool install -g T2FGame.Tools.Cli

导出 .proto 文件：

# 基本用法
t2f-proto export -a ./bin/Debug/net9.0/MyGame.dll -o ./protos

# 导出所有资源（包括 .ts 文件）
t2f-proto export -a ./bin/Debug/net9.0/MyGame.dll -o ./protos --all

# 不清理旧文件
t2f-proto export -a ./bin/Debug/net9.0/MyGame.dll -o ./protos --clean false

CLI 命令参数

错误码生成

使用 [ErrorCodeContainer] 和 [ErrorCode] 标记错误码：

[ErrorCodeContainer(Module = "Auth")]
public static class AuthErrorCodes
{
    [ErrorCode("用户名或密码错误")]
    public const int InvalidCredentials = 10001;

    [ErrorCode("Token 已过期")]
    public const int TokenExpired = 10002;
}

生成器会生成：

C# 版本（用于服务端）：

public static class ErrorCodeMessages
{
    public static string GetMessage(int code) => code switch
    {
        10001 => "用户名或密码错误",
        10002 => "Token 已过期",
        _ => "未知错误"
    };
}

TypeScript 版本（用于客户端）：

export const ErrorCodes = {
    Auth: {
        InvalidCredentials: 10001,
        TokenExpired: 10002,
    }
} as const;

export function getErrorMessage(code: number): string {
    switch (code) {
        case 10001: return "用户名或密码错误";
        case 10002: return "Token 已过期";
        default: return "未知错误";
    }
}

目录结构

T2FGame.CodeGen.Protocol/
├── Analyzers/
│   ├── ProtoContractAnalyzer.cs    # ProtoContract 分析器
│   └── ErrorCodeAnalyzer.cs        # 错误码分析器
├── Emitters/
│   ├── ProtoConfigEmitter.cs       # protobuf-net 配置发射器
│   ├── ProtoFileEmitter.cs         # .proto 文件发射器
│   └── ErrorCodeEmitter.cs         # 错误码发射器
├── Models/
│   └── ProtocolModels.cs           # 协议模型定义
├── build/
│   └── T2FGame.CodeGen.Protocol.targets  # MSBuild 任务
└── ProtocolSourceGenerator.cs      # 主生成器入口