C# 生成代码指南

准确描述协议缓冲区编译器为使用 proto3 语法的协议定义生成的 C# 代码。

在阅读本文档之前，您应该先阅读proto3 语言指南。

注意

从 release 3.10 开始，protobuf 编译器可以为使用 proto2 语法的定义生成 C# 接口。请参阅proto2 语言指南了解 proto2 定义的语义细节，并参阅 docs/csharp/proto2.md (在 GitHub 上查看) 了解 proto2 生成的 C# 代码的细节。

编译器调用

使用 --csharp_out 命令行标志调用协议缓冲区编译器时，会生成 C# 输出。--csharp_out 选项的参数是您希望编译器写入 C# 输出的目录，尽管根据其他选项，编译器可能会在该指定目录下创建子目录。编译器为每个 .proto 输入文件生成一个源文件，默认扩展名为 .cs，但可通过编译器选项进行配置。

C# 代码生成器仅支持 proto3 消息。确保每个 .proto 文件都以以下声明开头：

syntax = "proto3";

C# 特定选项

您可以使用 --csharp_opt 命令行标志为协议缓冲区编译器提供更多 C# 选项。支持的选项有：

file_extension: 设置生成代码的文件扩展名。默认为 .cs，但一个常用的替代是 .g.cs，表示该文件包含生成的代码。
base_namespace: 指定此选项时，生成器会为生成的源代码创建一个与生成类的命名空间对应的目录层次结构，使用该选项的值来指示应将命名空间的哪一部分视为输出目录的“基础”。例如，使用以下命令行：
```
protoc --proto_path=bar --csharp_out=src --csharp_opt=base_namespace=Example player.proto
```
其中 player.proto 具有 csharp_namespace 选项 Example.Game，协议缓冲区编译器会创建文件 src/Game/Player.cs。此选项通常对应于 Visual Studio 中 C# 项目的 default namespace 选项。如果指定了该选项但值为空，则生成的文件中使用的完整 C# 命名空间将用于目录层次结构。如果根本没有指定该选项，则生成的文件将直接写入由 --csharp_out 指定的目录，不创建任何层次结构。
internal_access: 指定此选项时，生成器会创建具有 internal 访问修饰符的类型，而不是 public。
serializable: 指定此选项时，生成器会向生成的 message 类添加 [Serializable] 属性。

可以通过逗号分隔来指定多个选项，如下例所示：

protoc --proto_path=src --csharp_out=build/gen --csharp_opt=file_extension=.g.cs,base_namespace=Example,internal_access src/foo.proto

文件结构

输出文件的名称根据 .proto 文件名转换而来，将其转换为 Pascal-case，并将下划线视为单词分隔符。例如，名为 player_record.proto 的文件将生成一个名为 PlayerRecord.cs 的输出文件（文件扩展名可以使用 --csharp_opt 指定，如上所示）。

每个生成的文件在公共成员方面采用以下形式。（此处未显示实现。）

namespace [...]
{
  public static partial class [... descriptor class name ...]
  {
    public static FileDescriptor Descriptor { get; }
  }

  [... Enums ...]
  [... Message classes ...]
}

namespace 是根据 proto 的 package 推断出来的，使用与文件名相同的转换规则。例如，proto package 为 example.high_score 将生成 Example.HighScore 的命名空间。您可以使用 csharp_namespace 文件选项覆盖特定 .proto 文件的默认生成命名空间。

每个顶层枚举和消息都会导致在命名空间中声明一个枚举或类。此外，始终会为文件描述符生成一个静态 partial 类。这用于基于反射的操作。描述符类的名称与文件名相同，不带扩展名。但是，如果存在与消息同名的消息（这很常见），则描述符类会放置在嵌套的 Proto 命名空间中，以避免与消息冲突。

作为所有这些规则的示例，请考虑 Protocol Buffers 中提供的 timestamp.proto 文件。timestamp.proto 的精简版本如下所示：

syntax = "proto3";
package google.protobuf;
option csharp_namespace = "Google.Protobuf.WellKnownTypes";

message Timestamp { ... }

生成的 Timestamp.cs 文件具有以下结构：

namespace Google.Protobuf.WellKnownTypes
{
  namespace Proto
  {
    public static partial class Timestamp
    {
      public static FileDescriptor Descriptor { get; }
    }
  }

  public sealed partial class Timestamp : IMessage<Timestamp>
  {
    [...]
  }
}

消息

给定一个简单的 message 声明：

message Foo {}

协议缓冲区编译器会生成一个密封的 partial 类，名为 Foo，该类实现了 IMessage<Foo> 接口，如下所示，并带有成员声明。有关更多信息，请参阅内联注释。

public sealed partial class Foo : IMessage<Foo>
{
  // Static properties for parsing and reflection
  public static MessageParser<Foo> Parser { get; }
  public static MessageDescriptor Descriptor { get; }

  // Explicit implementation of IMessage.Descriptor, to avoid conflicting with
  // the static Descriptor property. Typically the static property is used when
  // referring to a type known at compile time, and the instance property is used
  // when referring to an arbitrary message, such as during JSON serialization.
  MessageDescriptor IMessage.Descriptor { get; }

  // Parameterless constructor which calls the OnConstruction partial method if provided.
  public Foo();
  // Deep-cloning constructor
  public Foo(Foo);
  // Partial method which can be implemented in manually-written code for the same class, to provide
  // a hook for code which should be run whenever an instance is constructed.
  partial void OnConstruction();

  // Implementation of IDeepCloneable<T>.Clone(); creates a deep clone of this message.
  public Foo Clone();

  // Standard equality handling; note that IMessage<T> extends IEquatable<T>
  public override bool Equals(object other);
  public bool Equals(Foo other);
  public override int GetHashCode();

  // Converts the message to a JSON representation
  public override string ToString();

  // Serializes the message to the protobuf binary format
  public void WriteTo(CodedOutputStream output);
  // Calculates the size of the message in protobuf binary format
  public int CalculateSize();

  // Merges the contents of the given message into this one. Typically
  // used by generated code and message parsers.
  public void MergeFrom(Foo other);

  // Merges the contents of the given protobuf binary format stream
  // into this message. Typically used by generated code and message parsers.
  public void MergeFrom(CodedInputStream input);
}

请注意，所有这些成员始终存在；optimize_for 选项不影响 C# 代码生成器的输出。

嵌套类型

一个 message 可以声明在另一个 message 内部。例如：

message Foo {
  message Bar {
  }
}

在这种情况下——或者如果一个 message 包含一个嵌套枚举——编译器会生成一个嵌套的 Types 类，然后在 Types 类中生成一个 Bar 类，因此完整的生成代码将是：

namespace [...]
{
  public sealed partial class Foo : IMessage<Foo>
  {
    public static partial class Types
    {
      public sealed partial class Bar : IMessage<Bar> { ... }
    }
  }
}

尽管中间的 Types 类有些不便，但它对于处理嵌套类型在 message 中具有相应字段的常见情况是必需的。否则，您最终会在同一个类中嵌套一个同名属性和一个同名类型——这将是无效的 C# 代码。

字段

协议缓冲区编译器为 message 中定义的每个字段生成一个 C# 属性。该属性的确切性质取决于字段的性质：其类型，以及它是单数、重复还是 map 字段。

单数字段

任何单数字段都会生成一个读/写属性。如果指定 null 值，string 或 bytes 字段会生成 ArgumentNullException；从未显式设置的字段中获取值将返回空字符串或 ByteString。Message 字段可以设置为 null 值，这相当于清除该字段。这与将值设置为 message 类型的“空”实例不同。

重复字段

每个重复字段都会生成一个只读属性，类型为 Google.Protobuf.Collections.RepeatedField<T>，其中 T 是字段的元素类型。在很大程度上，这类似于 List<T>，但它有一个额外的 Add 重载，允许一次性添加一个项集合。这在对象初始化器中填充重复字段时很方便。此外，RepeatedField<T> 直接支持序列化、反序列化和克隆，但这通常由生成代码使用，而不是手动编写的应用程序代码。

重复字段不能包含 null 值，即使是 message 类型也不行，除了下面解释的可空包装类型。

Map 字段

每个 map 字段都会生成一个只读属性，类型为 Google.Protobuf.Collections.MapField<TKey, TValue>，其中 TKey 是字段的键类型，TValue 是字段的值类型。在很大程度上，这类似于 Dictionary<TKey, TValue>，但它有一个额外的 Add 重载，允许一次性添加另一个字典。这在对象初始化器中填充重复字段时很方便。此外，MapField<TKey, TValue> 直接支持序列化、反序列化和克隆，但这通常由生成代码使用，而不是手动编写的应用程序代码。map 中的键不允许为 null；如果相应的单数字段类型支持 null 值，则值可以为 null。

Oneof 字段

oneof 中的每个字段都有一个单独的属性，类似于常规单数字段。但是，编译器还会生成一个额外的属性来确定 oneof 中哪个字段已设置，以及一个枚举和一个方法来清除 oneof。例如，对于此 oneof 字段定义：

oneof avatar {
  string image_url = 1;
  bytes image_data = 2;
}

编译器将生成这些公共成员：

enum AvatarOneofCase
{
  None = 0,
  ImageUrl = 1,
  ImageData = 2
}

public AvatarOneofCase AvatarCase { get; }
public void ClearAvatar();
public string ImageUrl { get; set; }
public ByteString ImageData { get; set; }

如果某个属性是当前的 oneof“case”，获取该属性将返回为该属性设置的值。否则，获取该属性将返回该属性类型的默认值——oneof 中一次只能设置一个成员。

设置 oneof 的任何组成属性都会改变 oneof 报告的“case”。与常规单数字段一样，您不能将具有 string 或 bytes 类型的 oneof 字段设置为 null 值。将 message 类型字段设置为 null 相当于调用 oneof 特定的 Clear 方法。

包装类型字段

proto3 中的大多数知名类型不影响代码生成，但包装类型（StringWrapper、Int32Wrapper 等）会改变属性的类型和行为。

所有对应于 C# 值类型的包装类型（Int32Wrapper、DoubleWrapper、BoolWrapper 等）都映射到 Nullable<T>，其中 T 是相应的非空类型。例如，类型为 DoubleValue 的字段会生成类型为 Nullable<double> 的 C# 属性。

类型为 StringWrapper 或 BytesWrapper 的字段会生成类型为 string 和 ByteString 的 C# 属性，但默认值为 null，并允许将 null 设置为属性值。

对于所有包装类型，重复字段中不允许使用 null 值，但允许将其用作 map 条目的值。

枚举

给定一个枚举定义，例如：

enum Color {
  COLOR_UNSPECIFIED = 0;
  COLOR_RED = 1;
  COLOR_GREEN = 5;
  COLOR_BLUE = 1234;
}

协议缓冲区编译器会生成一个名为 Color 的 C# 枚举类型，其值集合与 proto 定义相同。枚举值的名称会经过转换，以便更符合 C# 开发人员的习惯：

如果原始名称以枚举名称本身的大写形式开头，则将其删除：
结果转换为 Pascal case：

因此，上面的 Color proto 枚举将变为以下 C# 代码：

enum Color
{
  Unspecified = 0,
  Red = 1,
  Green = 5,
  Blue = 1234
}

此名称转换不影响 message 的 JSON 表示中使用的文本。

请注意，.proto 语言允许多个枚举符号具有相同的数值。数值相同的符号是同义词。这些在 C# 中以完全相同的方式表示，多个名称对应于同一个数值。

非嵌套枚举会生成一个新的命名空间成员 C# 枚举；嵌套枚举会在对应于该枚举所嵌套 message 的类中的 Types 嵌套类中生成一个 C# 枚举。

服务

C# 代码生成器完全忽略 service。