Is it possible to add a rate limiter policy using chained limiters?

[bdcoder2]

Description

Currently, the rate limiting documentation shows a single example of creating chained limiters and applying them at a global level. But is it possible to do the same when adding a rate limiting policy?

I also found this discussion, but again, there does not seem to be an example of creating a policy (non-global) that uses chained limiters.

For example, given:

Microsoft.AspNetCore.RateLimiting.RateLimiterOptions options;

var limiters_array = new RateLimiter[ 2 ];

// limiters_array populated here (code omitted for brevity)

/*
The following will NOT work as the .AddPolicy method expects a
second argument of: Func<HttpContext, RateLimitPartition<TPartitionKey>>
*/
options.AddPolicy( "chained", RateLimiter.CreateChained( limiters_array) ); 

There does not seem to be an overload (or clear) way to create a policy that incorporates chained limiters.

I have not (yet) come across anything in the documentation that explicitly states something such as:

"chained limiters are only available at a global level"

but if that IS true, it should be added to the documentation.

If I missed something in the documentation, I apologize in advance, but do request a link to the relevant method or page that illustrates how to create a policy that uses chained limiters.

Thanks in advance.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit-samples?view=aspnetcore-10.0&source=recommendations

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/performance/rate-limit-samples.md

Document ID

d96ee509-2576-279e-29b3-89fbe44b0a28

Platform Id

05af3602-fe02-0ab6-50c5-1058509c4fd9

Article author

@wadepickett

Metadata

• ID: d96ee509-2576-279e-29b3-89fbe44b0a28
• PlatformId: 05af3602-fe02-0ab6-50c5-1058509c4fd9
• Service: aspnet-core
• Sub-service: performance

Related Issues

[wadepickett]

@bdcoder2, thanks for bringing this up. There is a gap you identified here is for a fundimental use case. We should cover it.

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution or answer to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution!

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-03-09
Issue: 36851
Model: GitHub Copilot

---

Issue Analysis: Chained Limiters Not Documented for Use with Named Policies (Non-Global)

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The issue author correctly identifies a documentation gap: the Create chained limiters section of the rate limiting documentation only demonstrates PartitionedRateLimiter.CreateChained when assigned to options.GlobalLimiter. There is no example or guidance on how to use chained limiters with a named policy (via options.AddPolicy), and there is no explicit statement clarifying whether or not this is possible.

Technical finding: After examining the ASP.NET Core source code for RateLimiterOptions.AddPolicy, the AddPolicy method accepts a Func<HttpContext, RateLimitPartition<TPartitionKey>> — a partitioner function that returns a RateLimitPartition. Using RateLimitPartition.Get, the factory parameter can return any RateLimiter, including one produced by RateLimiter.CreateChained(...). This means chained limiters can be used with named policies, but this pattern is not documented.

The existing chained limiter sample code at WebRate2/Program.cs (snippet_3) only shows global usage via _.GlobalLimiter = PartitionedRateLimiter.CreateChained(...).

📊 Scenario Frequency: Common (Not Edge Case)

Multiple independent signals confirm this is a commonly encountered scenario, not an edge case:

Signal	Evidence
Duplicate docs issue	#36043 — "UUF: Rate limiting: Multiple limiters, one policy: add example" — an open issue from the User Feedback (UUF) system with the same request: "how to use two limiters in one policy for the same endpoint."
Active product feature request	dotnet/aspnetcore#42691 — "Support Multiple PartitionedRateLimiter Per Endpoint" — 40 comments, filed by ASP.NET Core team member @Kahbazi, milestoned for .NET 11 Planning.
Community discussion	dotnet/aspnetcore Discussion #54051 — "Chained rate limiting policy" — another community member asking the same question (also referenced by the #36851 author).
Fundamental use case	Combining rate limiters (e.g., concurrency + token bucket, or per-IP + per-user) on a single endpoint is a standard production pattern for any API needing both burst protection and sustained-rate protection.

Recommendation: Consolidate #36851 and #36043 since they request the same documentation change, and prioritize accordingly.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/performance/rate-limit.md	374-382	"Create chained limiters"
Samples article	aspnetcore/performance/rate-limit-samples.md	All	Rate limiter samples
Code sample	WebRate2/Program.cs	117-173	snippet_3 (chained limiter sample)

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential Documentation Update 1: Add policy-based chained limiter example

File: aspnetcore/performance/rate-limit.md
Location: Lines 374-382, after the existing "Create chained limiters" section
Type: New subsection with code example

Current content (lines 374-382):

### Create chained limiters

The <xref:System.Threading.RateLimiting.PartitionedRateLimiter.CreateChained%2A> API allows passing in multiple <xref:System.Threading.RateLimiting.PartitionedRateLimiter> which are combined into one `PartitionedRateLimiter`. The combined limiter runs all the input limiters in sequence.

The following code uses `CreateChained`:

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/middleware/rate-limit/WebRate2/Program.cs" id="snippet_3" highlight="19,20,33":::

For more information, see the [CreateChained source code](https://github.com/dotnet/runtime/blob/79874806d246670ee5fe76e73ce566578fe675c0/src/libraries/System.Threading.RateLimiting/src/System/Threading/RateLimiting/PartitionedRateLimiter.cs#L52-L64)

Suggested direction:

After the existing chained limiter example, add a subsection showing the policy-based pattern. The key technical distinction to document:

• Global chained limiters: Use PartitionedRateLimiter.CreateChained(...) which chains multiple PartitionedRateLimiter<HttpContext> instances, assigned to options.GlobalLimiter.
• Policy-based chained limiters: Use RateLimitPartition.Get(...) with a factory that calls RateLimiter.CreateChained(...) to chain multiple RateLimiter instances within the policy partition.

#### Use chained limiters with a named policy

Chained limiters are not limited to the `GlobalLimiter`. They can also be used with named policies via `AddPolicy` by using `RateLimitPartition.Get` with a factory that returns a chained `RateLimiter`:

```csharp
builder.Services.AddRateLimiter(options =>
{
    options.AddPolicy("chained", context =>
        RateLimitPartition.Get(
            partitionKey: context.User.Identity?.Name ?? "anonymous",
            factory: key =>
            {
                var concurrencyLimiter = new ConcurrencyLimiter(
                    new ConcurrencyLimiterOptions
                    {
                        PermitLimit = 5,
                        QueueProcessingOrder = QueueProcessingOrder.OldestFirst,
                        QueueLimit = 2
                    });

                var tokenBucketLimiter = new TokenBucketRateLimiter(
                    new TokenBucketRateLimiterOptions
                    {
                        TokenLimit = 10,
                        QueueProcessingOrder = QueueProcessingOrder.OldestFirst,
                        QueueLimit = 0,
                        ReplenishmentPeriod = TimeSpan.FromSeconds(10),
                        TokensPerPeriod = 10,
                        AutoReplenishment = true
                    });

                return RateLimiter.CreateChained(concurrencyLimiter, tokenBucketLimiter);
            }
        ));
});

app.MapGet("/api/resource", () => "Rate limited resource")
   .RequireRateLimiting("chained");

In this example, a request to /api/resource must pass both the concurrency limiter and the token bucket limiter. RateLimitPartition.Get provides a factory function that creates a chained RateLimiter for each unique partition key.

Note

First-class support for applying multiple PartitionedRateLimiter policies per endpoint is being tracked in dotnet/aspnetcore#42691.

### Potential Documentation Update 2: Add clarifying note at section top
**File:** [`aspnetcore/performance/rate-limit.md`](https://github.com/dotnet/AspNetCore.Docs/blob/85dd6009e162cf834e9552f28191b8498b988a3e/aspnetcore/performance/rate-limit.md#L374-L376)
**Location:** Lines 374-376, beginning of "Create chained limiters" section
**Type:** `[!NOTE]` block

**Suggested direction:**
```markdown
> [!NOTE]
> Chained limiters can be used both as a `GlobalLimiter` (using `PartitionedRateLimiter.CreateChained`) and within a named policy (using `RateLimitPartition.Get` with `RateLimiter.CreateChained` inside the factory). The global approach chains multiple `PartitionedRateLimiter` instances, while the policy approach chains multiple `RateLimiter` instances within a single partition.

Potential Code Sample Updates

File: WebRate2/Program.cs
Change: Add a new #elif snippet (e.g., snippet_4) demonstrating the policy-based chained limiter pattern for use in the documentation.

Suggested direction:

#elif CHAINEDPOLICY
// <snippet_4>
using System.Threading.RateLimiting;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRateLimiter(options =>
{
    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;

    options.AddPolicy("chained", context =>
        RateLimitPartition.Get(
            partitionKey: context.User.Identity?.Name ?? "anonymous",
            factory: key =>
            {
                var concurrencyLimiter = new ConcurrencyLimiter(
                    new ConcurrencyLimiterOptions
                    {
                        PermitLimit = 5,
                        QueueProcessingOrder = QueueProcessingOrder.OldestFirst,
                        QueueLimit = 2
                    });

                var tokenBucketLimiter = new TokenBucketRateLimiter(
                    new TokenBucketRateLimiterOptions
                    {
                        TokenLimit = 10,
                        QueueProcessingOrder = QueueProcessingOrder.OldestFirst,
                        QueueLimit = 0,
                        ReplenishmentPeriod = TimeSpan.FromSeconds(10),
                        TokensPerPeriod = 10,
                        AutoReplenishment = true
                    });

                return RateLimiter.CreateChained(concurrencyLimiter, tokenBucketLimiter);
            }
        ));
});

var app = builder.Build();
app.UseRateLimiter();

app.MapGet("/api/resource", () => Results.Ok("Hello, rate limited!"))
   .RequireRateLimiting("chained");

app.Run();
// </snippet_4>

🎯 Suggested Action Plan

For documentation team review

1. Consolidate duplicate issues: Link or close #36043 as a duplicate of #36851 (or vice versa) — they request the same documentation change.

2. Review and update the main article: aspnetcore/performance/rate-limit.md

   • Navigate to: Lines 374-382
   • Section: "Create chained limiters"
   • Add a new subsection "Use chained limiters with a named policy" with a code example
   • Add a [!NOTE] block clarifying both global and policy patterns
   • Add a [!NOTE] referencing dotnet/aspnetcore#42691 for first-class multi-policy-per-endpoint support planned for .NET 11

3. Add a new code sample to the samples repository: WebRate2/Program.cs

   • Add a new snippet_4 demonstrating chained limiters used with AddPolicy + RateLimitPartition.Get

4. Consider updating the samples article: aspnetcore/performance/rate-limit-samples.md

   • Add a new section referencing the new policy-based chained limiter sample

⚠️ Review Considerations

• Verify the RateLimiter.CreateChained API (non-partitioned) works as expected in .NET 7+ for the policy-based pattern — confirm with product team if needed. The AddPolicy overload takes Func<HttpContext, RateLimitPartition<TPartitionKey>>, so the factory in RateLimitPartition.Get must return a RateLimiter (not a PartitionedRateLimiter). Ensure the code sample compiles and runs correctly.
• Distinguish clearly between PartitionedRateLimiter.CreateChained (global) and RateLimiter.CreateChained (per-partition factory) to avoid confusion.
• The product feature request dotnet/aspnetcore#42691 is milestoned for .NET 11 Planning — when that ships, the documentation will need to be revisited to show the first-class API alongside the current workaround.
• Check if related articles (e.g., rate-limit-samples.md) need corresponding updates.

🔗 References

• Published article: Rate limiting middleware in ASP.NET Core
• Published samples: Rate limiting middleware samples
• Duplicate docs issue: #36043 — UUF: Rate limiting: Multiple limiters, one policy: add example
• Product feature request: dotnet/aspnetcore#42691 — Support Multiple PartitionedRateLimiter Per Endpoint (40 comments, .NET 11 milestone)
• Community discussion: dotnet/aspnetcore Discussion #54051 — Chained rate limiting policy
• AddPolicy source code: RateLimiterOptions.cs
• PartitionedRateLimiter.CreateChained source: Runtime source
• Existing chained sample: WebRate2/Program.cs snippet_3

[wadepickett]

Closed a duplicate #36043 and will continue tracking instead on this issue.