關於.Net 7.0 RC gRPC JSON 轉碼為 Swagger/OpenAPI檔案的注意事項

大家好，我是失業在家，正在找工作的博主Jerry，找工作之餘，看到.Net 7.0 RC2釋出了，就想測試下.Net 7.0 RC2 gRPC JSON 轉碼為 Swagger/OpenAPI檔案的特性，這個特性大大提高了測試gRPC介面的方便性。本來以為按照官方檔案，也就是幾分鐘的事，結果搞了幾個小時才成功！我也是服了官方的檔案了！

我現在把要要注意的幾個問題列出來，給要使用這個特性的程式設計師節約一點時間。

一、官方檔案對gRPC JSON 轉碼設定描述不完整

這個特性是基於gRPC JSON 轉碼設定的，也就是說我們先要設定gRPC JSON 轉碼才能使用該特性。

// Add services to the container.
builder.Services.AddGrpc().AddJsonTranscoding();

如上我們在Program.cs中的程式碼，先要先加上gRPC JSON轉碼。如果按照官方檔案直接在.proto檔案的rpc方法中增加option

 option (google.api.http) = {
      get: "/v1/greeter/{name}"
    };

則編譯會報錯，「Option "(google.api.http)" unknown. Ensure that your proto definition file imports the proto which defines the option.」

要先按照另一個官方檔案專門設定gRPC JSON轉碼。要在.proto檔案中增加「import "google/api/annotations.proto";

import "google/api/annotations.proto";

二、官方檔案對gRPC JSON 轉碼設定描述不清楚

加上了import..., 還是會編譯出錯，"Import "google/api/annotations.proto" was not found or had errors.".

原因就是檔案裡的這一句「Imported from the google/api/annotations.proto file. The google/api/http.proto and google/api/annotations.proto files need to be in the project.」實在說的不清楚。

其實，我們要在我們專案的根目錄建立google資料夾，然後在下面建立api資料夾，再把這兩個檔案放到裡面。如下截圖：

然後還要確保專案檔案中，不要把這兩個檔案包含到Protobuf節點中。不然在啟動程式的時候就會出現物件轉換失敗的錯誤，「[A]Google.Protobuf.ExtensionValue`1[Google.Api.HttpRule] cannot be cast to [B]Google.Protobuf.ExtensionValue`1[Google.Api.HttpRule]. Type A originates from 'Google.Protobuf, Version=3.19.4.0, Culture=neutral, PublicKeyToken=a7d26565bac4d604' in the context 'Default' at location 'D:\\Study\\Test\\GrpcService4TestSwagger\\bin\\Debug\\net7.0\\Google.Protobuf.dll'. Type B originates from 'Google.Protobuf, Version=3.19.4.0, Culture=neutral, PublicKeyToken=a7d26565bac4d604' in the context 'Default' at location 'D:\\Study\\Test\\GrpcService4TestSwagger\\bin\\Debug\\net7.0\\Google.Protobuf.dll'」

<ItemGroup>
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

這樣就算設定gRPC JSON轉碼完成了，程式終於可以執行起來了。

三、官方檔案上的程式碼片段不正確

這時候，如果你存取Swagger的頁面還是會出錯，「System.IO.FileNotFoundException:「Could not find file 'D:\Study\Test\GrpcService4TestSwagger\bin\Debug\net7.0\Server.xml」，我真是服了這個官方檔案了，要把官方檔案給的程式碼：

var filePath = Path.Combine(System.AppContext.BaseDirectory, "Server.xml");
    c.IncludeXmlComments(filePath);
    c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);

改成這樣才行：

 var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var filePath = Path.Combine(AppContext.BaseDirectory, xmlFilename);
    c.IncludeXmlComments(filePath);
    c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);

終於， gRPC JSON 轉碼為 Swagger/OpenAPI檔案的特性可以成功執行了。

四、找工作

▪ 博主有15年以上的軟體技術實施經驗（Technical Leader），專注於微服務和雲原生（K8s）軟體架構設計、專注於 .Net Core\Java開發和Devops構建釋出。
▪ 博主10年以上的軟體交付管理經驗（Project Manager & Product Ower），致力於敏捷（Scrum）專案管理、軟體產品業務需求分析和原型設計。
▪ 博主熟練設定和使用 Microsoft Azure雲。
▪ 博主為人誠懇，積極樂觀，工作認真負責。

我家在廣州，也可以去深圳工作。做架構和專案管理都可以。有工作機會推薦的朋友可以加我微信 15920128707，微信名字叫Jerry。