NClient
v0.13.0
NCLIENT: Automatischer Typ-Safe .NET-HTTP-ClientNCLIENT ist ein automatischer HTTP-Client vom Typ Typ-Safe .NET, mit dem Web-API-Methoden mit kommentierten Schnittstellen aufrufen können. Der Hauptunterschied zwischen NClient und seinen Analoga besteht darin, dass Sie mit NCLIENT ASP.NET -Controller über Schnittstellen kommentieren und diese Schnittstellen dann verwenden, um Clients zu erstellen. Auf diese Weise können Sie unerwünschte Abhängigkeiten auf einer Kundenseite beseitigen und eine API -Beschreibung in Clients ohne Boilerplate -Code wiederverwenden.
// 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 ) ; Magst du es? Unterstützen Sie die Entwicklung dieses Projekts und spielen Sie dieses Repo!
Das Erstellen von Clients für Webdienste kann eine ziemliche Herausforderung sein, da Sie neben der Datenübertragung Abfrageberaufungen, Serialisierung, Wiederholung von Richtlinien, Zuordnung, Fehlerbehandlung und Protokollierung implementieren müssen - ganz zu schweigen von der Wartung, die mit jeder Aktualisierung Ihrer APIs geliefert wird. Was wäre, wenn Sie Kunden mit einem Bruchteil der Anstrengung erstellen könnten? Genau das zielt NCLIENT an, indem Sie es Ihnen ermöglichen, Kunden deklarativ zu erstellen.
Übrigens können Sie zum NClient beitragen, nicht nur verwenden?
Merkmale: Dynamisches Vorlagen -Routing; Statisches Routing; Dynamische Abfrageparameter; Sammlungen als Abfrageparameter; Dynamische Header; Statische Header; Dynamischer Körper; Autoserialisierung und Deserialisierung; HTTP/Transportkontext; Authentifizierung; Asynchrone Anfragen; Zeitüberschreitungen; Stornierungsanfragen; Resilienzpolitik; Antwortvalidierung; Antwortzuordnung; Datei Upload/Download; Generische Schnittstellen; Schnittstellenvererbung; Kundenfabrik; Versioning; Handhabung; Strukturierte Protokollierung; Abhängigkeitsinjektionsunterstützung.
Der einfachste Weg ist die Installation des NCLIENT -Pakets mit Nuget:
dotnet add package NClient
Die Verwendung der NClient -Bibliothek erfordert .NET Standard 2.0 oder höher. Die NCLient -Controller können mit ASP.NET CORE und .NET CORE 3.1 -Ziel oder höher verwendet werden.
Zunächst müssen Sie eine Schnittstelle erstellen, die die verfügbaren Endpunkte und Eingabe-/Ausgabedaten eines Dienstes über Annotationen beschreibt. Danach können Sie den erforderlichen Clienttyp in NClientGallery auswählen und dann bei Bedarf zusätzliche Einstellungen dafür festlegen.
Wenn Sie Anfragen an einen Drittanbieterdienst senden möchten, sollten Sie eine Schnittstelle erstellen, die den Dienst beschreibt, an den Sie Anfragen stellen möchten. Befolgen Sie die folgenden Schritte:
NClient im Client -Projekt 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
Dieser Befehl generiert eine Schnittstelle für die API unter Verwendung der Spezifikation von OpenAPI (Swagger):
[ Path ( "api" ) ]
public interface IProductServiceClient
{
[ PostMethod ( "products" ) ]
Task < Product > CreateAsync ( Product product ) ;
[ GetMethod ( "products/{id}" ) ]
Task < Product > GetAsync ( [ RouteParam ] int id ) ;
} Bei Bedarf kann die Schnittstelle geändert werden. Dies ist einfach, da die Annotation der Schnittstelle der Annotation von Controllern in ASP.NET sehr ähnlich ist. Das PathAttribute definiert den Basispfad für alle Schnittstellenmethoden. Die PostMethodAttribute gibt den Typ der HTTP -Methode und den Pfad zum Endpunkt an. Darüber hinaus funktionieren implizite Anmerkungen wie bei ASP.NET -Controllern. Beispielsweise wird das BodyParamAttribute -Attribut implizit auf den Produktparameter in der Createasync -Methode eingestellt. Und sicherlich werden auch Routenvorlagen unterstützt. Lesen Sie über alle Funktionen in den Annotations- und Routing -Abschnitten.
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. Build ( ) ; Die GetRest -Methode erstellt einen REST -Client mit System.Text.Json Serialisierung und ohne Resilienzpolitik.
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 ( ) ; Nach dem Aufrufen der For können Sie den Client nach Bedarf konfigurieren. Zum Beispiel können Sie den Serializer durch Newtonsoft.Json ersetzen, eine Wiederholungsrichtlinie hinzufügen und so weiter. Siehe die vollständige Dokumentation.
// 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" ) ) ;Wenn Sie einen Client für Ihren ASP.NET -Webdienst generieren möchten, müssen Sie eine Schnittstelle für Ihren Controller extrahieren und mit NCLient -Attributen kommentieren. Diese Attribute sind denen für ASP.NET -Controller sehr ähnlich. Befolgen Sie die folgenden Schritte:
NClient.AspNetCore -Paket auf der Serverseite dotnet add package NClient.AspNetCore
public class WeatherForecastController : ControllerBase
{
public async Task < WeatherForecast > GetAsync ( DateTime date ) =>
new WeatherForecast ( date : date , temperatureC : - 25 ) ;
}Kennzeichnen Sie Ihren Controller nicht mit ASP.NET -Attributen, die semantische Konflikte mit den von Ihnen beabsichtigten NCLient -Attributen verursachen können. Andere Attribute (einschließlich Ihrer) können jedoch ohne Einschränkungen verwendet werden.
[ 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 { .. . }Mit der Annotation in der Schnittstelle anstelle des Controllers können Sie die Schnittstelle in einer separaten Baugruppe platzieren. Infolgedessen hängt der Client, der diese Schnittstelle verwendet, nicht von der ASP.NET -Anwendung ab.
public interface IWeatherForecastClient : IWeatherForecastController { } Sie sollten dies tun, wenn Sie möchten, dass Ihr Client -Typ im Namen keinen "Controller" enthalten oder wenn Sie einige Methoden für den Client überschreiben möchten (siehe OverrideAttribute im Annotationsabschnitt). Es besteht keine Notwendigkeit, Schnittstellenattribute zu duplizieren, wie sie vererbt werden.
public void ConfigureServices ( IServiceCollection services )
{
.. .
services . AddNClientControllers ( ) ;
} Die AddNClientControllers -Methode kann in Kombination mit der AddControllers -Methode verwendet werden. Auf diese Weise können Sie Standard -ASP.NET -Controller zusammen mit NCLient -Controllern in derselben Anwendung verwenden.
NClient Paket auf clientseitig dotnet add package NClient
IWeatherForecastController client = NClientGallery . Clients . GetRest ( )
. For < IWeatherForecastController > ( host : "http://localhost:8080" )
. Build ( ) ; Wenn Sie sich für den 4. Schritt entscheiden, verwenden Sie die IWeatherForecastClient -Schnittstelle anstelle von 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 ) ; Sie können eine NCLIP -Dokumentation zum Wiki finden.
Siehe Proben von Anwendungen im NCLIENT.Sampules -Projekt.
Sie denken darüber nach, zu NClient beizutragen? Großartig! Wir lieben es, Beiträge von der Community zu erhalten! Der einfachste Beitrag besteht darin, diesem Projekt einen Stern zu geben.
Auch bei der Dokumentation, bei der Dokumentation, den Anfragen, Problemen, dem Kommentar oder allem anderen ist sehr willkommen. Bitte überprüfen Sie unseren Beitragsleitfaden.
Es lohnt sich, mit uns in Kontakt zu treten, um Änderungen bei Fragen zu besprechen. Wir können auch Ratschläge geben, um Dinge zu tun.
Der NcLient möchte JetBrains für die Unterstützung des Projekts mit kostenlosen Open -Source -Fahrerlizenzen danken.
