Initiate HTTP requests

By Glenn Condron, Ryan Nowak, and Steve Gordon

An IHttpClientFactory can be registered and used to configure and create HttpClient instances in an app. It offers the following benefits:

  • Provides a central location for naming and configuring logical HttpClient instances. For example, a “github” client can be registered and configured to access GitHub. A default client can be registered for other purposes.
  • Codifies the concept of outgoing middleware via delegating handlers in HttpClient and provides extensions for Polly-based middleware to take advantage of that.
  • Manages the pooling and lifetime of underlying HttpClientMessageHandler instances to avoid common DNS problems that occur when manually managing HttpClient lifetimes.
  • Adds a configurable logging experience (via ILogger) for all requests sent through clients created by the factory.

Consumption patterns

There are several ways IHttpClientFactory can be used in an app:

None of them are strictly superior to another. The best approach depends upon the app’s constraints.

Basic usage

The IHttpClientFactory can be registered by calling the AddHttpClient extension method on the IServiceCollection, inside the ConfigureServices method in Startup.cs.


Once registered, code can accept an IHttpClientFactory anywhere services can be injected with dependency injection (DI). The IHttpClientFactory can be used to create a HttpClient instance:

public class BasicUsageModel : PageModel

    private readonly IHttpClientFactory _clientFactory;

    public IEnumerable<GitHubBranch> Branches  get; private set; 

    public bool GetBranchesError  get; private set; 

    public BasicUsageModel(IHttpClientFactory clientFactory)
        _clientFactory = clientFactory;

    public async Task OnGet()
        var request = new HttpRequestMessage(HttpMethod.Get, "");
        request.Headers.Add("Accept", "application/vnd.github.v3+json");
        request.Headers.Add("User-Agent", "HttpClientFactory-Sample");

        var client = _clientFactory.CreateClient();

        var response = await client.SendAsync(request);

        if (response.IsSuccessStatusCode)
            Branches = await response.Content.ReadAsAsync<IEnumerable<GitHubBranch>>();
            GetBranchesError = true;
            Branches = Array.Empty<GitHubBranch>();

Using IHttpClientFactory in this fashion is a great way to refactor an existing app. It has no impact on the way HttpClient is used. In places where HttpClient instances are currently created, replace those occurrences with a call to CreateClient.

Named clients

If an app requires multiple distinct uses of HttpClient, each with a different configuration, an option is to use named clients. Configuration for a named HttpClient can be specified during registration in ConfigureServices.

services.AddHttpClient("github", c =>

    c.BaseAddress = new Uri("");
    c.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json"); // Github API versioning
    c.DefaultRequestHeaders.Add("User-Agent", "HttpClientFactory-Sample"); // Github requires a user-agent

In the preceding code, AddHttpClient is called, providing the name “github”. This client has some default configuration applied—namely the base address and two headers required to work with the GitHub API.

Each time CreateClient is called, a new instance of HttpClient is created and the configuration action is called.

To consume a named client, a string parameter can be passed to CreateClient. Specify the name of the client to be created:

public class NamedClientModel : PageModel

    private readonly IHttpClientFactory _clientFactory;

    public IEnumerable<GitHubPullRequest> PullRequests  get; private set; 

    public bool GetPullRequestsError  get; private set; 

    public bool HasPullRequests => PullRequests.Any();

    public NamedClientModel(IHttpClientFactory clientFactory)
        _clientFactory = clientFactory;

    public async Task OnGet()
        var request = new HttpRequestMessage(HttpMethod.Get, "repos/aspnet/docs/pulls");

        var client = _clientFactory.CreateClient("github");

        var response = await client.SendAsync(request);

        if (response.IsSuccessStatusCode)
            PullRequests = await response.Content.ReadAsAsync<IEnumerable<GitHubPullRequest>>();
            GetPullRequestsError = true;
            PullRequests = Array.Empty<GitHubPullRequest>();

In the preceding code, the request doesn’t need to specify a hostname. It can pass just the path, since the base address configured for the client is used.

Typed clients

Typed clients provide the same capabilities as named clients without the need to use strings as keys. The typed client approach provides IntelliSense and compiler help when consuming clients. They provide a single location to configure and interact with a particular HttpClient. For example, a single typed client might be used for a single backend endpoint and encapsulate all logic dealing with that endpoint. Another advantage is that they work with DI and can be injected where required in your app.

A typed client accepts a HttpClient parameter in its constructor:

public class GitHubService

    public HttpClient Client  get; 

    public GitHubService(HttpClient client)
        client.BaseAddress = new Uri("");
        client.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json"); // GitHub API versioning
        client.DefaultRequestHeaders.Add("User-Agent", "HttpClientFactory-Sample"); // GitHub requires a user-agent

        Client = client;

    public async Task<IEnumerable<GitHubIssue>> GetAspNetDocsIssues()
        var response = await Client.GetAsync("/repos/aspnet/docs/issues?state=open&sort=created&direction=desc");


        var result = await response.Content.ReadAsAsync<IEnumerable<GitHubIssue>>();

        return result;

In the preceding code, the configuration is moved into the typed client. The HttpClient object is exposed as a public property. It’s possible to define API-specific methods that expose HttpClient functionality. The GetAspNetDocsIssues method encapsulates the code needed to query for and parse out the latest open issues from a GitHub repository.

To register a typed client, the generic AddHttpClient extension method can be used within ConfigureServices, specifying the typed client class:


The typed client is registered as transient with DI. The typed client can be injected and consumed directly:

public class TypedClientModel : PageModel

    private readonly GitHubService _gitHubService;

    public IEnumerable<GitHubIssue> LatestIssues  get; private set; 

    public bool HasIssue => LatestIssues.Any();

    public bool GetIssuesError  get; private set; 

    public TypedClientModel(GitHubService gitHubService)
        _gitHubService = gitHubService;

    public async Task OnGet()
            LatestIssues = await _gitHubService.GetAspNetDocsIssues();
            GetIssuesError = true;
            LatestIssues = Array.Empty<GitHubIssue>();

If preferred, the configuration for a typed client can be specified during registration in ConfigureServices, rather than in the typed client’s constructor:

services.AddHttpClient<RepoService>(c =>

    c.BaseAddress = new Uri("");
    c.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
    c.DefaultRequestHeaders.Add("User-Agent", "HttpClientFactory-Sample");

It’s possible to entirely encapsulate the HttpClient within a typed client. Rather than exposing it as a property, public methods can be provided which call the HttpClient instance internally.

public class RepoService

    private readonly HttpClient _httpClient; // not exposed publicly

    public RepoService(HttpClient client)
        _httpClient = client;

    public async Task<IEnumerable<string>> GetRepos()
        var response = await _httpClient.GetAsync("aspnet/repos");


        var result = await response.Content.ReadAsAsync<IEnumerable<string>>();

        return result;

In the preceding code, the HttpClient is stored as a private field. All access to make external calls goes through the GetRepos method.

Generated clients

IHttpClientFactory can be used in combination with other third-party libraries such as Refit. Refit is a REST library for .NET. It converts REST APIs into live interfaces. An implementation of the interface is generated dynamically by the RestService, using HttpClient to make the external HTTP calls.

An interface and a reply are defined to represent the external API and its response:

public interface IHelloClient

    Task<Reply> GetMessageAsync();

public class Reply

    public string Message  get; set; 

A typed client can be added, using Refit to generate the implementation:

public void ConfigureServices(IServiceCollection services)

    services.AddHttpClient("hello", c =>
        c.BaseAddress = new Uri("http://localhost:5000");
    .AddTypedClient(c => Refit.RestService.For<IHelloClient>(c));


The defined interface can be consumed where necessary, with the implementation provided by DI and Refit:

public class ValuesController : ControllerBase

    private readonly IHelloClient _client;

    public ValuesController(IHelloClient client)
        _client = client;

    public async Task<ActionResult<Reply>> Index()
        return await _client.GetMessageAsync();

Outgoing request middleware

HttpClient already has the concept of delegating handlers that can be linked together for outgoing HTTP requests. The IHttpClientFactory makes it easy to define the handlers to apply for each named client. It supports registration and chaining of multiple handlers to build an outgoing request middleware pipeline. Each of these handlers is able to perform work before and after the outgoing request. This pattern is similar to the inbound middleware pipeline in ASP.NET Core. The pattern provides a mechanism to manage cross-cutting concerns around HTTP requests, including caching, error handling, serialization, and logging.

To create a handler, define a class deriving from DelegatingHandler. Override the SendAsync method to execute code before passing the request to the next handler in the pipeline:

public class ValidateHeaderHandler : DelegatingHandler

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request,
        CancellationToken cancellationToken)
        if (!request.Headers.Contains("X-API-KEY"))
            return new HttpResponseMessage(HttpStatusCode.BadRequest)
                Content = new StringContent("You must supply an API key header called X-API-KEY")

        return await base.SendAsync(request, cancellationToken);

The preceding code defines a basic handler. It checks to see if an X-API-KEY header has been included on the request. If the header is missing, it can avoid the HTTP call and return a suitable response.

During registration, one or more handlers can be added to the configuration for a HttpClient. This task is accomplished via extension methods on the IHttpClientBuilder.


services.AddHttpClient("externalservice", c =>

    c.BaseAddress = new Uri("https://localhost:5000/"); // assume this is an "external" service which requires an API KEY

In the preceding code, the ValidateHeaderHandler is registered with DI. The handler must be registered in DI as transient. Once registered, AddHttpMessageHandler can be called, passing in the type for the handler.

Multiple handlers can be registered in the order that they should execute. Each handler wraps the next handler until the final HttpClientHandler executes the request:


    // This handler is on the outside and called first during the request, last during the response.
    // This handler is on the inside, closest to the request being sent.

Use Polly-based handlers

IHttpClientFactory integrates with a popular third-party library called Polly. Polly is a comprehensive resilience and transient fault-handling library for .NET. It allows developers to express policies such as Retry, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback in a fluent and thread-safe manner.

Extension methods are provided to enable the use of Polly policies with configured HttpClient instances. The Polly extensions are available in a NuGet package called ‘Microsoft.Extensions.Http.Polly’. This package is not included by default by the ‘Microsoft.AspNetCore.App‘ metapackage. To use the extensions, a PackageReference should be explicitly included in the project.

<Project Sdk="Microsoft.NET.Sdk.Web">


    <PackageReference Include="Microsoft.AspNetCore.App" Version="2.1.0-rc1-final" />
    <PackageReference Include="Microsoft.Extensions.Http.Polly" Version="2.1.0-rc1-final" />
    <PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="2.1.0-rc1-final" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.1.0-rc1-final" />


After restoring this package, extension methods are available to support adding Polly-based handlers to clients.

Handle transient faults

The most common faults you may expect to occur when making external HTTP calls will be transient. A convenient extension method called AddTransientHttpErrorPolicy is included which allows a policy to be defined to handle transient errors. Policies configured with this extension method handle HttpRequestException, HTTP 5xx responses, and HTTP 408 responses.

The AddTransientHttpErrorPolicy extension can be used within ConfigureServices. The extension provides access to a PolicyBuilder object configured to handle errors representing a possible transient fault:

    .AddTransientHttpErrorPolicy(p => p.WaitAndRetryAsync(3, _ => TimeSpan.FromMilliseconds(600)));

In the preceding code, a WaitAndRetryAsync policy is defined. Failed requests are retried up to three times with a delay of 600 ms between attempts.

Dynamically select policies

Additional extension methods exist which can be used to add Polly-based handlers. One such extension is AddPolicyHandler, which has multiple overloads. One overload allows the request to be inspected when defining which policy to apply:

var timeout = Policy.TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(10));
var longTimeout = Policy.TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(30));

// Run some code to select a policy based on the request
    .AddPolicyHandler(request => request.Method == HttpMethod.Get ? timeout : longTimeout);

In the preceding code, if the outgoing request is a GET, a 10-second timeout is applied. For any other HTTP method, a 30-second timeout is used.

Add multiple Polly handlers

It is common to nest Polly policies to provide enhanced functionality:

    .AddTransientHttpErrorPolicy(p => p.RetryAsync(3))
    .AddTransientHttpErrorPolicy(p => p.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30)));

In the preceding example, two handlers are added. The first uses the AddTransientHttpErrorPolicy extension to add a retry policy. Failed requests are retried up to three times. The second call to AddTransientHttpErrorPolicy adds a circuit breaker policy. Further external requests are blocked for 30 seconds if five failed attempts occur sequentially. Circuit breaker policies are stateful. All calls through this client share the same circuit state.

Add policies from the Polly registry

An approach to managing regularly used policies is to define them once and register them with a PolicyRegistry. An extension method is provided which allows a handler to be added using a policy from the registry:

var registry = services.AddPolicyRegistry();

registry.Add("regular", timeout);
registry.Add("long", longTimeout);


In the preceding code, a PolicyRegistry is added to the ServiceCollection and two policies are registered with it. In order to use a policy from the registry, the AddPolicyHandlerFromRegistry method is used, passing the name of the policy to apply.

Further information about IHttpClientFactory and Polly integrations can be found on the Polly wiki.

HttpClient and lifetime management

Each time CreateClient is called on the IHttpClientFactory, a new instance of a HttpClient is returned. There will be a HttpMessageHandler per named client. IHttpClientFactory will pool the HttpMessageHandler instances created by the factory to reduce resource consumption. A HttpMessageHandler instance