[小菜一碟] 使用服務參考(Service Reference)參考 Web API 及 gRPC 服務

以往服務參考(Service Reference)只能參考 Web Service 或 WCF,但是在把玩 gRPC 服務的過程中,意外地發現,原來在 Visual Studio 2019 已經可以透過服務參考的方式,為 gRPC 服務自動產生客戶端的程式碼,甚至是 Web API 也可以。

建立 .NET Core 專案,在專案上按右鍵「加入」->「服務參考」。

點擊進入之後就能看到「gRPC」及「OpenAPI」兩個區塊

服務參考 gRPC 服務

點擊「新增 gRPC 服務參考」,我們就可以選擇本地磁碟或是共享目錄中的 .proto 檔案,還是一個有 gRPC 服務協定內容的 URL,以及想要產生的程式碼類型。

那我這邊選擇使用 URL,在服務端需要做一點前置作業,新增一個 Endpoint 將 .proto 檔案的內容 Host 成一個 URL。

由於服務參考的操作介面目前還無法支援 HTTP/2 的 URL,所以我們要在 WebHostBuilder 設定支援 HTTP/1。

新增參考成功之後,就會顯示在畫面上了。

而且,新增參考成功的當下,程式碼馬上就產生好了,立即就可以開始寫 Code。

服務參考 Web API

如果我們的 Web API 有套 Swagger 的話,那麼透過服務參考,簡單幾個步驟就可以自動產生客戶端的程式碼,我這邊就以 Swangger PetStore 做為範例,點擊「新增 OpenAPI 服務參考」,將 API 文件的 URL 填上,指定一下命名空間。

雖然會立即產生客戶端程式碼,但是有一些地方我想要微調一下,像是類別名稱、程式碼檔案名稱...等,服務參考的背後其實是用 NSwag 來產生程式碼,我翻了一下原始碼,在 NSwag.ApiDescription.Client.targets 找到產生 C# 程式碼的設定,其中就有找到幾個我覺得可以調整的參數。

依據我的需求,我就打開專案檔,輸入我想要調整的參數,並且重新建置,重新產生程式碼。

另外要提一下的是 Options 這個參數,NSwag 其實還有一大堆的參數,Options 則是保留了一個位置,讓我們可以選擇輸入我們想要的參數,它會被帶在指令的後面,至於還有哪些參數可以選,就請大家參考 OpenApiToCSharpClientCommand.cs,預設值則是設定在 CSharpClientGeneratorSettings.cs

使用方式的話,就假定我產生出來的程式碼要是 internal 的,我就將 ClientClassAccessModifier 這個參數設成 internal,有多個參數的話則是用空格隔開。

不過這邊有一個小小的問題,就是變更參數之後,要把已經產出的程式碼檔案刪除再建置才會生效,我相信再過一陣子應該就會被修好了,接下來我們就寫點 Code 來感受一下它的便利,不僅呼叫 Web API 的程式碼變得簡短了,還能使用強型別。

參考資料

C# 指南 ASP.NET 教學 ASP.NET MVC 指引
Azure SQL Database 教學 SQL Server 教學 Xamarin.Forms 教學