C# 生成代码指南
在阅读本文档之前,您应该阅读proto3 语言指南。
注意
从 3.10 版本开始,protobuf 编译器可以为使用proto2
语法的定义生成 C# 接口。有关 proto2
定义语义的详细信息,请参阅proto2 语言指南,并查看 docs/csharp/proto2.md
(在 GitHub 上查看) 以了解有关 proto2 生成的 C# 代码的详细信息。编译器调用
当使用 --csharp_out
命令行标志调用时,protocol buffer 编译器会生成 C# 输出。--csharp_out
选项的参数是您希望编译器写入 C# 输出的目录,尽管根据其他选项,编译器可能会创建指定目录的子目录。编译器为每个 .proto
文件输入创建一个源文件,默认为 .cs
扩展名,但可以通过编译器选项配置。
C# 代码生成器仅支持 proto3
消息。确保每个 .proto
文件都以声明开头
syntax = "proto3";
C# 特定选项
您可以使用 --csharp_opt
命令行标志向 protocol buffer 编译器提供更多 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
,protocol buffer 编译器会生成文件src/Game/Player.cs
。此选项通常对应于 Visual Studio 中 C# 项目中的**默认命名空间**选项。如果指定了该选项但值为空,则生成文件中使用的完整 C# 命名空间将用于目录层次结构。如果根本没有指定此选项,则生成的文 件将简单地写入--csharp_out
指定的目录中,而不会创建任何层次结构。internal_access:当指定此选项时,生成器会使用
internal
访问修饰符而不是public
创建类型。serializable:当指定此选项时,生成器会将
[Serializable]
属性添加到生成的 message 类。
可以通过逗号分隔多个选项,如下例所示
protoc --proto_path=src --csharp_out=build/gen --csharp_opt=file_extension=.g.cs,base_namespace=Example,internal_access src/foo.proto
文件结构
输出文件名是从 .proto
文件名派生的,将其转换为 Pascal 大小写,将下划线视为单词分隔符。因此,例如,名为 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 包 example.high_score
将导致命名空间 Example.HighScore
。您可以使用 csharp_namespace
文件选项 覆盖特定 .proto 的默认生成命名空间。
每个顶级枚举和消息都会导致一个枚举或类被声明为命名空间的成员。此外,始终为文件描述符生成单个静态部分类。这用于基于反射的操作。描述符类与文件同名,不带扩展名。但是,如果存在同名的消息(这很常见),则描述符类将放置在嵌套的 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 Foo {}
protocol buffer 编译器会生成一个名为 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 Foo {
message Bar {
}
}
在这种情况下——或者如果消息包含嵌套枚举——编译器会生成一个嵌套的 Types
类,然后在 Types
类中生成一个 Bar
类,因此完整的生成代码将为
namespace [...]
{
public sealed partial class Foo : IMessage<Foo>
{
public static partial class Types
{
public sealed partial class Bar : IMessage<Bar> { ... }
}
}
}
尽管中间的 Types
类不方便,但它需要处理嵌套类型在消息中具有相应字段的常见场景。否则,您最终会在同一个类中嵌套一个属性和一个同名的类型——这将是无效的 C#。
字段
protocol buffer 编译器为消息中定义的每个字段生成一个 C# 属性。属性的确切性质取决于字段的性质:其类型以及它是单一、重复还是映射字段。
单一字段
任何单一字段都会生成一个读/写属性。string
或 bytes
字段如果指定了 null 值,将生成 ArgumentNullException
;从尚未显式设置的字段中获取值将返回空字符串或 ByteString
。消息字段可以设置为 null 值,这实际上是清除字段。这等效于将值设置为消息类型的“空”实例。
重复字段
每个重复字段都会生成一个类型为 Google.Protobuf.Collections.RepeatedField<T>
的只读属性,其中 T
是字段的元素类型。在大多数情况下,这就像 List<T>
,但它有一个额外的 Add
重载,允许一次添加多个项目。当在对象初始值设定项中填充重复字段时,这很方便。此外,RepeatedField<T>
直接支持序列化、反序列化和克隆,但这通常由生成的代码而不是手动编写的应用程序代码使用。
重复字段不能包含 null 值,即使是消息类型,除了下面解释的可空包装器类型。
映射字段
每个映射字段生成一个类型为Google.Protobuf.Collections.MapField<TKey, TValue>
的只读属性,其中TKey
是字段的键类型,TValue
是字段的值类型。在大多数情况下,它的行为类似于Dictionary<TKey, TValue>
,但它还有一个额外的Add
重载,允许一次性添加另一个字典。这在使用对象初始化器填充重复字段时非常方便。此外,MapField<TKey, TValue>
直接支持序列化、反序列化和克隆,但这通常由生成的代码而不是手动编写的应用程序代码使用。映射中的键不允许为 null;如果相应的单数字段类型支持 null 值,则值可以为 null。
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 值。将消息类型字段设置为 null 等效于调用特定于 oneof 的Clear
方法。
包装器类型字段
proto3 中的大多数知名类型都不会影响代码生成,但包装类型(StringWrapper
、Int32Wrapper
等)会更改属性的类型和行为。
所有与 C# 值类型对应的包装类型(Int32Wrapper
、DoubleWrapper
、BoolWrapper
等)都映射到Nullable<T>
,其中T
是相应的非空类型。例如,类型为DoubleValue
的字段会导致 C# 属性类型为Nullable<double>
。
类型为StringWrapper
或BytesWrapper
的字段将生成类型为string
和ByteString
的 C# 属性,但默认值为 null,并允许将 null 设置为属性值。
对于所有包装类型,重复字段中不允许使用 null 值,但允许作为映射条目的值。
枚举
给定一个像这样的枚举定义
enum Color {
COLOR_UNSPECIFIED = 0;
COLOR_RED = 1;
COLOR_GREEN = 5;
COLOR_BLUE = 1234;
}
协议缓冲区编译器将生成一个名为Color
的 C# 枚举类型,它具有相同的数值集。枚举值的名称将被转换,使其更符合 C# 开发人员的习惯。
- 如果原始名称以枚举名称本身的大写形式开头,则将其删除
- 结果将转换为帕斯卡大小写
因此,上面的Color
proto 枚举将变为以下 C# 代码
enum Color
{
Unspecified = 0,
Red = 1,
Green = 5,
Blue = 1234
}
此名称转换不会影响消息的 JSON 表示形式中使用的文本。
请注意,.proto
语言允许多个枚举符号具有相同的数值。具有相同数值的符号是同义词。在 C# 中以完全相同的方式表示这些符号,多个名称对应于相同的数值。
非嵌套枚举导致生成一个作为新命名空间成员的 C# 枚举;嵌套枚举导致在对应于枚举嵌套在其内的消息的类内的Types
嵌套类中生成一个 C# 枚举。
服务
C# 代码生成器完全忽略服务。