From 82ccbcee4e21dda557835b00c0564ddef72599d5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 23:14:24 +0000 Subject: [PATCH 1/6] Initial plan From 03b401ef50981bf0cdeaace59e48c57e8743f549 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 23:23:25 +0000 Subject: [PATCH 2/6] Create memory management article and update Kestrel overview Co-authored-by: tdykstra <1569635+tdykstra@users.noreply.github.com> --- aspnetcore/fundamentals/servers/kestrel.md | 13 ++---- .../servers/kestrel/includes/kestrel6.md | 8 ---- .../servers/kestrel/memory-management.md | 43 +++++++++++++++++++ aspnetcore/toc.yml | 3 ++ 4 files changed, 49 insertions(+), 18 deletions(-) create mode 100644 aspnetcore/fundamentals/servers/kestrel/memory-management.md diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index d4c1ef0dca1d..15713534ab86 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -5,7 +5,7 @@ description: Learn about Kestrel, the cross-platform web server for ASP.NET Core monikerRange: '>= aspnetcore-3.1' ms.author: tdykstra ms.custom: mvc -ms.date: 08/25/2025 +ms.date: 12/04/2025 uid: fundamentals/servers/kestrel --- # Kestrel web server in ASP.NET Core @@ -14,7 +14,7 @@ uid: fundamentals/servers/kestrel By [Tom Dykstra](https://github.com/tdykstra), [Chris Ross](https://github.com/Tratcher), and [Stephen Halter](https://twitter.com/halter73) -:::moniker range=">= aspnetcore-10.0" +:::moniker range=">= aspnetcore-8.0" Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index). Kestrel is the recommended server for ASP.NET Core, and it's configured by default in ASP.NET Core project templates. @@ -33,7 +33,7 @@ Kestrel's features include: * Building a reverse proxy with [YARP](https://github.com/microsoft/reverse-proxy). * **Extensibility:** Customize Kestrel through configuration, middleware, and custom transports. * **Performance diagnostics:** Kestrel provides built-in performance diagnostics features, such as logging and metrics. -* **Memory management:** Kestrel includes features for efficient memory management, such as automatic eviction from memory pool. +* **Memory management:** Kestrel includes features for efficient memory management. For more information, see . ## Get started @@ -43,13 +43,6 @@ ASP.NET Core project templates use Kestrel by default when not hosted with IIS. For more information on configuring `WebApplication` and `WebApplicationBuilder`, see . -## Optional client certificates - -For information on apps that must protect a subset of the app with a certificate, see [Optional client certificates](xref:security/authentication/certauth#optional-client-certificates). - - -[!INCLUDE[](includes/memory-eviction2.md)] - ## Additional resources diff --git a/aspnetcore/fundamentals/servers/kestrel/includes/kestrel6.md b/aspnetcore/fundamentals/servers/kestrel/includes/kestrel6.md index 3c43dd078ffc..720b4e9a7919 100644 --- a/aspnetcore/fundamentals/servers/kestrel/includes/kestrel6.md +++ b/aspnetcore/fundamentals/servers/kestrel/includes/kestrel6.md @@ -21,10 +21,6 @@ ASP.NET Core project templates use Kestrel by default when not hosted with IIS. For more information on configuring `WebApplication` and `WebApplicationBuilder`, see . -## Optional client certificates - -For information on apps that must protect a subset of the app with a certificate, see [Optional client certificates](xref:security/authentication/certauth#optional-client-certificates). - ## Behavior with debugger attached The following timeouts and rate limits aren't enforced when a debugger is attached to a Kestrel process: @@ -82,10 +78,6 @@ ASP.NET Core project templates use Kestrel by default when not hosted with IIS. For more information on building the host, see the *Set up a host* and *Default builder settings* sections of . -## Optional client certificates - -For information on apps that must protect a subset of the app with a certificate, see [Optional client certificates](xref:security/authentication/certauth#optional-client-certificates). - ## Additional resources diff --git a/aspnetcore/fundamentals/servers/kestrel/memory-management.md b/aspnetcore/fundamentals/servers/kestrel/memory-management.md new file mode 100644 index 000000000000..94c2dbc7e983 --- /dev/null +++ b/aspnetcore/fundamentals/servers/kestrel/memory-management.md @@ -0,0 +1,43 @@ +--- +title: Memory management in Kestrel +author: tdykstra +description: Learn about memory management in Kestrel, including automatic eviction from memory pools and using memory pool metrics. +monikerRange: '>= aspnetcore-8.0' +ms.author: tdykstra +ms.date: 12/04/2024 +uid: fundamentals/servers/kestrel/memory-management +--- + +# Memory management in Kestrel + +[!INCLUDE[](~/includes/not-latest-version.md)] + +By [Tom Dykstra](https://github.com/tdykstra) + +This article provides guidance for managing memory in Kestrel, including automatic eviction from memory pools and using memory pool metrics. + +## Automatic eviction from memory pool + +The memory pools used by Kestrel, IIS, and HTTP.sys automatically evict memory blocks when the application is idle or under low load. The feature runs automatically and doesn't need to be enabled or configured manually. + +In versions of .NET earlier than 10, memory allocated by the pool remains reserved, even when not in use. This automatic eviction feature reduces overall memory usage and helps applications stay responsive under varying workloads. + +### Use memory pool metrics + +The default memory pool used by the ASP.NET Core server implementations includes metrics, which can be used to monitor and analyze memory usage patterns. The metrics are under the name `"Microsoft.AspNetCore.MemoryPool"`. + +For information about metrics and how to use them, see . + +## Manage memory pools + +Besides using memory pools efficiently by evicting unneeded memory blocks, ASP.NET Core provides a built-in [IMemoryPoolFactory](https://source.dot.net/#Microsoft.AspNetCore.Connections.Abstractions/IMemoryPoolFactory.cs) and an implementation. It makes the implementation available to your application through dependency injection. + +The following code example shows a simple background service that uses the built-in memory pool factory implementation to create memory pools. These pools benefit from the automatic eviction feature: + +:::code language="csharp" source="~/fundamentals/servers/snippets/10.x/my-background-service.cs"::: + +To use a custom memory pool factory, make a class that implements `IMemoryPoolFactory` and register it with dependency injection, as the following example does. Memory pools created this way also benefit from the automatic eviction feature: + +:::code language="csharp" source="~/fundamentals/servers/snippets/10.x/memory-pool-factory.cs"::: + +When you're using a memory pool, be aware of the pool's . diff --git a/aspnetcore/toc.yml b/aspnetcore/toc.yml index 5881c94e8cdb..f07b27baa166 100644 --- a/aspnetcore/toc.yml +++ b/aspnetcore/toc.yml @@ -1190,6 +1190,9 @@ items: - name: Diagnostics displayName: diagnostics uid: fundamentals/servers/kestrel/diagnostics + - name: Memory management + displayName: memory, pool, kestrel + uid: fundamentals/servers/kestrel/memory-management - name: HTTP/2 displayName: deploy, publish, server, Kestrel uid: fundamentals/servers/kestrel/http2 From 6a4b393acea0a68cdac654d1d7c9a2b15782a7ac Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 23:25:30 +0000 Subject: [PATCH 3/6] Address code review feedback for memory management article Co-authored-by: tdykstra <1569635+tdykstra@users.noreply.github.com> --- aspnetcore/fundamentals/servers/kestrel/memory-management.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/memory-management.md b/aspnetcore/fundamentals/servers/kestrel/memory-management.md index 94c2dbc7e983..9dc36ea33f76 100644 --- a/aspnetcore/fundamentals/servers/kestrel/memory-management.md +++ b/aspnetcore/fundamentals/servers/kestrel/memory-management.md @@ -20,7 +20,7 @@ This article provides guidance for managing memory in Kestrel, including automat The memory pools used by Kestrel, IIS, and HTTP.sys automatically evict memory blocks when the application is idle or under low load. The feature runs automatically and doesn't need to be enabled or configured manually. -In versions of .NET earlier than 10, memory allocated by the pool remains reserved, even when not in use. This automatic eviction feature reduces overall memory usage and helps applications stay responsive under varying workloads. +This automatic eviction feature reduces overall memory usage and helps applications stay responsive under varying workloads. In versions of .NET earlier than 10, memory allocated by the pool remained reserved even when not in use. ### Use memory pool metrics @@ -30,7 +30,7 @@ For information about metrics and how to use them, see Date: Thu, 4 Dec 2025 23:28:29 +0000 Subject: [PATCH 4/6] Address code review feedback and fix moniker ranges Co-authored-by: tdykstra <1569635+tdykstra@users.noreply.github.com> --- aspnetcore/fundamentals/servers/kestrel.md | 50 ++++++++++++++++++- .../servers/kestrel/memory-management.md | 6 +-- 2 files changed, 52 insertions(+), 4 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index 15713534ab86..425555d041d5 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -14,7 +14,7 @@ uid: fundamentals/servers/kestrel By [Tom Dykstra](https://github.com/tdykstra), [Chris Ross](https://github.com/Tratcher), and [Stephen Halter](https://twitter.com/halter73) -:::moniker range=">= aspnetcore-8.0" +:::moniker range=">= aspnetcore-10.0" Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index). Kestrel is the recommended server for ASP.NET Core, and it's configured by default in ASP.NET Core project templates. @@ -63,4 +63,52 @@ For more information on configuring `WebApplication` and `WebApplicationBuilder` :::moniker-end +:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0" + +Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index). Kestrel is the recommended server for ASP.NET Core, and it's configured by default in ASP.NET Core project templates. + +Kestrel's features include: + +* **Cross-platform:** Kestrel is a cross-platform web server that runs on Windows, Linux, and macOS. +* **High performance:** Kestrel is optimized to handle a large number of concurrent connections efficiently. +* **Lightweight:** Optimized for running in resource-constrained environments, such as containers and edge devices. +* **Security hardened:** Kestrel supports HTTPS and is hardened against web server vulnerabilities. +* **Wide protocol support:** Kestrel supports common web protocols, including: + * HTTP/1.1, [HTTP/2](xref:fundamentals/servers/kestrel/http2) and [HTTP/3](xref:fundamentals/servers/kestrel/http3) + * [WebSockets](xref:fundamentals/websockets) +* **Integration with ASP.NET Core:** Seamless integration with other ASP.NET Core components, such as the middleware pipeline, dependency injection, and configuration system. +* **Flexible workloads**: Kestrel supports many workloads: + * ASP.NET app frameworks such as Minimal APIs, MVC, Razor pages, SignalR, Blazor, and gRPC. + * Building a reverse proxy with [YARP](https://github.com/microsoft/reverse-proxy). +* **Extensibility:** Customize Kestrel through configuration, middleware, and custom transports. +* **Performance diagnostics:** Kestrel provides built-in performance diagnostics features, such as logging and metrics. + +## Get started + +ASP.NET Core project templates use Kestrel by default when not hosted with IIS. In the following template-generated `Program.cs`, the method calls internally: + +:::code language="csharp" source="~/fundamentals/servers/kestrel/samples/6.x/KestrelSample/Program.cs" id="snippet_CreateBuilder" highlight="1"::: + +For more information on configuring `WebApplication` and `WebApplicationBuilder`, see . + +## Additional resources + + +* + +* + +* + +* + +* +* +* +* +* [RFC 9110: HTTP Semantics (Section 7.2: Host and :authority)](https://www.rfc-editor.org/rfc/rfc9110#field.host) +* When using UNIX sockets on Linux, the socket isn't automatically deleted on app shutdown. For more information, see [this GitHub issue](https://github.com/dotnet/aspnetcore/issues/14134). + +:::moniker-end + [!INCLUDE[](~/fundamentals/servers/kestrel/includes/kestrel6.md)] diff --git a/aspnetcore/fundamentals/servers/kestrel/memory-management.md b/aspnetcore/fundamentals/servers/kestrel/memory-management.md index 9dc36ea33f76..5cddb2eb603a 100644 --- a/aspnetcore/fundamentals/servers/kestrel/memory-management.md +++ b/aspnetcore/fundamentals/servers/kestrel/memory-management.md @@ -2,9 +2,9 @@ title: Memory management in Kestrel author: tdykstra description: Learn about memory management in Kestrel, including automatic eviction from memory pools and using memory pool metrics. -monikerRange: '>= aspnetcore-8.0' +monikerRange: '>= aspnetcore-10.0' ms.author: tdykstra -ms.date: 12/04/2024 +ms.date: 12/04/2025 uid: fundamentals/servers/kestrel/memory-management --- @@ -30,7 +30,7 @@ For information about metrics and how to use them, see Date: Sat, 6 Dec 2025 00:07:50 +0000 Subject: [PATCH 5/6] Fix moniker range usage to avoid duplicate H2 headers Co-authored-by: tdykstra <1569635+tdykstra@users.noreply.github.com> --- aspnetcore/fundamentals/servers/kestrel.md | 49 +++------------------- 1 file changed, 5 insertions(+), 44 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index 425555d041d5..dd395ec53859 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -14,7 +14,7 @@ uid: fundamentals/servers/kestrel By [Tom Dykstra](https://github.com/tdykstra), [Chris Ross](https://github.com/Tratcher), and [Stephen Halter](https://twitter.com/halter73) -:::moniker range=">= aspnetcore-10.0" +:::moniker range=">= aspnetcore-8.0" Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index). Kestrel is the recommended server for ASP.NET Core, and it's configured by default in ASP.NET Core project templates. @@ -33,55 +33,16 @@ Kestrel's features include: * Building a reverse proxy with [YARP](https://github.com/microsoft/reverse-proxy). * **Extensibility:** Customize Kestrel through configuration, middleware, and custom transports. * **Performance diagnostics:** Kestrel provides built-in performance diagnostics features, such as logging and metrics. -* **Memory management:** Kestrel includes features for efficient memory management. For more information, see . - -## Get started - -ASP.NET Core project templates use Kestrel by default when not hosted with IIS. In the following template-generated `Program.cs`, the method calls internally: - -:::code language="csharp" source="~/fundamentals/servers/kestrel/samples/6.x/KestrelSample/Program.cs" id="snippet_CreateBuilder" highlight="1"::: - -For more information on configuring `WebApplication` and `WebApplicationBuilder`, see . - -## Additional resources - - -* - -* - -* - -* - -* -* -* -* -* [RFC 9110: HTTP Semantics (Section 7.2: Host and :authority)](https://www.rfc-editor.org/rfc/rfc9110#field.host) -* When using UNIX sockets on Linux, the socket isn't automatically deleted on app shutdown. For more information, see [this GitHub issue](https://github.com/dotnet/aspnetcore/issues/14134). :::moniker-end -:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0" +:::moniker range=">= aspnetcore-10.0" -Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index). Kestrel is the recommended server for ASP.NET Core, and it's configured by default in ASP.NET Core project templates. +* **Memory management:** Kestrel includes features for efficient memory management. For more information, see . -Kestrel's features include: +:::moniker-end -* **Cross-platform:** Kestrel is a cross-platform web server that runs on Windows, Linux, and macOS. -* **High performance:** Kestrel is optimized to handle a large number of concurrent connections efficiently. -* **Lightweight:** Optimized for running in resource-constrained environments, such as containers and edge devices. -* **Security hardened:** Kestrel supports HTTPS and is hardened against web server vulnerabilities. -* **Wide protocol support:** Kestrel supports common web protocols, including: - * HTTP/1.1, [HTTP/2](xref:fundamentals/servers/kestrel/http2) and [HTTP/3](xref:fundamentals/servers/kestrel/http3) - * [WebSockets](xref:fundamentals/websockets) -* **Integration with ASP.NET Core:** Seamless integration with other ASP.NET Core components, such as the middleware pipeline, dependency injection, and configuration system. -* **Flexible workloads**: Kestrel supports many workloads: - * ASP.NET app frameworks such as Minimal APIs, MVC, Razor pages, SignalR, Blazor, and gRPC. - * Building a reverse proxy with [YARP](https://github.com/microsoft/reverse-proxy). -* **Extensibility:** Customize Kestrel through configuration, middleware, and custom transports. -* **Performance diagnostics:** Kestrel provides built-in performance diagnostics features, such as logging and metrics. +:::moniker range=">= aspnetcore-8.0" ## Get started From c0dbc36daca8945d6435c7f5b9ac485ac64402d5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Dec 2025 00:37:13 +0000 Subject: [PATCH 6/6] Fix moniker ranges to eliminate duplicate headers Co-authored-by: tdykstra <1569635+tdykstra@users.noreply.github.com> --- aspnetcore/fundamentals/servers/kestrel.md | 11 +--- .../servers/kestrel/includes/kestrel6.md | 62 ++++++++++++++++++- 2 files changed, 62 insertions(+), 11 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index dd395ec53859..e29d1adfea3d 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -14,7 +14,7 @@ uid: fundamentals/servers/kestrel By [Tom Dykstra](https://github.com/tdykstra), [Chris Ross](https://github.com/Tratcher), and [Stephen Halter](https://twitter.com/halter73) -:::moniker range=">= aspnetcore-8.0" +:::moniker range=">= aspnetcore-10.0" Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index). Kestrel is the recommended server for ASP.NET Core, and it's configured by default in ASP.NET Core project templates. @@ -33,17 +33,8 @@ Kestrel's features include: * Building a reverse proxy with [YARP](https://github.com/microsoft/reverse-proxy). * **Extensibility:** Customize Kestrel through configuration, middleware, and custom transports. * **Performance diagnostics:** Kestrel provides built-in performance diagnostics features, such as logging and metrics. - -:::moniker-end - -:::moniker range=">= aspnetcore-10.0" - * **Memory management:** Kestrel includes features for efficient memory management. For more information, see . -:::moniker-end - -:::moniker range=">= aspnetcore-8.0" - ## Get started ASP.NET Core project templates use Kestrel by default when not hosted with IIS. In the following template-generated `Program.cs`, the method calls internally: diff --git a/aspnetcore/fundamentals/servers/kestrel/includes/kestrel6.md b/aspnetcore/fundamentals/servers/kestrel/includes/kestrel6.md index 720b4e9a7919..733f32e39b29 100644 --- a/aspnetcore/fundamentals/servers/kestrel/includes/kestrel6.md +++ b/aspnetcore/fundamentals/servers/kestrel/includes/kestrel6.md @@ -1,4 +1,64 @@ -:::moniker range=">= aspnetcore-6.0 <=aspnetcore-9.0" +:::moniker range=">= aspnetcore-8.0 <= aspnetcore-9.0" + +Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index). Kestrel is the recommended server for ASP.NET Core, and it's configured by default in ASP.NET Core project templates. + +Kestrel's features include: + +* **Cross-platform:** Kestrel is a cross-platform web server that runs on Windows, Linux, and macOS. +* **High performance:** Kestrel is optimized to handle a large number of concurrent connections efficiently. +* **Lightweight:** Optimized for running in resource-constrained environments, such as containers and edge devices. +* **Security hardened:** Kestrel supports HTTPS and is hardened against web server vulnerabilities. +* **Wide protocol support:** Kestrel supports common web protocols, including: + * HTTP/1.1, [HTTP/2](xref:fundamentals/servers/kestrel/http2) and [HTTP/3](xref:fundamentals/servers/kestrel/http3) + * [WebSockets](xref:fundamentals/websockets) +* **Integration with ASP.NET Core:** Seamless integration with other ASP.NET Core components, such as the middleware pipeline, dependency injection, and configuration system. +* **Flexible workloads**: Kestrel supports many workloads: + * ASP.NET app frameworks such as Minimal APIs, MVC, Razor pages, SignalR, Blazor, and gRPC. + * Building a reverse proxy with [YARP](https://github.com/microsoft/reverse-proxy). +* **Extensibility:** Customize Kestrel through configuration, middleware, and custom transports. +* **Performance diagnostics:** Kestrel provides built-in performance diagnostics features, such as logging and metrics. + +## Get started + +ASP.NET Core project templates use Kestrel by default when not hosted with IIS. In the following template-generated `Program.cs`, the method calls internally: + +:::code language="csharp" source="~/fundamentals/servers/kestrel/samples/6.x/KestrelSample/Program.cs" id="snippet_CreateBuilder" highlight="1"::: + +For more information on configuring `WebApplication` and `WebApplicationBuilder`, see . + +## Behavior with debugger attached + +The following timeouts and rate limits aren't enforced when a debugger is attached to a Kestrel process: + +* +* +* +* +* +* +* + +## Additional resources + + +* + +* + +* + +* + +* +* +* +* +* [RFC 9110: HTTP Semantics (Section 7.2: Host and :authority)](https://www.rfc-editor.org/rfc/rfc9110#field.host) +* When using UNIX sockets on Linux, the socket isn't automatically deleted on app shutdown. For more information, see [this GitHub issue](https://github.com/dotnet/aspnetcore/issues/14134). + +:::moniker-end + +:::moniker range=">= aspnetcore-6.0 < aspnetcore-8.0" Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index). Kestrel is the web server that's included and enabled by default in ASP.NET Core project templates.