PolicyHttpMessageHandler Class

Definition

Namespace:

Microsoft.Extensions.Http

Assembly:

Microsoft.Extensions.Http.Polly.dll

Package:

Microsoft.Extensions.Http.Polly v9.0.0-rc.2.24474.3

A DelegatingHandler implementation that executes request processing surrounded by a Policy.

public ref class PolicyHttpMessageHandler : System::Net::Http::DelegatingHandler

public class PolicyHttpMessageHandler : System.Net.Http.DelegatingHandler

type PolicyHttpMessageHandler = class
    inherit DelegatingHandler

Public Class PolicyHttpMessageHandler
Inherits DelegatingHandler

Inheritance

Object

HttpMessageHandler

DelegatingHandler

PolicyHttpMessageHandler

Remarks

This message handler implementation supports the use of policies provided by the Polly library for transient-fault-handling and resiliency.

The documentation provided here is focused guidance for using Polly together with the IHttpClientFactory. See the Polly project and its documentation for authoritative information on Polly.

The extension methods on PollyHttpClientBuilderExtensions are designed as a convenient and correct way to create a PolicyHttpMessageHandler.

The AddPolicyHandler(IHttpClientBuilder, IAsyncPolicy<HttpResponseMessage>) method supports the creation of a PolicyHttpMessageHandler for any kind of policy. This includes non-reactive policies, such as Timeout or Cache, which don't require the underlying request to fail first.

PolicyHttpMessageHandler and the PollyHttpClientBuilderExtensions convenience methods only accept the generic IAsyncPolicy`1. Generic policy instances can be created by using the generic methods on Policy such as TimeoutAsync``1(System.Int32).

To adapt an existing non-generic IAsyncPolicy, use code like the following:

policy.AsAsyncPolicy<HttpResponseMessage>()

The AddTransientHttpErrorPolicy(IHttpClientBuilder, Func<PolicyBuilder<HttpResponseMessage>,IAsyncPolicy<HttpResponseMessage>>) method is an opinionated convenience method that supports the application of a policy for requests that fail due to a connection failure or server error (5XX HTTP status code). This kind of method supports only reactive policies such as Retry, Circuit-Breaker or Fallback. This method is only provided for convenience; we recommend creating your own policies as needed if this does not meet your requirements.

Take care when using policies such as Retry or Timeout together, as HttpClient provides its own timeout via Timeout. When combining Retry and Timeout, Timeout will act as a timeout across all tries; a Polly Timeout policy can be configured after a Retry policy in the configuration sequence, to provide a timeout-per-try.

All policies provided by Polly are designed to be efficient when used in a long-lived way. Certain policies such as the Bulkhead and Circuit-Breaker maintain state and should be scoped across calls you wish to share the Bulkhead or Circuit-Breaker state. Take care to ensure the correct lifetimes when using policies and message handlers together in custom scenarios. The extension methods provided by PollyHttpClientBuilderExtensions are designed to assign a long lifetime to policies and ensure that they can be used when the handler rotation feature is active.

The PolicyHttpMessageHandler will attach a context to the HttpRequestMessage prior to executing a Policy, if one does not already exist. The Context will be provided to the policy for use inside the Policy and in other message handlers.

Constructors

PolicyHttpMessageHandler(Func<HttpRequestMessage,IAsyncPolicy<HttpResponseMessage>>)	Creates a new PolicyHttpMessageHandler.
PolicyHttpMessageHandler(IAsyncPolicy<HttpResponseMessage>)	Creates a new PolicyHttpMessageHandler.

Properties

InnerHandler

Gets or sets the inner handler which processes the HTTP response messages. (Inherited from DelegatingHandler)

Methods

Dispose()	Releases the unmanaged resources and disposes of the managed resources used by the HttpMessageHandler. (Inherited from HttpMessageHandler)
Dispose(Boolean)	Releases the unmanaged resources used by the DelegatingHandler, and optionally disposes of the managed resources. (Inherited from DelegatingHandler)
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
Send(HttpRequestMessage, CancellationToken)	Sends an HTTP request to the inner handler to send to the server. (Inherited from DelegatingHandler)
SendAsync(HttpRequestMessage, CancellationToken)	Sends an HTTP request to the inner handler to send to the server as an asynchronous operation.
SendCoreAsync(HttpRequestMessage, Context, CancellationToken)	Called inside the execution of the Policy to perform request processing.
ToString()	Returns a string that represents the current object. (Inherited from Object)