{"id":37045252,"url":"https://github.com/nclient/nclient","last_synced_at":"2026-01-14T05:13:54.652Z","repository":{"id":42023916,"uuid":"346124957","full_name":"nclient/NClient","owner":"nclient","description":":dizzy: NClient is an automatic type-safe .Net HTTP client that allows you to call web service API methods using annotated interfaces or controllers without boilerplate code.","archived":false,"fork":false,"pushed_at":"2024-08-29T19:32:54.000Z","size":3299,"stargazers_count":51,"open_issues_count":29,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-12-02T05:01:50.128Z","etag":null,"topics":["api","api-client","asp-net","asp-net-core","c-sharp","client","dotnet","good-first-issue","http-client","rest","rest-client","web-api"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nclient.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-09T19:44:58.000Z","updated_at":"2025-10-26T11:56:26.000Z","dependencies_parsed_at":"2023-01-31T23:01:09.865Z","dependency_job_id":null,"html_url":"https://github.com/nclient/NClient","commit_stats":null,"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"purl":"pkg:github/nclient/NClient","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nclient%2FNClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nclient%2FNClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nclient%2FNClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nclient%2FNClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nclient","download_url":"https://codeload.github.com/nclient/NClient/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nclient%2FNClient/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28410336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","asp-net","asp-net-core","c-sharp","client","dotnet","good-first-issue","http-client","rest","rest-client","web-api"],"created_at":"2026-01-14T05:13:53.940Z","updated_at":"2026-01-14T05:13:54.643Z","avatar_url":"https://github.com/nclient.png","language":"C#","readme":"# \u003cimg src=\"logo.png\" width=\"50\" height=\"50\" align=\"left\" alt=\"logo\"\u003eNClient: automatic type-safe .NET HTTP client\n\n[![Nuget](https://img.shields.io/nuget/v/NClient)](https://www.nuget.org/packages/NClient/)\n[![Nuget (with prereleases)](https://img.shields.io/nuget/vpre/NClient?label=nuget-pre)](https://www.nuget.org/packages/NClient/)\n[![Nuget](https://img.shields.io/nuget/dt/NClient)](https://www.nuget.org/packages/NClient/)\n[![GitHub last commit](https://img.shields.io/github/last-commit/nclient/NClient)](https://github.com/nclient/NClient/branches)\n[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/nclient/NClient/Test:%20Full)](https://github.com/nclient/NClient/actions)\n[![Documentation](https://img.shields.io/badge/doc-wiki-brightgreen)](https://github.com/nclient/NClient/wiki)\n[![GitHub](https://img.shields.io/github/license/nclient/NClient)](https://github.com/nclient/NClient/blob/main/LICENSE)  \n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=nclient_NClient\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=nclient_NClient)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=nclient_NClient\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=nclient_NClient)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=nclient_NClient\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=nclient_NClient)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=nclient_NClient\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=nclient_NClient)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=nclient_NClient\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=nclient_NClient)\n\nNClient is an automatic, type-safe .NET HTTP client that can call web API methods using annotated interfaces.\nThe main difference between NClient and its analogues is that NClient lets you annotate ASP.NET controllers via interfaces and then use these interfaces to create clients.\nThis allows you get rid of unwanted dependencies on a client side and to reuse an API description in clients without boilerplate code. \n\n```C#\n// WebService.dll:\npublic class WeatherController : ControllerBase, IWeatherFacade {\n    public Task\u003cWeather\u003e GetAsync(string city, DateTime date) =\u003e ...;\n}\n\n// WebService.Facade.dll:\n[HttpFacade, Path(\"api/[facade]\")] \npublic interface IWeatherFacade {\n    [GetMethod(\"{city}\")] \n    Task\u003cWeather\u003e GetAsync([RouteParam] string city, [QueryParam] DateTime date);\n}\n\n// Client.dll:\nIWeatherFacade weatherFacade = NClientGallery.Clients.GetRest()\n    .For\u003cIWeatherFacade\u003e(host: \"http://localhost:5000\")\n    .WithSafeResilience(maxRetries: 3)\n    .Build();\nWeather todaysWeather = await weatherFacade.GetAsync(city: \"Chelyabinsk\", date: DateTime.Today);\n```\n## ⭐ Give us a star\nDo you like it? Support the development of this project and star this repo!\n\n\u003ca name=\"why\" /\u003e  \n\n## 🚀 Why use NClient?\nCreating 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.\n\nBy the way, you can [contribute](#contributing) to the NClient, not just use it :smiley:\n\n\u003ca name=\"advantages\" /\u003e\n\n## 💪 Advantages of NClient\n- **Integration with ASP.NET:** Clients are available for all controllers out of the box.\n- **Generation of interfaces:** Interfaces and DTOs are generated by the OpenAPI (Swagger) specification.\n- **Resilience:** Resilience is provided by different strategies. There is Polly support.\n- **Serialization selection:** Various serializers are available for use: System.Text.Json, Newtonsoft.JSON, System.XML, MessagePack, Protobuf, and your own.\n- **Auto validation of responses:** Preset or custom validation of responses can be set.\n- **Auto mapping of responses:** Native or your own models can be returned from the client instead of responses or DTOs.\n- **Extension using handlers:** Handlers allow adding custom logic to the client parts.\n- **Extension using providers:** The client functionality can be extended with native or your own providers.\n- **Easy error analysis:** Your logger can be used in clients, and exceptions have all the required information for investigation.\n- **Easy to use with DI:** Extension methods allow adding a client to a collection of services easily.\n- **Maximum flexibility:** Any step of the request execution pipeline can be replaced with your own.\n- **[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).\n- **[WIP] Various protocols:** The REST protocol is provided as a ready-made solution, and it is planned to add GraphQL and RPC.\n\n**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.\n\n## 📖 Table of Contents\n- [How to install?](#install)\n- [Requirements](#requirements)\n- [How to use?](#usage)\n  - [Usage with third-party service](#usage-non-aspnet)\n  - [Usage with ASP.NET Core](#usage-aspnet)\n- [Documentation](#documentation)\n- [Samples of applications](#sample-applications)\n- [Contributing](#contributing)\n- [NuGet Packages](#nuget)\n\n\u003ca name=\"install\" /\u003e  \n\n## 🏁 How to install?\nThe easiest way is to install [NClient package](https://www.nuget.org/packages/NClient) using Nuget:\n```\ndotnet add package NClient\n```\n\n\u003ca name=\"requirements\" /\u003e\n\n## 🚧 Requirements\nUse 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.\n\n\u003ca name=\"usage\" /\u003e  \n\n## 👩🏼‍💻 How to use?\nFirst, 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.\n\n\u003ca name=\"usage-non-aspnet\" /\u003e\n\n### Usage with third-party service\nIf 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:\n#### Step 1: Install `NClient` in the client project\n```\ndotnet add package NClient\n```\n#### Step 2: Install `dotnet-nclient` tool\n```\ndotnet tool install --global dotnet-nclient\n```\n#### Step 3: Generate the interface describing the API of the web service\n```\ndotnet nclient generate facade --api path/to/product-service-swagger.json --output MyProject/Client.cs\n```\nThis command will generate an interface for the API using the OpenAPI (Swagger) specification:\n```C#\n[Path(\"api\")]\npublic interface IProductServiceClient\n{\n    [PostMethod(\"products\")]\n    Task\u003cProduct\u003e CreateAsync(Product product);\n    \n    [GetMethod(\"products/{id}\")]\n    Task\u003cProduct\u003e GetAsync([RouteParam] int id);\n}\n```\nIf necessary, the interface can be changed. It is easy to do this because interface annotation is very similar to the annotation of controllers in ASP.NET. The `PathAttribute` defines the base path for all interface methods. The `PostMethodAttribute` specifies the type of HTTP method and the path to the endpoint.\nMoreover, implicit annotations work as in ASP.NET controllers; for example, the `BodyParamAttribute` attribute will be implicitly set to the product parameter in the CreateAsync method. And certainly, route templates are also supported.\nRead about all the features in the [Annotation](https://github.com/nclient/NClient/wiki/Annotation) and [Routing](https://github.com/nclient/NClient/wiki/Routing) sections.\n#### Step 4: Create the client\n```C#\nIProductServiceClient client = NClientGallery.Clients.GetRest()\n    .For\u003cIProductServiceClient\u003e(host: \"http://localhost:8080\")\n    .Build();\n```\nThe `GetRest` method creates a REST client with `System.Text.Json` serialization and without a resilience policy.\n#### Step 5 (optional): Configure the client\n```C#\nIProductServiceClient client = NClientGallery.Clients.GetRest()\n    .For\u003cIProductServiceClient\u003e(host: \"http://localhost:8080\")\n    .WithNewtonsoftJsonSerialization()\n    .WithResilience(x =\u003e x\n        .ForMethod(client =\u003e (Func\u003cProduct, Task\u003cProduct\u003e\u003e) client.CreateAsync)\n        .Use(maxRetries: 2, attempt =\u003e TimeSpan.FromSeconds(Math.Pow(2, attempt))))\n    ...\n    .Build();\n```\nAfter calling the `For` method, you can configure the client as needed. For example, you can replace the serializer with `Newtonsoft.Json`, add a retry policy, and so on. See the full [documentation](https://github.com/nclient/NClient/wiki).\n#### Step 6: Send an http request\n```C#\n// Equivalent to the following request: \n// curl -X POST -H \"Content-type: application/json\" --data \"{ id: 1 }\" http://localhost:8080/api/products\nProduct product = await client.CreateAsync(new Product(name: \"MyProduct\"));\n```\n\n\u003ca name=\"usage-aspnet\" /\u003e\n\n### Usage with ASP.NET Core\nIf 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:\n#### Step 1: Install `NClient.AspNetCore` package on server-side\n```\ndotnet add package NClient.AspNetCore\n```\n#### Step 2: Create the controller\n```C#\npublic class WeatherForecastController : ControllerBase\n{\n    public async Task\u003cWeatherForecast\u003e GetAsync(DateTime date) =\u003e\n        new WeatherForecast(date: date, temperatureC: -25);\n}\n```\nDo not annotate your controller with ASP.NET attributes that may cause semantic conflicts with the NClient attributes you intend to use. \nHowever, other attributes (including your own) can be used without restrictions.\n#### Step 3: Extract the interface for your controller and annotate it with NClient attributes\n```C#\n[HttpFacade, Path(\"[controller]\")]                                // equivalent to [ApiController, Route(\"[controller]\")]\npublic interface IWeatherForecastController\n{\n    [GetMethod]                                                   // equivalent to [HttpGet]\n    Task\u003cWeatherForecast\u003e GetAsync([QueryParam] DateTime date);   // equivalent to [FromQuery]\n}\n\npublic class WeatherForecastController : ControllerBase, IWeatherForecastController { ... }\n```\nThe annotation in the interface instead of the controller allows you to place the interface in a separate assembly. \nConsequently, the client using this interface doesn't depend on the ASP.NET application.\n#### Step 4 (optional): Create the interface for the client\n```C#\npublic interface IWeatherForecastClient : IWeatherForecastController { }\n```\nYou should do it if you want your client type not to contain \"Controller\" in the name or if you want to override some methods for the client (see `OverrideAttribute` in [Annotation](https://github.com/nclient/NClient/wiki/Annotation#override) section). \nThere is no need to duplicate interface attributes, as they are inherited.\n#### Step 5: Add NClient controllers to ServiceCollection in Startup.cs\n```C#\npublic void ConfigureServices(IServiceCollection services)\n{\n    ...\n    services.AddNClientControllers();\n}\n```\nThe `AddNClientControllers` method can be used in combination with the `AddControllers` method. This allows you to use standard ASP.NET controllers together with NClient controllers in the same application.\n#### Step 6: Install `NClient` package on client-side\n```\ndotnet add package NClient\n```\n#### Step 7: Create the client\n```C#\nIWeatherForecastController client = NClientGallery.Clients.GetRest()\n    .For\u003cIWeatherForecastController\u003e(host: \"http://localhost:8080\")\n    .Build();\n```\nIf you decide to follow the 4th step, use the `IWeatherForecastClient` interface instead of `IWeatherForecastController`.\n#### Step 8: Send an http request\n```C#\n// Equivalent to the following request: \n// curl -X GET -H \"Content-type: application/json\" http://localhost:8080/WeatherForecast?date=2021-03-13T00:15Z\nWeatherForecast forecast = await client.GetAsync(DateTime.Now);\n```\n\n\u003ca name=\"documentation\" /\u003e  \n\n## 🗄 Documentation\nYou can find NClient documentation on the [Wiki](https://github.com/nclient/NClient/wiki).\n\n\u003ca name=\"sample-applications\" /\u003e  \n\n## 👩🏼‍🏫 Samples of applications\nSee samples of applications in the [NClient.Samples](https://github.com/nclient/NClient.Samples) project.\n\n\u003ca name=\"contributing\" /\u003e  \n\n## ❤️ Contributing\nYou’re thinking about contributing to NClient? Great! We love to receive contributions from the community! The simplest contribution is to give this project a star ⭐.  \nHelping with documentation, pull requests, issues, commentary or anything else is also very welcome. Please review our [contribution guide](CONTRIBUTING.md).  \nIt's worth getting in touch with us to discuss changes in case of any questions. We can also give advice on the easiest way to do things.\n\n\u003ca name=\"nuget\" /\u003e  \n\n## 📦 NuGet Packages\n\n### Main\n- [NClient](https://www.nuget.org/packages/NClient): Package for creating clients from interfaces including third-party.\n- [NClient.Standalone](https://www.nuget.org/packages/NClient.Standalone): The same as NClient package, but without third-party.\n- [NClient.AspNetCore](https://www.nuget.org/packages/NClient.AspNetCore): Allows you to annotate controllers via interfaces.\n- [NClient.Abstractions](https://www.nuget.org/packages/NClient.Abstractions): Abstractions for clients and providers.\n- [NClient.Annotations](https://www.nuget.org/packages/NClient.Annotations): Attributes for annotation of clients and controllers interfaces.\n\n### Extensions\n- [NClient.Extensions.DependencyInjection](https://www.nuget.org/packages/NClient.Extensions.DependencyInjection): Extension methods for registration of clients in ServiceCollection.\n\n### Tools\n- [dotnet-nclient](https://www.nuget.org/packages/dotnet-nclient): The tool for generating interfaces and DTO's by the OpenAPI (Swagger) specification.\n\n### Providers\n- [NClient.Providers.Api.Rest](https://www.nuget.org/packages/NClient.Providers.Api.Rest): The provider that allows you to create clients for the REST API.\n- [NClient.Providers.Transport.SystemNetHttp](https://www.nuget.org/packages/NClient.Providers.Transport.SystemNetHttp): The provider that allows you to transport messages using System.Net.Http.\n- [NClient.Providers.Transport.RestSharp](https://www.nuget.org/packages/NClient.Providers.Transport.RestSharp): The provider that allows you to transport messages using RestSharp.\n- [NClient.Providers.Serialization.SystemTextJson](https://www.nuget.org/packages/NClient.Providers.Serialization.SystemTextJson): The provider that allows you to use the System.Text.Json serializer.\n- [NClient.Providers.Serialization.NewtonsoftJson](https://www.nuget.org/packages/NClient.Providers.Serialization.NewtonsoftJson): The provider that allows you to use the Newtonsoft.Json serializer.\n- [NClient.Providers.Serialization.SysteTmXml](https://www.nuget.org/packages/NClient.Providers.Serialization.SystemXml): The provider that allows you to use the System.Xml.XmlSerializer serializer.\n- [NClient.Providers.Serialization.MessagePack](https://www.nuget.org/packages/NClient.Providers.Serialization.MessagePack): The provider that allows you to use the MessagePackCSharp serializer.\n- [NClient.Providers.Serialization.ProtobufNet](https://www.nuget.org/packages/NClient.Providers.Serialization.ProtobufNet): The provider that allows you to use the ProtobufNet serializer.\n- [NClient.Providers.Resilience.Polly](https://www.nuget.org/packages/NClient.Providers.Resilience.Polly): The provider that allows you to implement resilience policies using the Polly library.\n- [NClient.Providers.Mapping.HttpResponses](https://www.nuget.org/packages/NClient.Providers.Mapping.HttpResponses): The provider that allows you to return native HTTP responses.\n- [NClient.Providers.Mapping.LanguageExt](https://www.nuget.org/packages/NClient.Providers.Mapping.LanguageExt): The provider that allows you to return the LanguageExt of a monad as responses.\n\n## Acknowledgements\n\u003ca link=\"https://www.jetbrains.com\"\u003e\u003cimg src=\"jetbrains.png\" style=\"width:150px\" align=\"left\" alt=\"logo\"\u003e\u003c/a\u003e\u003c/br\u003e  \nThe NClient wishes to thank [JetBrains](https://www.jetbrains.com) for supporting the project with free open source Rider licenses.  \n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnclient%2Fnclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnclient%2Fnclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnclient%2Fnclient/lists"}