Compactação de resposta no ASP.NET CoreResponse compression in ASP.NET Core

A largura de banda da rede é um recurso limitado.Network bandwidth is a limited resource. Reduzir o tamanho da resposta geralmente aumenta a capacidade de resposta de um aplicativo, muitas vezes drasticamente.Reducing the size of the response usually increases the responsiveness of an app, often dramatically. Uma maneira de reduzir os tamanhos de carga é compactar as respostas de um aplicativo.One way to reduce payload sizes is to compress an app's responses.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Quando usar o middleware de compactação de respostaWhen to use Response Compression Middleware

Use tecnologias de compactação de resposta baseadas em servidor no IIS, Apache ou nginx.Use server-based response compression technologies in IIS, Apache, or Nginx. O desempenho do middleware provavelmente não corresponderá ao dos módulos do servidor.The performance of the middleware probably won't match that of the server modules. Atualmente, o servidor do HTTP.sys Server e o Kestrel Server não oferecem suporte interno à compactação.HTTP.sys server server and Kestrel server don't currently offer built-in compression support.

Use o middleware de compactação de resposta quando você estiver:Use Response Compression Middleware when you're:

Compactação de respostaResponse compression

Normalmente, qualquer resposta não compactada nativamente pode se beneficiar da compactação de resposta.Usually, any response not natively compressed can benefit from response compression. As respostas não compactadas nativamente normalmente incluem: CSS, JavaScript, HTML, XML e JSON.Responses not natively compressed typically include: CSS, JavaScript, HTML, XML, and JSON. Você não deve compactar ativos compactados nativamente, como arquivos PNG.You shouldn't compress natively compressed assets, such as PNG files. Se você tentar compactar ainda mais uma resposta compactada nativamente, qualquer pequena redução adicional no tamanho e no tempo de transmissão provavelmente será ofuscada no tempo necessário para processar a compactação.If you attempt to further compress a natively compressed response, any small additional reduction in size and transmission time will likely be overshadowed by the time it took to process the compression. Não compacte arquivos com menos de 150-1000 bytes (dependendo do conteúdo do arquivo e da eficiência da compactação).Don't compress files smaller than about 150-1000 bytes (depending on the file's content and the efficiency of compression). A sobrecarga de compactação de arquivos pequenos pode produzir um arquivo compactado maior do que o arquivo descompactado.The overhead of compressing small files may produce a compressed file larger than the uncompressed file.

Quando um cliente pode processar conteúdo compactado, o cliente deve informar o servidor de seus recursos enviando o Accept-Encoding cabeçalho com a solicitação.When a client can process compressed content, the client must inform the server of its capabilities by sending the Accept-Encoding header with the request. Quando um servidor envia conteúdo compactado, ele deve incluir informações no Content-Encoding cabeçalho sobre como a resposta compactada é codificada.When a server sends compressed content, it must include information in the Content-Encoding header on how the compressed response is encoded. As designações de codificação de conteúdo com suporte no middleware são mostradas na tabela a seguir.Content encoding designations supported by the middleware are shown in the following table.

Accept-Encoding valores de cabeçalhoAccept-Encoding header values Suporte do middlewareMiddleware Supported DescriçãoDescription
br Sim (padrão)Yes (default) Formato de dados compactados BrotliBrotli compressed data format
deflate NãoNo Desinflar formato de dados compactadosDEFLATE compressed data format
exi NãoNo Intercâmbio de XML eficiente do W3CW3C Efficient XML Interchange
gzip YesYes Formato de arquivo gzipGzip file format
identity YesYes Identificador "sem codificação": a resposta não deve ser codificada."No encoding" identifier: The response must not be encoded.
pack200-gzip NãoNo Formato de transferência de rede para arquivos JavaNetwork Transfer Format for Java Archives
* YesYes Qualquer codificação de conteúdo disponível não explicitamente solicitadaAny available content encoding not explicitly requested

Para obter mais informações, consulte a lista de código de conteúdo oficial da IANA.For more information, see the IANA Official Content Coding List.

O middleware permite que você adicione outros provedores de compactação para Accept-Encoding valores de cabeçalho personalizados.The middleware allows you to add additional compression providers for custom Accept-Encoding header values. Para obter mais informações, consulte provedores personalizados abaixo.For more information, see Custom Providers below.

O middleware é capaz de reagir ao valor de qualidade (qvalue, q ) ponderado quando enviado pelo cliente para priorizar os esquemas de compactação.The middleware is capable of reacting to quality value (qvalue, q) weighting when sent by the client to prioritize compression schemes. Para obter mais informações, consulte RFC 7231: Accept-Encoding.For more information, see RFC 7231: 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.Compression algorithms are subject to a tradeoff between compression speed and the effectiveness of the compression. A eficácia neste contexto refere-se ao tamanho da saída após a compactação.Effectiveness in this context refers to the size of the output after compression. O menor tamanho é obtido pela compactação ideal .The smallest size is achieved by the most optimal compression.

Os cabeçalhos envolvidos na solicitação, no envio, no cache e no recebimento de conteúdo compactado são descritos na tabela a seguir.The headers involved in requesting, sending, caching, and receiving compressed content are described in the table below.

CabeçalhoHeader FunçãoRole
Accept-Encoding Enviado do cliente para o servidor para indicar os esquemas de codificação de conteúdo aceitáveis para o cliente.Sent from the client to the server to indicate the content encoding schemes acceptable to the client.
Content-Encoding Enviado do servidor para o cliente para indicar a codificação do conteúdo na carga.Sent from the server to the client to indicate the encoding of the content in the payload.
Content-Length Quando ocorre a compactação, o Content-Length cabeçalho é removido, pois o conteúdo do corpo é alterado quando a resposta é compactada.When compression occurs, the Content-Length header is removed, since the body content changes when the response is compressed.
Content-MD5 Quando ocorre a compactação, o Content-MD5 cabeçalho é removido, pois o conteúdo do corpo foi alterado e o hash não é mais válido.When compression occurs, the Content-MD5 header is removed, since the body content has changed and the hash is no longer valid.
Content-Type Especifica o tipo MIME do conteúdo.Specifies the MIME type of the content. Cada resposta deve especificar seu Content-Type .Every response should specify its Content-Type. O middleware verifica esse valor para determinar se a resposta deve ser compactada.The middleware checks this value to determine if the response should be compressed. O middleware especifica um conjunto de tipos MIME padrão que ele pode codificar, mas você pode substituir ou adicionar tipos de MIME.The middleware specifies a set of default MIME types that it can encode, but you can replace or add MIME types.
Vary Quando enviado pelo servidor com um valor de Accept-Encoding para clientes e proxies, o Vary cabeçalho indica ao cliente ou ao proxy que ele deve armazenar em cache (variar) as respostas com base no valor do Accept-Encoding cabeçalho da solicitação.When sent by the server with a value of Accept-Encoding to clients and proxies, the Vary header indicates to the client or proxy that it should cache (vary) responses based on the value of the Accept-Encoding header of the request. O resultado do retorno do conteúdo com o Vary: Accept-Encoding cabeçalho é que as respostas compactadas e não compactadas são armazenadas em cache separadamente.The result of returning content with the Vary: Accept-Encoding header is that both compressed and uncompressed responses are cached separately.

Explore os recursos do middleware de compactação de resposta com o aplicativo de exemplo.Explore the features of the Response Compression Middleware with the sample app. O exemplo ilustra:The sample illustrates:

  • A compactação de respostas de aplicativo usando gzip e provedores de compactação personalizados.The compression of app responses using Gzip and custom compression providers.
  • Como adicionar um tipo de MIME à lista padrão de tipos de MIME para compactação.How to add a MIME type to the default list of MIME types for compression.

PacotePackage

O middleware de compactação de resposta é fornecido pelo pacote Microsoft. AspNetCore. ResponseCompression , que é incluído implicitamente em aplicativos ASP.NET Core.Response Compression Middleware is provided by the Microsoft.AspNetCore.ResponseCompression package, which is implicitly included in ASP.NET Core apps.

ConfiguraçãoConfiguration

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):The following code shows how to enable the Response Compression Middleware for default MIME types and compression providers (Brotli and Gzip):

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

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

Observações:Notes:

  • app.UseResponseCompression deve ser chamado antes de qualquer middleware que compacta as respostas.app.UseResponseCompression must be called before any middleware that compresses responses. Para obter mais informações, consulte Middleware do ASP.NET Core.For more information, see Middleware do ASP.NET Core.
  • Use uma ferramenta como o Fiddler, o Firebugou o postmaster para definir o Accept-Encoding cabeçalho da solicitação e estudar os cabeçalhos, o tamanho e o corpo da resposta.Use a tool such as Fiddler, Firebug, or Postman to set the Accept-Encoding request header and study the response headers, size, and body.

Envie uma solicitação para o aplicativo de exemplo sem o Accept-Encoding cabeçalho e observe que a resposta é descompactada.Submit a request to the sample app without the Accept-Encoding header and observe that the response is uncompressed. Os Content-Encoding Vary cabeçalhos e não estão presentes na resposta.The Content-Encoding and Vary headers aren't present on the response.

Janela Fiddler mostrando o resultado de uma solicitação sem o cabeçalho Accept-Encoding.

Envie uma solicitação para o aplicativo de exemplo com o Accept-Encoding: br cabeçalho (compactação Brotli) e observe que a resposta está compactada.Submit a request to the sample app with the Accept-Encoding: br header (Brotli compression) and observe that the response is compressed. Os Content-Encoding Vary cabeçalhos e estão presentes na resposta.The Content-Encoding and Vary headers are present on the response.

Janela Fiddler mostrando o resultado de uma solicitação com o cabeçalho Accept-Encoding e um valor de br.

ProvedoresProviders

Provedor de compactação BrotliBrotli Compression Provider

Use o BrotliCompressionProvider para compactar respostas com o formato de dados compactados Brotli.Use the BrotliCompressionProvider to compress responses with the Brotli compressed data format.

Se nenhum provedor de compactação for explicitamente adicionado ao CompressionProviderCollection :If no compression providers are explicitly added to the 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.The Brotli Compression Provider is added by default to the array of compression providers along with the Gzip compression provider.
  • O padrão de compactação é a compactação Brotli quando o formato de dados compactados Brotli é suportado pelo cliente.Compression defaults to Brotli compression when the Brotli compressed data format is supported by the client. Se Brotli não for suportado pelo cliente, a compactação padronizará para gzip quando o cliente oferecer suporte à compactação Gzip.If Brotli isn't supported by the client, compression defaults to Gzip when the client supports Gzip compression.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();
}

O provedor de compactação Brotli deve ser adicionado quando qualquer provedor de compactação for explicitamente adicionado:The Brotli Compression Provider must be added when any compression providers are explicitly added:

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 BrotliCompressionProviderOptions .Set the compression level with BrotliCompressionProviderOptions. O provedor de compactação Brotli usa como padrão o nível de compactação mais rápido (CompressionLevel. mais rápido), que pode não produzir a compactação mais eficiente.The Brotli Compression Provider defaults to the fastest compression level (CompressionLevel.Fastest), which might not produce the most efficient compression. Se a compactação mais eficiente for desejada, configure o middleware para uma compactação ideal.If the most efficient compression is desired, configure the middleware for optimal compression.

Nível de CompactaçãoCompression Level DescriçãoDescription
CompressionLevel. mais rápidoCompressionLevel.Fastest A compactação deve ser concluída o mais rápido possível, mesmo que a saída resultante não seja compactada de forma ideal.Compression should complete as quickly as possible, even if the resulting output isn't optimally compressed.
CompressionLevel. NoCompressionCompressionLevel.NoCompression Nenhuma compactação deve ser executada.No compression should be performed.
CompressionLevel. idealCompressionLevel.Optimal As respostas devem ser compactadas de forma ideal, mesmo que a compactação leve mais tempo para ser concluída.Responses should be optimally compressed, even if the compression takes more time to complete.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();

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

Provedor de compactação GzipGzip Compression Provider

Use o GzipCompressionProvider para compactar respostas com o formato de arquivo gzip.Use the GzipCompressionProvider to compress responses with the Gzip file format.

Se nenhum provedor de compactação for explicitamente adicionado ao CompressionProviderCollection :If no compression providers are explicitly added to the 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.The Gzip Compression Provider is added by default to the array of compression providers along with the Brotli Compression Provider.
  • O padrão de compactação é a compactação Brotli quando o formato de dados compactados Brotli é suportado pelo cliente.Compression defaults to Brotli compression when the Brotli compressed data format is supported by the client. Se Brotli não for suportado pelo cliente, a compactação padronizará para gzip quando o cliente oferecer suporte à compactação Gzip.If Brotli isn't supported by the client, compression defaults to Gzip when the client supports Gzip compression.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();
}

O provedor de compactação Gzip deve ser adicionado quando qualquer provedor de compactação for explicitamente adicionado:The Gzip Compression Provider must be added when any compression providers are explicitly added:

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 GzipCompressionProviderOptions .Set the compression level with GzipCompressionProviderOptions. O provedor de compactação Gzip usa como padrão o nível de compactação mais rápido (CompressionLevel. mais rápido), que pode não produzir a compactação mais eficiente.The Gzip Compression Provider defaults to the fastest compression level (CompressionLevel.Fastest), which might not produce the most efficient compression. Se a compactação mais eficiente for desejada, configure o middleware para uma compactação ideal.If the most efficient compression is desired, configure the middleware for optimal compression.

Nível de CompactaçãoCompression Level DescriçãoDescription
CompressionLevel. mais rápidoCompressionLevel.Fastest A compactação deve ser concluída o mais rápido possível, mesmo que a saída resultante não seja compactada de forma ideal.Compression should complete as quickly as possible, even if the resulting output isn't optimally compressed.
CompressionLevel. NoCompressionCompressionLevel.NoCompression Nenhuma compactação deve ser executada.No compression should be performed.
CompressionLevel. idealCompressionLevel.Optimal As respostas devem ser compactadas de forma ideal, mesmo que a compactação leve mais tempo para ser concluída.Responses should be optimally compressed, even if the compression takes more time to complete.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();

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

Provedores personalizadosCustom providers

Crie implementações de compactação personalizadas com o ICompressionProvider .Create custom compression implementations with ICompressionProvider. O EncodingName representa a codificação de conteúdo que isso ICompressionProvider produz.The EncodingName represents the content encoding that this ICompressionProvider produces. O middleware usa essas informações para escolher o provedor com base na lista especificada no Accept-Encoding cabeçalho da solicitação.The middleware uses this information to choose the provider based on the list specified in the Accept-Encoding header of the request.

Usando o aplicativo de exemplo, o cliente envia uma solicitação com o Accept-Encoding: mycustomcompression cabeçalho.Using the sample app, the client submits a request with the Accept-Encoding: mycustomcompression header. O middleware usa a implementação de compactação personalizada e retorna a resposta com um Content-Encoding: mycustomcompression cabeçalho.The middleware uses the custom compression implementation and returns the response with a Content-Encoding: mycustomcompression header. O cliente deve ser capaz de descompactar a codificação personalizada para que uma implementação de compactação personalizada funcione.The client must be able to decompress the custom encoding in order for a custom compression implementation to work.

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 Accept-Encoding: mycustomcompression cabeçalho e observe os cabeçalhos de resposta.Submit a request to the sample app with the Accept-Encoding: mycustomcompression header and observe the response headers. Os Vary Content-Encoding cabeçalhos e estão presentes na resposta.The Vary and Content-Encoding headers are present on the response. O corpo da resposta (não mostrado) não é compactado pelo exemplo.The response body (not shown) isn't compressed by the sample. Não há uma implementação de compactação na CustomCompressionProvider classe do exemplo.There isn't a compression implementation in the CustomCompressionProvider class of the sample. No entanto, o exemplo mostra onde você implementaria esse algoritmo de compactação.However, the sample shows where you would implement such a compression algorithm.

Janela Fiddler mostrando o resultado de uma solicitação com o cabeçalho Accept-Encoding e um valor de mycustomcompression.

tipos MIMEMIME types

O middleware especifica um conjunto padrão de tipos MIME para compactação:The middleware specifies a default set of MIME types for compression:

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

Substitua ou acrescente tipos MIME com as opções de middleware de compactação de resposta.Replace or append MIME types with the Response Compression Middleware options. Observe que os tipos MIME curinga, como text/* não têm suporte.Note that wildcard MIME types, such as text/* aren't supported. O aplicativo de exemplo adiciona um tipo MIME para image/svg+xml e compacta e serve a imagem de faixa ASP.NET Core (banner. svg).The sample app adds a MIME type for image/svg+xml and compresses and serves the ASP.NET Core banner image (banner.svg).

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 seguroCompression with secure protocol

As respostas compactadas sobre conexões seguras podem ser controladas com a EnableForHttps opção, que é desabilitada por padrão.Compressed responses over secure connections can be controlled with the EnableForHttps option, which is disabled by default. O uso da compactação com páginas geradas dinamicamente pode levar a problemas de segurança, como ataques de crime e violação .Using compression with dynamically generated pages can lead to security problems such as the CRIME and BREACH attacks.

Adicionando o cabeçalho VaryAdding the Vary header

Ao compactar respostas com base no Accept-Encoding cabeçalho, há potencialmente várias versões compactadas da resposta e uma versão não compactada.When compressing responses based on the Accept-Encoding header, there are potentially multiple compressed versions of the response and an uncompressed version. Para instruir os caches de cliente e proxy de que várias versões existem e devem ser armazenadas, o Vary cabeçalho é adicionado com um Accept-Encoding valor.In order to instruct client and proxy caches that multiple versions exist and should be stored, the Vary header is added with an Accept-Encoding value. No ASP.NET Core 2,0 ou posterior, o middleware adiciona o Vary cabeçalho automaticamente quando a resposta é compactada.In ASP.NET Core 2.0 or later, the middleware adds the Vary header automatically when the response is compressed.

Problema de middleware quando por trás de um proxy reverso NginxMiddleware issue when behind an Nginx reverse proxy

Quando uma solicitação é modificada por proxy pelo Nginx, o Accept-Encoding cabeçalho é removido.When a request is proxied by Nginx, the Accept-Encoding header is removed. A remoção do Accept-Encoding cabeçalho impede que o middleware compacte a resposta.Removal of the Accept-Encoding header prevents the middleware from compressing the response. Para obter mais informações, consulte Nginx: compactação e descompactação.For more information, see NGINX: Compression and Decompression. Esse problema é rastreado por descobrir a compactação de passagem para Nginx (ASPNET/BasicMiddleware #123).This issue is tracked by Figure out pass-through compression for Nginx (aspnet/BasicMiddleware #123).

Trabalhando com compactação dinâmica do IISWorking with IIS dynamic compression

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 de web.config .If you have an active IIS Dynamic Compression Module configured at the server level that you would like to disable for an app, disable the module with an addition to the web.config file. Para obter mais informações, consulte Desabilitando módulos do IIS.For more information, see Disabling IIS modules.

Solução de problemasTroubleshooting

Use uma ferramenta como Fiddler, Firebugou postmaster, que permite definir o Accept-Encoding cabeçalho da solicitação e estudar os cabeçalhos, o tamanho e o corpo da resposta.Use a tool like Fiddler, Firebug, or Postman, which allow you to set the Accept-Encoding request header and study the response headers, size, and body. Por padrão, o middleware de compactação de resposta compacta as respostas que atendem às seguintes condições:By default, Response Compression Middleware compresses responses that meet the following conditions:

  • O Accept-Encoding cabeçalho está presente com um valor de br , gzip , * ou codificação personalizada que corresponde a um provedor de compactação personalizado que você estabeleceu.The Accept-Encoding header is present with a value of br, gzip, *, or custom encoding that matches a custom compression provider that you've established. O valor não deve ser identity ou ter uma configuração de valor de qualidade (qvalue) q de 0 (zero).The value must not be identity or have a quality value (qvalue, q) setting of 0 (zero).
  • O tipo MIME ( Content-Type ) deve ser definido e deve corresponder a um tipo MIME configurado no ResponseCompressionOptions .The MIME type (Content-Type) must be set and must match a MIME type configured on the ResponseCompressionOptions.
  • A solicitação não deve incluir o Content-Range cabeçalho.The request must not include the Content-Range header.
  • A solicitação deve usar o protocolo http, a menos que o protocolo SSL (https) esteja configurado nas opções de middleware de compactação de resposta.The request must use insecure protocol (http), unless secure protocol (https) is configured in the Response Compression Middleware options. Observe o perigo descrito acima ao habilitar a compactação de conteúdo seguro.Note the danger described above when enabling secure content compression.

Recursos adicionaisAdditional resources

A largura de banda da rede é um recurso limitado.Network bandwidth is a limited resource. Reduzir o tamanho da resposta geralmente aumenta a capacidade de resposta de um aplicativo, muitas vezes drasticamente.Reducing the size of the response usually increases the responsiveness of an app, often dramatically. Uma maneira de reduzir os tamanhos de carga é compactar as respostas de um aplicativo.One way to reduce payload sizes is to compress an app's responses.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Quando usar o middleware de compactação de respostaWhen to use Response Compression Middleware

Use tecnologias de compactação de resposta baseadas em servidor no IIS, Apache ou nginx.Use server-based response compression technologies in IIS, Apache, or Nginx. O desempenho do middleware provavelmente não corresponderá ao dos módulos do servidor.The performance of the middleware probably won't match that of the server modules. Atualmente, o servidor do HTTP.sys Server e o Kestrel Server não oferecem suporte interno à compactação.HTTP.sys server server and Kestrel server don't currently offer built-in compression support.

Use o middleware de compactação de resposta quando você estiver:Use Response Compression Middleware when you're:

Compactação de respostaResponse compression

Normalmente, qualquer resposta não compactada nativamente pode se beneficiar da compactação de resposta.Usually, any response not natively compressed can benefit from response compression. As respostas não compactadas nativamente normalmente incluem: CSS, JavaScript, HTML, XML e JSON.Responses not natively compressed typically include: CSS, JavaScript, HTML, XML, and JSON. Você não deve compactar ativos compactados nativamente, como arquivos PNG.You shouldn't compress natively compressed assets, such as PNG files. Se você tentar compactar ainda mais uma resposta compactada nativamente, qualquer pequena redução adicional no tamanho e no tempo de transmissão provavelmente será ofuscada no tempo necessário para processar a compactação.If you attempt to further compress a natively compressed response, any small additional reduction in size and transmission time will likely be overshadowed by the time it took to process the compression. Não compacte arquivos com menos de 150-1000 bytes (dependendo do conteúdo do arquivo e da eficiência da compactação).Don't compress files smaller than about 150-1000 bytes (depending on the file's content and the efficiency of compression). A sobrecarga de compactação de arquivos pequenos pode produzir um arquivo compactado maior do que o arquivo descompactado.The overhead of compressing small files may produce a compressed file larger than the uncompressed file.

Quando um cliente pode processar conteúdo compactado, o cliente deve informar o servidor de seus recursos enviando o Accept-Encoding cabeçalho com a solicitação.When a client can process compressed content, the client must inform the server of its capabilities by sending the Accept-Encoding header with the request. Quando um servidor envia conteúdo compactado, ele deve incluir informações no Content-Encoding cabeçalho sobre como a resposta compactada é codificada.When a server sends compressed content, it must include information in the Content-Encoding header on how the compressed response is encoded. As designações de codificação de conteúdo com suporte no middleware são mostradas na tabela a seguir.Content encoding designations supported by the middleware are shown in the following table.

Accept-Encoding valores de cabeçalhoAccept-Encoding header values Suporte do middlewareMiddleware Supported DescriçãoDescription
br Sim (padrão)Yes (default) Formato de dados compactados BrotliBrotli compressed data format
deflate NãoNo Desinflar formato de dados compactadosDEFLATE compressed data format
exi NãoNo Intercâmbio de XML eficiente do W3CW3C Efficient XML Interchange
gzip YesYes Formato de arquivo gzipGzip file format
identity YesYes Identificador "sem codificação": a resposta não deve ser codificada."No encoding" identifier: The response must not be encoded.
pack200-gzip NãoNo Formato de transferência de rede para arquivos JavaNetwork Transfer Format for Java Archives
* YesYes Qualquer codificação de conteúdo disponível não explicitamente solicitadaAny available content encoding not explicitly requested

Para obter mais informações, consulte a lista de código de conteúdo oficial da IANA.For more information, see the IANA Official Content Coding List.

O middleware permite que você adicione outros provedores de compactação para Accept-Encoding valores de cabeçalho personalizados.The middleware allows you to add additional compression providers for custom Accept-Encoding header values. Para obter mais informações, consulte provedores personalizados abaixo.For more information, see Custom Providers below.

O middleware é capaz de reagir ao valor de qualidade (qvalue, q ) ponderado quando enviado pelo cliente para priorizar os esquemas de compactação.The middleware is capable of reacting to quality value (qvalue, q) weighting when sent by the client to prioritize compression schemes. Para obter mais informações, consulte RFC 7231: Accept-Encoding.For more information, see RFC 7231: 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.Compression algorithms are subject to a tradeoff between compression speed and the effectiveness of the compression. A eficácia neste contexto refere-se ao tamanho da saída após a compactação.Effectiveness in this context refers to the size of the output after compression. O menor tamanho é obtido pela compactação ideal .The smallest size is achieved by the most optimal compression.

Os cabeçalhos envolvidos na solicitação, no envio, no cache e no recebimento de conteúdo compactado são descritos na tabela a seguir.The headers involved in requesting, sending, caching, and receiving compressed content are described in the table below.

CabeçalhoHeader FunçãoRole
Accept-Encoding Enviado do cliente para o servidor para indicar os esquemas de codificação de conteúdo aceitáveis para o cliente.Sent from the client to the server to indicate the content encoding schemes acceptable to the client.
Content-Encoding Enviado do servidor para o cliente para indicar a codificação do conteúdo na carga.Sent from the server to the client to indicate the encoding of the content in the payload.
Content-Length Quando ocorre a compactação, o Content-Length cabeçalho é removido, pois o conteúdo do corpo é alterado quando a resposta é compactada.When compression occurs, the Content-Length header is removed, since the body content changes when the response is compressed.
Content-MD5 Quando ocorre a compactação, o Content-MD5 cabeçalho é removido, pois o conteúdo do corpo foi alterado e o hash não é mais válido.When compression occurs, the Content-MD5 header is removed, since the body content has changed and the hash is no longer valid.
Content-Type Especifica o tipo MIME do conteúdo.Specifies the MIME type of the content. Cada resposta deve especificar seu Content-Type .Every response should specify its Content-Type. O middleware verifica esse valor para determinar se a resposta deve ser compactada.The middleware checks this value to determine if the response should be compressed. O middleware especifica um conjunto de tipos MIME padrão que ele pode codificar, mas você pode substituir ou adicionar tipos de MIME.The middleware specifies a set of default MIME types that it can encode, but you can replace or add MIME types.
Vary Quando enviado pelo servidor com um valor de Accept-Encoding para clientes e proxies, o Vary cabeçalho indica ao cliente ou ao proxy que ele deve armazenar em cache (variar) as respostas com base no valor do Accept-Encoding cabeçalho da solicitação.When sent by the server with a value of Accept-Encoding to clients and proxies, the Vary header indicates to the client or proxy that it should cache (vary) responses based on the value of the Accept-Encoding header of the request. O resultado do retorno do conteúdo com o Vary: Accept-Encoding cabeçalho é que as respostas compactadas e não compactadas são armazenadas em cache separadamente.The result of returning content with the Vary: Accept-Encoding header is that both compressed and uncompressed responses are cached separately.

Explore os recursos do middleware de compactação de resposta com o aplicativo de exemplo.Explore the features of the Response Compression Middleware with the sample app. O exemplo ilustra:The sample illustrates:

  • A compactação de respostas de aplicativo usando gzip e provedores de compactação personalizados.The compression of app responses using Gzip and custom compression providers.
  • Como adicionar um tipo de MIME à lista padrão de tipos de MIME para compactação.How to add a MIME type to the default list of MIME types for compression.

PacotePackage

Para incluir o middleware em um projeto, adicione uma referência ao metapacote Microsoft. AspNetCore. app, que inclui o pacote Microsoft. AspNetCore. ResponseCompression .To include the middleware in a project, add a reference to the Microsoft.AspNetCore.App metapackage, which includes the Microsoft.AspNetCore.ResponseCompression package.

ConfiguraçãoConfiguration

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):The following code shows how to enable the Response Compression Middleware for default MIME types and compression providers (Brotli and Gzip):

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

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

Observações:Notes:

  • app.UseResponseCompression deve ser chamado antes de qualquer middleware que compacta as respostas.app.UseResponseCompression must be called before any middleware that compresses responses. Para obter mais informações, consulte Middleware do ASP.NET Core.For more information, see Middleware do ASP.NET Core.
  • Use uma ferramenta como o Fiddler, o Firebugou o postmaster para definir o Accept-Encoding cabeçalho da solicitação e estudar os cabeçalhos, o tamanho e o corpo da resposta.Use a tool such as Fiddler, Firebug, or Postman to set the Accept-Encoding request header and study the response headers, size, and body.

Envie uma solicitação para o aplicativo de exemplo sem o Accept-Encoding cabeçalho e observe que a resposta é descompactada.Submit a request to the sample app without the Accept-Encoding header and observe that the response is uncompressed. Os Content-Encoding Vary cabeçalhos e não estão presentes na resposta.The Content-Encoding and Vary headers aren't present on the response.

Janela Fiddler mostrando o resultado de uma solicitação sem o cabeçalho Accept-Encoding.

Envie uma solicitação para o aplicativo de exemplo com o Accept-Encoding: br cabeçalho (compactação Brotli) e observe que a resposta está compactada.Submit a request to the sample app with the Accept-Encoding: br header (Brotli compression) and observe that the response is compressed. Os Content-Encoding Vary cabeçalhos e estão presentes na resposta.The Content-Encoding and Vary headers are present on the response.

Janela Fiddler mostrando o resultado de uma solicitação com o cabeçalho Accept-Encoding e um valor de br.

ProvedoresProviders

Provedor de compactação BrotliBrotli Compression Provider

Use o BrotliCompressionProvider para compactar respostas com o formato de dados compactados Brotli.Use the BrotliCompressionProvider to compress responses with the Brotli compressed data format.

Se nenhum provedor de compactação for explicitamente adicionado ao CompressionProviderCollection :If no compression providers are explicitly added to the 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.The Brotli Compression Provider is added by default to the array of compression providers along with the Gzip compression provider.
  • O padrão de compactação é a compactação Brotli quando o formato de dados compactados Brotli é suportado pelo cliente.Compression defaults to Brotli compression when the Brotli compressed data format is supported by the client. Se Brotli não for suportado pelo cliente, a compactação padronizará para gzip quando o cliente oferecer suporte à compactação Gzip.If Brotli isn't supported by the client, compression defaults to Gzip when the client supports Gzip compression.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();
}

O provedor de compactação Brotli deve ser adicionado quando qualquer provedor de compactação for explicitamente adicionado:The Brotli Compression Provider must be added when any compression providers are explicitly added:

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 BrotliCompressionProviderOptions .Set the compression level with BrotliCompressionProviderOptions. O provedor de compactação Brotli usa como padrão o nível de compactação mais rápido (CompressionLevel. mais rápido), que pode não produzir a compactação mais eficiente.The Brotli Compression Provider defaults to the fastest compression level (CompressionLevel.Fastest), which might not produce the most efficient compression. Se a compactação mais eficiente for desejada, configure o middleware para uma compactação ideal.If the most efficient compression is desired, configure the middleware for optimal compression.

Nível de CompactaçãoCompression Level DescriçãoDescription
CompressionLevel. mais rápidoCompressionLevel.Fastest A compactação deve ser concluída o mais rápido possível, mesmo que a saída resultante não seja compactada de forma ideal.Compression should complete as quickly as possible, even if the resulting output isn't optimally compressed.
CompressionLevel. NoCompressionCompressionLevel.NoCompression Nenhuma compactação deve ser executada.No compression should be performed.
CompressionLevel. idealCompressionLevel.Optimal As respostas devem ser compactadas de forma ideal, mesmo que a compactação leve mais tempo para ser concluída.Responses should be optimally compressed, even if the compression takes more time to complete.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();

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

Provedor de compactação GzipGzip Compression Provider

Use o GzipCompressionProvider para compactar respostas com o formato de arquivo gzip.Use the GzipCompressionProvider to compress responses with the Gzip file format.

Se nenhum provedor de compactação for explicitamente adicionado ao CompressionProviderCollection :If no compression providers are explicitly added to the 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.The Gzip Compression Provider is added by default to the array of compression providers along with the Brotli Compression Provider.
  • O padrão de compactação é a compactação Brotli quando o formato de dados compactados Brotli é suportado pelo cliente.Compression defaults to Brotli compression when the Brotli compressed data format is supported by the client. Se Brotli não for suportado pelo cliente, a compactação padronizará para gzip quando o cliente oferecer suporte à compactação Gzip.If Brotli isn't supported by the client, compression defaults to Gzip when the client supports Gzip compression.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();
}

O provedor de compactação Gzip deve ser adicionado quando qualquer provedor de compactação for explicitamente adicionado:The Gzip Compression Provider must be added when any compression providers are explicitly added:

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 GzipCompressionProviderOptions .Set the compression level with GzipCompressionProviderOptions. O provedor de compactação Gzip usa como padrão o nível de compactação mais rápido (CompressionLevel. mais rápido), que pode não produzir a compactação mais eficiente.The Gzip Compression Provider defaults to the fastest compression level (CompressionLevel.Fastest), which might not produce the most efficient compression. Se a compactação mais eficiente for desejada, configure o middleware para uma compactação ideal.If the most efficient compression is desired, configure the middleware for optimal compression.

Nível de CompactaçãoCompression Level DescriçãoDescription
CompressionLevel. mais rápidoCompressionLevel.Fastest A compactação deve ser concluída o mais rápido possível, mesmo que a saída resultante não seja compactada de forma ideal.Compression should complete as quickly as possible, even if the resulting output isn't optimally compressed.
CompressionLevel. NoCompressionCompressionLevel.NoCompression Nenhuma compactação deve ser executada.No compression should be performed.
CompressionLevel. idealCompressionLevel.Optimal As respostas devem ser compactadas de forma ideal, mesmo que a compactação leve mais tempo para ser concluída.Responses should be optimally compressed, even if the compression takes more time to complete.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();

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

Provedores personalizadosCustom providers

Crie implementações de compactação personalizadas com o ICompressionProvider .Create custom compression implementations with ICompressionProvider. O EncodingName representa a codificação de conteúdo que isso ICompressionProvider produz.The EncodingName represents the content encoding that this ICompressionProvider produces. O middleware usa essas informações para escolher o provedor com base na lista especificada no Accept-Encoding cabeçalho da solicitação.The middleware uses this information to choose the provider based on the list specified in the Accept-Encoding header of the request.

Usando o aplicativo de exemplo, o cliente envia uma solicitação com o Accept-Encoding: mycustomcompression cabeçalho.Using the sample app, the client submits a request with the Accept-Encoding: mycustomcompression header. O middleware usa a implementação de compactação personalizada e retorna a resposta com um Content-Encoding: mycustomcompression cabeçalho.The middleware uses the custom compression implementation and returns the response with a Content-Encoding: mycustomcompression header. O cliente deve ser capaz de descompactar a codificação personalizada para que uma implementação de compactação personalizada funcione.The client must be able to decompress the custom encoding in order for a custom compression implementation to work.

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 Accept-Encoding: mycustomcompression cabeçalho e observe os cabeçalhos de resposta.Submit a request to the sample app with the Accept-Encoding: mycustomcompression header and observe the response headers. Os Vary Content-Encoding cabeçalhos e estão presentes na resposta.The Vary and Content-Encoding headers are present on the response. O corpo da resposta (não mostrado) não é compactado pelo exemplo.The response body (not shown) isn't compressed by the sample. Não há uma implementação de compactação na CustomCompressionProvider classe do exemplo.There isn't a compression implementation in the CustomCompressionProvider class of the sample. No entanto, o exemplo mostra onde você implementaria esse algoritmo de compactação.However, the sample shows where you would implement such a compression algorithm.

Janela Fiddler mostrando o resultado de uma solicitação com o cabeçalho Accept-Encoding e um valor de mycustomcompression.

tipos MIMEMIME types

O middleware especifica um conjunto padrão de tipos MIME para compactação:The middleware specifies a default set of MIME types for compression:

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

Substitua ou acrescente tipos MIME com as opções de middleware de compactação de resposta.Replace or append MIME types with the Response Compression Middleware options. Observe que os tipos MIME curinga, como text/* não têm suporte.Note that wildcard MIME types, such as text/* aren't supported. O aplicativo de exemplo adiciona um tipo MIME para image/svg+xml e compacta e serve a imagem de faixa ASP.NET Core (banner. svg).The sample app adds a MIME type for image/svg+xml and compresses and serves the ASP.NET Core banner image (banner.svg).

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 seguroCompression with secure protocol

As respostas compactadas sobre conexões seguras podem ser controladas com a EnableForHttps opção, que é desabilitada por padrão.Compressed responses over secure connections can be controlled with the EnableForHttps option, which is disabled by default. O uso da compactação com páginas geradas dinamicamente pode levar a problemas de segurança, como ataques de crime e violação .Using compression with dynamically generated pages can lead to security problems such as the CRIME and BREACH attacks.

Adicionando o cabeçalho VaryAdding the Vary header

Ao compactar respostas com base no Accept-Encoding cabeçalho, há potencialmente várias versões compactadas da resposta e uma versão não compactada.When compressing responses based on the Accept-Encoding header, there are potentially multiple compressed versions of the response and an uncompressed version. Para instruir os caches de cliente e proxy de que várias versões existem e devem ser armazenadas, o Vary cabeçalho é adicionado com um Accept-Encoding valor.In order to instruct client and proxy caches that multiple versions exist and should be stored, the Vary header is added with an Accept-Encoding value. No ASP.NET Core 2,0 ou posterior, o middleware adiciona o Vary cabeçalho automaticamente quando a resposta é compactada.In ASP.NET Core 2.0 or later, the middleware adds the Vary header automatically when the response is compressed.

Problema de middleware quando por trás de um proxy reverso NginxMiddleware issue when behind an Nginx reverse proxy

Quando uma solicitação é modificada por proxy pelo Nginx, o Accept-Encoding cabeçalho é removido.When a request is proxied by Nginx, the Accept-Encoding header is removed. A remoção do Accept-Encoding cabeçalho impede que o middleware compacte a resposta.Removal of the Accept-Encoding header prevents the middleware from compressing the response. Para obter mais informações, consulte Nginx: compactação e descompactação.For more information, see NGINX: Compression and Decompression. Esse problema é rastreado por descobrir a compactação de passagem para Nginx (ASPNET/BasicMiddleware #123).This issue is tracked by Figure out pass-through compression for Nginx (aspnet/BasicMiddleware #123).

Trabalhando com compactação dinâmica do IISWorking with IIS dynamic compression

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 de web.config .If you have an active IIS Dynamic Compression Module configured at the server level that you would like to disable for an app, disable the module with an addition to the web.config file. Para obter mais informações, consulte Desabilitando módulos do IIS.For more information, see Disabling IIS modules.

Solução de problemasTroubleshooting

Use uma ferramenta como Fiddler, Firebugou postmaster, que permite definir o Accept-Encoding cabeçalho da solicitação e estudar os cabeçalhos, o tamanho e o corpo da resposta.Use a tool like Fiddler, Firebug, or Postman, which allow you to set the Accept-Encoding request header and study the response headers, size, and body. Por padrão, o middleware de compactação de resposta compacta as respostas que atendem às seguintes condições:By default, Response Compression Middleware compresses responses that meet the following conditions:

  • O Accept-Encoding cabeçalho está presente com um valor de br , gzip , * ou codificação personalizada que corresponde a um provedor de compactação personalizado que você estabeleceu.The Accept-Encoding header is present with a value of br, gzip, *, or custom encoding that matches a custom compression provider that you've established. O valor não deve ser identity ou ter uma configuração de valor de qualidade (qvalue) q de 0 (zero).The value must not be identity or have a quality value (qvalue, q) setting of 0 (zero).
  • O tipo MIME ( Content-Type ) deve ser definido e deve corresponder a um tipo MIME configurado no ResponseCompressionOptions .The MIME type (Content-Type) must be set and must match a MIME type configured on the ResponseCompressionOptions.
  • A solicitação não deve incluir o Content-Range cabeçalho.The request must not include the Content-Range header.
  • A solicitação deve usar o protocolo http, a menos que o protocolo SSL (https) esteja configurado nas opções de middleware de compactação de resposta.The request must use insecure protocol (http), unless secure protocol (https) is configured in the Response Compression Middleware options. Observe o perigo descrito acima ao habilitar a compactação de conteúdo seguro.Note the danger described above when enabling secure content compression.

Recursos adicionaisAdditional resources

A largura de banda da rede é um recurso limitado.Network bandwidth is a limited resource. Reduzir o tamanho da resposta geralmente aumenta a capacidade de resposta de um aplicativo, muitas vezes drasticamente.Reducing the size of the response usually increases the responsiveness of an app, often dramatically. Uma maneira de reduzir os tamanhos de carga é compactar as respostas de um aplicativo.One way to reduce payload sizes is to compress an app's responses.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Quando usar o middleware de compactação de respostaWhen to use Response Compression Middleware

Use tecnologias de compactação de resposta baseadas em servidor no IIS, Apache ou nginx.Use server-based response compression technologies in IIS, Apache, or Nginx. O desempenho do middleware provavelmente não corresponderá ao dos módulos do servidor.The performance of the middleware probably won't match that of the server modules. Atualmente, o servidor do HTTP.sys Server e o Kestrel Server não oferecem suporte interno à compactação.HTTP.sys server server and Kestrel server don't currently offer built-in compression support.

Use o middleware de compactação de resposta quando você estiver:Use Response Compression Middleware when you're:

Compactação de respostaResponse compression

Normalmente, qualquer resposta não compactada nativamente pode se beneficiar da compactação de resposta.Usually, any response not natively compressed can benefit from response compression. As respostas não compactadas nativamente normalmente incluem: CSS, JavaScript, HTML, XML e JSON.Responses not natively compressed typically include: CSS, JavaScript, HTML, XML, and JSON. Você não deve compactar ativos compactados nativamente, como arquivos PNG.You shouldn't compress natively compressed assets, such as PNG files. Se você tentar compactar ainda mais uma resposta compactada nativamente, qualquer pequena redução adicional no tamanho e no tempo de transmissão provavelmente será ofuscada no tempo necessário para processar a compactação.If you attempt to further compress a natively compressed response, any small additional reduction in size and transmission time will likely be overshadowed by the time it took to process the compression. Não compacte arquivos com menos de 150-1000 bytes (dependendo do conteúdo do arquivo e da eficiência da compactação).Don't compress files smaller than about 150-1000 bytes (depending on the file's content and the efficiency of compression). A sobrecarga de compactação de arquivos pequenos pode produzir um arquivo compactado maior do que o arquivo descompactado.The overhead of compressing small files may produce a compressed file larger than the uncompressed file.

Quando um cliente pode processar conteúdo compactado, o cliente deve informar o servidor de seus recursos enviando o Accept-Encoding cabeçalho com a solicitação.When a client can process compressed content, the client must inform the server of its capabilities by sending the Accept-Encoding header with the request. Quando um servidor envia conteúdo compactado, ele deve incluir informações no Content-Encoding cabeçalho sobre como a resposta compactada é codificada.When a server sends compressed content, it must include information in the Content-Encoding header on how the compressed response is encoded. As designações de codificação de conteúdo com suporte no middleware são mostradas na tabela a seguir.Content encoding designations supported by the middleware are shown in the following table.

Accept-Encoding valores de cabeçalhoAccept-Encoding header values Suporte do middlewareMiddleware Supported DescriçãoDescription
br NãoNo Formato de dados compactados BrotliBrotli compressed data format
deflate NãoNo Desinflar formato de dados compactadosDEFLATE compressed data format
exi NãoNo Intercâmbio de XML eficiente do W3CW3C Efficient XML Interchange
gzip Sim (padrão)Yes (default) Formato de arquivo gzipGzip file format
identity YesYes Identificador "sem codificação": a resposta não deve ser codificada."No encoding" identifier: The response must not be encoded.
pack200-gzip NãoNo Formato de transferência de rede para arquivos JavaNetwork Transfer Format for Java Archives
* YesYes Qualquer codificação de conteúdo disponível não explicitamente solicitadaAny available content encoding not explicitly requested

Para obter mais informações, consulte a lista de código de conteúdo oficial da IANA.For more information, see the IANA Official Content Coding List.

O middleware permite que você adicione outros provedores de compactação para Accept-Encoding valores de cabeçalho personalizados.The middleware allows you to add additional compression providers for custom Accept-Encoding header values. Para obter mais informações, consulte provedores personalizados abaixo.For more information, see Custom Providers below.

O middleware é capaz de reagir ao valor de qualidade (qvalue, q ) ponderado quando enviado pelo cliente para priorizar os esquemas de compactação.The middleware is capable of reacting to quality value (qvalue, q) weighting when sent by the client to prioritize compression schemes. Para obter mais informações, consulte RFC 7231: Accept-Encoding.For more information, see RFC 7231: 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.Compression algorithms are subject to a tradeoff between compression speed and the effectiveness of the compression. A eficácia neste contexto refere-se ao tamanho da saída após a compactação.Effectiveness in this context refers to the size of the output after compression. O menor tamanho é obtido pela compactação ideal .The smallest size is achieved by the most optimal compression.

Os cabeçalhos envolvidos na solicitação, no envio, no cache e no recebimento de conteúdo compactado são descritos na tabela a seguir.The headers involved in requesting, sending, caching, and receiving compressed content are described in the table below.

CabeçalhoHeader FunçãoRole
Accept-Encoding Enviado do cliente para o servidor para indicar os esquemas de codificação de conteúdo aceitáveis para o cliente.Sent from the client to the server to indicate the content encoding schemes acceptable to the client.
Content-Encoding Enviado do servidor para o cliente para indicar a codificação do conteúdo na carga.Sent from the server to the client to indicate the encoding of the content in the payload.
Content-Length Quando ocorre a compactação, o Content-Length cabeçalho é removido, pois o conteúdo do corpo é alterado quando a resposta é compactada.When compression occurs, the Content-Length header is removed, since the body content changes when the response is compressed.
Content-MD5 Quando ocorre a compactação, o Content-MD5 cabeçalho é removido, pois o conteúdo do corpo foi alterado e o hash não é mais válido.When compression occurs, the Content-MD5 header is removed, since the body content has changed and the hash is no longer valid.
Content-Type Especifica o tipo MIME do conteúdo.Specifies the MIME type of the content. Cada resposta deve especificar seu Content-Type .Every response should specify its Content-Type. O middleware verifica esse valor para determinar se a resposta deve ser compactada.The middleware checks this value to determine if the response should be compressed. O middleware especifica um conjunto de tipos MIME padrão que ele pode codificar, mas você pode substituir ou adicionar tipos de MIME.The middleware specifies a set of default MIME types that it can encode, but you can replace or add MIME types.
Vary Quando enviado pelo servidor com um valor de Accept-Encoding para clientes e proxies, o Vary cabeçalho indica ao cliente ou ao proxy que ele deve armazenar em cache (variar) as respostas com base no valor do Accept-Encoding cabeçalho da solicitação.When sent by the server with a value of Accept-Encoding to clients and proxies, the Vary header indicates to the client or proxy that it should cache (vary) responses based on the value of the Accept-Encoding header of the request. O resultado do retorno do conteúdo com o Vary: Accept-Encoding cabeçalho é que as respostas compactadas e não compactadas são armazenadas em cache separadamente.The result of returning content with the Vary: Accept-Encoding header is that both compressed and uncompressed responses are cached separately.

Explore os recursos do middleware de compactação de resposta com o aplicativo de exemplo.Explore the features of the Response Compression Middleware with the sample app. O exemplo ilustra:The sample illustrates:

  • A compactação de respostas de aplicativo usando gzip e provedores de compactação personalizados.The compression of app responses using Gzip and custom compression providers.
  • Como adicionar um tipo de MIME à lista padrão de tipos de MIME para compactação.How to add a MIME type to the default list of MIME types for compression.

PacotePackage

Para incluir o middleware em um projeto, adicione uma referência ao metapacote Microsoft. AspNetCore. app, que inclui o pacote Microsoft. AspNetCore. ResponseCompression .To include the middleware in a project, add a reference to the Microsoft.AspNetCore.App metapackage, which includes the Microsoft.AspNetCore.ResponseCompression package.

ConfiguraçãoConfiguration

O código a seguir mostra como habilitar o middleware de compactação de resposta para tipos MIME padrão e o provedor de compactação Gzip:The following code shows how to enable the Response Compression Middleware for default MIME types and the Gzip Compression Provider:

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

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

Observações:Notes:

  • app.UseResponseCompression deve ser chamado antes de qualquer middleware que compacta as respostas.app.UseResponseCompression must be called before any middleware that compresses responses. Para obter mais informações, consulte Middleware do ASP.NET Core.For more information, see Middleware do ASP.NET Core.
  • Use uma ferramenta como o Fiddler, o Firebugou o postmaster para definir o Accept-Encoding cabeçalho da solicitação e estudar os cabeçalhos, o tamanho e o corpo da resposta.Use a tool such as Fiddler, Firebug, or Postman to set the Accept-Encoding request header and study the response headers, size, and body.

Envie uma solicitação para o aplicativo de exemplo sem o Accept-Encoding cabeçalho e observe que a resposta é descompactada.Submit a request to the sample app without the Accept-Encoding header and observe that the response is uncompressed. Os Content-Encoding Vary cabeçalhos e não estão presentes na resposta.The Content-Encoding and Vary headers aren't present on the response.

Janela Fiddler mostrando o resultado de uma solicitação sem o cabeçalho Accept-Encoding.

Envie uma solicitação para o aplicativo de exemplo com o Accept-Encoding: gzip cabeçalho e observe que a resposta está compactada.Submit a request to the sample app with the Accept-Encoding: gzip header and observe that the response is compressed. Os Content-Encoding Vary cabeçalhos e estão presentes na resposta.The Content-Encoding and Vary headers are present on the response.

Janela Fiddler mostrando o resultado de uma solicitação com o cabeçalho Accept-Encoding e um valor de gzip.

ProvedoresProviders

Provedor de compactação GzipGzip Compression Provider

Use o GzipCompressionProvider para compactar respostas com o formato de arquivo gzip.Use the GzipCompressionProvider to compress responses with the Gzip file format.

Se nenhum provedor de compactação for explicitamente adicionado ao CompressionProviderCollection :If no compression providers are explicitly added to the CompressionProviderCollection:

  • O provedor de compactação Gzip é adicionado por padrão à matriz de provedores de compactação.The Gzip Compression Provider is added by default to the array of compression providers.
  • O padrão de compactação é gzip quando o cliente dá suporte à compactação Gzip.Compression defaults to Gzip when the client supports Gzip compression.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();
}

O provedor de compactação Gzip deve ser adicionado quando qualquer provedor de compactação for explicitamente adicionado:The Gzip Compression Provider must be added when any compression providers are explicitly added:

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 GzipCompressionProviderOptions .Set the compression level with GzipCompressionProviderOptions. O provedor de compactação Gzip usa como padrão o nível de compactação mais rápido (CompressionLevel. mais rápido), que pode não produzir a compactação mais eficiente.The Gzip Compression Provider defaults to the fastest compression level (CompressionLevel.Fastest), which might not produce the most efficient compression. Se a compactação mais eficiente for desejada, configure o middleware para uma compactação ideal.If the most efficient compression is desired, configure the middleware for optimal compression.

Nível de CompactaçãoCompression Level DescriçãoDescription
CompressionLevel. mais rápidoCompressionLevel.Fastest A compactação deve ser concluída o mais rápido possível, mesmo que a saída resultante não seja compactada de forma ideal.Compression should complete as quickly as possible, even if the resulting output isn't optimally compressed.
CompressionLevel. NoCompressionCompressionLevel.NoCompression Nenhuma compactação deve ser executada.No compression should be performed.
CompressionLevel. idealCompressionLevel.Optimal As respostas devem ser compactadas de forma ideal, mesmo que a compactação leve mais tempo para ser concluída.Responses should be optimally compressed, even if the compression takes more time to complete.
public void ConfigureServices(IServiceCollection services)
{
    services.AddResponseCompression();

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

Provedores personalizadosCustom providers

Crie implementações de compactação personalizadas com o ICompressionProvider .Create custom compression implementations with ICompressionProvider. O EncodingName representa a codificação de conteúdo que isso ICompressionProvider produz.The EncodingName represents the content encoding that this ICompressionProvider produces. O middleware usa essas informações para escolher o provedor com base na lista especificada no Accept-Encoding cabeçalho da solicitação.The middleware uses this information to choose the provider based on the list specified in the Accept-Encoding header of the request.

Usando o aplicativo de exemplo, o cliente envia uma solicitação com o Accept-Encoding: mycustomcompression cabeçalho.Using the sample app, the client submits a request with the Accept-Encoding: mycustomcompression header. O middleware usa a implementação de compactação personalizada e retorna a resposta com um Content-Encoding: mycustomcompression cabeçalho.The middleware uses the custom compression implementation and returns the response with a Content-Encoding: mycustomcompression header. O cliente deve ser capaz de descompactar a codificação personalizada para que uma implementação de compactação personalizada funcione.The client must be able to decompress the custom encoding in order for a custom compression implementation to work.

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 Accept-Encoding: mycustomcompression cabeçalho e observe os cabeçalhos de resposta.Submit a request to the sample app with the Accept-Encoding: mycustomcompression header and observe the response headers. Os Vary Content-Encoding cabeçalhos e estão presentes na resposta.The Vary and Content-Encoding headers are present on the response. O corpo da resposta (não mostrado) não é compactado pelo exemplo.The response body (not shown) isn't compressed by the sample. Não há uma implementação de compactação na CustomCompressionProvider classe do exemplo.There isn't a compression implementation in the CustomCompressionProvider class of the sample. No entanto, o exemplo mostra onde você implementaria esse algoritmo de compactação.However, the sample shows where you would implement such a compression algorithm.

Janela Fiddler mostrando o resultado de uma solicitação com o cabeçalho Accept-Encoding e um valor de mycustomcompression.

tipos MIMEMIME types

O middleware especifica um conjunto padrão de tipos MIME para compactação:The middleware specifies a default set of MIME types for compression:

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

Substitua ou acrescente tipos MIME com as opções de middleware de compactação de resposta.Replace or append MIME types with the Response Compression Middleware options. Observe que os tipos MIME curinga, como text/* não têm suporte.Note that wildcard MIME types, such as text/* aren't supported. O aplicativo de exemplo adiciona um tipo MIME para image/svg+xml e compacta e serve a imagem de faixa ASP.NET Core (banner. svg).The sample app adds a MIME type for image/svg+xml and compresses and serves the ASP.NET Core banner image (banner.svg).

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 seguroCompression with secure protocol

As respostas compactadas sobre conexões seguras podem ser controladas com a EnableForHttps opção, que é desabilitada por padrão.Compressed responses over secure connections can be controlled with the EnableForHttps option, which is disabled by default. O uso da compactação com páginas geradas dinamicamente pode levar a problemas de segurança, como ataques de crime e violação .Using compression with dynamically generated pages can lead to security problems such as the CRIME and BREACH attacks.

Adicionando o cabeçalho VaryAdding the Vary header

Ao compactar respostas com base no Accept-Encoding cabeçalho, há potencialmente várias versões compactadas da resposta e uma versão não compactada.When compressing responses based on the Accept-Encoding header, there are potentially multiple compressed versions of the response and an uncompressed version. Para instruir os caches de cliente e proxy de que várias versões existem e devem ser armazenadas, o Vary cabeçalho é adicionado com um Accept-Encoding valor.In order to instruct client and proxy caches that multiple versions exist and should be stored, the Vary header is added with an Accept-Encoding value. No ASP.NET Core 2,0 ou posterior, o middleware adiciona o Vary cabeçalho automaticamente quando a resposta é compactada.In ASP.NET Core 2.0 or later, the middleware adds the Vary header automatically when the response is compressed.

Problema de middleware quando por trás de um proxy reverso NginxMiddleware issue when behind an Nginx reverse proxy

Quando uma solicitação é modificada por proxy pelo Nginx, o Accept-Encoding cabeçalho é removido.When a request is proxied by Nginx, the Accept-Encoding header is removed. A remoção do Accept-Encoding cabeçalho impede que o middleware compacte a resposta.Removal of the Accept-Encoding header prevents the middleware from compressing the response. Para obter mais informações, consulte Nginx: compactação e descompactação.For more information, see NGINX: Compression and Decompression. Esse problema é rastreado por descobrir a compactação de passagem para Nginx (ASPNET/BasicMiddleware #123).This issue is tracked by Figure out pass-through compression for Nginx (aspnet/BasicMiddleware #123).

Trabalhando com compactação dinâmica do IISWorking with IIS dynamic compression

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 de web.config .If you have an active IIS Dynamic Compression Module configured at the server level that you would like to disable for an app, disable the module with an addition to the web.config file. Para obter mais informações, consulte Desabilitando módulos do IIS.For more information, see Disabling IIS modules.

Solução de problemasTroubleshooting

Use uma ferramenta como Fiddler, Firebugou postmaster, que permite definir o Accept-Encoding cabeçalho da solicitação e estudar os cabeçalhos, o tamanho e o corpo da resposta.Use a tool like Fiddler, Firebug, or Postman, which allow you to set the Accept-Encoding request header and study the response headers, size, and body. Por padrão, o middleware de compactação de resposta compacta as respostas que atendem às seguintes condições:By default, Response Compression Middleware compresses responses that meet the following conditions:

  • O Accept-Encoding cabeçalho está presente com um valor de gzip , * ou codificação personalizada que corresponde a um provedor de compactação personalizado que você estabeleceu.The Accept-Encoding header is present with a value of gzip, *, or custom encoding that matches a custom compression provider that you've established. O valor não deve ser identity ou ter uma configuração de valor de qualidade (qvalue) q de 0 (zero).The value must not be identity or have a quality value (qvalue, q) setting of 0 (zero).
  • O tipo MIME ( Content-Type ) deve ser definido e deve corresponder a um tipo MIME configurado no ResponseCompressionOptions .The MIME type (Content-Type) must be set and must match a MIME type configured on the ResponseCompressionOptions.
  • A solicitação não deve incluir o Content-Range cabeçalho.The request must not include the Content-Range header.
  • A solicitação deve usar o protocolo http, a menos que o protocolo SSL (https) esteja configurado nas opções de middleware de compactação de resposta.The request must use insecure protocol (http), unless secure protocol (https) is configured in the Response Compression Middleware options. Observe o perigo descrito acima ao habilitar a compactação de conteúdo seguro.Note the danger described above when enabling secure content compression.

Recursos adicionaisAdditional resources