使用 protobuf-net 生成 C# 时保留 proto 注释

Question

我们正在使用protobuf-net来处理 C# 应用程序中的协议缓冲区需求。由于我们与其他非托管应用程序共享我们的 .proto 文件，我们从 .proto 文件生成我们的代码（不使用代码优先的 protobuf-net 方法）。为了尽可能保持DRY，我们在 .proto 文件中保留了大量接口文档。我们通过项目构建目标调用的 protogen.exe 生成 C# 代码。

现在，有没有办法（自动）将这些注释传输到已编译的 C# 代码中？

基本上，给定这样的 .proto：

// This message is used to request a resource from the server
message GetResource
{
    // The identifier of the requested resource 
    required string resourceId = 1;
}

...我想要这样的东西（为了可读性省略了 IExtensible 方法）：

/// <summary>
/// This message is used to request a resource from the server
/// </summary>
[global::System.Serializable,global::ProtoBuf.ProtoContract(Name=@"GetResource")]
public partial class GetResource : global::ProtoBuf.IExtensible
{
    public GetResource() {}

    private string _resourceId;

    /// <summary>
    /// The identifier of the requested resource 
    /// [Required] <-- Would be nice...
    /// </summary>
    [global::ProtoBuf.ProtoMember(1, IsRequired = true, Name=@"resourceId", 
    DataFormat = global::ProtoBuf.DataFormat.Default)]
    public string ResourceId
    {
        get { return _resourceId; }
        set { _resourceId = value; }
    }
}

Answer 1

实际上当前版本确实支持评论。它可以通过 --include_source_info 启用。

评论在 descriptor.Location[n].leading_comments 和 trailing_comments 中可用：https : //code.google.com/p/protobuf/source/browse/trunk/src/google/protobuf/descriptor.proto

我已经在 protobuf-net Location 类中添加了相应的属性：

private string _leading_comments = "";
[global::ProtoBuf.ProtoMember(3, IsRequired = false, Name = @"leading_comments", DataFormat = global::ProtoBuf.DataFormat.Default)]
[global::System.ComponentModel.DefaultValue("")]
public string leading_comments
{
    get { return _leading_comments; }
    set { _leading_comments = value; }
}

private string _trailing_comments = "";
[global::ProtoBuf.ProtoMember(4, IsRequired = false, Name = @"trailing_comments", DataFormat = global::ProtoBuf.DataFormat.Default)]
[global::System.ComponentModel.DefaultValue("")]
public string trailing_comments
{
    get { return _trailing_comments; }
    set { _trailing_comments = value; }
}

并将 --include_source_info 添加到 protoc 调用（ProtoBuf.CodeGenerator.InputFileLoader）

并将带有注释的位置添加到生成的 xml 中：

<?xml version="1.0" encoding="utf-16"?>
<FileDescriptorSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <file>
    <FileDescriptorProto>
      <name>Test.proto</name>
      <dependency />
      <message_type>
        <DescriptorProto>
          <name>Test2</name>
          <field>
            <FieldDescriptorProto>
              <name>IntValue</name>
              <number>1</number>
              <type>TYPE_INT32</type>
            </FieldDescriptorProto>
          </field>
          <extension />
          <nested_type />
          <enum_type />
          <extension_range />
        </DescriptorProto>
      </message_type>
      <enum_type />
      <service />
      <extension />
      <source_code_info>
        <location>
...
        <Location>
            <path>
              <int>4</int>
              <int>0</int>
              <int>2</int>
              <int>0</int>
            </path>
            <span>
              <int>1</int>
              <int>0</int>
              <int>28</int>
            </span>
            <trailing_comments> some comment
</trailing_comments>
          </Location>
...
          </location>
      </source_code_info>
    </FileDescriptorProto>
  </file>
</FileDescriptorSet>

源.proto：

message Test2{
optional int32 IntValue = 1;// some comment
}

但我不擅长 xslt 更新 ProtoGen/csharp.xslt 以将注释包含到生成的 CS 文件中

Answer 2

目前，我相信答案是否定的。据我所知，“protoc”（Google 用于解析 .proto 文件的工具，在幕后使用）会默默地丢弃注释 - 因此没有任何内容可供读取。如果编写了自定义解析器，那么是的，这是可能的，但是对于哪些注释适用于哪些行也存在语言歧义，例如：

// this probably relates to resourceId
required string resourceId = 1;

required int foo = 2; // but... is this foo? or bar?
                      // and what about this?

       // what does this relate to? and why?

// and this? what are the rules?
required int bar = 3;

因此，出于两个不同的原因：目前还没有。不过，考虑了所有建议...特别是如果它们附带了自定义解析器:)

请注意，据我所知，由于这个原因，大多数（所有？）实现中都缺少此信息。不过，我很高兴得到纠正。