Skip to content
Tutorials Center
My learning

Topics

Lesson 144 of 182 ยท ASP.NET Core

Health Checks and Rate Limiting

Run ASP.NET Core in production with health checks (tags, degraded state, timeouts, JSON reports) and built-in rate limiting (fixed window, sliding window, token bucket, concurrency, per-client policies).

Two things separate a demo web app from a service you can run for years. The first is that the platform around it can tell whether it is healthy. The second is that it can protect itself from clients that ask for too much, whether that is a bug in a mobile app, a scraper, or an attacker. ASP.NET Core ships both as ready-made features: health checks (Microsoft.Extensions.Diagnostics.HealthChecks) and rate limiting (Microsoft.AspNetCore.RateLimiting, built on System.Threading.RateLimiting). Both are part of the shared framework, so there are no NuGet packages to add.

You met a first health-check endpoint in deployment. This lesson goes further: custom checks with data, degraded states, timeouts, JSON reports and what status codes to return. Then it turns to rate limiting: the four algorithms, how to build them by hand to see how they behave, and how to apply them per endpoint and per client. It builds on the middleware pipeline, minimal APIs and dependency injection.

The using lines in the examples are implicit in a real web project. They are spelled out because our runner compiles a single file. Every server here listens on loopback and calls itself with HttpClient, so you can run the whole lesson in the browser.

Health checks beyond "ok"

A health check is a small piece of code that answers "is this part of the system working?" with one of three statuses:

Status Meaning Default HTTP code
Healthy Everything works 200
Degraded Works, but not well: slow, running on a fallback, nearly full 200
Unhealthy Broken, or the check itself threw or timed out 503

The report's overall status is the worst status of the checks that ran. You register checks with AddHealthChecks().AddCheck(...), give them tags (so different endpoints can run different groups), and map one or more endpoints with MapHealthChecks. A check can return a description and a data dictionary, which is perfect for numbers an operator wants ("free disk: 12%"). Three details are worth knowing:

  • Exceptions are caught. If a check throws, the framework reports Unhealthy and puts the exception message in the description (and the exception object in the report) instead of crashing the endpoint.
  • Timeouts. AddCheck(name, check, timeout: ...) cancels a check that takes too long and reports it as unhealthy. A hanging database check without a timeout would hang your health endpoint, which makes the orchestrator think the whole app is hung.
  • The default writer is plain text (Healthy, Degraded, Unhealthy). Orchestrators only need the status code, but dashboards and humans like JSON, which you produce with a ResponseWriter delegate.

The next program registers four checks (healthy, degraded with data, throwing, and too slow), splits them across two endpoints by tag, and writes a JSON report. It also changes the status-code mapping so that Degraded returns 503 on the readiness endpoint, which tells a load balancer to stop sending traffic to an instance that is struggling.

C# Custom checks, tags, timeouts and a JSON report

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The liveness endpoint runs only the process check and answers 200. The readiness endpoint ran all three ready checks and reports the worst: the disk is Degraded (with its data), the gateway check threw (description is the exception message, status Unhealthy), and the slow check was cancelled by its timeout. The overall status is Unhealthy, so the code is 503. Notice what the JSON leaves out on purpose: no connection strings, no stack traces. Health endpoints are often public, so never put secrets or internal topology in descriptions. Many teams expose the detailed JSON only on an internal port or behind authorization (.RequireAuthorization() on the mapped endpoint works as it does for any endpoint) and give the public load balancer a bare status code.

Which checks go where

flowchart TD
    P["Platform / load balancer"] -->|"every few seconds"| L["/health/live"]
    P -->|"every few seconds"| R["/health/ready"]
    L --> LC["process check only"]
    R --> RC["database, cache, disk, gateway"]
    LC -->|"fails"| X["restart the instance"]
    RC -->|"fails"| Y["stop sending traffic,<br/>do not restart"]

Liveness failures cause restarts; readiness failures only pull the instance out of rotation.

Do not check a database from the liveness endpoint: when the database goes down, the platform would restart every healthy app instance in a loop and turn a partial outage into a complete one. Real projects add packaged checks (AspNetCore.HealthChecks.* NuGet packages for SQL Server, Redis, RabbitMQ, URLs) and sometimes a publisher (IHealthCheckPublisher) that pushes the results to a monitoring system on a schedule instead of waiting to be polled. Both are read-only here, because they need packages or external systems.

Why rate limit?

A server has finite CPU, memory, database connections and downstream quotas. Without limits, one client in a tight loop can starve everyone else. Reasons to limit:

  • Fairness: share capacity between customers or plans.
  • Protection: slow down password guessing, scrapers and denial-of-service attempts.
  • Cost: stay inside the limit of a paid third-party API you call on behalf of clients.
  • Stability: shed load deliberately with a quick 429 Too Many Requests instead of collapsing slowly under a queue.

.NET offers four limiter algorithms, all in System.Threading.RateLimiting. You can use them in any program, not just web apps.

Algorithm Idea Good for Watch out for
Fixed window N permits per time window; the counter resets at each boundary Simple quotas ("100 per minute") A client can do 2N in a short burst across a boundary
Sliding window The window is split into segments; permits expire segment by segment Smoother limits without boundary bursts A little more bookkeeping
Token bucket A bucket holds up to N tokens; tokens are added at a steady rate; each request takes one Allowing short bursts while capping the average rate Two settings to tune (size and refill rate)
Concurrency At most N operations running at the same time; a permit returns when the work ends Protecting slow or expensive operations Limits parallelism, not request rate
stateDiagram-v2
    [*] --> Acquire: request arrives
    Acquire --> Granted: permit available
    Acquire --> Queued: none free, queue has room
    Acquire --> Rejected: none free, queue full
    Queued --> Granted: a permit is replenished
    Granted --> Handled: run the request
    Handled --> [*]
    Rejected --> [*]: respond 429

Every limiter answers an acquire request with granted, queued or rejected; the middleware turns "rejected" into HTTP 429.

The algorithms by hand

The best way to understand a limiter is to drive it yourself. Each limiter has AttemptAcquire(permits) (immediate answer) and AcquireAsync (can wait in a queue). Normally the limiter replenishes itself with a background timer, which makes experiments depend on the clock. Setting AutoReplenishment = false and calling TryReplenish() ourselves makes each step predictable. TryReplenish() does nothing until a whole window or period has really elapsed, so the example uses 300 ms periods and waits 350 ms for each "tick".

C# Fixed window, token bucket and concurrency limiters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The fixed-window limiter rejected requests 4 and 5 and recovered when the window rolled over. The token bucket allowed a burst of 4 (it started full), then could only do 2 per tick, and idle time cannot bank more than the bucket size: this "bursty but bounded average" behavior is why token buckets are the usual choice for public APIs. The concurrency limiter counts running work, not time, so there is no replenish step: disposing the lease is what gives the permit back. Always dispose leases (the middleware does it for you).

A sliding window limiter works like the fixed window but divides the window into SegmentsPerWindow segments, so permits used in the oldest segment return to the pool one segment at a time rather than all at once. The code looks the same with SlidingWindowRateLimiter; the difference shows in the boundary case, where a client cannot burst 2N around a reset.

Queueing instead of rejecting

With QueueLimit > 0, a request that finds no permit waits (AcquireAsync) until one is replenished, up to the queue size, and only then is rejected. QueueProcessingOrder chooses OldestFirst (fair) or NewestFirst (fresh requests are more likely to still have a waiting client). Queueing smooths short spikes at the cost of latency; for APIs, QueueLimit = 0 (fail fast) is the common default because clients can retry.

Rate limiting in ASP.NET Core

The middleware wraps these limiters. You call AddRateLimiter to define named policies, add UseRateLimiter() to the pipeline, and attach a policy to endpoints with RequireRateLimiting("name") (or the [EnableRateLimiting("name")] attribute on controllers, [DisableRateLimiting] to opt out). Order matters: put UseRateLimiter after UseRouting if you use endpoint-specific policies, and before the expensive middleware. A rejected request gets status 429 (set RejectionStatusCode, because the default is 503) and your OnRejected callback runs, a good place to add a Retry-After header and a friendly body.

The key concept is the partition. A policy does not create one limiter; it creates a limiter per partition key. Partitioning by client means each client gets its own counter:

  • by API key or authenticated user id (best, because it cannot be dodged);
  • by IP address (context.Connection.RemoteIpAddress; behind a proxy, configure forwarded headers first or every request appears to come from the proxy);
  • by tenant or plan, with different limits per partition (GetTokenBucketLimiter(key, _ => options) receives the key, so a "premium" key can get larger options).
flowchart LR
    R["Request"] --> K["Partition key<br/>e.g. X-Api-Key"]
    K --> A["limiter for client A<br/>3 per window"]
    K --> B["limiter for client B<br/>3 per window"]
    A --> D{"permit?"}
    B --> D
    D -- yes --> H["Endpoint runs"]
    D -- no --> T["429 + Retry-After"]

One policy, one independent counter per partition key, so a noisy client cannot exhaust another client's allowance.

The program defines a per-client fixed-window policy, a concurrency policy for an expensive endpoint, and leaves a health endpoint unlimited. It prints what each client experiences:

C# Per-client policies, 429 responses and concurrency limits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Client alpha got three 200 responses and then 429 with a Retry-After header; beta, with another key, still had its full allowance, which is the whole point of partitioning. The /health endpoint had no policy attached and was never limited. The concurrency policy let one report run; a second request arriving while it ran was rejected immediately, and once the first finished the next request was accepted again.

Rate limiting in the ASP.NET Core middleware is per server instance and kept in memory. If you run four instances behind a load balancer, a client can use four times the limit, and restarting an instance resets its counters. For strict global limits, enforce them at the gateway or CDN, or keep the counters in a shared store such as Redis (several packages provide this). The in-process limiter is still valuable as a last line of defense for each instance.

Practical advice

  • Tell clients what happened. Return 429 (not 500 or 503), a Retry-After header, and a short problem-details body (see validation and problem details). Well-behaved clients back off.
  • Limit expensive things more. Login, password reset, search and export endpoints deserve tighter limits than a product list.
  • Use a global limiter as a safety net, set with options.GlobalLimiter, and policies on top for specific endpoints.
  • Choose the partition carefully. An IP-based limit punishes users behind one corporate NAT; an anonymous bucket shared by everyone punishes everyone for one abuser.
  • Log rejections and watch the metrics (the middleware emits Microsoft.AspNetCore.RateLimiting meters you can export). Rejections that suddenly spike are either an attack or a limit that is set too low.
  • Test the limits. The examples above are the model: a loopback server plus an HttpClient, with long windows and manual control to keep tests deterministic (see testing basics).
  • Combine with authentication: first identify the caller (see authentication and authorization), then partition by user id.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A health check reports Degraded. With the default settings, which HTTP status does the health endpoint return?

    By default Healthy and Degraded both map to 200 and only Unhealthy maps to 503. You can change this with HealthCheckOptions.ResultStatusCodes.
  2. 2. Why should the liveness endpoint not check the database?

    A failed liveness probe means restart me. Restarting does not fix the database and can turn a partial outage into a full one, so dependency checks belong in readiness.
  3. 3. Which limiter lets a client send a short burst of requests while capping the long-term average rate?

    A token bucket starts full, so a burst up to the bucket size is allowed, and then requests proceed at the refill rate.
  4. 4. What does partitioning a rate-limit policy by API key achieve?

    The policy creates one limiter per partition key. That is what makes the limit fair per client instead of global.
  5. 5. You run three instances of your app behind a load balancer, each with an in-memory limit of 100 requests per minute. What is the real limit for one client?

    The built-in middleware limiter keeps counters per process. A client spread across three instances can use each instance's allowance. Use a gateway or shared store for exact global limits.

Summary

  • Health checks return Healthy, Degraded or Unhealthy; tags split them into liveness (restart me) and readiness (stop sending traffic) endpoints.
  • Give every check a timeout, never leak secrets in descriptions, and customize ResultStatusCodes and the response writer to fit your platform.
  • Rate limiting protects fairness, cost and stability. The four algorithms are fixed window, sliding window, token bucket and concurrency.
  • In ASP.NET Core, define policies with AddRateLimiter, add UseRateLimiter, attach with RequireRateLimiting or [EnableRateLimiting], and partition by client key.
  • Reject with 429 plus Retry-After; the built-in limiter is per instance and in memory.

Next: Blazor Components