0

評估過 AutoRest、NSwag、Swagger CodeGen 的客戶端程式碼產生功能，我選擇 Swag Studio，理由是 GUI 介面友善，不依賴第三方套件，且輸出結果為單一檔案，較符合我的要求。

實務應用上，難免需要微調產出結果以符合專案的特殊要求，而我遇到的情境得支援 .NET 3.5，更是不改不行，故如何客製客戶端程式範本為首要之急，阻礙太大時甚至該當機立斷早早轉向。

經過一番研究，做到修改範本支援 .NET 3.5 版的目標，過程有點繁瑣，特整理分享給有類似需求的同學參考。

先說我的改法：在 NSwag Studio 上加一個「For .NET 3.5」選項，選取後改輸出適用 .NET 3.5 的程式碼。

.NET 3.5 版與原有版本主要差別在 .NET 3.5 沒有 System.Threading.Tasks(4.0+) 及 HttpClient(4.5+)，不支援 async、await，還有一些零星小差別。一開始本想靠替代套件(System.Threading.Tasks.Unofficial、Rackspace.HttpClient35)解決，但替代程式庫與 .NET 內建版本存在差距，程式終究得改。何況依賴外部程式庫，有違選擇 NSwag Studio 的初衷，故我採行的策略是針對差異較大的部分另寫一套 .NET 3.5 樣版，細節容後再提。

修改後的 NSwag Studio 長這樣。理論上，勾選 For .NET 3.5 後，有些選項不適用該停用或隱藏(如 Inject HttpClient via constructor... 等等)，但自用工具就不鈑烤打腊了，達到目的比較重要。

下面是修改細節。首先，我從 Github Fork 專案取得 NSwag 原始碼。 開啟 src/NSwag.sln，這個完整版解決方案共有 45 個專案，從核心元件、Console 程式、ASP.NET Core Middleware、自動測試、NuGet 程式包、Chocolatey 程式包到 NSwag Studio，應有盡有。

產生 C# 的樣版在 NSwag.CodeGeneration.CSharp 專案 Templates 目錄下，裡面有一堆 .liquid 附檔名的檔案，

.liquid 是 Ruby 的 Liquid Markup 樣版，用來依據 Model 物件產生 C# 程式， Liquid 語法類以這樣：

大家若有 ASP 或 cshtml 經驗，要看懂及改寫不算難。改寫幅度太大的部分，我選擇拆檔(例如上上圖中的 Client.Class.liquid 與 Client.Class35.liquid)以簡化樣版結構，由於原本的設計已模組化，有多處靠 {% template Client.Class %} 方式載入外部樣版，故可在源頭加入 if 邏輯搞定：

{%     if GenerateImplementation -%}
{%          if Net35Mode -%}
{% template Client.Class35 %}
{%          else -%}
{% template Client.Class %}
{%          endif -%}
{%     endif -%}

再來是加入 Net35Mode 參數，共有幾個地方：

  • NSwag.CodeGeneration.CSharp\SwaggerToCSharpClientGeneratorSettings.cs
    加入 Net35Mode 屬性
  • NSwag.CodeGeneration.CSharp\Models\CSharpClientTemplateModel.cs
    這是要傳入 Liquid 樣版的 Model，需新增 Net35Mode 傳出 SwaggerToCSharpClientGeneratorSettings.Net35Mode
  • NSwag.Commands\Commands\CodeGeneration\SwaggerToCSharpClientCommand.cs
    這是 NSwag Studio WPF 用的 ViewModel，也要加入 Net35Mode 屬性對應 SwaggerToCSharpClientGeneratorSettings.Net35Mode
  • NSwagStudio\Views\CodeGenerators\SwaggerToCSharpClientGeneratorView.xaml
    在 UI 加上 Checkbox 繫結到 SwaggerToCSharpClientCommand.Net35Mode 屬性

修改後要部署 NSwag Studio 測試稍麻煩，建議可在測試專案增加測試項目，如心有餘力將測試案例補齊就更完美了。

我先在 NSwag.CodeGeneration.CSharp.Tests\SCharpClientSettingsTests.cs 加入以下方法，測試啟用 Net35Mode 時程式碼不會出現 Task，基本上就是成功了。

[Fact]
public async Task When_net35Mode_is_set_then_no_Task_is_found()
{
    //// Arrange
    var swaggerGenerator = new WebApiToSwaggerGenerator(
        new WebApiToSwaggerGeneratorSettings());

    //為假想對象 ApiController 建立 Swagger 文件
    var document = await swaggerGenerator.GenerateForControllerAsync<FooController>();

    //指定不同參數
    var generator = new SwaggerToCSharpClientGenerator(document,
        new SwaggerToCSharpClientGeneratorSettings
        {
            Net35Mode = true
        });

    //// Act
    var code = generator.GenerateFile();

    //// Assert
    Assert.DoesNotContain("Task", code);
}

最後說一下如何執行修改版 NSwag Studio。

NSwag Studio 產生 C# 程式碼時並不是直接呼叫元件，而是在 Temp 目錄產生一個 nswag_document_75debafd-8a81-41b5-93c6-007cb39cf461_config.json 設定檔，再呼叫指定 Runtime 目錄下的 NSwag.exe(Win) / NSwag.dll(.NET Core) 命令列工具程式產生程式碼。設計成這樣是為了讓 AspNetCoreToSwaggerCommand、WebApiToSwaggerCommand、TypesToSwaggerCommand 可以在獨立 AppDomain (.NET Framework) 或 AssemblyLoadContext (.NET Core) 執行，使其與 ASP.NET 網站或 NSwag Studio 脫鉤(二者使用的平台或 DLL 版本可能不同)，詳細說明可參考官方文件：NSwag Assembly loading

故要修改邏輯有多處元件要更新，netcoreapp1.0/1.1/2.0/2.1/2.2 等資料夾位於 \NSwag.ConsoleCore\bin\Release，Win 資料夾則來自 \NSwag.Console\bin\Release\net461 (再加上 \NSwag.Console.x86\bin\Release\net461\ NSwag.x86.exe & NSwag.x86.exe.config )，NSwag Studio 主程式則位於 \NSwagStudio\bin\Release (若有修改 UI 增加選項，NSwag.Commands.dll 與 NSwagStudio.exe)。

經過這番手腳，NSwag Studio 就能產生為專案量身訂做的 C# 程式碼囉~

Tutorial of how to customize the C# code template of NSwag Studio.


Comments

Be the first to post a comment

Post a comment