Compressão de resposta no ASP.NET Core

A largura de banda da rede é um recurso limitado. Reduzir o tamanho da resposta geralmente aumenta a capacidade de resposta de um aplicativo, muitas vezes dramaticamente. Uma maneira de reduzir o tamanho da carga útil é compactar as respostas de um aplicativo.

Compressão com HTTPS

Respostas compactadas em conexões seguras podem ser controladas com a opção EnableForHttps, que é 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 ataques BREACH. Ataques como CRIME e BREACH podem ser mitigados no ASP.NET Core com tokens antifalsificação. Para obter mais informações, consulte Impedir ataques de falsificação de solicitação entre sites (XSRF/CSRF) no ASP.NET Core. Para obter informações sobre como atenuar BREACH ataques, consulte mitigações em http://www.breachattack.com/

Mesmo quando EnableForHttps está desabilitado no aplicativo, o IIS, o IIS Express e o Serviço de Aplicativo do Azure podem aplicar gzip no servidor Web do IIS. Ao revisar cabeçalhos de resposta, anote o valor Server . Um valor de cabeçalho de resposta inesperado content-encoding pode ser o resultado do servidor Web e não a 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 compressão de resposta provavelmente não corresponderá ao dos módulos do servidor. HTTP.sys servidor e Kestrel servidor não oferecem atualmente suporte de compressão incorporado.

Use o middleware de compactação de resposta quando o aplicativo for:

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

Compressão de resposta

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

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

Accept-Encoding valores de cabeçalho	Middleware suportado	Description
br	Sim (padrão)	Formato de dados comprimidos Brotli
deflate	No	DEFLATE formato de dados compactados
exi	No	Intercâmbio XML eficiente do W3C
gzip	Yes	Formato de arquivo Gzip
identity	Yes	Identificador "Sem codificação": A resposta não deve ser codificada.
pack200-gzip	No	Formato de transferência de rede para arquivos Java
*	Yes	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 compressão de resposta permite adicionar provedores adicionais de compactação para valores personalizados no cabeçalho Accept-Encoding. Para obter mais informações, consulte Provedores personalizados neste artigo.

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

Os algoritmos de compressão estão sujeitos a um equilíbrio entre a velocidade de compressão e a eficácia da compressão. A eficácia neste contexto refere-se ao tamanho da saída após a compressão. O menor tamanho é alcançado pela compressão ideal.

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

Header	Role
Accept-Encoding	Enviado do cliente para o servidor para indicar os esquemas de codificação de conteúdo aceitáveis para o cliente.
Content-Encoding	É enviado do servidor para o cliente para indicar a codificação do conteúdo na carga útil.
Content-Length	Quando a compressão ocorre, o Content-Length cabeçalho é removido, porque o conteúdo do corpo do texto muda quando a resposta é comprimida.
Content-MD5	Quando ocorre a compactação, o Content-MD5 cabeçalho é removido, uma vez que 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 o 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 deve armazenar em cache (variar) as respostas com base no valor do cabeçalho Accept-Encoding da solicitação. O resultado do retorno de conteúdo com o Vary: Accept-Encoding cabeçalho é que as respostas compactadas e não compactadas são armazenadas em cache separadamente.

Explore os recursos do middleware de compactação de resposta com o aplicativo de exemplo. A amostra ilustra:

• A compactação de respostas de aplicações usando Gzip e fornecedores de compactação personalizados.
• Como adicionar um tipo MIME à lista padrão de tipos MIME para compactação.
• Como adicionar um provedor de compactação de resposta personalizado.

Configuration

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();

Notes:

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

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

Por exemplo, no Firefox Developer:

• Selecione a aba Rede.
• Clique com o botão direito do mouse na solicitação na lista Solicitação de rede e selecione Editar e reenviar
• Mudar 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 está compactada. Os cabeçalhos Content-Encoding e Vary estão presentes na resposta.

Providers

Provedores de compressão Brotli e Gzip

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

Se nenhum provedor de compactação for explicitamente adicionado ao 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 compressão predefinida é Brotli quando o formato de dados comprimidos Brotli é suportado pelo cliente. Se a compressão Brotli não for suportada pelo cliente, a compressão padrão será Gzip quando o cliente suportar a compressão Gzip.

Note

Os links de documentação para a fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma tag para uma versão específica, use a lista suspensa Alternar entre ramificações ou tags. Para obter mais informações, consulte Como selecionar uma marca de versão do código-fonte 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:

• Permite a compactação de resposta para solicitações HTTPS.
• Adiciona os provedores de compressã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 compressão com BrotliCompressionProviderOptions e GzipCompressionProviderOptions. Os provedores de compressão Brotli e Gzip usam 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 desejada, configure o middleware de compactação de resposta para uma compactação ideal.

Consulte CompressionLevel Enum para obter valores que indicam se uma operação de compressão enfatiza a velocidade ou o tamanho da compressã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();

Fornecedores personalizados

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

As solicitações para o aplicativo de exemplo com o Accept-Encoding: mycustomcompression cabeçalho retornam uma resposta com um Content-Encoding: mycustomcompression cabeçalho. 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 personalizado.

Tipos MIME

O middleware de compressã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 suportados.

Note

Os links de documentação para a fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma tag para uma versão específica, use a lista suspensa Alternar entre ramificações ou tags. Para obter mais informações, consulte Como selecionar uma marca de versão do código-fonte ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Substitua ou acrescente tipos MIME por ResponseCompressionOptions.MimeTypes. Note que os tipos MIME curinga, como text/*, não são suportados. O aplicativo de exemplo adiciona um tipo MIME para image/svg+xml , compacta e serve a imagem de banner ASP.NET Core banner.svg.

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();

Adicionando o cabeçalho Vary

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

Note

Os links de documentação para a fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma tag para uma versão específica, use a lista suspensa Alternar entre ramificações ou tags. Para obter mais informações, consulte Como selecionar uma marca de versão do código-fonte ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Problema de middleware quando atrás de um proxy reverso Nginx

Quando uma solicitação é encaminhada pelo Nginx, o cabeçalho Accept-Encoding é removido. A remoção do cabeçalho Accept-Encoding impede que o middleware de compressão da resposta comprima a resposta. Para obter mais informações, consulte NGINX: Compactação e descompressão. Esse problema é rastreado pela compactação de passagem Figure out para Nginx (dotnet/aspnetcore#5989).

Desativando 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 Desabilitando módulos do IIS.

Solucionar problemas de compactação de resposta

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

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

Exemplo implantado no Azure

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

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

Note

Os links de documentação para a fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma tag para uma versão específica, use a lista suspensa Alternar entre ramificações ou tags. Para obter mais informações, consulte Como selecionar uma marca de versão do código-fonte ASP.NET Core (dotnet/AspNetCore.Docs #26205).

• Visualizar ou descarregar amostra de código (como descarregar)
• Origem do middleware de compressão de resposta
• ASP.NET Middleware principal
• Mozilla Developer Network: Aceitação-Codificação
• RFC 9110 Seção 8.4.1: Codificação 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