Compactação de resposta no ASP.NET Core

A largura de banda de rede é um recurso limitado. A redução do tamanho da resposta geralmente aumenta a capacidade de resposta de um aplicativo, muitas vezes dramaticamente. Uma maneira de reduzir os tamanhos de carga é compactar as respostas de um aplicativo.

Compactação com HTTPS

As respostas compactadas em conexões seguras podem ser controladas com a opção EnableForHttps, que está desabilitada por padrão devido ao risco de segurança. O uso da compactação com páginas geradas dinamicamente pode expor o aplicativo a ataques CRIME e BREACH. Os ataques CRIME e BREACH podem ser mitigados no ASP.NET Core com tokens antifalsificação. Para obter mais informações, consulte Impedir ataques de XSRF/CSRF (solicitação intersite forjada) no ASP.NET Core. Para obter informações sobre como mitigar ataques BREACH, consulte mitigações em http://www.breachattack.com/

Mesmo quando EnableForHttps está desabilitado no aplicativo, o IIS, IIS Express e Serviço de Aplicativo do Azure podem aplicar o gzip no servidor Web do IIS. Ao revisar os cabeçalhos de resposta, anote o valor do Servidor. Um valor de cabeçalho de resposta content-encoding inesperado pode ser o resultado do servidor Web e não da configuração do aplicativo ASP.NET Core.

Quando usar o middleware de compactação de resposta

Use tecnologias de compactação de resposta baseadas em servidor no IIS, Apache ou Nginx. O desempenho do middleware de compactação de resposta provavelmente não corresponde ao desempenho dos módulos do servidor. O servidor HTTP.sys e o servidor Kestrel não oferecem suporte à compactação integrada no momento.

Use o Middleware de Compactação de Resposta quando o aplicativo:

• Não é possível usar as seguintes tecnologias de compactação baseadas em servidor:
  • Módulo de compactação Dinâmica do IIS
  • Módulo mod_deflate do Apache
  • Descompactação e compactação do Nginx
• Hospedagem diretamente no:
  • Servidor HTTP.sys
  • Servidor Kestrel

Compactação de resposta

Normalmente, qualquer resposta não compactada nativamente pode se beneficiar da compactação de resposta. As respostas não compactadas de forma nativa normalmente incluem CSS, JavaScript, HTML, XML e JSON. Não faça compactação de ativos compactados nativamente, como arquivos PNG. Ao tentar compactar ainda mais uma resposta compactada nativamente, qualquer redução adicional no tamanho e no tempo de transmissão provavelmente será ofuscada pelo tempo necessário para processar a compactação. Não faça compactação de arquivos menores que cerca de 150 a 1.000 bytes, dependendo do conteúdo do arquivo e da eficiência da compactação. A sobrecarga de compactação de arquivos pequenos pode produzir um arquivo compactado maior que o arquivo descompactado.

Quando um cliente pode processar o conteúdo compactado, o cliente deve informar o servidor de seus recursos enviando o cabeçalho Accept-Encoding com a solicitação. Quando um servidor envia conteúdo compactado, ele deve incluir informações no cabeçalho Content-Encoding sobre como a resposta compactada é codificada. As designações de codificação de conteúdo compatíveis com o middleware de compactação de resposta são mostradas na tabela a seguir.

Valores do cabeçalho Accept-Encoding	Middleware com suporte	Descrição
br	Sim (padrão)	Formato de dados compactados Brotli
deflate	Não	Formato de dados compactados DEFLATE
exi	No	Efficient XML Interchange da W3C
gzip	Sim	Formato de arquivo Gzip
identity	Sim	Identificador “Sem codificação”: a resposta não deve ser codificada.
pack200-gzip	No	Formato de transferência de rede para arquivos Java
*	Sim	Qualquer codificação de conteúdo disponível não solicitada explicitamente

Para obter mais informações, consulte a Lista de Codificação de Conteúdo Oficial da IANA.

O middleware de compactação de resposta permite adicionar provedores de compactação adicionais para valores de cabeçalho Accept-Encoding personalizados. Para obter mais informações, consulte Provedores personalizados neste artigo.

O middleware de compactação de resposta é capaz de reagir à ponderação de valor de qualidade (qvalue, q) quando enviado pelo cliente para priorizar esquemas de compactação. Para obter mais informações, confira RFC 9110: Accept-Encoding.

Os algoritmos de compactação estão sujeitos a uma compensação entre a velocidade de compactação e a eficácia da compactação. A eficácia nesse contexto se refere ao tamanho da saída após a compactação. O menor tamanho é obtido pela compactação ideal.

Os cabeçalhos envolvidos na solicitação, envio, cache e recebimento de conteúdo compactado são descritos na tabela a seguir.

parâmetro	Função
Accept-Encoding	Enviado do cliente ao servidor para indicar os esquemas de codificação de conteúdo aceitáveis para o cliente.
Content-Encoding	Enviado do servidor ao cliente para indicar a codificação do conteúdo na carga.
Content-Length	Quando ocorre compactação, o cabeçalho Content-Length é removido, pois o conteúdo do corpo é alterado quando a resposta é compactada.
Content-MD5	Quando ocorre compactação, o cabeçalho Content-MD5 é removido, pois o conteúdo do corpo foi alterado e o hash não é mais válido.
Content-Type	Especifica o tipo MIME do conteúdo. Cada resposta deve especificar seu Content-Type. O middleware de compactação de resposta verifica esse valor para determinar se a resposta deve ser compactada. O middleware de compactação de resposta especifica um conjunto de tipos MIME padrão que ele pode codificar e eles podem ser substituídos ou adicionados.
Vary	Quando enviado pelo servidor com um valor de Accept-Encoding para clientes e proxies, o cabeçalho Vary indica ao cliente ou proxy que ele deve armazenar em cache (vary) as respostas com base no valor do cabeçalho Accept-Encoding da solicitação. O resultado do retorno de conteúdo com o cabeçalho Vary: Accept-Encoding é que as respostas compactadas e descompactadas são armazenadas em cache separadamente.

Explore os recursos do Middleware de Compactação de Resposta com o aplicativo de exemplo. O exemplo ilustra:

• A compactação de respostas do aplicativo usando Gzip e provedores de compactação personalizada.
• Como adicionar um tipo MIME à lista padrão de tipos MIME para compactação.
• Como adicionar um provedor de compactação de resposta personalizada.

Configuração

O código a seguir mostra como habilitar o Middleware de Compactação de Resposta para tipos MIME padrão e provedores de compactação (Brotli e Gzip):

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
});

var app = builder.Build();

app.UseResponseCompression();

app.MapGet("/", () => "Hello World!");

app.Run();

Observações:

• Configurar EnableForHttps para true é um risco à segurança. Consulte Compactação com HTTPS neste artigo para obter mais informações.
• A app.UseResponseCompression deve ser chamada antes de qualquer middleware que compacte as respostas. Para obter mais informações, confira Middleware do ASP.NET Core.
• Use uma ferramenta como o Firefox Browser Developer para definir o cabeçalho Accept-Encoding da solicitação e examinar os cabeçalhos, tamanho e corpo de resposta.

Envie uma solicitação para o aplicativo de exemplo sem o cabeçalho Accept-Encoding e observe que a resposta é descompactada. O cabeçalho Content-Encoding não está na coleção Cabeçalhos de Resposta.

Por exemplo, no Firefox Developer:

• Selecione a guia rede.
• Clique com o botão direito do mouse na solicitação na Lista de solicitação de rede e selecione Editar e reenviar
• Altere Accept-Encoding: de gzip, deflate, br para none.
• Selecione Enviar.

Envie uma solicitação para o aplicativo de exemplo com um navegador usando as ferramentas de desenvolvedor e observe que a resposta é compactada. Os cabeçalhos Content-Encoding e Vary estão presentes na resposta.

Provedores

Provedores de compactação Brotli e Gzip

Use o BrotliCompressionProvider para compactar respostas com o formato de dados compactado Brotli.

Se nenhum provedor de compactação for adicionado explicitamente à CompressionProviderCollection:

• O provedor de compactação Brotli e o provedor de compactação Gzip são adicionados por padrão à matriz de provedores de compactação.
• A compactação usa como padrão a compactação Brotli quando há suporte para o formato de dados compactado Brotli pelo cliente. Se o Brotli não tiver suporte no cliente, a compactação usará o Gzip como padrão quando o cliente der suporte à compactação Gzip.

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Quando um provedor de compactação é adicionado, outros provedores não são adicionados. Por exemplo, se o provedor de compactação Gzip for o único provedor explicitamente adicionado, nenhum outro provedor de compactação será adicionado.

O seguinte código:

• Habilita a compactação de resposta para solicitações HTTPS.
• Adiciona os provedores de compactação de resposta Brotli e Gzip.

using System.IO.Compression;
using Microsoft.AspNetCore.ResponseCompression;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
});

builder.Services.Configure<BrotliCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.Fastest;
});

builder.Services.Configure<GzipCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.SmallestSize;
});

var app = builder.Build();

app.UseResponseCompression();

app.MapGet("/", () => "Hello World!");

app.Run();

Defina o nível de compactação com o BrotliCompressionProviderOptions e o GzipCompressionProviderOptions. Os provedores de compactação Brotli e Gzip assumem como padrão o nível de compactação mais rápido, CompressionLevel.Fastest, que pode não produzir a compactação mais eficiente. Se a compactação mais eficiente for a desejada, configure o middleware de compactação de resposta para a compactação ideal.

Consulte Enumeração do CompressionLevel para obter os valores que indicam se uma operação de compactação enfatiza a velocidade ou tamanho da compactação.

using System.IO.Compression;
using Microsoft.AspNetCore.ResponseCompression;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
});

builder.Services.Configure<BrotliCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.Fastest;
});

builder.Services.Configure<GzipCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.SmallestSize;
});

var app = builder.Build();

app.UseResponseCompression();

app.MapGet("/", () => "Hello World!");

app.Run();

Provedores personalizados

Crie implementações de compactação personalizadas com ICompressionProvider. O EncodingName representa a codificação de conteúdo que esse ICompressionProvider produz. O middleware de compactação de resposta usa essas informações para escolher o provedor com base na lista especificada no cabeçalho Accept-Encoding da solicitação.

As solicitações para o aplicativo de exemplo com o cabeçalho Accept-Encoding: mycustomcompression retornam uma resposta com um cabeçalho Content-Encoding: mycustomcompression. O cliente deve ser capaz de descompactar a codificação personalizada para que uma implementação de compactação personalizada funcione.

using Microsoft.AspNetCore.ResponseCompression;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
    options.Providers.Add<CustomCompressionProvider>();
});

var app = builder.Build();

app.UseResponseCompression();

app.MapGet("/", () => "Hello World!");

app.Run();

using Microsoft.AspNetCore.ResponseCompression;

public class CustomCompressionProvider : ICompressionProvider
{
    public string EncodingName => "mycustomcompression";
    public bool SupportsFlush => true;

    public Stream CreateStream(Stream outputStream)
    {
        // Replace with a custom compression stream wrapper.
        return outputStream;
    }
}

Com o código anterior, o corpo da resposta não é compactado pelo exemplo. No entanto, o exemplo mostra onde implementar um algoritmo de compactação personalizada.

tipos MIME

O middleware de compactação de resposta especifica um conjunto padrão de tipos MIME para compactação. Consulte o código-fonte para obter uma lista completa dos tipos MIME com suporte.

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Substitua ou acrescente tipos MIME por ResponseCompressionOptions.MimeTypes. Observe que não há suporte para tipos MIME curinga, como text/* . O aplicativo de exemplo adiciona um tipo MIME para image/svg+xml e compacta e fornece a imagem de banner banner.svg ao ASP.NET Core.

using Microsoft.AspNetCore.ResponseCompression;
using ResponseCompressionSample;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
    options.Providers.Add<CustomCompressionProvider>();
    options.MimeTypes =
    ResponseCompressionDefaults.MimeTypes.Concat(
        new[] { "image/svg+xml" });
});

var app = builder.Build();

app.UseResponseCompression();

Adicionar o cabeçalho Vary

Ao compactar respostas com base no cabeçalho Accept-Encoding da solicitação, pode haver versões descompactadas e várias compactadas da resposta. Para instruir caches de cliente e proxy que essas várias versões existem e devem ser armazenadas, o cabeçalho Vary é adicionado com um valor Accept-Encoding. O middleware de resposta adiciona o cabeçalho Vary automaticamente quando a resposta é compactada.

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Problema de middleware quando está por trás de um proxy reverso do Nginx

Quando uma solicitação é feita com proxy pelo Nginx, o cabeçalho Accept-Encoding é removido. A remoção do cabeçalho Accept-Encoding impede que o middleware de compactação de resposta compacte a resposta. Para obter mais informações, consulte NGINX: Compactação e Descompactação. Esse problema é acompanhado por Descobrir compactação de passagem para Nginx (dotnet/aspnetcore#5989).

Desabilitar a compactação dinâmica do IIS

Para desabilitar o Módulo de Compactação Dinâmica do IIS configurado no nível do servidor, consulte Desabilitar módulos do IIS.

Solucionar problemas da compactação de resposta

Use uma ferramenta como o Firefox Browser Developer, que permite definir o cabeçalho Accept-Encoding da solicitação e estudar os cabeçalhos, o tamanho e o corpo da resposta. Por padrão, o Middleware de Compactação de Resposta compacta as respostas que atendem às seguintes condições:

• O cabeçalho Accept-Encoding está presente com um valor de br, gzip, * ou uma codificação personalizada que corresponde a um provedor de compactação personalizada. O valor não deve ser identity ou ter um valor de qualidade (qvalue, q) de 0 (zero).
• O tipo MIME (Content-Type) deve ser definido e deve corresponder a um tipo MIME configurado nas ResponseCompressionOptions.
• As solicitações devem incluir o cabeçalho Content-Range.
• A solicitação deve usar o protocolo não seguro (http), a menos que o protocolo seguro (https) esteja configurado nas opções de Middleware de Compactação de Resposta. Observe o perigo descrito acima ao habilitar a compactação de conteúdo seguro.

Exemplo implantado do Azure

O aplicativo de exemplo implantado no Azure tem o seguinte arquivo Program.cs:

using Microsoft.AspNetCore.ResponseCompression;
using ResponseCompressionSample;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
    options.Providers.Add<CustomCompressionProvider>();
    options.MimeTypes =
    ResponseCompressionDefaults.MimeTypes.Concat(
        new[] { "image/svg+xml" });
});

var app = builder.Build();

app.UseResponseCompression();

app.Map("/trickle", async (HttpResponse httpResponse) =>
{
    httpResponse.ContentType = "text/plain;charset=utf-8";

    for (int i = 0; i < 20; i++)
    {
        await httpResponse.WriteAsync("a");
        await httpResponse.Body.FlushAsync();
        await Task.Delay(TimeSpan.FromMilliseconds(50));
    }
});

app.Map("/testfile1kb.txt", () => Results.File(
    app.Environment.ContentRootFileProvider.GetFileInfo("testfile1kb.txt").PhysicalPath,
    "text/plain;charset=utf-8"));

app.Map("/banner.svg", () => Results.File(
    app.Environment.ContentRootFileProvider.GetFileInfo("banner.svg").PhysicalPath,
    "image/svg+xml;charset=utf-8"));

app.MapFallback(() => LoremIpsum.Text);

app.Run();

Recursos adicionais

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

• Exibir ou baixar código de exemplo (como baixar)
• Fonte do middleware de compactação de resposta
• Middleware do ASP.NET Core
• Mozilla Developer Network: Accept-Encoding
• RFC 9110 Seção 8.4.1: Codificações de conteúdo
• RFC 9110 Seção 8.4.1.3: Codificação Gzip
• Especificação do formato de arquivo GZIP versão 4.3