ホーム>ASPソースコード>その他のカテゴリー
ダウンロード

厳密に型指定されたクライアント Web API ジェネレーターは、Swagger/OpenAPI または Swashbuckle を介さずに、ASP.NET (コア) Web API から直接 C# および TypeScript でクライアント API コードを生成するため、ASP.NET Web API のコード ファースト アプローチのデータ型のサポートを最大限に活用できます。 。

製品

このプロジェクトは次の製品を提供します。

  1. .NET および Xamarin.Forms をサポートする C# の厳密に型指定されたクライアント API のコード ジェネレーター。
  2. jQuery、Angular 2+、Aurelia、Axios、Fetch API 用の TypeScript で厳密に型指定されたクライアント API 用のコード ジェネレーター。
  3. TypeScript CodeDOM は、TypeScript コード ジェネレーターを開発するための TypeScript 用の .NET CodeDOM コンポーネントです。
  4. POCO2TS.exe、POCO クラスから TypeScript インターフェイスを生成するコマンド ライン プログラム。
  5. Fonlow.Poco2Ts、POCO クラスから TypeScript インターフェイスを生成するコンポーネント。
  6. jQuery、AXIOS、Fetch API、Aurelia、Angular 2+、および Angular Typed Reactive Forms 用のプラグイン。
  7. 異なるタイムゾーンにあるクライアントとサーバーの間で日付のみのシナリオを処理するための JSON コンバーターを備えた Fonlow.DataOnlyExtensions。 .NET Framework パッケージも利用できます。

パッケージ

使用例とダウンロード

製品は主に NuGet を通じてリリースされます。

  1. C# クライアント API を生成し、パッケージ Fonlow.WebApiClientGenCore を使用します。
  2. TypeScript クライアント API を生成し、Fonlow.WebApiClientGenCore のプラグインの 1 つを使用します。
    1. jQuery および HttpClient ヘルパー ライブラリ
    2. 角度 6+
    3. Angular 6 以降、および説明付きのリアクティブ フォーム用の FormGroup の作成
    4. アクシオス
    5. オーレリア
    6. APIを取得する
  3. CodeDOM アプローチを通じて TypeScript コード ジェネレーターを開発し、Fonlow.TypeScriptCodeDOMCore パッケージを使用します。
  4. POCO などの CodeDOM アプローチを通じて TypeScript コード ジェネレーターを開発し、パッケージ Fonlow.Poco2TSCore を使用するか、PowerShell 7 スクリプトを使用します。
  5. TypeScript 型インターフェイスを生成し、コンソール アプリである Poco2TSCore.exe を使用します。
  6. .NET アセンブリの XML ドキュメントを読み取る機能を開発し、Fonlow.DocCommentCore パッケージを使用します。

ヒント:

  • WebApiClientGen の主要コンポーネントに基づく OpenApiClientGen は、Swagger/Open API 仕様の定義ファイルに従って C# および TypeScript でクライアント API コードを生成するためのスピンオフです。
  • WebApiClientGen は Swagger/OpenAPI 定義を利用しませんが、デバッグ ビルドの実行中の Web API の実行時型情報からコードを生成し、.NET 型および Web API に対する OpenAPI の固有の制限を取り除き、ASP により良い開発者エクスペリエンスを提供します。 NET (コア) Web API 開発者。

備考：

  • 開発は 2015 年に開始され、.NET Framework をサポートし、次に .NET Core 2 をサポートしました。タグ "LastCore31" は、.NET Framework 4.6.2 および .NET Core 3.1 をサポートする最後のスナップショットをマークします。
  • 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. 10 進数を含むすべての .NET プリミティブ型をサポートします。
  3. DataTime、DataTimeOffset、DateOnly、配列、タプル、動的オブジェクト、辞書、KeyValuePair をサポート
  4. 厳密に型指定された生成コードは、設計時の型チェックとコンパイル時の型チェックの対象になります。
  5. 高レベルの抽象化を提供し、RESTful プラクティスの反復的な技術的な詳細や AJAX 呼び出しの従来のコードからアプリケーション開発者を保護します。
  6. ドキュメント コメントを含む豊富なメタ情報により、IDE インテリセンスがより便利になるため、アプリケーション開発者は個別の API ドキュメントを読む必要が少なくなります。
  7. .NET検証属性に基づいて生成されたドキュメントコメント。
  8. TypeScript コードの数値型、DateOnly、および GUID に基づいてドキュメント コメントを生成しました。
  9. 生成された TypeScript コードは TypeScript strict モードに準拠し、生成された Angular 2+ コードは Angular strict モードに準拠します。

例

  1. POCOクラス
  2. ウェブAPI
  3. 生成されたクライアント API C# コード
  4. C# で生成されたライブラリを使用したクライアント コード
  5. jQuery、Angular 2、Aurelia、Axios 用に TypeScript で生成されたクライアント データ モデルと API
  6. TypeScript で生成されたライブラリを使用したクライアント コード
  7. GitHub.IO でホストされている Angular Heroes が実際のバックエンドと通信するオンライン デモ

備考：

  1. 生成された TypeScript コードからコンパイルされた JavaScript コードは JS アプリケーションで使用できますが、明らかに型情報は利用できませんが、アプリケーション プログラマは依然として AJAX の詳細からのインテリセンスと抽象化を享受できます。
    1. React および Vue.js アプリケーションは通常、HTTP リクエストに Axios または Fetch API を使用します。 2019 年 6 月以降、babel はこのプル リクエストのおかげで名前空間をサポートしているため、生成された TypeScript コードを使用して React TSX プログラミングを行うことができるはずです。

コンセプト

  1. Web API ベンダー/開発者は、RESTful Web API をより広範な消費者 (内部および外部) に効率的に届けるために、Google や Amazon などが行うように、クライアント API ライブラリをクライアント プログラムの開発者に提供する必要があります。
  2. クライアント開発者にとって、 ReturnType DoSomething(Type1 t1, Type2 t2 ...)のような古典的な関数プロトタイプは API 関数であり、残りはトランスポートの技術的な実装の詳細です。TCP/IP、HTTP、SOAP、リソース指向、CRUDベースの URI、RESTful、XML、JSON など。API 関数を呼び出すには、関数プロトタイプと API ドキュメントの一部があれば十分です。
  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 ステータス コード (オプション)

例外を処理して 2xx 以外の HTTP ステータス コードを返すコードを API 関数に明示的に作成した場合でも、キャッチされない例外をキャッチして HTTP ステータス コードを返す安全網を用意する必要があります。

参考文献:

  • ASP.NETコアミドルウェア

前提条件

サーバー側:

  1. .NET 7/8
  2. CodeGenControllerを追加します。
  3. サービス起動コードに次のコードを追加します。 
 services . AddControllers (
	options =>
	{
#if DEBUG
		options . Conventions . Add ( new Fonlow . CodeDom . Web . ApiExplorerVisibilityEnabledConvention ( ) ) ;
#endif
	}
)

備考：

  • Microsoft は 2016 年から毎年 .NET (Core) のメジャー アップグレードをリリースしており、このリポジトリ内のライブラリは通常、約半年後に最新のバージョンに従うことになります。
  • パブリック ライブラリは最新バージョンの 1 つ前の .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. Content-Type application/json 用 Newtonsoft の Json.NET
  4. Microsoft ビルド ツール 2015

NewtonSoft.Json または System.Text.Json

.NET 7 では、シリアル化のために System.Text.Json が NewtonSoft.Json の 95% 以上を再アセンブルします。 System.Text.Json が処理できない複雑な POCO 構造の特殊なケースはごくわずかです。

WebApiClientGen はサーバー側と C# クライアント側の両方をサポートします。 C# クライアントの場合は、codegen 設定で「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. ザマリン
  3. マウイ島。 Xamarin Heroes から移行されました。
  4. オーレリア。統合テストスイートが含まれています。
  5. 反応してください。統合テストスイートが含まれています。
  6. ブレーザースタンドアロン

NewtonSoft.Json または System.Text.Json

ただし、WebApiClientGen は両方をサポートしていますが、2024 年以降、主なサポートは System.Text.Json に移行しています。

NewtonSoft.Json には、特定のシナリオやコンテキストに対していくつかの利点があります。

  1. 従来のアプリのサポート、または XML と JSON の両方のシリアル化のサポートのために、DataContractAttributes で修飾された POCO クラスが多数ある場合、NewtonSoft.Json は固有のサポートを提供しますが、System.Text.Json は .NET 7 以降、いくつかの面倒で間接的なサポートを提供します。
  2. 一部の配列型や動的では、NewtonSoft.Json の方がまだ優れています。
拡大する
追加情報
関連アプリ
おすすめ
関連情報 すべて