Compartilhar via


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:

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:

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).

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.

Exibir ou baixar código de exemplo (como baixar)

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 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:

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. Você não deve fazer compactação de ativos compactados nativamente, como arquivos PNG. Se estiver tentando 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 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 permite adicionar provedores de compactação adicionais para valores de cabeçalho Accept-Encoding personalizados. Para obter mais informações, consulte Provedores personalizados abaixo.

O middleware é 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 abaixo.

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 verifica esse valor para determinar se a resposta deve ser compactada. O middleware especifica um conjunto de tipos MIME padrão que ele pode codificar, mas você pode substituir ou adicionar tipos MIME.
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.

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):

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddResponseCompression();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        app.UseResponseCompression();
    }
}

Observaçõ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 Fiddler, Firefox Browser Developer para definir o cabeçalho Accept-Encoding da solicitação e estudar 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. Os cabeçalhos Content-Encoding e Vary não estão presentes na resposta.

Janela do Fiddler mostrando o resultado de uma solicitação sem o cabeçalho Accept-Encoding. A resposta não está compactada.

Envie uma solicitação para o aplicativo de exemplo com o cabeçalho Accept-Encoding: br (compactação Brotli) e observe que a resposta é compactada. Os cabeçalhos Content-Encoding e Vary estão presentes na resposta.

Janela do Fiddler mostrando o resultado de uma solicitação com o cabeçalho Accept-Encoding e o valor br. Os cabeçalhos Vary e Content-Encoding são adicionados à resposta. A resposta é compactada.

Provedores

Provedor de Compactação Brotli

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 é adicionado por padrão à matriz de provedores de compactação junto com o provedor de compactação Gzip.
  • 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.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();
}

O Provedor de Compactação Brotli deve ser adicionado quando quaisquer provedores de compactação são adicionados explicitamente:

public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression(options =>
    {
        options.Providers.Add<BrotliCompressionProvider>();
        options.Providers.Add<GzipCompressionProvider>();
        options.Providers.Add<CustomCompressionProvider>();
        options.MimeTypes = 
            ResponseCompressionDefaults.MimeTypes.Concat(
                new[] { "image/svg+xml" });
    });
}

Defina o nível de compactação com o BrotliCompressionProviderOptions. O Provedor de Compactação Brotli assume 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 para a compactação ideal.

Nível de Compactação Descrição
CompressionLevel.Fastest A compactação deve ser concluída o mais rápido possível, mesmo se a saída resultante não for compactada de forma ideal.
CompressionLevel.NoCompression Nenhuma compactação deve ser executada no arquivo.
CompressionLevel.Optimal As respostas devem ser compactadas de forma ideal, mesmo se a compactação demorar mais tempo para ser concluída.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();

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

Provedor de Compactação Gzip

Use o GzipCompressionProvider para compactar respostas com o formato de arquivo Gzip.

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

  • O Provedor de Compactação Gzip é adicionado por padrão à matriz de provedores de compactação junto com o Provedor de Compactação Brotli.
  • 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.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();
}

O Provedor de Compactação Gzip deve ser adicionado quando quaisquer provedores de compactação são adicionados explicitamente:

public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression(options =>
    {
        options.Providers.Add<BrotliCompressionProvider>();
        options.Providers.Add<GzipCompressionProvider>();
        options.Providers.Add<CustomCompressionProvider>();
        options.MimeTypes = 
            ResponseCompressionDefaults.MimeTypes.Concat(
                new[] { "image/svg+xml" });
    });
}

Defina o nível de compactação com o GzipCompressionProviderOptions. O Provedor de Compactação Gzip assume 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 para a compactação ideal.

Nível de Compactação Descrição
CompressionLevel.Fastest A compactação deve ser concluída o mais rápido possível, mesmo se a saída resultante não for compactada de forma ideal.
CompressionLevel.NoCompression Nenhuma compactação deve ser executada no arquivo.
CompressionLevel.Optimal As respostas devem ser compactadas de forma ideal, mesmo se a compactação demorar mais tempo para ser concluída.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();

    services.Configure<GzipCompressionProviderOptions>(options => 
    {
        options.Level = CompressionLevel.Fastest;
    });
}

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 usa essas informações para escolher o provedor com base na lista especificada no cabeçalho Accept-Encoding da solicitação.

Usando o aplicativo de exemplo, o cliente envia uma solicitação com o cabeçalho Accept-Encoding: mycustomcompression. O middleware usa a implementação de compactação personalizada e retorna a 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.

public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression(options =>
    {
        options.Providers.Add<BrotliCompressionProvider>();
        options.Providers.Add<GzipCompressionProvider>();
        options.Providers.Add<CustomCompressionProvider>();
        options.MimeTypes = 
            ResponseCompressionDefaults.MimeTypes.Concat(
                new[] { "image/svg+xml" });
    });
}
public class CustomCompressionProvider : ICompressionProvider
{
    public string EncodingName => "mycustomcompression";
    public bool SupportsFlush => true;

    public Stream CreateStream(Stream outputStream)
    {
        // Create a custom compression stream wrapper here
        return outputStream;
    }
}

Envie uma solicitação para o aplicativo de exemplo com o cabeçalho Accept-Encoding: mycustomcompression e observe os cabeçalhos de resposta. Os cabeçalhos Vary e Content-Encoding estão presentes na resposta. O corpo da resposta (não mostrado) não é compactado pelo exemplo. Não há uma implementação de compactação na classe do CustomCompressionProvider do exemplo. No entanto, o exemplo mostra onde você implementaria esse algoritmo de compactação.

Janela do Fiddler mostrando o resultado de uma solicitação com o cabeçalho Accept-Encoding e o valor de mycustomcompressiondos. Os cabeçalhos Vary e Content-Encoding são adicionados à resposta.

tipos MIME

O middleware especifica um conjunto padrão de tipos MIME para a compactação:

  • application/javascript
  • application/json
  • application/xml
  • text/css
  • text/html
  • text/json
  • text/plain
  • text/xml

Acrescente ou substitua tipos MIME pelas opções de Middleware de Compactação de Resposta. 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.

public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression(options =>
    {
        options.Providers.Add<BrotliCompressionProvider>();
        options.Providers.Add<GzipCompressionProvider>();
        options.Providers.Add<CustomCompressionProvider>();
        options.MimeTypes = 
            ResponseCompressionDefaults.MimeTypes.Concat(
                new[] { "image/svg+xml" });
    });
}

Compactação com protocolo seguro

As respostas compactadas em conexões seguras podem ser controladas com a opção EnableForHttps, que está desabilitada por padrão. O uso da compactação com páginas geradas dinamicamente pode resultar em problemas de segurança, como os ataques CRIME e BREACH.

Adicionar o cabeçalho Vary

Ao compactar respostas com base no cabeçalho Accept-Encoding, há potencialmente várias versões compactadas da resposta e uma versão descompactada. 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. No ASP.NET Core 2.0 ou posterior, o middleware adiciona o cabeçalho Vary automaticamente quando a resposta é compactada.

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 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).

Trabalhar com a compactação dinâmica do IIS

Se você tiver um Módulo de Compactação Dinâmica do IIS ativo configurado no nível do servidor que deseja desabilitar para um aplicativo, desabilite o módulo com uma adição ao arquivo web.config . Para obter mais informações, consulte Desabilitando módulos do IIS.

Solução de problemas

Use uma ferramenta como o Fiddler ou Firefox Browser Developer que permitem definir o cabeçalho Accept-Encoding da solicitação e estudar os cabeçalhos, tamanho e corpo de 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 que você estabeleceu. 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.

Recursos adicionais