Evitar problemas de cache HTTP ao atualizar aplicativos do ASP.NET Core Blazor

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão do .NET 10 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, consulte a Política de Suporte do .NET e do .NET Core. Para informações sobre a versão vigente, confira a versão .NET 9 deste artigo.

Este artigo explica como evitar problemas de cache HTTP ao atualizar Blazor aplicativos.

Quando Blazor os aplicativos são atualizados ou configurados incorretamente, isso pode resultar em atualizações não perfeitas para usuários existentes. Este artigo discute alguns dos problemas comuns de cache HTTP que podem ocorrer ao atualizar Blazor aplicativos em versões principais. Ele também fornece algumas ações recomendadas para garantir uma transição tranquila para seus usuários.

Embora versões futuras Blazor possam fornecer soluções melhores para lidar com problemas de cache HTTP, cabe ao aplicativo configurar corretamente o cache. A configuração de cache adequada garante que os usuários do aplicativo sempre tenham a versão mais up-todata do aplicativo, melhorando sua experiência e reduzindo a probabilidade de encontrar erros.

Problemas comuns que afetam negativamente a experiência de atualização do usuário incluem:

• Tratamento incorreto de atualizações de projeto e pacote: isso acontece se você não atualizar todos os projetos implantados do aplicativo para usar a mesma versão principal da estrutura ou se você usar pacotes de uma versão anterior quando uma versão mais recente estiver disponível como parte da atualização principal.
• Configuração incorreta de cabeçalhos de cache: cabeçalhos de cache HTTP controlam como, onde e por quanto tempo as respostas do aplicativo são armazenadas em cache. Se os cabeçalhos não estiverem configurados corretamente, os usuários poderão receber arquivos obsoletos ou incompatíveis. Isso inclui Blazor o armazenamento em cache de ativos de pacote, em que os cabeçalhos de cache do servidor devem ser configurados corretamente para evitar problemas de cache no cliente.
• Configuração incorreta de outras camadas: CDNs (Redes de Distribuição de Conteúdo) e outras camadas do aplicativo implantado podem causar problemas se configuradas incorretamente. Por exemplo, as CDNs são projetadas para armazenar em cache e fornecer conteúdo para melhorar o desempenho e reduzir a latência. Se uma CDN estiver atendendo incorretamente versões armazenadas em cache de ativos, ela poderá levar à entrega de conteúdo obsoleto para o usuário.

Detectar e diagnosticar problemas de atualização

Os problemas de atualização normalmente aparecem como uma falha ao iniciar o aplicativo no navegador. Normalmente, um aviso indica a presença de um ativo obsoleto ou um ativo ausente ou inconsistente com o aplicativo.

• Primeiro, verifique se o aplicativo é carregado com êxito em uma instância limpa do navegador. Use um modo de navegador privado para carregar o aplicativo, como o modo InPrivate do Microsoft Edge ou o modo Anônimo do Google Chrome. Se o aplicativo falhar ao carregar, isso provavelmente significa que um ou mais pacotes ou a estrutura não foi atualizada corretamente.
• Se o aplicativo for carregado corretamente em uma instância limpa do navegador, é provável que o aplicativo esteja sendo fornecido a partir de um cache antigo. Na maioria dos casos, uma atualização do navegador rígido com Ctrl+F5 libera o cache, o que permite que o aplicativo carregue e execute com os ativos mais recentes.
• Se o aplicativo continuar falhando, é provável que um cache de CDN obsoleto esteja servindo o aplicativo. Tente liberar o cache DNS por meio de qualquer mecanismo que seu provedor de CDN ofereça.

Ações recomendadas antes de uma atualização

O processo anterior para servir o aplicativo pode tornar o processo de atualização mais desafiador. Por exemplo, evitar ou usar incorretamente cabeçalhos de cache no passado pode levar a problemas de cache atuais para os usuários. Você pode executar as ações nas seções a seguir para atenuar o problema e melhorar o processo de atualização para os usuários.

Alinhar pacotes do framework com a versão do framework

Verifique se os pacotes de estrutura se alinham com a versão da estrutura. O uso de pacotes de uma versão anterior quando uma versão mais recente está disponível pode levar a problemas de compatibilidade. Também é importante garantir que todos os projetos implantados do aplicativo usem a mesma versão principal da estrutura. Essa consistência ajuda a evitar erros e comportamentos inesperados.

Verificar a presença de cabeçalhos de cache corretos

Os cabeçalhos de cache corretos devem estar presentes em respostas a solicitações de recurso. Isso inclui ETag, Cache-Controle outros cabeçalhos de cache. A configuração desses cabeçalhos depende do serviço de hospedagem ou da plataforma do servidor de hospedagem. Eles são particularmente importantes para ativos como o Blazor script e qualquer coisa que o script baixe.

Cabeçalhos de cache HTTP incorretos também podem afetar os trabalhadores do serviço. Os trabalhadores de serviço dependem de cabeçalhos de cache para gerenciar recursos armazenados em cache efetivamente. Portanto, cabeçalhos incorretos ou ausentes podem interromper a funcionalidade do trabalhador do serviço.

Usar Clear-Site-Data para excluir o estado no navegador

Considere usar o Clear-Site-Data cabeçalho para excluir o estado no navegador.

Normalmente, a origem dos problemas de estado de cache é limitada ao cache do navegador HTTP, portanto, o uso da diretiva cache deve ser suficiente. Essa ação pode ajudar a garantir que o navegador busque os recursos mais recentes do servidor, em vez de servir conteúdo obsoleto do cache.

Opcionalmente, você pode incluir a storage diretiva para limpar os caches de armazenamento local ao mesmo tempo em que está limpando o cache do navegador HTTP. No entanto, os aplicativos que usam o armazenamento do cliente poderão sofrer uma perda de informações importantes se a storage diretiva for usada.

Acrescentar uma cadeia de caracteres de consulta à tag de Blazor script

Se nenhuma das ações recomendadas anteriores for eficaz ou aplicável à sua implantação ou ao seu aplicativo, considere acrescentar temporariamente uma string de consulta à source do elemento Blazor script <script>. Essa ação deve ser suficiente na maioria das situações para forçar o navegador a ignorar o cache HTTP local e baixar uma nova versão do aplicativo. Não é necessário ler ou usar a cadeia de caracteres de consulta no aplicativo.

No exemplo a seguir, a cadeia de consulta temporaryQueryString=1 é temporariamente aplicada ao URI de fonte externa relativa da tag <script>.

<script src="_framework/blazor.webassembly.js?temporaryQueryString=1"></script>

Depois que todos os usuários do aplicativo recarregarem o aplicativo, a cadeia de caracteres de consulta poderá ser removida.

Como alternativa, você pode aplicar uma cadeia de caracteres de consulta persistente com versionamento relevante. O exemplo a seguir pressupõe que a versão do aplicativo corresponde à versão de lançamento do .NET (8 para .NET 8):

<script src="_framework/blazor.webassembly.js?version=8"></script>

Para localizar a tag de Blazor script <script>, consulte a estrutura do projeto ASP.NET CoreBlazor.