NClient
v0.13.0
nclient：自动类型安全.NET HTTP客户端NClient是一种自动，类型的SAFE .NET HTTP客户端，可以使用带注释的接口调用Web API方法。 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 Core和.NET Core 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属性将被隐式设置为CreateSync方法中的乘积参数。当然，还支持路线模板。阅读注释和路由部分中的所有功能。
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方法后，您可以根据需要配置客户端。例如，您可以用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 ) ;
}请勿使用ASP.NET属性注释控制器，这些属性可能会引起与您打算使用的NClient属性的语义冲突。但是，可以无限制地使用其他属性（包括您自己的）。
[ 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 ( ) ;如果您决定遵循第四步，请使用IWeatherForecastClient接口而不是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 ) ; 您可以在Wiki上找到Nclient文档。
请参阅nclient中的应用程序样本。
您正在考虑为Nclient做出贡献吗？伟大的！我们喜欢从社区获得贡献！最简单的贡献是使该项目成为明星。
也非常欢迎帮助文档，提取请求，问题，评论或其他任何内容。请查看我们的贡献指南。
值得与我们联系以讨论任何问题的变化。我们还可以就最简单的做事方式提供建议。
Nclient希望感谢JetBrains通过免费的开源骑手许可证为该项目提供支持。
