NClient
v0.13.0
nclient：自動タイプセーフ.NET HTTPクライアントNclientは、注釈付きインターフェイスを使用してWeb APIメソッドを呼び出すことができる自動、タイプセーフ.NET HTTPクライアントです。 NCLIENTとその類似体の主な違いは、NCLIENTを使用すると、インターフェイスを介してASP.NETコントローラーに注釈を付け、これらのインターフェイスを使用してクライアントを作成できることです。これにより、クライアント側の不要な依存関係を取り除き、ボイラープレートコードなしでクライアントのAPI説明を再利用できます。
// WebService.dll:
public class WeatherController : ControllerBase , IWeatherFacade {
public Task < Weather > GetAsync ( string city , DateTime date ) => .. . ;
}
// WebService.Facade.dll:
[ HttpFacade , Path ( "api/[facade]" ) ]
public interface IWeatherFacade {
[ GetMethod ( "{city}" ) ]
Task < Weather > GetAsync ( [ RouteParam ] string city , [ QueryParam ] DateTime date ) ;
}
// Client.dll:
IWeatherFacade weatherFacade = NClientGallery . Clients . GetRest ( )
. For < IWeatherFacade > ( host : "http://localhost:5000" )
. WithSafeResilience ( maxRetries : 3 )
. Build ( ) ;
Weather todaysWeather = await weatherFacade . GetAsync ( city : "Chelyabinsk" , date : DateTime . Today ) ; あなたはそれが好きですか？このプロジェクトの開発をサポートし、このレポを主演してください！
Webサービスのクライアントの作成は、データ転送に加えて、クエリビルディング、シリアル化、再試行ポリシー、マッピング、エラー処理、ロギングを実装する必要があるため、非常に困難です。APIの各更新に伴うメンテナンスは言うまでもありません。努力のほんの一部でクライアントを作成できるとしたらどうでしょうか？これは、NCLIENTがクライアントを宣言的に作成できるようにすることにより、まさに達成することを目指しているものです。
ちなみに、あなたはそれを使用するだけでなく、nclientに貢献することができますか？
機能：動的テンプレートルーティング。静的ルーティング;動的クエリパラメーター。クエリパラメーターとしてのコレクション。動的ヘッダー。静的ヘッダー。ダイナミックボディ;自動シリアル化と脱派化; HTTP/輸送コンテキスト。認証;非同期リクエスト;タイムアウト;キャンセルリクエスト。レジリエンスポリシー。応答検証。応答マッピング;ファイルアップロード/ダウンロード;一般的なインターフェイス。インターフェイス継承;クライアント工場;バージョン化;取り扱い;構造化されたロギング;依存関係噴射サポート。
最も簡単な方法は、nugetを使用してnclientパッケージをインストールすることです。
dotnet add package NClient
nclientライブラリの使用には、.NET標準2.0以上が必要です。 NCLIENTコントローラーは、ASP.NETコアおよび.NETコア3.1ターゲット以上で使用できます。
まず、注釈を介してサービスの使用可能なエンドポイントと入力/出力データを説明するインターフェイスを作成する必要があります。その後、 NClientGalleryで必要なタイプのクライアントを選択し、必要に応じて追加の設定を設定できます。
リクエストをサードパーティサービスに送信する場合は、リクエストを行うサービスを説明するインターフェイスを作成する必要があります。以下の手順に従ってください。
NClientをインストールします dotnet add package NClient
dotnet-nclientツールをインストールします dotnet tool install --global dotnet-nclient
dotnet nclient generate facade --api path/to/product-service-swagger.json --output MyProject/Client.cs
このコマンドは、OpenAPI（Swagger）仕様を使用してAPIのインターフェイスを生成します。
[ Path ( "api" ) ]
public interface IProductServiceClient
{
[ PostMethod ( "products" ) ]
Task < Product > CreateAsync ( Product product ) ;
[ GetMethod ( "products/{id}" ) ]
Task < Product > GetAsync ( [ RouteParam ] int id ) ;
}必要に応じて、インターフェイスを変更できます。インターフェイスアノテーションはASP.NETのコントローラーの注釈と非常に似ているため、これを行うのは簡単です。 PathAttribute 、すべてのインターフェイスメソッドのベースパスを定義します。 PostMethodAttribute 、HTTPメソッドのタイプとエンドポイントへのパスを指定します。さらに、ASP.NETコントローラーのように、暗黙の注釈が機能します。たとえば、 BodyParamAttribute属性は、createasyncメソッドの製品パラメーターに暗黙的に設定されます。そして確かに、ルートテンプレートもサポートされています。注釈とルーティングセクションのすべての機能について読んでください。
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. Build ( ) ; GetRestメソッドは、 System.Text.Jsonのシリアル化を備えたRESTクライアントを作成し、回復力ポリシーを作成します。
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. WithNewtonsoftJsonSerialization ( )
. WithResilience ( x => x
. ForMethod ( client => ( Func < Product , Task < Product > > ) client . CreateAsync )
. Use ( maxRetries : 2 , attempt => TimeSpan . FromSeconds ( Math . Pow ( 2 , attempt ) ) ) )
.. .
. Build ( ) ; For Methodを呼び出した後、必要に応じてクライアントを構成できます。たとえば、SerializerをNewtonsoft.Jsonに置き換えたり、再試行ポリシーを追加したりできます。完全なドキュメントを参照してください。
// Equivalent to the following request:
// curl -X POST -H "Content-type: application/json" --data "{ id: 1 }" http://localhost:8080/api/products
Product product = await client . CreateAsync ( new Product ( name : "MyProduct" ) ) ;ASP.NET Webサービスのクライアントを生成する場合は、コントローラーのインターフェイスを抽出し、nclient属性で注釈を付ける必要があります。これらの属性は、ASP.NETコントローラーに使用される属性と非常に似ています。以下の手順に従ってください。
NClient.AspNetCoreパッケージをインストールします dotnet add package NClient.AspNetCore
public class WeatherForecastController : ControllerBase
{
public async Task < WeatherForecast > GetAsync ( DateTime date ) =>
new WeatherForecast ( date : date , temperatureC : - 25 ) ;
}使用する予定のnclient属性とセマンティックな競合を引き起こす可能性のあるASP.NET属性をコントローラーに注釈しないでください。ただし、他の属性（独自の属性を含む）は、制限なしに使用できます。
[ HttpFacade , Path ( "[controller]" ) ] // equivalent to [ApiController, Route("[controller]")]
public interface IWeatherForecastController
{
[ GetMethod ] // equivalent to [HttpGet]
Task < WeatherForecast > GetAsync ( [ QueryParam ] DateTime date ) ; // equivalent to [FromQuery]
}
public class WeatherForecastController : ControllerBase , IWeatherForecastController { .. . }コントローラーの代わりにインターフェイス内の注釈を使用すると、インターフェイスを別のアセンブリに配置できます。したがって、このインターフェイスを使用しているクライアントは、ASP.NETアプリケーションに依存しません。
public interface IWeatherForecastClient : IWeatherForecastController { }クライアントタイプが名前に「コントローラー」を含めないようにしたい場合、またはクライアントのメソッドをオーバーライドする場合は、それを行う必要があります（注釈セクションのOverrideAttributeを参照）。インターフェイス属性は継承されているため、複製する必要はありません。
public void ConfigureServices ( IServiceCollection services )
{
.. .
services . AddNClientControllers ( ) ;
} AddNClientControllersメソッドは、 AddControllersメソッドと組み合わせて使用できます。これにより、同じアプリケーションで標準のASP.NETコントローラーとNCLIENTコントローラーを使用できます。
NClientパッケージをインストールします dotnet add package NClient
IWeatherForecastController client = NClientGallery . Clients . GetRest ( )
. For < IWeatherForecastController > ( host : "http://localhost:8080" )
. Build ( ) ; 4番目のステップに従うことにした場合は、 IWeatherForecastControllerの代わりにIWeatherForecastClientインターフェイスを使用します。
// Equivalent to the following request:
// curl -X GET -H "Content-type: application/json" http://localhost:8080/WeatherForecast?date=2021-03-13T00:15Z
WeatherForecast forecast = await client . GetAsync ( DateTime . Now ) ; wikiでnclientドキュメントを見つけることができます。
nclient.samplesプロジェクトのアプリケーションのサンプルを参照してください。
あなたはnclientに貢献することを考えていますか？素晴らしい！私たちはコミュニティから貢献を受けるのが大好きです！最も簡単な貢献は、このプロジェクトにスターを与えることです。
ドキュメント、リクエスト、問題、解説などを手伝うことも大歓迎です。寄付ガイドを確認してください。
質問がある場合に変更を議論するために、私たちと連絡を取る価値があります。また、物事を行う最も簡単な方法についてアドバイスをすることもできます。
Nclientは、無料のオープンソースライダーライセンスでプロジェクトをサポートしてくれたJetbrainsに感謝したいと考えています。
