NClient
v0.13.0
Nclient: klien http. NET http otomatisNClient adalah klien .NET HTTP. Perbedaan utama antara NClient dan analognya adalah bahwa NClient memungkinkan Anda memberi anotasi pengontrol ASP.NET melalui antarmuka dan kemudian menggunakan antarmuka ini untuk membuat klien. Ini memungkinkan Anda menyingkirkan dependensi yang tidak diinginkan di sisi klien dan menggunakan kembali deskripsi API pada klien tanpa kode boilerplate.
// 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 ) ; Apakah kamu menyukainya? Dukung pengembangan proyek ini dan membintangi repo ini!
Membuat klien untuk layanan web dapat menjadi tantangan yang cukup karena, selain transfer data, Anda perlu menerapkan pembangunan kueri, serialisasi, coba lagi kebijakan, pemetaan, penanganan kesalahan, dan pencatatan - belum lagi pemeliharaan yang datang dengan setiap pembaruan API Anda. Bagaimana jika Anda dapat membuat klien dengan sedikit upaya? Inilah yang ingin dicapai oleh NClient dengan memungkinkan Anda membuat klien secara deklaratif.
Ngomong -ngomong, Anda dapat berkontribusi pada NClient, tidak hanya menggunakannya?
Fitur: routing templated dinamis; Routing statis; Parameter kueri dinamis; Koleksi sebagai parameter kueri; Header dinamis; Header statis; Tubuh dinamis; Serialisasi dan deserialisasi otomatis; Konteks http/transportasi; Otentikasi; Permintaan asinkron; Batas waktu; Permintaan pembatalan; Kebijakan ketahanan; Validasi respons; Pemetaan respons; Unggahan/unduhan file; Antarmuka generik; Warisan antarmuka; Pabrik klien; Versi; Penanganan; Logging terstruktur; Dukungan Injeksi Ketergantungan.
Cara termudah adalah dengan menginstal Paket NClient menggunakan Nuget:
dotnet add package NClient
Penggunaan pustaka NClient membutuhkan .NET Standar 2.0 atau lebih tinggi. Pengontrol NClient dapat digunakan dengan ASP.NET Core dan .NET Core 3.1 target atau lebih tinggi.
Pertama, Anda harus membuat antarmuka yang menggambarkan titik akhir yang tersedia dan data input/output suatu layanan melalui anotasi. Setelah itu, Anda dapat memilih jenis klien yang diperlukan di NClientGallery dan kemudian mengatur pengaturan tambahan untuk itu jika perlu.
Jika Anda ingin mengirim permintaan ke layanan pihak ketiga, Anda harus membuat antarmuka yang menjelaskan layanan yang ingin Anda buat. Ikuti langkah -langkah di bawah ini:
NClient di Proyek Klien dotnet add package NClient
dotnet-nclient Tool dotnet tool install --global dotnet-nclient
dotnet nclient generate facade --api path/to/product-service-swagger.json --output MyProject/Client.cs
Perintah ini akan menghasilkan antarmuka untuk API menggunakan spesifikasi OpenAPI (Swagger):
[ Path ( "api" ) ]
public interface IProductServiceClient
{
[ PostMethod ( "products" ) ]
Task < Product > CreateAsync ( Product product ) ;
[ GetMethod ( "products/{id}" ) ]
Task < Product > GetAsync ( [ RouteParam ] int id ) ;
} Jika perlu, antarmuka dapat diubah. Sangat mudah untuk melakukan ini karena anotasi antarmuka sangat mirip dengan anotasi pengontrol di ASP.NET. PathAttribute mendefinisikan jalur dasar untuk semua metode antarmuka. PostMethodAttribute menentukan jenis metode HTTP dan jalur ke titik akhir. Selain itu, anotasi implisit berfungsi seperti pada pengontrol ASP.NET; Misalnya, atribut BodyParamAttribute akan secara implisit diatur ke parameter produk dalam metode CreateAsync. Dan tentu saja, templat rute juga didukung. Baca tentang semua fitur di bagian anotasi dan perutean.
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. Build ( ) ; Metode GetRest menciptakan klien REST dengan serialisasi System.Text.Json dan tanpa kebijakan ketahanan.
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 ( ) ; Setelah menelepon metode For , Anda dapat mengonfigurasi klien sesuai kebutuhan. Misalnya, Anda dapat mengganti serializer dengan Newtonsoft.Json , menambahkan kebijakan coba lagi, dan sebagainya. Lihat dokumentasi lengkapnya.
// 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" ) ) ;Jika Anda ingin menghasilkan klien untuk layanan web ASP.NET Anda, Anda perlu mengekstrak antarmuka untuk pengontrol Anda dan memberi anotasi dengan atribut NClient. Atribut ini sangat mirip dengan yang digunakan untuk pengontrol ASP.NET. Ikuti langkah -langkah di bawah ini:
NClient.AspNetCore di sisi server dotnet add package NClient.AspNetCore
public class WeatherForecastController : ControllerBase
{
public async Task < WeatherForecast > GetAsync ( DateTime date ) =>
new WeatherForecast ( date : date , temperatureC : - 25 ) ;
}Jangan anotasi pengontrol Anda dengan atribut ASP.NET yang dapat menyebabkan konflik semantik dengan atribut NClient yang ingin Anda gunakan. Namun, atribut lain (termasuk milik Anda) dapat digunakan tanpa batasan.
[ 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 { .. . }Anotasi di antarmuka alih -alih pengontrol memungkinkan Anda untuk menempatkan antarmuka dalam perakitan terpisah. Akibatnya, klien yang menggunakan antarmuka ini tidak tergantung pada aplikasi ASP.NET.
public interface IWeatherForecastClient : IWeatherForecastController { } Anda harus melakukannya jika Anda ingin jenis klien Anda tidak mengandung "pengontrol" dalam nama atau jika Anda ingin mengganti beberapa metode untuk klien (lihat OverrideAttribute di bagian anotasi). Tidak perlu menduplikasi atribut antarmuka, karena diwarisi.
public void ConfigureServices ( IServiceCollection services )
{
.. .
services . AddNClientControllers ( ) ;
} Metode AddNClientControllers dapat digunakan dalam kombinasi dengan metode AddControllers . Ini memungkinkan Anda untuk menggunakan pengontrol ASP.NET standar bersama dengan pengontrol NClient dalam aplikasi yang sama.
NClient di sisi klien dotnet add package NClient
IWeatherForecastController client = NClientGallery . Clients . GetRest ( )
. For < IWeatherForecastController > ( host : "http://localhost:8080" )
. Build ( ) ; Jika Anda memutuskan untuk mengikuti langkah ke -4, gunakan antarmuka IWeatherForecastClient alih -alih IWeatherForecastController .
// 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 ) ; Anda dapat menemukan dokumentasi NClient di wiki.
Lihat sampel aplikasi dalam proyek NClient.Samples.
Anda sedang berpikir untuk berkontribusi pada NClient? Besar! Kami senang menerima kontribusi dari komunitas! Kontribusi paling sederhana adalah memberi proyek ini bintang.
Membantu dokumentasi, permintaan tarik, masalah, komentar atau apa pun juga sangat disambut. Harap tinjau panduan kontribusi kami.
Layak untuk menghubungi kami untuk membahas perubahan jika ada pertanyaan. Kami juga dapat memberikan nasihat tentang cara termudah untuk melakukan sesuatu.
NClient ingin mengucapkan terima kasih kepada JetBrains karena telah mendukung proyek dengan lisensi pengendara open source gratis.
