NClient: automatic type-safe .NET HTTP client

🚀 Why use NClient?

Creating clients for web services can be quite a challenge because, in addition to data transfer, you need to implement query building, serialization, retry policies, mapping, error handling, and logging — not to mention the maintenance that comes with each update of your APIs. What if you could create clients with a fraction of the effort? This is exactly what NClient aims to achieve by allowing you to create clients declaratively.

💪 Advantages of NClient

• Integration with ASP.NET: Clients are available for all controllers out of the box.
• Generation of interfaces: Interfaces and DTOs are generated by the OpenAPI (Swagger) specification.
• Resilience: Resilience is provided by different strategies. There is Polly support.
• Serialization selection: Various serializers are available for use: System.Text.Json, Newtonsoft.JSON, System.XML, MessagePack, Protobuf, and your own.
• Auto validation of responses: Preset or custom validation of responses can be set.
• Auto mapping of responses: Native or your own models can be returned from the client instead of responses or DTOs.
• Extension using handlers: Handlers allow adding custom logic to the client parts.
• Extension using providers: The client functionality can be extended with native or your own providers.
• Easy error analysis: Your logger can be used in clients, and exceptions have all the required information for investigation.
• Easy to use with DI: Extension methods allow adding a client to a collection of services easily.
• Maximum flexibility: Any step of the request execution pipeline can be replaced with your own.
• [WIP] All types of applications: The library can be used on the backend (ASP.NET) and frontend (Blazor), and it is planned to support mobile/desktop (MAUI).
• [WIP] Various protocols: The REST protocol is provided as a ready-made solution, and it is planned to add GraphQL and RPC.

Features: Dynamic templated routing; Static routing; Dynamic query parameters; Collections as query parameters; Dynamic headers; Static headers; Dynamic body; Auto serialization and deserialization; HTTP/Transport context; Authentication; Asynchronous requests; Timeouts; Cancellation requests; Resilience policy; Response validation; Response mapping; File upload/download; Generic interfaces; Interface inheritance; Client factory; Versioning; Handling; Structured logging; Dependency injection support.

📖 Table of Contents

🏁 How to install?

🚧 Requirements

Use of the NClient library requires .NET Standard 2.0 or higher. The NClient controllers can be used with ASP.NET Core and .NET Core 3.1 target or higher.

👩🏼‍💻 How to use?

First, you have to create an interface describing the available endpoints and input/output data of a service via annotations. After that, you can select the required type of client in NClientGallery and then set additional settings for it if necessary.

Usage with third-party service

If you want to send requests to a third-party service, you should create an interface that describes the service you want to make requests to. Follow the steps below:

Step 1: Install NClient in the client project

dotnet add package NClient

Step 2: Install dotnet-nclient tool

dotnet tool install --global dotnet-nclient

Step 3: Generate the interface describing the API of the web service

dotnet nclient generate facade --api path/to/product-service-swagger.json --output MyProject/Client.cs

This command will generate an interface for the API using the OpenAPI (Swagger) specification:

[Path("api")]
public interface IProductServiceClient
{
    [PostMethod("products")]
    Task<Product> CreateAsync(Product product);

    [GetMethod("products/{id}")]
    Task<Product> GetAsync([RouteParam] int id);
}

Usage with ASP.NET Core

If you want to generate a client for your ASP.NET web service, you need to extract an interface for your controller and annotate it with NClient attributes. These attributes are very similar to those used for ASP.NET controllers. Follow the steps below:

Step 1: Install NClient.AspNetCore package on server-side

dotnet add package NClient.AspNetCore

Step 2: Create the controller

public class WeatherForecastController : ControllerBase
{
    public async Task<WeatherForecast> GetAsync(DateTime date) =>
        new WeatherForecast(date: date, temperatureC: -25);
}

Do not annotate your controller with ASP.NET attributes that may cause semantic conflicts with the NClient attributes you intend to use. However, other attributes (including your own) can be used without restrictions.

Step 3: Extract the interface for your controller and annotate it with NClient attributes

[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 { ... }

The annotation in the interface instead of the controller allows you to place the interface in a separate assembly. Consequently, the client using this interface doesn't depend on the ASP.NET application.

Step 4 (optional): Create the interface for the client

public interface IWeatherForecastClient : IWeatherForecastController { }

🗄 Documentation

👩🏼‍🏫 Samples of applications

❤️ Contributing

📦 NuGet Packages

Main