Add docs for request timeouts middleware

[adityamandaleeka]

.NET 8 has a new request timeouts middleware, which allows users to set request timeouts for individual endpoints, controllers, or dynamically per request. We should document it.

Some notes that may be useful...

To apply request timeouts, first add the request timeout services:

builder.Services.AddRequestTimeouts();

You can then apply request timeouts using middleware by calling UseRequestTimeouts():

app.UseRequestTimeouts();

To apply request timeouts to a particular endpoint call WithRequestTimeout(timeout) or add [RequestTimeout(timeout)] to the controller or action.

The timeouts are cooperative; when they expire, the HttpContext.RequestAborted cancellation token will trigger but the request will not be forcibly aborted. It's up to the application to monitor the token and decide how to end the request processing.

---

More info at:

• Issue: Request timeouts middleware aspnetcore#45732
• PR: Implement request timeout middleware aspnetcore#46115

EDIT by @Rick-Anderson to add the following metadata

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: 9898482c-fa54-7ce2-1716-d14fbe03990d
• Version Independent ID: 3926c686-0ccc-f9fe-ca52-0134612a1623
• Content: ASP.NET Core Middleware
• Content Source: aspnetcore/fundamentals/middleware/index.md
• Product: aspnet-core
• Technology: aspnetcore-fundamentals
• GitHub Login: @Rick-Anderson
• Microsoft Alias: riande

---

Associated WorkItem - 85532

[adityamandaleeka]

cc @Tratcher

[tdykstra]

@Kahbazi do you have a sample app or code snippets that show how to use the timeout middleware?

[dodyg]

@tdykstra I wrote a sample here https://github.com/dodyg/practical-aspnetcore/tree/net6.0/projects/.net8/request-timeout

[tdykstra]

@dodyg Thanks. Can you also show code that uses the TimeoutStatusCode and WriteTimeoutResponse properties of Microsoft.AspNetCore.Http.Timeouts.RequestTimeoutPolicy?

Edit -- Please put any sample code you want to contribute in the same folder as this stub.txt file

[dodyg]

Default timeout policy https://github.com/dodyg/practical-aspnetcore/tree/net6.0/projects/.net8/request-timeout-3

Named timeout policy https://github.com/dodyg/practical-aspnetcore/blob/net6.0/projects/.net8/request-timeout-2

[tdykstra]

@dodyg Thanks.

[prinsalvino]

Hi @dodyg. could you please show the code to use the RequestTimeout attribute?
already registered the service using builder.Services.AddRequestTimeouts() and app.UseRequestTimeouts(). but when I try to use the attribute in the controller, it doesn't seems to work

 public class CountryController : ControllerBase
 {
       [HttpGet]
       [RequestTimeout(milliseconds: 1)]
       public override IActionResult GetList()
       {
            return Ok(MdlCountry.GetList());
       }
}

[dodyg]

@prinsalvino dodyg/practical-aspnetcore#376

[tdykstra]

@prinsalvino Are you testing in debug mode? You won't see any timeouts when testing in debug mode.

[prinsalvino]

@tdykstra I have tried doing it in release mode but problem is still the same. I use docker to run my application

[Kahbazi]

@prinsalvino The timeout middleware only sets the HttpContext.RequestAborted. You have to check it yourself in theapplication code and decide if you want to throw if HttpContext.RequestAborted is cancelled.

public class CountryController : ControllerBase
 {
    [HttpGet]
    [RequestTimeout(milliseconds: 1)]
    public override async Task<IActionResult> GetList()
    {
        await Task.Delay(2);
        HttpContext.RequestAborted.ThrowIfCancellationRequested();
        return Ok(MdlCountry.GetList());
    }
}

[prinsalvino]

@Kahbazi I copy pasted the code. run both in debug and release mode but still not successful. tried to debug the request aborted value
▶ | HttpContext.RequestAborted | IsCancellationRequested = false | System.Threading.CancellationToken

Checked the services as well and it is registered

[dodyg]

@prinsalvino try this sample https://github.com/dodyg/practical-aspnetcore/blob/net6.0/projects/.net8/request-timeout-4/Program.cs

[dodyg]

This one shows how to use a named policy https://github.com/dodyg/practical-aspnetcore/tree/net6.0/projects/.net8/request-timeout-5.

I can't figure out how to use default policy using RequestTimeout although you can do so with minimal API extension method .WithRequestTimeout(policy: null);

[tdykstra]

I can't figure out how to use default policy using RequestTimeout although you can do so with minimal API extension method .WithRequestTimeout(policy: null);

The Request timeouts doc has a section that shows an example of setting and using a default timeout. https://learn.microsoft.com/en-us/aspnet/core/performance/timeouts?view=aspnetcore-8.0#set-global-default-timeout-policy

[dodyg]

Thanks. Somehow I ended up with a wrong mental model on how the default timeout policy should work.

[prinsalvino]

@dodyg I copy pasted this sample https://github.com/dodyg/practical-aspnetcore/blob/net6.0/projects/.net8/request-timeout-4/Program.cs. Also added builder.Services.AddRequestTimeouts(); because it throws an exception. Run it and test using swagger. Still got the response "Hello World!"

[dodyg]

@prinsalvino

[prinsalvino]

@dodyg I have no idea what's going on here

[dodyg]

Perhaps this

https://learn.microsoft.com/en-us/aspnet/core/performance/timeouts?view=aspnetcore-8.0#set-global-default-timeout-policy

[prinsalvino]

I see. in my previous screenshot, I run it in release mode via visual studio.

Now, I run dotnet publish and dotnet applicationName.dll via cli and it seems to be working. Thank you! @dodyg