Class ServiceCollectionExtensions

Namespace

RateLimitHeaders

Assembly

RateLimitHeaders.dll

Extension methods for adding rate limit aware handlers to an IHttpClientBuilder.

public static class ServiceCollectionExtensions

Inheritance

object

ServiceCollectionExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

Basic usage with default options:

services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler();

Configuration from appsettings.json:

// appsettings.json:
// {
//   "RateLimitHandler": {
//     "EnableProactiveThrottling": true,
//     "QuotaLowThreshold": 0.2,
//     "TrackStatePerEndpoint": true
//   }
// }

services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler(configuration.GetSection("RateLimitHandler"));

Using IOptions<T> pattern:

services.Configure<RateLimitAwareOptions>("MyApi", configuration.GetSection("RateLimitHandler"));
services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler("MyApi");

Methods

AddRateLimitAwareHandler(IHttpClientBuilder)

Adds a RateLimitAwareHandler to the HTTP client builder with default options.

public static IHttpClientBuilder AddRateLimitAwareHandler(this IHttpClientBuilder builder)

Parameters

builder IHttpClientBuilder

The HTTP client builder.

Returns

IHttpClientBuilder

The HTTP client builder for chaining.

Examples

services.AddHttpClient("MyApi", client => client.BaseAddress = new Uri("https://api.example.com"))
    .AddRateLimitAwareHandler();

Remarks

The handler is added as a transient service as required by IHttpClientFactory. Handler instances are pooled for approximately 2 minutes.

AddRateLimitAwareHandler(IHttpClientBuilder, IConfiguration)

Adds a RateLimitAwareHandler to the HTTP client builder with options bound from an IConfiguration section.

public static IHttpClientBuilder AddRateLimitAwareHandler(this IHttpClientBuilder builder, IConfiguration configuration)

Parameters

builder IHttpClientBuilder

The HTTP client builder.

configuration IConfiguration

The configuration section to bind options from.

Returns

IHttpClientBuilder

The HTTP client builder for chaining.

Examples

// appsettings.json:
// {
//   "RateLimitHandler": {
//     "EnableProactiveThrottling": true,
//     "QuotaLowThreshold": 0.2,
//     "TrackStatePerEndpoint": true
//   }
// }

services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler(configuration.GetSection("RateLimitHandler"));

Remarks

The handler is added as a transient service as required by IHttpClientFactory. Handler instances are pooled for approximately 2 minutes.

Bindable properties from configuration:

• EnableProactiveThrottling - boolean (default: true)
• QuotaLowThreshold - double between 0.0 and 1.0 (default: 0.1)
• TrackStatePerEndpoint - boolean (default: true)

Callbacks (OnRateLimitInfo, OnQuotaLow, OnThrottling) cannot be bound from configuration and must be set programmatically using the overload with configure action.

AddRateLimitAwareHandler(IHttpClientBuilder, IConfiguration, Action<RateLimitAwareOptions>)

Adds a RateLimitAwareHandler to the HTTP client builder with options bound from an IConfiguration section, with an additional configure action for callbacks.

public static IHttpClientBuilder AddRateLimitAwareHandler(this IHttpClientBuilder builder, IConfiguration configuration, Action<RateLimitAwareOptions> configure)

Parameters

builder IHttpClientBuilder

The HTTP client builder.

configuration IConfiguration

The configuration section to bind options from.

configure Action<RateLimitAwareOptions>

An action to configure additional options (typically callbacks).

Returns

IHttpClientBuilder

The HTTP client builder for chaining.

Examples

services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler(
        configuration.GetSection("RateLimitHandler"),
        options => options.OnQuotaLow = args => logger.LogWarning("Quota low!"));

Remarks

This overload allows combining configuration file settings with programmatic callback setup. The configuration is applied first, then the configure action is invoked.

AddRateLimitAwareHandler(IHttpClientBuilder, Action<RateLimitAwareOptions>?)

Adds a RateLimitAwareHandler to the HTTP client builder with the specified options.

public static IHttpClientBuilder AddRateLimitAwareHandler(this IHttpClientBuilder builder, Action<RateLimitAwareOptions>? configure)

Parameters

builder IHttpClientBuilder

The HTTP client builder.

configure Action<RateLimitAwareOptions>

An optional action to configure the handler options.

Returns

IHttpClientBuilder

The HTTP client builder for chaining.

Examples

services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler(options =>
    {
        options.EnableProactiveThrottling = true;
        options.QuotaLowThreshold = 0.2;
        options.OnQuotaLow = args => Console.WriteLine($"Quota low: {args.RateLimitInfo.Remaining}");
    });

Remarks

The handler is added as a transient service as required by IHttpClientFactory. Handler instances are pooled for approximately 2 minutes.

AddRateLimitAwareHandler(IHttpClientBuilder, Action<IServiceProvider, RateLimitAwareOptions>)

Adds a RateLimitAwareHandler to the HTTP client builder with options configured from a callback that has access to the service provider.

public static IHttpClientBuilder AddRateLimitAwareHandler(this IHttpClientBuilder builder, Action<IServiceProvider, RateLimitAwareOptions> configure)

Parameters

builder IHttpClientBuilder

The HTTP client builder.

configure Action<IServiceProvider, RateLimitAwareOptions>

An action to configure the handler options with access to the service provider.

Returns

IHttpClientBuilder

The HTTP client builder for chaining.

Examples

services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler((sp, options) =>
    {
        var telemetry = sp.GetRequiredService<ITelemetryService>();
        options.OnRateLimitInfo = args => telemetry.TrackRateLimit(args.RateLimitInfo);
    });

Remarks

The handler is added as a transient service as required by IHttpClientFactory. Handler instances are pooled for approximately 2 minutes.

AddRateLimitAwareHandler(IHttpClientBuilder, string)

Adds a RateLimitAwareHandler to the HTTP client builder using named options from the IOptionsMonitor<TOptions> pattern.

public static IHttpClientBuilder AddRateLimitAwareHandler(this IHttpClientBuilder builder, string optionsName)

Parameters

builder IHttpClientBuilder

The HTTP client builder.

optionsName string

The name of the options to use. Use DefaultName for unnamed options.

Returns

IHttpClientBuilder

The HTTP client builder for chaining.

Examples

// Register options with a name matching the client name
services.Configure<RateLimitAwareOptions>("MyApi", options =>
{
    options.EnableProactiveThrottling = true;
    options.QuotaLowThreshold = 0.2;
});

// Or bind from configuration
services.Configure<RateLimitAwareOptions>("MyApi", configuration.GetSection("RateLimitHandler"));

// Use the named options
services.AddHttpClient("MyApi")
    .AddRateLimitAwareHandler("MyApi");

Remarks

This overload integrates with the IOptions<T> pattern, allowing options to be registered separately and resolved at runtime. This is useful for scenarios where options need to be shared across multiple components or when using options validation.