webapiclientgen

強型用戶端Web API 產生器直接從ASP.NET (Core) Web API 產生C# 和TypeScript 用戶端API 程式碼，無需涉及Swagger/OpenAPI 或Swashbuckle，因此最大限度地支援ASP.NET Web API 的Code First 方法的資料類型。

產品

此項目提供以下產品：

1. 支援 .NET 和 Xamarin.Forms 的 C# 強型別客戶端 API 程式碼產生器。
2. 適用於 jQuery、Angular 2+、Aurelia、Axios 和 Fetch API 的 TypeScript 中強型別客戶端 API 的程式碼產生器。
3. TypeScript CodeDOM，TypeScript 的 .NET CodeDOM 元件，用於開發 TypeScript 程式碼產生器。
4. POCO2TS.exe，從 POCO 類別產生 TypeScript 介面的命令列程式。
5. Fonlow.Poco2Ts，從 POCO 類別產生 TypeScript 介面的元件。
6. 適用於 jQuery、AXIOS、Fetch API、Aurelia、Angular 2+ 以及 Angular Typed Reactive Forms 的插件。
7. Fonlow.DataOnlyExtensions 隨附 JSON 轉換器，用於處理位於不同時區的用戶端和伺服器之間的僅日期場景。 .NET Framework 套件也可用。

使用案例和下載

產品主要透過 NuGet 發布。

1. 產生 C# 客戶端 API，然後使用套件 Fonlow.WebApiClientGenCore
2. 產生 TypeScript 用戶端 API，然後使用 Fonlow.WebApiClientGenCore 的插件之一：
   1. jQuery 和 HttpClient 幫助程式庫
   2. 角度 6+
   3. Angular 6+，加上帶有描述的反應式表單的 FormGroup 創建
   4. AXIOS
   5. 奧雷利亞
   6. 取得API
3. 透過CodeDOM方法開發TypeScript程式碼產生器，然後使用套件Fonlow.TypeScriptCodeDOMCore。
4. 透過 CodeDOM 方法為 POCO 等開發 TypeScript 程式碼產生器，然後使用套件 Fonlow.Poco2TSCore 或使用 PowerShell 7 腳本。
5. 產生 TypeScript 類型接口，然後使用 Poco2TSCore.exe（一個控制台應用程式）。
6. 開發讀取 .NET 組件的 XML 文件的功能，然後使用套件 Fonlow.DocCommentCore。

提示：

• OpenApiClientGen 基於 WebApiClientGen 的關鍵元件，是衍生產品，用於根據 Swagger/Open API 規範的定義檔產生 C# 和 TypeScript 用戶端 API 程式碼。
• WebApiClientGen 不使用Swagger / OpenAPI 定義，而是從偵錯版本的正在運行的Web API 的運行時類型資訊產生程式碼，擺脫了OpenAPI 針對.NET 類型和Web API 的固有限制，為ASP 提供更好的開發人員體驗。

評論：

• 開發始於 2015 年，支援 .NET Framework，然後支援 .NET Core 2。
• 從2021年2月10日開始，開發將僅支援.NET 5及更高版本。
• 關於 .NET Framework 的 Wiki 內容將在可預見的將來保留。

主要特點

1. 產生的客戶端 API 程式碼直接從 Web API 控制器方法、.NET 基元類型和 POCO 類別對應。這與 WCF 中的 svcutil.exe 提供的類似。
2. 複製控制器方法和 POCO 類別的文件註解。
3. 一些驗證屬性用於為 TypeScript 程式碼產生文件註解。

開發者體驗的主要優勢

1. WebApiClientGen 與 ASP.NET Core Web API 無縫集成，在 RAD 或敏捷軟體開發期間，只需很少的步驟/開銷即可在 Web API 和客戶端 API 之間進行設定、維護和同步。
2. 支援所有 .NET 基元類型，包括十進制。
3. 支援DataTime、DataTimeOffset、DateOnly、Array、Tuple、Dynamic Object、Dictionary和KeyValuePair
4. 強型別產生的程式碼需要接受設計時類型檢查和編譯時類型檢查。
5. 提供高層次的抽象，使應用程式開發人員免受 RESTful 實踐的重複技術細節和 AJAX 呼叫的傳統程式碼的影響。
6. 包括文件註釋在內的豐富元資訊使 IDE 智慧感知更加有用，因此應用程式開發人員無需閱讀單獨的 API 文件。
7. 基於 .NET 驗證屬性產生的文件註解。
8. 基於數位類型、DateOnly 和 TypeScript 程式碼的 GUID 產生文件註解。
9. 產生的 TypeScript 程式碼符合 TypeScript 嚴格模式，產生的 Angular 2+ 程式碼符合 Angular 嚴格模式。

範例

1. POCO 類
2. 網路應用程式介面
3. 產生的客戶端 API C# 程式碼
4. 使用 C# 產生的庫的客戶端程式碼
5. 在 TypeScript 中為 jQuery、Angular 2、Aurelia 和 Axios 產生客戶端資料模型和 API
6. 使用 TypeScript 中產生的庫的客戶端程式碼
7. GitHub.IO 中託管的 Angular Heroes 線上演示與真實後端對話

評論：

1. 從生成的 TypeScript 程式碼編譯而來的 JavaScript 程式碼可以在 JS 應用程式中使用，但是，顯然沒有可用的類型信息，而應用程式程式設計師可能仍然喜歡從 AJAX 細節中進行智能感知和抽象。
   1. React 和 Vue.js 應用程式通常使用 Axios 或 Fetch API 進行 HTTP 請求。自 2019 年 6 月以來，由於此拉取請求，babel 已支援命名空間，因此您應該能夠使用生成的 TypeScript 程式碼進行 React TSX 程式設計。

概念

1. Web API 供應商/開發人員應該像 Google 和 Amazon 等一樣向客戶端程式的開發人員提供用戶端 API 庫，以便使 RESTful Web API 有效地接觸到更廣泛的消費者（內部和外部）。
2. 對於客戶端開發者來說，像ReturnType DoSomething(Type1 t1, Type2 t2 ...)這樣的經典函數原型就是API 函數，剩下的就是傳輸的技術實作細節：TCP/IP、HTTP、SOAP、面向資源、CRUD－基於URI、RESTful、XML和JSON等。
3. Web API 設計中的關注點分離得越好，您就越能從該專案的元件中受益，從而更快地交付業務價值，同時減少手動程式碼、重複性任務和人為錯誤的可能性。

預期的程式設計實踐

強型別函數原型

ReturnType DoSomething(Type1 t1, Type2 t2 ...)

		[ HttpGet ]
		[ Route ( "getPerson/{id}" ) ]
		public Person GetPerson ( long id )

透過中間件進行模型驗證

您不需要編寫驗證請求有效負載的明確程式碼，而是使用中間件進行驗證。例如：

 public void ConfigureServices ( IServiceCollection services )
{
	services . AddControllers (
		options =>
		{
			options . Filters . Add ( new ValidateModelAttribute ( ) ) ; // wholesale style to check model binding for all API calls.

參考：

• ASP.NET Web API 中的模型驗證
• ASP.NET Core MVC 與 Razor 頁面的模型驗證

透過 ApiControllerAttribute 進行模型驗證

例如：

	[ ApiController ]
	[ Route ( "api/[controller]" ) ]
	public class HeroesController : ControllerBase
	{

由中介軟體處理的非 2xx HTTP 狀態碼，可選

即使您在 API 函數中明確編寫程式碼來處理異常並傳回非 2xx HTTP 狀態碼，您也應該有一個安全網來捕獲未捕獲的異常並傳回 HTTP 狀態碼。

參考：

• ASP.NET Core 中介軟體

先決條件

伺服器端：

1. .NET 7/8
2. 新增 CodeGenController。
3. 在服務啟動程式碼中加入以下內容：

 services . AddControllers (
	options =>
	{
#if DEBUG
		options . Conventions . Add ( new Fonlow . CodeDom . Web . ApiExplorerVisibilityEnabledConvention ( ) ) ;
#endif
	}
)

評論：

• 微軟自2016年以來每年都會發布.NET（Core）的重大升級，該存儲庫中的庫一般會在半年後發布最新版本。
• 公用程式庫的 .NET 版本比最新版本低一個版本，而 ASP.NET 示範應用程式和具有產生的 .NET 用戶端 API 的整合測試套件則使用目前版本的 .NET。

.NET 客戶端：

1. .NET Framework 4.5.2、通用 Windows、Mono.Android、Xamarin.iOS、.NET Core 2.0/2.1/3 和 .NET 5
2. ASP.NET Web API 2.2 用戶端程式庫
3. Newtonsoft 的 Json.NET for Content-Type application/json
4. 微軟建置工具 2015

NewtonSoft.Json 或 System.Text.Json

從 .NET 7 開始，為了序列化，System.Text.Json 重新組裝了超過 95% 的 NewtonSoft.Json。只有少數複雜 POCO 結構的邊緣情況是 System.Text.Json 無法處理的。

WebApiClientGen 同時支援伺服器端和 C# 用戶端。對於 C# 用戶端，您可以在程式碼產生設定中使用“UseSystemTextJson”。

不過，如果您的應用程式涉及複雜的 POCO 結構，那麼從 .NET 7 開始，使用 NewtonSoft.Json 是一個安全的選擇。

TypeScript 用戶端：

1. TypeScript 編譯器
2. jQuery
3. 角度 2-17
4. 奧雷利亞
5. 阿克西奧斯
6. 取得API

欲了解更多詳情，請查看：

1. 維基百科
2. 設定說明
3. 為 ASP.NET Web API 產生 C# .NET 用戶端 API
4. 為 ASP.NET Web API 產生 TypeScript 用戶端 API
5. ASP.NET Web API、Angular2、TypeScript 和 WebApiClientGen
6. 為 ASP.NET Core Web API 產生 C# 客戶端 API
7. 強型別 OpenAPI 客戶端產生器的有意限制的預期解決方案。本文僅以 OpenApiClientGen 為例，其中的原理和解決方案可以應用於 WebApiClientGen 為您的客戶端應用程式產生的程式碼。
8. ASP.NET Core 6 中的 DateOnly

演示應用程式

此儲存庫中的示範應用程式主要用於在開發過程中測試WebApiClientGen。以下存儲庫中還有其他演示應用程序，演示了現實世界的應用程式如何利用 WebApiClientGen：

1. 適用於 .NET Framework、.NET Standard、Xamarin 和 vue TS 的 WebApiClientGen 範例。
2. 適用於 ASP.NET Core MVC、Web API、ASP.NET Core + Angular、MAUI、fetchAPI、vue TS 和 React TS 的 .NET Core 示範。
3. WebApiClientGen 與 Swagger

這些演示應用程式得到積極維護並與最新框架保持同步。如果您仍然使用一些較舊的框架，例如 Angular 4 或 5 或 .NET Core 2.0，您可以導航至儲存庫的相應標籤並結帳。

英雄之旅

Tour of Heroes 是官方 Angular 教程演示應用程式。

為了說明程式設計師使用 WebApiClientGen 的體驗，以下示範應用程式採用類似的架構設計，在各種開發框架或程式庫上具有相同的功能特性，但與真實的後端通訊。

1. Angular 2+ 和類型化反應形式
2. Xamarin
3. 毛伊島。從 Xamarin Heroes 遷移。
4. 奧蕾莉亞.包括集成測試套件。
5. 反應。包括集成測試套件。
6. Blazor 獨立版

NewtonSoft.Json 或 System.Text.Json

然而，雖然 WebApiClientGen 兩者都支持，但自 2024 年以來主要支援已轉向 System.Text.Json。

NewtonSoft.Json 在某些場景和上下文中仍然具有一些優勢：

1. 如果您有很多由DataContractAttributes 修飾的POCO 類，因為支持遺留應用程序，或者支持XML 和JSON 序列化，NewtonSoft.Json 為您提供固有的支持，而System.Text.Json 自.NET 7 以來提供了一些麻煩的和間接的支持。
2. 對於某些陣列類型和動態，NewtonSoft.Json 還是更好。