Microsoft.Extensions.Http.Polly.xml
|
<?xml version="1.0"?>
<doc> <assembly> <name>Microsoft.Extensions.Http.Polly</name> </assembly> <members> <member name="T:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions"> <summary> Extensions methods for configuring <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> message handlers as part of and <see cref="T:System.Net.Http.HttpClient"/> message handler pipeline. </summary> </member> <member name="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddPolicyHandler(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage})"> <summary> Adds a <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> which will surround request execution with the provided <see cref="T:Polly.IAsyncPolicy`1"/>. </summary> <param name="builder">The <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/>.</param> <param name="policy">The <see cref="T:Polly.IAsyncPolicy`1"/>.</param> <returns>An <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/> that can be used to configure the client.</returns> <remarks> <para> See the remarks on <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> for guidance on configuring policies. </para> </remarks> </member> <member name="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddPolicyHandler(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,System.Func{System.Net.Http.HttpRequestMessage,Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage}})"> <summary> Adds a <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> which will surround request execution with a policy returned by the <paramref name="policySelector"/>. </summary> <param name="builder">The <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/>.</param> <param name="policySelector"> Selects an <see cref="T:Polly.IAsyncPolicy`1"/> to apply to the current request. </param> <returns>An <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/> that can be used to configure the client.</returns> <remarks> <para> See the remarks on <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> for guidance on configuring policies. </para> </remarks> </member> <member name="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddPolicyHandler(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,System.Func{System.IServiceProvider,System.Net.Http.HttpRequestMessage,Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage}})"> <summary> Adds a <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> which will surround request execution with a policy returned by the <paramref name="policySelector"/>. </summary> <param name="builder">The <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/>.</param> <param name="policySelector"> Selects an <see cref="T:Polly.IAsyncPolicy`1"/> to apply to the current request. </param> <returns>An <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/> that can be used to configure the client.</returns> <remarks> <para> See the remarks on <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> for guidance on configuring policies. </para> </remarks> </member> <member name="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddPolicyHandlerFromRegistry(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,System.String)"> <summary> Adds a <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> which will surround request execution with a policy returned by the <see cref="T:Polly.Registry.IReadOnlyPolicyRegistry`1"/>. </summary> <param name="builder">The <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/>.</param> <param name="policyKey"> The key used to resolve a policy from the <see cref="T:Polly.Registry.IReadOnlyPolicyRegistry`1"/>. </param> <returns>An <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/> that can be used to configure the client.</returns> <remarks> <para> See the remarks on <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> for guidance on configuring policies. </para> </remarks> </member> <member name="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddPolicyHandlerFromRegistry(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,System.Func{Polly.Registry.IReadOnlyPolicyRegistry{System.String},System.Net.Http.HttpRequestMessage,Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage}})"> <summary> Adds a <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> which will surround request execution with a policy returned by the <see cref="T:Polly.Registry.IReadOnlyPolicyRegistry`1"/>. </summary> <param name="builder">The <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/>.</param> <param name="policySelector"> Selects an <see cref="T:Polly.IAsyncPolicy`1"/> to apply to the current request. </param> <returns>An <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/> that can be used to configure the client.</returns> <remarks> <para> See the remarks on <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> for guidance on configuring policies. </para> </remarks> </member> <member name="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddTransientHttpErrorPolicy(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,System.Func{Polly.PolicyBuilder{System.Net.Http.HttpResponseMessage},Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage}})"> <summary> Adds a <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> which will surround request execution with a <see cref="T:Polly.Policy"/> created by executing the provided configuration delegate. The policy builder will be preconfigured to trigger application of the policy for requests that fail with conditions that indicate a transient failure. </summary> <param name="builder">The <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/>.</param> <param name="configurePolicy">A delegate used to create a <see cref="T:Polly.IAsyncPolicy`1"/>.</param> <returns>An <see cref="T:Microsoft.Extensions.DependencyInjection.IHttpClientBuilder"/> that can be used to configure the client.</returns> <remarks> <para> See the remarks on <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> for guidance on configuring policies. </para> <para> The <see cref="T:Polly.PolicyBuilder`1"/> provided to <paramref name="configurePolicy"/> has been preconfigured errors to handle errors in the following categories: <list type="bullet"> <item><description>Network failures (as <see cref="T:System.Net.Http.HttpRequestException"/>)</description></item> <item><description>HTTP 5XX status codes (server errors)</description></item> <item><description>HTTP 408 status code (request timeout)</description></item> </list> </para> <para> The policy created by <paramref name="configurePolicy"/> will be cached indefinitely per named client. Policies are generally designed to act as singletons, and can be shared when appropriate. To share a policy across multiple named clients, first create the policy and then pass it to multiple calls to <see cref="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddPolicyHandler(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage})"/> as desired. </para> </remarks> </member> <member name="T:Microsoft.Extensions.DependencyInjection.PollyServiceCollectionExtensions"> <summary> Provides convenience extension methods to register <see cref="T:Polly.Registry.IPolicyRegistry`1"/> and <see cref="T:Polly.Registry.IReadOnlyPolicyRegistry`1"/> in the service collection. </summary> </member> <member name="M:Microsoft.Extensions.DependencyInjection.PollyServiceCollectionExtensions.AddPolicyRegistry(Microsoft.Extensions.DependencyInjection.IServiceCollection)"> <summary> Registers an empty <see cref="T:Polly.Registry.PolicyRegistry"/> in the service collection with service types <see cref="T:Polly.Registry.IPolicyRegistry`1"/>, and <see cref="T:Polly.Registry.IReadOnlyPolicyRegistry`1"/> and returns the newly created registry. </summary> <param name="services">The <see cref="T:Microsoft.Extensions.DependencyInjection.IServiceCollection"/>.</param> <returns>The newly created <see cref="T:Polly.Registry.PolicyRegistry"/>.</returns> </member> <member name="M:Microsoft.Extensions.DependencyInjection.PollyServiceCollectionExtensions.AddPolicyRegistry(Microsoft.Extensions.DependencyInjection.IServiceCollection,Polly.Registry.IPolicyRegistry{System.String})"> <summary> Registers the provided <see cref="T:Polly.Registry.IPolicyRegistry`1"/> in the service collection with service types <see cref="T:Polly.Registry.IPolicyRegistry`1"/>, and <see cref="T:Polly.Registry.IReadOnlyPolicyRegistry`1"/> and returns the provided registry. </summary> <param name="services">The <see cref="T:Microsoft.Extensions.DependencyInjection.IServiceCollection"/>.</param> <param name="registry">The <see cref="T:Polly.Registry.IPolicyRegistry`1"/>.</param> <returns>The provided <see cref="T:Polly.Registry.IPolicyRegistry`1"/>.</returns> </member> <member name="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"> <summary> A <see cref="T:System.Net.Http.DelegatingHandler"/> implementation that executes request processing surrounded by a <see cref="T:Polly.Policy"/>. </summary> <remarks> <para> This message handler implementation supports the use of policies provided by the Polly library for transient-fault-handling and resiliency. </para> <para> The documentation provided here is focused guidance for using Polly together with the <see cref="T:System.Net.Http.IHttpClientFactory"/>. See the Polly project and its documentation (https://github.com/app-vnext/Polly) for authoritative information on Polly. </para> <para> The extension methods on <see cref="T:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions"/> are designed as a convenient and correct way to create a <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/>. </para> <para> The <see cref="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddPolicyHandler(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage})"/> method supports the creation of a <see cref="T:Microsoft.Extensions.Http.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. </para> <para> <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> and the <see cref="T:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions"/> convenience methods only accept the generic <see cref="T:Polly.IAsyncPolicy`1"/>. Generic policy instances can be created by using the generic methods on <see cref="T:Polly.Policy"/> such as <see cref="M:Polly.Policy.TimeoutAsync``1(System.Int32)"/>. </para> <para> To adapt an existing non-generic <see cref="T:Polly.IAsyncPolicy"/>, use code like the following: <example> Converting a non-generic <code>IAsyncPolicy policy</code> to <see cref="T:Polly.IAsyncPolicy`1"/>. <code> policy.AsAsyncPolicy<HttpResponseMessage>() </code> </example> </para> <para> The <see cref="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddTransientHttpErrorPolicy(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,System.Func{Polly.PolicyBuilder{System.Net.Http.HttpResponseMessage},Polly.IAsyncPolicy{System.Net.Http.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. </para> <para> Take care when using policies such as Retry or Timeout together as HttpClient provides its own timeout via <see cref="P:System.Net.Http.HttpClient.Timeout"/>. When combining Retry and Timeout, <see cref="P:System.Net.Http.HttpClient.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. </para> <para> 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 <see cref="T:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions"/> are designed to assign a long lifetime to policies and ensure that they can be used when the handler rotation feature is active. </para> <para> The <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> will attach a context to the <see cref="T:System.Net.Http.HttpRequestMessage"/> prior to executing a <see cref="T:Polly.Policy"/>, if one does not already exist. The <see cref="T:Polly.Context"/> will be provided to the policy for use inside the <see cref="T:Polly.Policy"/> and in other message handlers. </para> </remarks> </member> <member name="M:Microsoft.Extensions.Http.PolicyHttpMessageHandler.#ctor(Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage})"> <summary> Creates a new <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/>. </summary> <param name="policy">The policy.</param> </member> <member name="M:Microsoft.Extensions.Http.PolicyHttpMessageHandler.#ctor(System.Func{System.Net.Http.HttpRequestMessage,Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage}})"> <summary> Creates a new <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/>. </summary> <param name="policySelector">A function which can select the desired policy for a given <see cref="T:System.Net.Http.HttpRequestMessage"/>.</param> </member> <member name="M:Microsoft.Extensions.Http.PolicyHttpMessageHandler.SendAsync(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)"> <inheritdoc /> </member> <member name="M:Microsoft.Extensions.Http.PolicyHttpMessageHandler.SendCoreAsync(System.Net.Http.HttpRequestMessage,Polly.Context,System.Threading.CancellationToken)"> <summary> Called inside the execution of the <see cref="T:Polly.Policy"/> to perform request processing. </summary> <param name="request">The <see cref="T:System.Net.Http.HttpRequestMessage"/>.</param> <param name="context">The <see cref="T:Polly.Context"/>.</param> <param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken"/>.</param> <returns>Returns a <see cref="T:System.Threading.Tasks.Task`1"/> that will yield a response when completed.</returns> </member> <member name="P:Microsoft.Extensions.Http.Resources.PolicyHttpMessageHandler_PolicySelector_ReturnedNull"> <summary> The '{0}' function must return a non-null policy instance. To create a policy that takes no action, use '{1}'. </summary> </member> <member name="M:Microsoft.Extensions.Http.Resources.FormatPolicyHttpMessageHandler_PolicySelector_ReturnedNull(System.Object,System.Object)"> <summary> The '{0}' function must return a non-null policy instance. To create a policy that takes no action, use '{1}'. </summary> </member> <member name="T:Polly.HttpRequestMessageExtensions"> <summary> Extension methods for <see cref="T:System.Net.Http.HttpRequestMessage"/> Polly integration. </summary> </member> <member name="M:Polly.HttpRequestMessageExtensions.GetPolicyExecutionContext(System.Net.Http.HttpRequestMessage)"> <summary> Gets the <see cref="T:Polly.Context"/> associated with the provided <see cref="T:System.Net.Http.HttpRequestMessage"/>. </summary> <param name="request">The <see cref="T:System.Net.Http.HttpRequestMessage"/>.</param> <returns>The <see cref="T:Polly.Context"/> if set, otherwise <c>null</c>.</returns> <remarks> The <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> will attach a context to the <see cref="T:System.Net.Http.HttpResponseMessage"/> prior to executing a <see cref="T:Polly.Policy"/>, if one does not already exist. The <see cref="T:Polly.Context"/> will be provided to the policy for use inside the <see cref="T:Polly.Policy"/> and in other message handlers. </remarks> </member> <member name="M:Polly.HttpRequestMessageExtensions.SetPolicyExecutionContext(System.Net.Http.HttpRequestMessage,Polly.Context)"> <summary> Sets the <see cref="T:Polly.Context"/> associated with the provided <see cref="T:System.Net.Http.HttpRequestMessage"/>. </summary> <param name="request">The <see cref="T:System.Net.Http.HttpRequestMessage"/>.</param> <param name="context">The <see cref="T:Polly.Context"/>, may be <c>null</c>.</param> <remarks> The <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler"/> will attach a context to the <see cref="T:System.Net.Http.HttpResponseMessage"/> prior to executing a <see cref="T:Polly.Policy"/>, if one does not already exist. The <see cref="T:Polly.Context"/> will be provided to the policy for use inside the <see cref="T:Polly.Policy"/> and in other message handlers. </remarks> </member> </members> </doc> |