NClient
v0.13.0
NCLIENT: cliente automático de tipo .NET HTTPO NCLIENT é um cliente HTTP .NET automático e seguro de tipo que pode chamar métodos da API da Web usando interfaces anotadas. A principal diferença entre o NCLIENT e seus análogos é que o NCLient permite anotar os controladores ASP.NET por meio de interfaces e, em seguida, usar essas interfaces para criar clientes. Isso permite que você se livre de dependências indesejadas do lado do cliente e reutilize uma descrição da API em clientes sem código de caldeira.
// 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 ) ; Você gosta disso? Apoie o desenvolvimento deste projeto e estrela este repositório!
Criar clientes para serviços da Web pode ser um grande desafio porque, além da transferência de dados, você precisa implementar a construção de consultas, serialização, políticas de repetição, mapeamento, manipulação de erros e registro - sem mencionar a manutenção que vem com cada atualização das suas APIs. E se você pudesse criar clientes com uma fração do esforço? É exatamente isso que o NCLIENT pretende alcançar, permitindo que você crie clientes declarativamente.
A propósito, você pode contribuir para o NCLIENT, e não apenas usá -lo?
Recursos: roteamento modelado dinâmico; Roteamento estático; Parâmetros de consulta dinâmica; Coleções como parâmetros de consulta; Cabeçalhos dinâmicos; Cabeçalhos estáticos; Corpo dinâmico; Serialização e desserialização de automóveis; HTTP/contexto de transporte; Autenticação; Solicitações assíncronas; Tempos limite; Solicitações de cancelamento; Política de resiliência; Validação de resposta; Mapeamento de resposta; Upload/download de arquivo; Interfaces genéricas; Herança da interface; Fábrica cliente; Versão; Manuseio; Registro estruturado; Suporte à injeção de dependência.
A maneira mais fácil é instalar o pacote NCLient usando o NUGET:
dotnet add package NClient
O uso da biblioteca NCLient requer .NET Standard 2.0 ou superior. Os controladores NCLient podem ser usados com o alvo ASP.NET CORE e .NET CORE 3.1 ou superior.
Primeiro, você deve criar uma interface descrevendo os pontos de extremidade disponíveis e os dados de entrada/saída de um serviço por meio de anotações. Depois disso, você pode selecionar o tipo necessário de cliente no NClientGallery e definir configurações adicionais para ele, se necessário.
Se você deseja enviar solicitações para um serviço de terceiros, crie uma interface que descreva o serviço para o qual deseja fazer solicitações. Siga as etapas abaixo:
NClient no projeto do cliente 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
Este comando gerará uma interface para a API usando a especificação OpenApi (Swagger):
[ Path ( "api" ) ]
public interface IProductServiceClient
{
[ PostMethod ( "products" ) ]
Task < Product > CreateAsync ( Product product ) ;
[ GetMethod ( "products/{id}" ) ]
Task < Product > GetAsync ( [ RouteParam ] int id ) ;
} Se necessário, a interface pode ser alterada. É fácil fazer isso porque a anotação da interface é muito semelhante à anotação dos controladores no ASP.NET. O PathAttribute define o caminho base para todos os métodos de interface. O PostMethodAttribute especifica o tipo de método HTTP e o caminho para o terminal. Além disso, anotações implícitas funcionam como nos controladores ASP.NET; Por exemplo, o atributo BodyParamAttribute será definido implicitamente como o parâmetro do produto no método createasync. E certamente, modelos de rota também são suportados. Leia sobre todos os recursos nas seções de anotação e roteamento.
IProductServiceClient client = NClientGallery . Clients . GetRest ( )
. For < IProductServiceClient > ( host : "http://localhost:8080" )
. Build ( ) ; O método GetRest cria um cliente REST com System.Text.Json serialização e sem uma política de resiliência.
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 ( ) ; Depois de ligar para o método For , você pode configurar o cliente conforme necessário. Por exemplo, você pode substituir o serializador pelo Newtonsoft.Json , adicionar uma política de repetição e assim por diante. Veja a documentação completa.
// 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" ) ) ;Se você deseja gerar um cliente para o seu serviço Web ASP.NET, precisará extrair uma interface para o seu controlador e anotá -lo com atributos NCLient. Esses atributos são muito semelhantes aos usados para controladores ASP.NET. Siga as etapas abaixo:
NClient.AspNetCore no lado do servidor dotnet add package NClient.AspNetCore
public class WeatherForecastController : ControllerBase
{
public async Task < WeatherForecast > GetAsync ( DateTime date ) =>
new WeatherForecast ( date : date , temperatureC : - 25 ) ;
}Não anote seu controlador com os atributos ASP.NET que podem causar conflitos semânticos com os atributos NCLIENT que você pretende usar. No entanto, outros atributos (incluindo o seu) podem ser usados sem restrições.
[ 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 { .. . }A anotação na interface em vez do controlador permite que você coloque a interface em um conjunto separado. Consequentemente, o cliente que usa essa interface não depende do aplicativo ASP.NET.
public interface IWeatherForecastClient : IWeatherForecastController { } Você deve fazê -lo se desejar que seu tipo de cliente não conterá "controlador" no nome ou se deseja substituir alguns métodos para o cliente (consulte OverrideAttribute na seção de anotação). Não há necessidade de duplicar os atributos da interface, pois eles são herdados.
public void ConfigureServices ( IServiceCollection services )
{
.. .
services . AddNClientControllers ( ) ;
} O método AddNClientControllers pode ser usado em combinação com o método AddControllers . Isso permite que você use controladores ASP.NET padrão, juntamente com os controladores NCLient no mesmo aplicativo.
NClient no lado do cliente dotnet add package NClient
IWeatherForecastController client = NClientGallery . Clients . GetRest ( )
. For < IWeatherForecastController > ( host : "http://localhost:8080" )
. Build ( ) ; Se você decidir seguir a 4ª etapa, use a interface IWeatherForecastClient em vez do 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 ) ; Você pode encontrar documentação NCLIental no wiki.
Consulte Amostras de aplicações no projeto NCLIENT.SAMPLES.
Você está pensando em contribuir para o NCLIENT? Ótimo! Adoramos receber contribuições da comunidade! A contribuição mais simples é dar a este projeto uma estrela.
Ajudar na documentação, a retirar solicitações, problemas, comentários ou qualquer outra coisa também é muito bem -vindo. Por favor, revise nosso guia de contribuição.
Vale a pena entrar em contato conosco para discutir mudanças em caso de qualquer dúvida. Também podemos dar conselhos sobre a maneira mais fácil de fazer as coisas.
O NCLient deseja agradecer à JetBrains por apoiar o projeto com licenças gratuitas de pilotos de código aberto.
