Usar HTTP/2 com o servidor Web Kestrel de ASP.NET Core

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

O HTTP/2 estará disponível para aplicativos ASP.NET Core se os seguintes requisitos básicos forem atendidos:

  • Sistema operacional
    • Windows Server 2016/Windows 10 ou posterior‡
    • Linux com OpenSSL 1.0.2 ou posterior (por exemplo, Ubuntu 16.04 ou posterior)
    • macOS 10.15 ou versões posteriores
  • Estrutura de destino: .NET Core 2.2 ou posterior
  • Conexão ALPN (Negociação de protocolo de camada de aplicativo)
  • Conexão TLS 1.2 ou posterior

‡Kestrel tem suporte limitado para HTTP/2 no Windows Server 2012 R2 e Windows 8.1. O suporte é limitado porque a lista de conjuntos de codificação TLS disponível nesses sistemas operacionais é limitada. Um certificado gerado usando um ECDSA (Algoritmo de Assinatura Digital Curva Elíptica) pode ser necessário para proteger conexões TLS.

Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/2.

A partir do .NET Core 3.0, o HTTP/2 está habilitado por padrão. Para obter mais informações sobre a configuração, confira as seções Kestrel Limites do HTTP/2 e ListenOptions.Protocols.

Recursos HTTP/2 avançados

Os recursos HTTP/2 adicionais no Kestrel dão suporte a gRPC, incluindo suporte para trailers de resposta e envio de quadros de redefinição.

Trailers

Os trailers HTTP são semelhantes aos cabeçalhos HTTP, exceto por serem enviados após o corpo da resposta ser enviado. Para IIS e HTTP.sys, há suporte apenas para trailers de resposta HTTP/2.

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

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

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

No código de exemplo anterior:

  • SupportsTrailers garante que os trailers sejam compatíveis com a resposta.
  • DeclareTrailer adiciona o nome do trailer fornecido ao cabeçalho de resposta Trailer. Declarar os trailers de uma resposta é opcional, mas recomendado. Se DeclareTrailer for chamado, deverá ser antes que os cabeçalhos de resposta sejam enviados.
  • O AppendTrailer acrescenta o trailer.

Redefinir

A opção Redefinir permite que o servidor redefina uma solicitação HTTP/2 com um código de erro especificado. Uma solicitação de redefinição é considerada anulada.

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

Reset no exemplo de código anterior especifica o código de erro INTERNAL_ERROR. Para obter mais informações sobre códigos de erro HTTP/2, visite a seção de código de erro de especificação HTTP/2.

O HTTP/2 estará disponível para aplicativos ASP.NET Core se os seguintes requisitos básicos forem atendidos:

  • Sistema operacional†
    • Windows Server 2016/Windows 10 ou posterior‡
    • Linux com OpenSSL 1.0.2 ou posterior (por exemplo, Ubuntu 16.04 ou posterior)
  • Estrutura de destino: .NET Core 2.2 ou posterior
  • Conexão ALPN (Negociação de protocolo de camada de aplicativo)
  • Conexão TLS 1.2 ou posterior

O HTTP/2 será compatível com macOS em uma versão futura. ‡Kestrel tem suporte limitado para HTTP/2 no Windows Server 2012 R2 e Windows 8.1. O suporte é limitado porque a lista de conjuntos de codificação TLS disponível nesses sistemas operacionais é limitada. Um certificado gerado usando um ECDSA (Algoritmo de Assinatura Digital Curva Elíptica) pode ser necessário para proteger conexões TLS.

Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/2.

A partir do .NET Core 3.0, o HTTP/2 está habilitado por padrão. Para obter mais informações sobre a configuração, confira as seções Kestrel Limites do HTTP/2 e ListenOptions.Protocols.

Recursos HTTP/2 avançados

Os recursos HTTP/2 adicionais no Kestrel dão suporte a gRPC, incluindo suporte para trailers de resposta e envio de quadros de redefinição.

Trailers

Os trailers HTTP são semelhantes aos cabeçalhos HTTP, exceto por serem enviados após o corpo da resposta ser enviado. Para IIS e HTTP.sys, há suporte apenas para trailers de resposta HTTP/2.

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

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

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

No código de exemplo anterior:

  • SupportsTrailers garante que os trailers sejam compatíveis com a resposta.
  • DeclareTrailer adiciona o nome do trailer fornecido ao cabeçalho de resposta Trailer. Declarar os trailers de uma resposta é opcional, mas recomendado. Se DeclareTrailer for chamado, deverá ser antes que os cabeçalhos de resposta sejam enviados.
  • O AppendTrailer acrescenta o trailer.

Redefinir

A opção Redefinir permite que o servidor redefina uma solicitação HTTP/2 com um código de erro especificado. Uma solicitação de redefinição é considerada anulada.

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

Reset no exemplo de código anterior especifica o código de erro INTERNAL_ERROR. Para obter mais informações sobre códigos de erro HTTP/2, visite a seção de código de erro de especificação HTTP/2.

O HTTP/2 estará disponível para aplicativos ASP.NET Core se os seguintes requisitos básicos forem atendidos:

  • Sistema operacional†
    • Windows Server 2016/Windows 10 ou posterior‡
    • Linux com OpenSSL 1.0.2 ou posterior (por exemplo, Ubuntu 16.04 ou posterior)
  • Estrutura de destino: .NET Core 2.2 ou posterior
  • Conexão ALPN (Negociação de protocolo de camada de aplicativo)
  • Conexão TLS 1.2 ou posterior

O HTTP/2 será compatível com macOS em uma versão futura. ‡Kestrel tem suporte limitado para HTTP/2 no Windows Server 2012 R2 e Windows 8.1. O suporte é limitado porque a lista de conjuntos de codificação TLS disponível nesses sistemas operacionais é limitada. Um certificado gerado usando um ECDSA (Algoritmo de Assinatura Digital Curva Elíptica) pode ser necessário para proteger conexões TLS.

Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/2.

A partir do .NET Core 3.0, o HTTP/2 está habilitado por padrão. Para obter mais informações sobre a configuração, confira as seções Kestrel Limites do HTTP/2 e ListenOptions.Protocols.

Recursos HTTP/2 avançados

Os recursos HTTP/2 adicionais no Kestrel dão suporte a gRPC, incluindo suporte para trailers de resposta e envio de quadros de redefinição.

Trailers

Os trailers HTTP são semelhantes aos cabeçalhos HTTP, exceto por serem enviados após o corpo da resposta ser enviado. Para IIS e HTTP.sys, há suporte apenas para trailers de resposta HTTP/2.

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

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

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

No código de exemplo anterior:

  • SupportsTrailers garante que os trailers sejam compatíveis com a resposta.
  • DeclareTrailer adiciona o nome do trailer fornecido ao cabeçalho de resposta Trailer. Declarar os trailers de uma resposta é opcional, mas recomendado. Se DeclareTrailer for chamado, deverá ser antes que os cabeçalhos de resposta sejam enviados.
  • O AppendTrailer acrescenta o trailer.

Redefinir

A opção Redefinir permite que o servidor redefina uma solicitação HTTP/2 com um código de erro especificado. Uma solicitação de redefinição é considerada anulada.

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

Reset no exemplo de código anterior especifica o código de erro INTERNAL_ERROR. Para obter mais informações sobre códigos de erro HTTP/2, visite a seção de código de erro de especificação HTTP/2.