Cache de lote de aplicativo e runtime do ASP.NET Core Blazor WebAssembly .NET

Observação

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

Importante

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

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

Quando um aplicativo Blazor WebAssembly é carregado no navegador, o aplicativo baixa recursos de inicialização do servidor:

• Código JavaScript para inicializar o aplicativo
• Runtime e assemblies do .NET
• Dados específicos da localidade

Com exceção do arquivo de recursos de inicialização (blazor.boot.json) do Blazor, os arquivos lote de aplicativo e runtime do WebAssembly .NET são armazenados em cache nos clientes. O arquivo blazor.boot.json contém um manifesto dos arquivos que compõem o aplicativo, que precisam ser baixados juntamente com um hash do conteúdo do arquivo. Isso é usado para detectar se houve alguma alteração nos recursos de inicialização. Blazor armazena os arquivos baixados em cache usando a API Cache do navegador.

Quando o Blazor WebAssembly baixa os arquivos de inicialização de um aplicativo, ele instrui o navegador a executar verificações de integridade nas respostas. Blazor envia os valores de hash SHA-256 para DLL (.dll), WebAssembly (.wasm) e outros arquivos no arquivo blazor.boot.json. Os hashes de arquivos armazenados em cache são comparados aos hashes no arquivo blazor.boot.json. Para arquivos armazenados em cache com um hash correspondente, Blazor usa os arquivos armazenados em cache. Caso contrário, os arquivos serão solicitados do servidor. Depois que um arquivo é baixado, o hash é verificado novamente para validação de integridade. Um erro será gerado pelo navegador, em caso de falha na verificação de integridade de qualquer arquivo baixado.

O algoritmo do Blazor para gerenciar a integridade do arquivo:

• Garante que o aplicativo não corre o risco de carregar um conjunto inconsistente de arquivos, por exemplo, se uma nova implantação for aplicada ao servidor Web, enquanto o usuário estiver em processo de download dos arquivos do aplicativo. Os arquivos inconsistentes podem resultar em um aplicativo com defeito.
• Garante que o navegador do usuário nunca armazene em cache respostas inconsistentes ou inválidas, o que pode impedir que o aplicativo seja iniciado mesmo que o usuário atualize a página manualmente.
• Torna seguro armazenar em cache as respostas e não verificar quanto a alterações do lado do servidor até que os hashes SHA-256 esperados sejam alterados. Portanto, as cargas de página subsequentes envolvem menos solicitações e são concluídas mais rapidamente.

Se o servidor Web retornar respostas que não correspondem aos hashes SHA-256 esperados, um erro semelhante ao exemplo a seguir será exibido no console do desenvolvedor do navegador:

Falha ao localizar um código hash válido no atributo 'integrity' para o 'https://myapp.example.com/_framework/MyBlazorApp.dll' do recurso com a integridade SHA-256 calculada 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. O recurso foi bloqueado.

Na maioria dos casos, o aviso não indica um problema na verificação de integridade. Em vez disso, o aviso geralmente significa que existe algum outro problema.

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

Como diagnosticar problemas de integridade

Quando um aplicativo é criado, o manifesto blazor.boot.json gerado descreve os hashes SHA-256 dos recursos de inicialização no momento em que a saída do build é produzida. A verificação de integridade é aprovada desde que os hashes SHA-256 no blazor.boot.json correspondam aos arquivos entregues ao navegador.

Motivos comuns para dessa falha incluem:

• A resposta do servidor Web é um erro (por exemplo, 404 – Não Encontrado ou 500 – Erro do Servidor Interno), em vez do arquivo solicitado pelo navegador. Isso é relatado pelo navegador como uma falha na verificação de integridade e não como falha de resposta.
• Algo alterou o conteúdo dos arquivos entre o build e a entrega dos arquivos no navegador. Isso pode acontecer:
  • Se você ou as ferramentas de build modificarem manualmente a saída do build.
  • Se algum aspecto do processo de implantação tiver modificado os arquivos. Por exemplo, se você usar um mecanismo de implantação baseado em Git, tenha em mente que o Git converte de forma transparente as terminações de linha no estilo Windows em terminações de linha no estilo Unix, se você confirmar os arquivos no Windows e marcá-los no Linux. Alterar as terminações de linha de arquivo altera os hashes SHA-256. Para evitar esse problema, use .gitattributes para tratar artefatos de build como arquivos binary.
  • O servidor Web modifica o conteúdo do arquivo como parte do serviço. Por exemplo, algumas CDNs (redes de distribuição de conteúdo) tentam minificar o HTML automaticamente, modificando-o. Talvez seja necessário desabilitar esses recursos.
• O arquivo blazor.boot.json não é carregado corretamente ou é armazenado em cache incorretamente no cliente. As causas comuns incluem uma das seguintes opções:
  • Código de desenvolvedor personalizado configurado incorretamente ou com defeito.
  • Uma ou mais camadas de cache intermediárias configuradas incorretamente.

Para diagnosticar qual dessas opções se aplica ao seu caso:

1. Observe qual arquivo está disparando o erro, lendo a mensagem de erro.
2. Abra as ferramentas de desenvolvedor no navegador e dê uma olhada na guia Rede. Se necessário, recarregue a página para ver a lista de solicitações e respostas. Localize o arquivo que está disparando o erro nessa lista.
3. Verifique o código de status HTTP na resposta. Se o servidor retornar algo diferente de 200 – OK (ou outro código de status 2xx), significa que há um problema no lado do servidor para diagnosticar. Por exemplo, o código de status 403 significa que há um problema de autorização, enquanto o código de status 500 significa que o servidor está falhando de maneira não especificada. Veja os logs do lado do servidor para diagnosticar e corrigir o aplicativo.
4. Se o código de status for 200 – OK para o recurso, examine o conteúdo da resposta nas ferramentas de desenvolvedor do navegador e verifique se o conteúdo corresponde aos dados esperados. Por exemplo, um problema comum é configurar incorretamente o roteamento de modo que as solicitações retornem os dados do index.html até mesmo para outros arquivos. Verifique se as respostas às solicitações do .wasm são binários do WebAssembly e se as respostas às solicitações do .dll são binários de assembly do .NET. Caso contrário, significa que há um problema de roteamento do lado do servidor para diagnosticar.
5. Procure validar a saída publicada e implantada do aplicativo com o script do PowerShell Solucionar problemas de integridade.

Se você confirmar que o servidor está retornando dados plausivelmente corretos, deve haver outra coisa modificando o conteúdo entre o build e a entrega do arquivo. Para investigar isso:

• Examine a cadeia de ferramentas de build e o mecanismo de implantação, caso estejam modificando os arquivos depois que os arquivos são compilados. Um exemplo disso é quando o Git transforma as terminações de linha de arquivo, conforme descrito anteriormente.
• Examine o servidor Web ou a configuração da CDN, caso estejam configurados para modificar as respostas dinamicamente (por exemplo, tentando minificar o HTML). Não há problema se o servidor Web implementa a compactação HTTP (por exemplo, retornando content-encoding: br ou content-encoding: gzip), pois isso não afeta o resultado após a descompactação. No entanto, há problema se o servidor Web modifica os dados descompactados.

Script do PowerShell Solucionar problemas de integridade

Use o script do PowerShell integrity.ps1 para validar um aplicativo Blazor publicado e implantado. O script é fornecido para o PowerShell Core 7 ou posterior como ponto de partida, quando o aplicativo tem problemas de integridade que a estrutura Blazor não pode identificar. A personalização do script pode ser necessária para seus aplicativos, incluindo se estiver em execução na versão do PowerShell posterior à versão 7.2.0.

O script verifica os arquivos na pasta publish e baixados pelo aplicativo implantado para detectar problemas nos diferentes manifestos que contêm hashes de integridade. Essas verificações devem detectar os problemas mais comuns:

• Você modificou um arquivo na saída publicada sem perceber.
• O aplicativo não foi implantado corretamente no destino de implantação ou algo foi alterado no ambiente do destino de implantação.
• Há diferenças entre o aplicativo implantado e a saída da publicação do aplicativo.

Invoque o script com o seguinte comando em um shell de comando do PowerShell:

.\integrity.ps1 {BASE URL} {PUBLISH OUTPUT FOLDER}

No exemplo a seguir, o script é executado em um aplicativo em execução local em https://localhost:5001/:

.\integrity.ps1 https://localhost:5001/ C:\TestApps\BlazorSample\bin\Release\net6.0\publish\

Espaços reservados:

• {BASE URL}: a URL do aplicativo implantado. A barra à direita (/) é necessária.
• {PUBLISH OUTPUT FOLDER}: o caminho para a pasta ou o local publish do aplicativo em que o aplicativo é publicado para implantação.

Observação

Ao clonar o repositório GitHub dotnet/AspNetCore.Docs, o script integrity.ps1 pode ser colocado em quarentena pelo Bitdefender ou por outro verificador de vírus presente no sistema. Normalmente, o arquivo é interceptado pela tecnologia de verificação heurística de um verificador de vírus, que apenas procura padrões em arquivos que podem indicar a presença de malware. Para impedir que o verificador de vírus coloque o arquivo em quarentena, adicione uma exceção ao verificador de vírus antes de clonar o repositório. O exemplo a seguir é um caminho típico para o script em um sistema Windows. Ajuste o caminho conforme necessário para outros sistemas. O espaço reservado {USER} é o segmento de caminho do usuário.

C:\Users\{USER}\Documents\GitHub\AspNetCore.Docs\aspnetcore\blazor\host-and-deploy\webassembly\_samples\integrity.ps1

Aviso: criar exceções no verificador de vírus é perigoso e isso só deve ser feito quando você tiver certeza de que o arquivo está seguro.

Comparar a soma de verificação de um arquivo com um valor de soma de verificação válido não garante a segurança do arquivo, mas modificar um arquivo de forma a manter um valor de soma de verificação não é trivial para usuários mal-intencionados. Portanto, as somas de verificação são úteis como uma abordagem de segurança geral. Compare a soma de verificação do arquivo local integrity.ps1 com um dos seguintes valores:

• SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
• MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Obtenha a soma de verificação do arquivo no sistema operacional Windows com o comando a seguir. Forneça o caminho e o nome do arquivo para o espaço reservado {PATH AND FILE NAME} e indique o tipo de soma de verificação a ser produzida para o espaço reservado {SHA512|MD5}, SHA256 ou MD5:

CertUtil -hashfile {PATH AND FILE NAME} {SHA256|MD5}

Se você tiver algum motivo para se preocupar com o fato de que a validação da soma de verificação não é segura o suficiente no seu ambiente, consulte a liderança de segurança da sua organização para obter diretrizes.

Para obter mais informações, confira Visão geral da proteção contra ameaças pelo Microsoft Defender Antivírus.

Desabilitar o cache de recursos e as verificações de integridade para aplicativos que não são PWA

Na maioria dos casos, não desabilite a verificação de integridade. Desabilitar a verificação de integridade não resolve o problema subjacente que causou as respostas inesperadas e resulta na perda dos benefícios listados anteriormente.

Pode haver casos em que o servidor Web não pode ser invocado para retornar respostas consistentes e você não tem escolha a não ser desabilitar temporariamente as verificações de integridade até que o problema subjacente seja resolvido.

Para desabilitar as verificações de integridade, adicione o seguinte a um grupo de propriedades no arquivo de projeto do aplicativo Blazor WebAssembly (.csproj):

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources também desabilita o comportamento padrão do Blazor de armazenar em cache os arquivos .dll, .wasm e outros arquivos com base nos hashes SHA-256, pois a propriedade indica que os hashes SHA-256 não podem ser considerados corretos. Mesmo com essa configuração, o cache HTTP normal do navegador ainda pode armazenar em cache esses arquivos, mas se isso acontecerá ou não depende da configuração do servidor Web e dos cabeçalhos cache-control atendidos.

Observação

A propriedade BlazorCacheBootResources não desabilita as verificações de integridade para PWAs (Aplicativos Web Progressivos). Para obter diretrizes relativas aos PWAs, confira a seção Desabilitar verificação de integridade para PWAs.

Não é possível fornecer uma lista completa de cenários em que é necessário desabilitar a verificação de integridade. Os servidores podem responder a uma solicitação de maneiras arbitrárias fora do escopo da estrutura Blazor. A estrutura fornece a configuração BlazorCacheBootResources para tornar o aplicativo executável às custas de perder a garantia de integridade que o aplicativo pode fornecer. Novamente, não recomendamos desabilitar a verificação de integridade, especialmente para implantações de produção. Os desenvolvedores devem procurar resolver o problema de integridade subjacente que está causando falha na verificação de integridade.

Alguns casos gerais que podem causar problemas de integridade são:

• Em execução em HTTP, onde a integridade não pode ser verificada.
• Se o processo de implantação modificar os arquivos após a publicação de alguma forma.
• Se o host modificar os arquivos de alguma forma.

Desabilitar o cache de recursos e as verificações de integridade para PWAs

O modelo de PWA (Aplicativo Web Progressivo) do Blazor contém um arquivo service-worker.published.js sugerido, que é responsável por buscar e armazenar arquivos de aplicativo para uso offline. Esse é um processo separado do mecanismo normal de inicialização do aplicativo e tem sua própria lógica de verificação de integridade separada.

Dentro do arquivo service-worker.published.js, a seguinte linha está presente:

.map(asset => new Request(asset.url, { integrity: asset.hash }));

Para desabilitar a verificação de integridade, remova o parâmetro integrity alterando a linha para o seguinte:

.map(asset => new Request(asset.url));

Novamente, desabilitar a verificação de integridade significa que você perderá as garantias de segurança oferecidas pela verificação de integridade. Por exemplo, existe o risco de que, se o navegador do usuário estiver armazenando em cache o aplicativo no momento exato em que você implantar uma nova versão, ele poderá armazenar em cache alguns arquivos da implantação antiga e outros da nova implantação. Se isso acontecer, o aplicativo ficará paralisado em um estado interrompido até que você implante uma nova atualização.

Recursos adicionais

Carregamento de recursos de inicialização