Edit

Share via

Use ASP.NET Core with HTTP/2 on IIS

  • Article

Note

This isn't the latest version of this article. For the current release, see the .NET 8 version of this article.

Warning

This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.

Important

This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

For the current release, see the .NET 8 version of this article.

By Justin Kotalik

HTTP/2 is supported with ASP.NET Core in the following IIS deployment scenarios:

  • Windows Server 2016 or later / Windows 10 or later
  • IIS 10 or later
  • TLS 1.2 or later connection
  • When hosting out-of-process: Public-facing edge server connections use HTTP/2, but the reverse proxy connection to the Kestrel server uses HTTP/1.1.

For an in-process deployment when an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2. For an out-of-process deployment when an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/1.1.

For more information on the in-process and out-of-process hosting models, see ASP.NET Core Module (ANCM) for IIS.

HTTP/2 is enabled by default for HTTPS/TLS connections. Connections fall back to HTTP/1.1 if an HTTP/2 connection isn't established. For more information on HTTP/2 configuration with IIS deployments, see HTTP/2 on IIS.

Advanced HTTP/2 features to support gRPC

Additional HTTP/2 features in IIS support gRPC, including support for response trailers and sending reset frames.

Requirements to run gRPC on IIS:

  • In-process hosting.
  • Windows 11 Build 22000 or later, Windows Server 2022 Build 20348 or later.
  • TLS 1.2 or later connection.

Trailers

HTTP Trailers are similar to HTTP Headers, except they are sent after the response body is sent. For IIS and HTTP.sys, only HTTP/2 response trailers are supported.

if (httpContext.Response.SupportsTrailers())
{
    httpContext.Response.DeclareTrailer("trailername");	

    // Write body
    httpContext.Response.WriteAsync("Hello world");

    httpContext.Response.AppendTrailer("trailername", "TrailerValue");
}

In the preceding example code:

  • SupportsTrailers ensures that trailers are supported for the response.
  • DeclareTrailer adds the given trailer name to the Trailer response header. Declaring a response's trailers is optional, but recommended. If DeclareTrailer is called, it must be before the response headers are sent.
  • AppendTrailer appends the trailer.

Reset

Reset allows for the server to reset a HTTP/2 request with a specified error code. A reset request is considered aborted.

var resetFeature = httpContext.Features.Get<IHttpResetFeature>();
resetFeature.Reset(errorCode: 2);

Reset in the preceding code example specifies the INTERNAL_ERROR error code. For more information about HTTP/2 error codes, visit the HTTP/2 specification error code section.