NClient
v0.13.0
NCLIENT: Client automatique de type .Net.Nclient est un client HTTP .NET Automatique et sa sécurité qui peut appeler les méthodes d'API Web à l'aide d'interfaces annotées. La principale différence entre Nclient et ses analogues est que NClient vous permet d'annoter les contrôleurs ASP.NET via des interfaces, puis d'utiliser ces interfaces pour créer des clients. Cela vous permet de vous débarrasser des dépendances indésirables d'un côté client et de réutiliser une description de l'API chez les clients sans code passe-partout.
// 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 ) ; Aimez-vous? Soutenez le développement de ce projet et jouez ce dépôt!
La création de clients pour les services Web peut être un défi car, en plus du transfert de données, vous devez implémenter la construction de requêtes, la sérialisation, les politiques de réessayer, la cartographie, la gestion des erreurs et la journalisation - sans parler de la maintenance qui vient avec chaque mise à jour de vos API. Et si vous pouviez créer des clients avec une fraction de l'effort? C'est exactement ce que NClient vise à réaliser en vous permettant de créer des clients de manière déclarative.
Soit dit en passant, vous pouvez contribuer au nclient, pas seulement l'utiliser?
Caractéristiques: routage dynamique des modèles; Routage statique; Paramètres de requête dynamique; Collections comme paramètres de requête; En-têtes dynamiques; En-têtes statiques; Corps dynamique; Sérialisation automatique et désérialisation; HTTP / Contexte de transport; Authentification; Demandes asynchrones; Délais d'attente; Demandes d'annulation; Politique de résilience; Validation de la réponse; Mappage de réponse; Téléchargement / téléchargement de fichiers; Interfaces génériques; Héritage de l'interface; Client Factory; Versioning; Manutention; Journalisation structurée; Support d'injection de dépendance.
Le moyen le plus simple est d'installer le package NClient à l'aide de NuGet:
dotnet add package NClient
L'utilisation de la bibliothèque NClient nécessite un standard .NET 2.0 ou plus. Les contrôleurs NClient peuvent être utilisés avec ASP.NET CORE et .NET CORE 3.1 cible ou supérieur.
Tout d'abord, vous devez créer une interface décrivant les points de terminaison et les données d'entrée / sortie disponibles d'un service via des annotations. Après cela, vous pouvez sélectionner le type de client requis dans NClientGallery , puis définir des paramètres supplémentaires pour cela si nécessaire.
Si vous souhaitez envoyer des demandes à un service tiers, vous devez créer une interface qui décrit le service auquel vous souhaitez faire des demandes. Suivez les étapes ci-dessous:
NClient dans le projet client 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
Cette commande générera une interface pour l'API à l'aide de la spécification OpenAPI (Swagger):
[ Path ( "api" ) ]
public interface IProductServiceClient
{
[ PostMethod ( "products" ) ]
Task < Product > CreateAsync ( Product product ) ;
[ GetMethod ( "products/{id}" ) ]
Task < Product > GetAsync ( [ RouteParam ] int id ) ;
} Si nécessaire, l'interface peut être modifiée. Il est facile de le faire car l'annotation d'interface est très similaire à l'annotation des contrôleurs dans ASP.NET. Le PathAttribute définit le chemin de base pour toutes les méthodes d'interface. Le PostMethodAttribute spécifie le type de méthode HTTP et le chemin du point de terminaison. De plus, les annotations implicites fonctionnent comme dans les contrôleurs ASP.NET; Par exemple, l'attribut BodyParamAttribute sera implicitement défini sur le paramètre du produit dans la méthode CreateAsync. Et certainement, les modèles d'itinéraire sont également pris en charge. Découvrez toutes les fonctionnalités des sections d'annotation et de routage.
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. Build ( ) ; La méthode GetRest crée un client REST avec System.Text.Json Serialization et sans politique de résilience.
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 ( ) ; Après avoir appelé la méthode For , vous pouvez configurer le client selon les besoins. Par exemple, vous pouvez remplacer le sérialiseur par Newtonsoft.Json , ajouter une stratégie de réessayer, etc. Voir la documentation complète.
// 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" ) ) ;Si vous souhaitez générer un client pour votre service Web ASP.NET, vous devez extraire une interface pour votre contrôleur et l'annoter avec des attributs NClient. Ces attributs sont très similaires à ceux utilisés pour les contrôleurs ASP.NET. Suivez les étapes ci-dessous:
NClient.AspNetCore à côté du serveur dotnet add package NClient.AspNetCore
public class WeatherForecastController : ControllerBase
{
public async Task < WeatherForecast > GetAsync ( DateTime date ) =>
new WeatherForecast ( date : date , temperatureC : - 25 ) ;
}Ne pas annoter votre contrôleur avec des attributs ASP.NET qui peuvent provoquer des conflits sémantiques avec les attributs NClient que vous avez l'intention d'utiliser. Cependant, d'autres attributs (y compris les vôtres) peuvent être utilisés sans restrictions.
[ 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 { .. . }L'annotation dans l'interface au lieu du contrôleur vous permet de placer l'interface dans un assemblage séparé. Par conséquent, le client utilisant cette interface ne dépend pas de l'application ASP.NET.
public interface IWeatherForecastClient : IWeatherForecastController { } Vous devez le faire si vous souhaitez que votre client ne contienne pas "Controller" dans le nom ou si vous souhaitez remplacer certaines méthodes pour le client (voir OverrideAttribute dans la section Annotation). Il n'est pas nécessaire de dupliquer les attributs d'interface, car ils sont hérités.
public void ConfigureServices ( IServiceCollection services )
{
.. .
services . AddNClientControllers ( ) ;
} La méthode AddNClientControllers peut être utilisée en combinaison avec la méthode AddControllers . Cela vous permet d'utiliser des contrôleurs ASP.NET standard avec des contrôleurs NClient dans la même application.
NClient sur côté client dotnet add package NClient
IWeatherForecastController client = NClientGallery . Clients . GetRest ( )
. For < IWeatherForecastController > ( host : "http://localhost:8080" )
. Build ( ) ; Si vous décidez de suivre la 4ème étape, utilisez l'interface IWeatherForecastClient au lieu de 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 ) ; Vous pouvez trouver une documentation NClient sur le wiki.
Voir les échantillons d'applications dans le projet NClient.Samples.
Vous songez à contribuer à Nclient? Super! Nous aimons recevoir des contributions de la communauté! La contribution la plus simple est de donner à ce projet une étoile.
Aider avec la documentation, les demandes de traction, les problèmes, les commentaires ou toute autre chose est également très bienvenu. Veuillez consulter notre guide de contribution.
Cela vaut la peine de nous contacter pour discuter des changements en cas de questions. Nous pouvons également donner des conseils sur la façon la plus simple de faire les choses.
Le NClient souhaite remercier JetBrains pour avoir soutenu le projet avec des licences GRATUITES Open Source Rider.
