Hospede e implante ASP.NET Core Blazor WebAssembly

Este artigo explica como hospedar e implantar Blazor WebAssembly usando o ASP.NET Core, redes de distribuição de conteúdo (CDN), servidores de arquivos e páginas do GitHub.

Com o modelo de hospedagem Blazor WebAssembly:

• O aplicativo Blazor, suas dependências e o tempo de execução do .NET são baixados para o navegador em paralelo.
• O aplicativo é executado diretamente no thread da interface do usuário do navegador.

Hospedagem de subdomínio e subaplicativo do IIS

A hospedagem de subdomínio não requer configuração especial do aplicativo. Você não precisa configurar o caminho base da aplicação (a etiqueta <base> em wwwroot/index.html) para hospedar a aplicação em um subdomínio.

A hospedagem de subaplicações do IIS requer que seja definido o caminho base da aplicação. Para obter mais informações e hiperligações para orientações adicionais sobre o alojamento de subaplicações do IIS, consulte Host e implantar ASP.NET Core Blazor.

Diminuir o tamanho máximo de heap para alguns navegadores de dispositivos móveis

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Para obter mais informações sobre as propriedades e alvos do Mono/WebAssembly MSBuild , consulte ( repositório GitHub).

<PropertyGroup>
  <WasmEnableWebcil>false</WasmEnableWebcil>
</PropertyGroup>

Personalizar como os recursos de inicialização são carregados

Personalize como os recursos de inicialização são carregados usando a API loadBootResource. Para obter mais informações, consulte ASP.NET Core Blazor startup.

Compressão

Quando um aplicativo Blazor WebAssembly é publicado, a saída é compactada estaticamente durante a publicação para reduzir o tamanho do aplicativo e remover a sobrecarga para compactação em tempo de execução. Os seguintes algoritmos de compressão são usados:

• Brotli (nível mais alto)
• Gzip

• Para a configuração de compactação do IIS, consulte a seção de compactação IIS: Brotli e Gzip.
• Ao hospedar em soluções de hospedagem estática que não suportam negociação de conteúdo de arquivo compactado estaticamente, considere configurar o aplicativo para buscar e decodificar arquivos compactados Brotli:

Obtenha o decodificador JavaScript Brotli do repositório google/brotli GitHub. O arquivo decodificador minificado é chamado decode.min.js e encontrado na pasta js do repositório.

Atualize o aplicativo para usar o decodificador.

No arquivo wwwroot/index.html, defina autostart como false na tag <script> do Blazor:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>

Depois da tag <script> de Blazore antes da tag de fechamento </body>, adicione o bloco de código JavaScript <script>. A função a seguir chama fetch com cache: 'no-cache' para manter o cache do navegador atualizado.

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration' && type !== 'manifest') {
          return (async function () {
            const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
            if (!response.ok) {
              throw new Error(response.statusText);
            }
            const originalResponseBuffer = await response.arrayBuffer();
            const originalResponseArray = new Int8Array(originalResponseBuffer);
            const decompressedResponseArray = BrotliDecode(originalResponseArray);
            const contentType = type === 
              'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
            return new Response(decompressedResponseArray, 
              { headers: { 'content-type': contentType } });
          })();
        }
      }
    }
  });
</script>

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration') {
        return (async function () {
          const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
          if (!response.ok) {
            throw new Error(response.statusText);
          }
          const originalResponseBuffer = await response.arrayBuffer();
          const originalResponseArray = new Int8Array(originalResponseBuffer);
          const decompressedResponseArray = BrotliDecode(originalResponseArray);
          const contentType = type === 
            'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
          return new Response(decompressedResponseArray, 
            { headers: { 'content-type': contentType } });
        })();
      }
    }
  });
</script>

Para obter mais informações sobre como carregar recursos de inicialização, consulte ASP.NET Core Blazorde inicialização .

<PropertyGroup>
  <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

dotnet publish -p:CompressionEnabled=false

<PropertyGroup>
  <BlazorEnableCompression>false</BlazorEnableCompression>
</PropertyGroup>

dotnet publish -p:BlazorEnableCompression=false

Reescrever URLs para roteamento correto

Rotear solicitações para componentes de página em um aplicativo Blazor WebAssembly não é tão simples quanto rotear solicitações em um aplicativo Blazor Server. Considere um aplicativo Blazor WebAssembly com dois componentes:

• Main.razor: Carrega na raiz do aplicativo e contém um link para o componente About (href="About").
• About.razor: About componente.

Quando o documento padrão do aplicativo é solicitado usando a barra de endereço do navegador (por exemplo, https://www.contoso.com/):

1. O navegador faz um pedido.
2. A página padrão é retornada, que geralmente é index.html.
3. index.html inicializa o aplicativo.
4. O componente Router é carregado e o componente RazorMain é renderizado.

Na página principal, selecionar o link para o componente About funciona no cliente porque o roteador Blazor impede que o navegador faça uma solicitação na Internet para www.contoso.com em busca de About e fornece ele próprio o componente About já renderizado. Todas as solicitações para pontos de extremidade internos dentro do aplicativo Blazor WebAssembly funcionam da mesma maneira: as solicitações não acionam pedidos através do navegador para recursos hospedados em servidores na Internet. O roteador lida com as solicitações internamente.

Se uma solicitação for feita usando a barra de endereço do navegador para www.contoso.com/About, a solicitação falhará. Esse recurso não existe no host de Internet do aplicativo, portanto, uma resposta 404 - Não encontrado é retornada.

Como os navegadores fazem solicitações a hosts baseados na Internet para páginas do lado do cliente, os servidores Web e os serviços de hospedagem devem reescrever todas as solicitações de recursos que não estejam fisicamente no servidor para a página index.html. Quando index.html é retornado, o roteador Blazor do aplicativo assume o controle e responde com o recurso correto.

Ao implementar num servidor IIS, pode usar o Módulo de Reescrita de URL com o ficheiro publicado web.config do aplicativo. Para obter mais informações, consulte a seção do IIS.

<SelfContained>false</SelfContained>

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

<SelfContained>false</SelfContained>

Implantação independente

Um de implantação independente serve como um conjunto de arquivos estáticos que são solicitados diretamente pelos clientes ao aplicativo Blazor WebAssembly. Qualquer servidor de arquivos estáticos é capaz de servir o aplicativo Blazor.

Os ativos de implantação autônomos são publicados na pasta /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot ou bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish\ (dependendo da versão do SDK do .NET em uso), onde o espaço reservado {TARGET FRAMEWORK} é a estrutura de destino.

Serviço de Aplicativo do Azure

Blazor WebAssembly Aplicações podem ser implementadas nos Serviços de Aplicação do Azure no Windows, que hospeda a aplicação em IIS.

Atualmente, não há suporte para a implantação de um aplicativo Blazor WebAssembly autônomo no Serviço de Aplicativo do Azure para Linux. Recomendamos hospedar uma aplicação Blazor WebAssembly autónoma usando Azure Static Web Apps, que dá suporte a este cenário.

Aplicativos Web estáticos do Azure

Use uma das seguintes abordagens para implantar um aplicativo Blazor WebAssembly nos Aplicativos Web Estáticos do Azure:

• Implementar a partir do Visual Studio
• Publicar a partir do Visual Studio Code
• Implantar a partir do GitHub

Implantar a partir do Visual Studio

Para implantar a partir do Visual Studio, crie um perfil de publicação para os Aplicativos Web Estáticos do Azure:

1. Salve qualquer trabalho não salvo no projeto, pois uma reinicialização do Visual Studio pode ser necessária durante o processo.

2. Na interface de utilizador do Publish do Visual Studio, selecione Destino>Azure>Destino Específico>Aplicativos Web Estáticos do Azure para criar um perfil de publicação .

3. Se o componente Ferramentas de WebJobs do Azure para Visual Studio não estiver instalado, será exibido um prompt para instalar o componente ASP.NET e desenvolvimento Web. Siga as instruções para instalar as ferramentas usando o Visual Studio Installer. O Visual Studio fecha e reabre automaticamente durante a instalação das ferramentas. Depois que as ferramentas forem instaladas, comece de novo na primeira etapa para criar o perfil de publicação.

4. Na configuração do perfil de publicação, forneça o nome Assinatura. Selecione uma instância existente ou selecione Criar uma nova instância . Ao criar uma nova instância na interface do usuário do Create Static Web App do portal do Azure, defina os detalhes da Implantação de origem para Outros. Aguarde a conclusão da implantação no portal do Azure antes de continuar.

5. Na configuração do perfil de publicação, selecione a instância dos Aplicativos Web Estáticos do Azure no grupo de recursos da instância. Selecione Finalizar para criar o perfil de publicação. Se o Visual Studio solicitar a instalação da CLI de aplicativos Web estáticos (SWA), instale a CLI seguindo os prompts. A SWA CLI requer NPM/Node.js (documentação do Visual Studio).

Depois que o perfil de publicação for criado, implante o aplicativo na instância dos Aplicativos Web Estáticos do Azure usando o perfil de publicação selecionando o botão Publicar.

Implantar a partir de Visual Studio Code

Para implantar a partir do Visual Studio Code, consulte Guia de início rápido: criar seu primeiro site estático com o Azure Static Web Apps.

Implantar a partir do GitHub

Para implantar a partir de um repositório GitHub, consulte Tutorial: Construindo uma aplicação Web estática com Blazor em Aplicações Web Estáticas do Azure.

IIS

O IIS é um servidor eficaz de arquivos estáticos para aplicações Blazor. Para configurar o IIS para hospedar Blazor, consulte Criar um site estático no IIS.

Os conteúdos publicados são criados na pasta /bin/Release/{TARGET FRAMEWORK}/publish ou bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, dependendo de qual versão do SDK é utilizada, e onde o marcador de posição {TARGET FRAMEWORK} indica a framework de destino. Hospede o conteúdo da pasta publish no servidor Web ou serviço de hospedagem.

web.config

Quando um projeto Blazor é publicado, um arquivo de web.config é criado com a seguinte configuração do IIS:

• Tipos MIME
• A compactação HTTP está habilitada para os seguintes tipos de MIME:
  • application/octet-stream
  • application/wasm
• As regras do Módulo de Reescrita de URL são estabelecidas:
  • Sirva o subdiretório onde residem os ativos estáticos do aplicativo (wwwroot/{PATH REQUESTED}).
  • Crie o roteamento de fallback do SPA para que as solicitações de ativos que não sejam de arquivo sejam redirecionadas para o documento padrão do aplicativo em sua pasta de ativos estáticos (wwwroot/index.html).

Utilize um web.config personalizado

Para usar um arquivo de web.config personalizado:

Se a geração ou transformação de web.config do SDK durante a publicação não mover o arquivo para ativos publicados na pasta publish ou modificar a configuração personalizada em seu arquivo de web.config personalizado, use qualquer uma das seguintes abordagens, conforme necessário, para assumir o controle total do processo:

• Se o SDK não gerar o ficheiro, por exemplo, num app independente de Blazor WebAssembly em /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot ou bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, dependendo de qual versão do SDK é utilizada e onde o espaço reservado {TARGET FRAMEWORK} representa a framework de destino, defina a propriedade <PublishIISAssets> como true no ficheiro de projeto (.csproj). Normalmente, para aplicativos WebAssembly autônomos, essa é a única configuração necessária para mover um arquivo de web.config personalizado e impedir a transformação do arquivo pelo SDK.

  <PropertyGroup>
    <PublishIISAssets>true</PublishIISAssets>
  </PropertyGroup>
  

• Desative a transformação de web.config do SDK no arquivo de projeto (.csproj):

  <PropertyGroup>
    <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
  </PropertyGroup>
  

• Adicione um destino personalizado ao arquivo de projeto (.csproj) para mover um arquivo de web.config personalizado. No exemplo a seguir, o arquivo de web.config personalizado é colocado pelo desenvolvedor na raiz do projeto. Se o arquivo web.config residir em outro lugar, especifique o caminho para o arquivo em SourceFiles. O exemplo a seguir especifica a pasta publish com $(PublishDir), mas fornece um caminho para DestinationFolder para um local de saída personalizado.

  <Target Name="CopyWebConfig" AfterTargets="Publish">
    <Copy SourceFiles="web.config" DestinationFolder="$(PublishDir)" />
  </Target>
  

Instalar o módulo de reescrita de URL

O Módulo de Reescrita de URL é necessário para reescrever URLs. O módulo não é instalado por padrão e não está disponível para instalação como um recurso de serviço de função do Servidor Web (IIS). O módulo deve ser baixado do site do IIS. Use o Web Platform Installer para instalar o módulo:

1. Localmente, navegue até a página de downloads do Módulo de Reescrita de URL . Para a versão em inglês, selecione WebPI para baixar o instalador do WebPI. Para outros idiomas, selecione a arquitetura apropriada para o servidor (x86/x64) para baixar o instalador.
2. Copie o instalador para o servidor. Corra o instalador. Selecione o botão Instalar e aceite os termos da licença. Não é necessário reiniciar o servidor após a conclusão da instalação.

Configurar o site

Defina o caminho físico do site para a pasta do aplicativo. A pasta contém:

• O arquivo web.config que o IIS usa para configurar o site, incluindo as regras de redirecionamento necessárias e os tipos de conteúdo de arquivo.
• A pasta de ficheiros estáticos do aplicativo.

Hospedar como um subaplicativo do IIS

Se um aplicativo autônomo estiver hospedado como um subaplicativo do IIS, execute um dos seguintes procedimentos:

• Desative o manipulador herdado do ASP.NET Core Module.

  Remova o gestor no ficheiro web.config publicado da aplicação Blazor, adicionando uma secção <handlers> à secção <system.webServer> do ficheiro:

  <handlers>
    <remove name="aspNetCore" />
  </handlers>
  

• Desative a herança da seção <system.webServer> do aplicativo raiz (pai) usando um elemento <location> com inheritInChildApplications definido como false:

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <location path="." inheritInChildApplications="false">
      <system.webServer>
        <handlers>
          <add name="aspNetCore" ... />
        </handlers>
        <aspNetCore ... />
      </system.webServer>
    </location>
  </configuration>
  

  Observação

  A desativação da herança da seção <system.webServer> do aplicativo raiz (pai) é a configuração padrão para aplicativos publicados usando o SDK do .NET.

A remoção do manipulador ou a desativação da herança é realizada para além da configuração do caminho base do aplicativo. Defina o caminho base do aplicativo no arquivo de index.html do aplicativo para o alias do IIS usado ao configurar o subaplicativo no IIS.

Configure o caminho base da aplicação seguindo as orientações do artigo Host e implementar ASP.NET Core Blazor.

Compressão Brotli e Gzip

O IIS pode ser configurado via web.config para fornecer ativos de Blazor compactados Brotli ou Gzip para aplicativos Blazor WebAssembly autônomos. Para obter um exemplo de arquivo de configuração, consulte web.config.

A configuração adicional do arquivo de web.config de exemplo pode ser necessária nos seguintes cenários:

• A especificação do aplicativo exige um dos seguintes:
  • Servindo ficheiros comprimidos que não estão configurados pelo exemplo de ficheiro web.config.
  • Servindo arquivos compactados configurados pelo exemplo web.config arquivo em um formato não compactado.
• A configuração do IIS do servidor (por exemplo, applicationHost.config) fornece padrões do IIS no nível do servidor. Dependendo da configuração no nível do servidor, o aplicativo pode exigir uma configuração do IIS diferente da que o arquivo de web.config de exemplo contém.

Para obter mais informações sobre arquivos web.config personalizados, consulte a seção Usar um web.config personalizado.

Solução de problemas

Se um 500 - Erro Interno do Servidor for recebido e o Gestor do IIS lançar erros ao tentar aceder à configuração do site, confirme se o Módulo de Reescrita de URL está instalado. Quando o módulo não está instalado, o arquivo de web.config não pode ser analisado pelo IIS. Isso impede que o Gerenciador do IIS carregue a configuração do site e que o site sirva os arquivos estáticos do Blazor.

Para obter mais informações sobre como solucionar problemas de implantações no IIS, consulte Solucionar problemas do ASP.NET Core no Serviço de Aplicativo do Azure e no IIS.

Armazenamento do Azure

Armazenamento do Azure hospedagem de arquivos estáticos permite a hospedagem de aplicativos Blazor sem servidor. Há suporte para nomes de domínio personalizados, a CDN (Rede de Entrega de Conteúdo) do Azure e HTTPS.

Quando o serviço de blob está habilitado para hospedagem de site estático em uma conta de armazenamento:

• Defina o nome do documento Índice para index.html.
• Defina o caminho do documento Erro como index.html. Razor componentes e outros pontos de extremidade que não sejam de arquivo não residem em caminhos físicos no conteúdo estático armazenado pelo serviço BLOB. Quando uma solicitação para um desses recursos é recebida, que deve ser manipulada pelo roteador Blazor, o erro 404 - Not Found, gerado pelo serviço de blobs, roteia a solicitação para o caminho do documento de erro . O blob index.html é retornado e o roteador Blazor carrega e processa o caminho.

Se os arquivos não forem carregados em tempo de execução devido a tipos MIME inadequados nos cabeçalhos Content-Type dos arquivos, execute uma das seguintes ações:

• Configure suas ferramentas para definir os tipos MIME corretos (cabeçalhosContent-Type) quando os arquivos forem implantados.

• Altere os tipos MIME (cabeçalhosContent-Type) dos arquivos após a implantação do aplicativo.

  No Gerenciador de Armazenamento (portal do Azure) para cada arquivo:

  1. Clique com o botão direito do mouse no arquivo e selecione Propriedades.
  2. Configure o ContentType e selecione o botão Guardar.

Para obter mais informações, consulte hospedagem de websites estáticos no Armazenamento do Azure.

Nginx

O seguinte arquivo de nginx.conf é simplificado para mostrar como configurar o Nginx para enviar o arquivo index.html sempre que não conseguir encontrar um arquivo correspondente no disco.

events { }
http {
    server {
        listen 80;

        location / {
            root      /usr/share/nginx/html;
            try_files $uri $uri/ /index.html =404;
        }
    }
}

Ao definir o limite de taxa de rajada NGINX com limit_req, as aplicações Blazor WebAssembly podem exigir um valor de parâmetro burst bastante elevado para acomodar o número relativamente grande de solicitações feitas por uma aplicação. Inicialmente, defina o valor como pelo menos 60:

http {
    server {
        ...

        location / {
            ...

            limit_req zone=one burst=60 nodelay;
        }
    }
}

Aumente o valor se as ferramentas de desenvolvedor do navegador ou uma ferramenta de tráfego de rede indicarem que as solicitações estão recebendo um código de status 503 - Serviço Indisponível.

Para obter mais informações sobre a configuração do servidor Web Nginx de produção, consulte Criando arquivos de configuração NGINX Plus e NGINX.

Apache

Para implantar um aplicativo Blazor WebAssembly no Apache:

1. Coloque o arquivo de configuração do Apache no diretório /etc/httpd/conf.d/.

2. Coloque os ativos publicados da aplicação (/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot, onde o espaço reservado {TARGET FRAMEWORK} é a estrutura de destino) no diretório /var/www/blazorapp (o local especificado para DocumentRoot no ficheiro de configuração).

3. Reinicie o serviço Apache.

Para obter mais informações, consulte mod_mime e mod_deflate.

Páginas do GitHub

As diretrizes a seguir para implantações de aplicações Blazor WebAssembly em GitHub Pages demonstram conceitos através de uma ferramenta em tempo real implantada nas Páginas do GitHub. A ferramenta é usada pelos autores da documentação do ASP.NET Core para criar links de referência cruzada (XREF) para a documentação da API para marcação de artigos:

• BlazorWebAssemblyXrefGenerator aplicativo de exemplo (blazor-samples/BlazorWebAssemblyXrefGenerator)
• Site do Live Xref Generator

Configurações do GitHub Pages

• Ações>Geral
  • Permissões de Ações
    • Permitir ações empresariais e selecionar ações não empresariais, e fluxos de trabalho reutilizáveis> Ativado (selecionado)
    • Permitir ações criadas pelo GitHub> Ativado (selecionado)
    • Permitir ações e fluxos de trabalho reutilizáveis>stevesandersonms/ghaction-rewrite-base-href@v1,
  • Permissões de fluxo de trabalho>Ler conteúdo do repositório e permissões de pacotes
• Pages>Compilação e implementação
  • Fonte>Ações do GitHub
  • Fluxo de trabalho selecionado: HTML estático e baseie seu script de ação de implantação estática no de arquivos do Xref Generator para a ferramenta Xref Generator. A configuração no arquivo é descrita na próxima seção.
  • de domínio personalizado: defina se você pretende usar um domínio personalizado, que não é coberto por estas diretrizes. Para obter mais informações, consulte Configurando um domínio personalizado para seu site de Páginas do GitHub.
  • Forçar HTTPS> Ativado (selecionado)

Configuração de script de implantação estática

Xref Generator static.yml arquivo

Configure as seguintes entradas no script para sua implantação:

• Diretório de publicação (PUBLISH_DIR): Use o caminho para a pasta do repositório onde o aplicativo Blazor WebAssembly está publicado. A aplicação é compilada para uma versão específica do .NET e o segmento de caminho correspondente à versão deve corresponder. Exemplo: é o caminho para um aplicativo que adota o Target Framework Moniker (TFM) para o SDK do .NET 9.0
• Push path (on:push:paths): defina o push path para corresponder à pasta repo do aplicativo com um curinga **. Exemplo: BlazorWebAssemblyXrefGenerator/**
• Versão do SDK do .NET ( via a Ação): Atualmente, não há maneira de definir a versão como "mais recente" (veja para Permitir especificar 'mais recente' como dotnet-version ( #497) e apoiar o pedido do recurso). Defina a versão do SDK pelo menos tão alta quanto a versão da estrutura do aplicativo.
• Caminho de publicação (comandodotnet publish): defina o caminho da pasta de publicação para a pasta de repositório do aplicativo. Exemplo: dotnet publish BlazorWebAssemblyXrefGenerator -c Release
• Base HREF (base_href for the SteveSandersonMS/ghaction-rewrite-base-href Action): Definir o href base da aplicação para o nome do repositório. Exemplo: O proprietário do repositório do Blazor sample é dotnet. O nome do repositório do exemplo de Blazor é blazor-samples. Quando a ferramenta Xref Generator é implantada nas páginas do GitHub, seu endereço da Web é baseado no nome do repositório (https://dotnet.github.io/blazor-samples/). O href base da aplicação é /blazor-samples/, que é definido em base_href para que a ação ghaction-rewrite-base-href seja gravada na tag wwwroot/index.html<base> da aplicação quando ela for implantada. Para obter mais informações, consulte Host e implantar ASP.NET Core Blazor.

O servidor Ubuntu (mais recente) hospedado no GitHub tem uma versão do SDK do .NET pré-instalada. Você pode remover a etapa actions/setup-dotnet Action do script static.yml se o SDK do .NET pré-instalado for suficiente para compilar a aplicação. Para determinar o SDK do .NET instalado para ubuntu-latest:

1. Vá para a seção Imagens Disponíveis do repositório actions/runner-images GitHub.
2. Localize a imagem ubuntu-latest, que é a primeira linha da tabela.
3. Selecione o link na coluna Included Software.
4. Role para baixo até a seção Ferramentas do .NET para ver o SDK do .NET Core instalado com a imagem.

Notas de implantação

A ação padrão do GitHub, que implanta páginas, ignora a implantação de pastas começando com sublinhado, a pasta _framework, por exemplo. Para implantar pastas começando com sublinhado, adicione um arquivo de .nojekyll vazio à raiz do repositório do aplicativo. Exemplo: Xref Generator .nojekyll arquivo

Execute esta etapa antes da primeira implantação do aplicativo: o Git trata arquivos JavaScript (JS), como blazor.webassembly.js, como texto e converte terminações de linha de CRLF (alimentação de linha de retorno de carro) para LF (alimentação de linha) no pipeline de implantação. Essas alterações em arquivos JS produzem hashes de arquivo diferentes do que Blazor envia para o cliente no arquivo blazor.boot.json. As incompatibilidades resultam em falhas de verificação de integridade no cliente. Uma abordagem para resolver este problema é adicionar um arquivo .gitattributes com *.js binary linha antes de adicionar os recursos da aplicação à ramificação do Git. A linha *.js binary configura o Git para tratar os JS ficheiros como ficheiros binários, o que evita o processamento dos ficheiros no pipeline de entrega. Os hashes de arquivo dos arquivos não processados correspondem às entradas no arquivo blazor.boot.json e as verificações de integridade do lado do cliente são aprovadas. Para obter mais informações, consulte ASP.NET Core Blazor WebAssembly tempo de execução .NET e armazenamento em cache do pacote de aplicações. Exemplo: Xref Generator .gitattributes arquivo

Para lidar com regravações de URL com base em aplicativos de página única para páginas do GitHub (rafrex/spa-github-pages repositório GitHub):

• Adicione um arquivo wwwroot/404.html com um script que lida com o redirecionamento da solicitação para a página index.html. Exemplo: Xref Generator 404.html arquivo
• No wwwroot/index.html, adicione o script ao conteúdo <head>. Exemplo: Xref Generator index.html arquivo

O GitHub Pages não suporta nativamente o uso de recursos compactados pelo Brotli. Para usar Brotli:

• Adicione o script wwwroot/decode.js à pasta wwwroot do aplicativo. Exemplo: Xref Generator decode.js arquivo

• Adicione a tag <script> para carregar o script decode.js no arquivo wwwroot/index.html imediatamente acima da tag <script> que carrega o script Blazor. Exemplo: Xref Generator index.html arquivo

  • Defina autostart="false" para o script Blazor WebAssembly.
  • Adicione o script loadBootResource após a tag <script> que carrega o script Blazor WebAssembly. Exemplo: Xref Generator index.html arquivo

• Adicione robots.txt e sitemap.txt arquivos para melhorar o SEO. Exemplos: Xref Generator robots.txt arquivo, Xref Generator sitemap.txt arquivo

Autónomo com Docker

Um aplicativo Blazor WebAssembly autônomo é publicado como um conjunto de arquivos estáticos para hospedagem por um servidor de arquivos estático.

Para hospedar o aplicativo no Docker:

• Escolha um contêiner Docker com suporte a servidor Web, como Ngnix ou Apache.
• Copie os ativos da pasta publish para uma pasta de local definida no servidor Web para servir arquivos estáticos.
• Aplique a configuração adicional conforme necessário para servir o aplicativo Blazor WebAssembly.

Para obter orientações de configuração, consulte os seguintes recursos:

• seção Nginx ou seção Apache deste artigo
• Documentação do Docker

Valores de configuração do host

Blazor WebAssembly aplicativos podem aceitar os seguintes valores de configuração de host como argumentos de linha de comando em tempo de execução no ambiente de desenvolvimento.

Raiz do conteúdo

O argumento --contentroot define o caminho absoluto para o diretório que contém os arquivos de conteúdo do aplicativo (raiz de conteúdo). Nos exemplos a seguir, /content-root-path é o caminho raiz do conteúdo do aplicativo.

• Passe o argumento ao executar o aplicativo localmente em um prompt de comando. No diretório do aplicativo, execute:

  dotnet watch --contentroot=/content-root-path
  

• Adicione uma entrada no arquivo launchSettings.json do aplicativo no perfil IIS Express. Essa configuração é usada quando a aplicação é executada com o depurador do Visual Studio e a partir de uma linha de comandos com dotnet watch (ou dotnet run).

  "commandLineArgs": "--contentroot=/content-root-path"
  

• No Visual Studio, especifique o argumento em Propriedades>Depurar>argumentos do aplicativo. Definir o argumento na página de propriedades do Visual Studio adiciona o argumento ao arquivo launchSettings.json.

  --contentroot=/content-root-path
  

Base de caminho

O argumento --pathbase define o caminho base da aplicação para uma execução local com um caminho de URL relativo não raiz (a tag <base>href é definida para um caminho diferente de / para os ambientes de teste e produção). Nos exemplos a seguir, /relative-URL-path é a base de caminho do aplicativo. Para obter mais informações, consulte Caminho base do aplicativo.

• Passe o argumento ao executar o aplicativo localmente em um prompt de comando. No diretório do aplicativo, execute:

  dotnet watch --pathbase=/relative-URL-path
  

• Adicione uma entrada ao arquivo do aplicativo no perfil do IIS Express. Essa configuração é usada ao executar o aplicativo com o Depurador do Visual Studio e a partir de um prompt de comando com dotnet watch (ou dotnet run).

  "commandLineArgs": "--pathbase=/relative-URL-path"
  

• No Visual Studio, especifique o argumento em Propriedades>Depurar>argumentos da aplicação. Definir o argumento na página de propriedades do Visual Studio adiciona o argumento ao arquivo launchSettings.json.

  --pathbase=/relative-URL-path
  

URLs

O argumento --urls define os endereços IP ou endereços de host com portas e protocolos para escutar solicitações.

• Passe o argumento ao executar o aplicativo localmente em um prompt de comando. No diretório do aplicativo, execute:

  dotnet watch --urls=http://127.0.0.1:0
  

• Adicione uma entrada ao ficheiro da aplicação no perfil do IIS Express . Essa configuração é usada ao executar o aplicativo com o Depurador do Visual Studio e a partir de um prompt de comando com dotnet watch (ou dotnet run).

  "commandLineArgs": "--urls=http://127.0.0.1:0"
  

• No Visual Studio, especifique o argumento em Propriedades>Modo de Depuração>argumentos da aplicação. Definir o argumento na página de propriedades do Visual Studio adiciona o argumento ao arquivo launchSettings.json.

  --urls=http://127.0.0.1:0
  

dir {PATH} | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
((Get-Content {PATH}\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\blazor.boot.json

((Get-Content {PATH}\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\service-worker-assets.js

for f in {PATH}/*; do mv "$f" "`echo $f | sed -e 's/\.dll/.bin/g'`"; done
sed -i 's/\.dll"/.bin"/g' {PATH}/blazor.boot.json

sed -i 's/\.dll"/.bin"/g' {PATH}/service-worker-assets.js

param([string]$filepath,[string]$tfm)
dir $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
((Get-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json.gz
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json.br

((Get-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js.gz
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js.br

<Target Name="ChangeDLLFileExtensions" AfterTargets="AfterPublish" Condition="'$(Configuration)'=='Release'">
  <Exec Command="powershell.exe -command &quot;&amp; { .\ChangeDLLExtensions.ps1 '$(SolutionDir)' '$(TargetFramework)'}&quot;" />
</Target>

<staticContent>
  ...
  <mimeMap fileExtension=".bin" mimeType="application/octet-stream" />
  ...
</staticContent>

<mimeMap fileExtension=".bin.br" mimeType="application/octet-stream" />
<mimeMap fileExtension=".bin.gz" mimeType="application/octet-stream" />

- <mimeMap fileExtension=".dll" mimeType="application/octet-stream" />

- <mimeMap fileExtension=".dll.br" mimeType="application/octet-stream" />
- <mimeMap fileExtension=".dll.gz" mimeType="application/octet-stream" />

Corrupção de implantação anterior

Normalmente, na implantação:

• Somente os arquivos que foram alterados são substituídos, o que geralmente resulta em uma implantação mais rápida.
• Os arquivos existentes que não fazem parte da nova implantação são deixados no local para uso pela nova implantação.

Em casos raros, arquivos persistentes de uma implantação anterior podem corromper uma nova implantação. A exclusão completa da implantação existente (ou do aplicativo publicado localmente antes da implantação) pode resolver o problema com uma implantação corrompida. Muitas vezes, excluir a implantação existente após é suficiente para resolver o problema, inclusive para um pipeline de compilação e implantação de DevOps.

Se você determinar que a limpeza de uma implantação anterior é sempre necessária quando um pipeline de compilação e implantação de DevOps estiver em uso, poderá adicionar temporariamente uma etapa ao pipeline de compilação para excluir a implantação anterior para cada nova implantação até solucionar a causa exata da corrupção.

Resolver falhas de verificação de integridade

Quando 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 valores de hash SHA-256 para DLL (.dll), WebAssembly (.wasm) e outros arquivos no arquivo blazor.boot.json, que não é armazenado em cache nos clientes. Os hashes dos ficheiros em cache são comparados aos hashes no ficheiro blazor.boot.json. Para arquivos armazenados em cache com um hash correspondente, Blazor usa os arquivos armazenados em cache. Caso contrário, os arquivos são solicitados do servidor. Depois que um arquivo é baixado, seu hash é verificado novamente para validação de integridade. Um erro é gerado pelo navegador se a verificação de integridade de qualquer arquivo baixado falhar.

Blazoralgoritmo para gerir a integridade do ficheiro:

• Garante que o aplicativo não corra o risco de carregar um conjunto inconsistente de arquivos, por exemplo, se uma nova implantação for aplicada ao seu servidor Web enquanto o usuário estiver no processo de download dos arquivos do aplicativo. 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 manualmente a página.
• Torna seguro armazenar em cache as respostas e não verificar se há alterações no servidor até que os próprios hashes SHA-256 esperados mudem, para que os carregamentos de página subsequentes envolvam menos solicitações e sejam concluídos 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 encontrar um resumo válido no atributo 'integridade' para o recurso 'https://myapp.example.com/_framework/MyBlazorApp.dll' com integridade SHA-256 computada 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. O recurso foi bloqueado.

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

Para obter a fonte de referência de inicialização do Blazor WebAssembly, consulte o arquivo Boot.WebAssembly.ts no repositório dotnet/aspnetcore GitHub.

Diagnosticar problemas de integridade

Quando uma aplicação é criada, o manifesto gerado blazor.boot.json descreve os hashes SHA-256 dos recursos de arranque no momento em que o resultado da compilação é gerado. A verificação de integridade passa desde que os hashes SHA-256 em blazor.boot.json correspondam aos arquivos entregues ao navegador.

As razões comuns pelas quais isso não acontece incluem:

• A resposta do servidor Web é um erro (por exemplo, um 404 - Not Found ou um 500 - Internal Server Error) em vez do ficheiro que o navegador solicitou. Isso é relatado pelo navegador como uma falha de verificação de integridade e não como uma falha de resposta.
• Algo mudou o conteúdo dos arquivos entre a compilação e a entrega dos arquivos para o navegador. Isto pode acontecer:
  • Se você ou as ferramentas de compilação modificarem manualmente a saída da compilação.
  • Se algum aspeto do processo de implantação modificou os arquivos. Por exemplo, se você usar um mecanismo de implantação baseado em Git, lembre-se de que o Git converte de forma transparente terminações de linha no estilo Windows em terminações de linha no estilo Unix se você confirmar arquivos no Windows e verificá-los no Linux. A alteração das terminações das linhas de arquivo altera os hashes SHA-256. Para evitar esse problema, considere usando .gitattributes para tratar artefatos de compilação como arquivos binary.
  • O servidor Web modifica o conteúdo do arquivo como parte do seu serviço. Por exemplo, algumas redes de distribuição de conteúdo (CDNs) tentam automaticamente minificar HTML, modificando-o. Pode ser necessário desativar esses recursos.
• O arquivo de blazor.boot.json não é carregado corretamente ou está incorretamente armazenado em cache no cliente. As causas comuns incluem uma das seguintes:
  • Código de desenvolvedor personalizado mal configurado ou com mau funcionamento.
  • Uma ou mais camadas de cache intermediárias mal configuradas.

Para diagnosticar qual delas se aplica no seu caso:

1. Observe qual arquivo está disparando o erro lendo a mensagem de erro.
2. Abra as ferramentas de desenvolvedor do seu navegador e procure 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 qualquer coisa diferente de 200 - OK (ou outro código de status 2xx), então você tem um problema do 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. Consulte os logs 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 desenvolvimento do navegador e verifique se o conteúdo corresponde aos dados esperados. Por exemplo, um problema comum é configurar incorretamente o roteamento para que as solicitações retornem seus dados index.html, mesmo para outros arquivos. Certifique-se de que as respostas de pedidos .wasm são binários de WebAssembly e que as respostas de pedidos .dll são binários de assembly .NET. Se não, você tem um problema de roteamento do lado do servidor para diagnosticar.
5. Tente validar a saída publicada e implantada da aplicação com o script PowerShell de Resolução de problemas de integridade .

Se você confirmar que o servidor está retornando dados plausivelmente corretos, deve haver algo mais modificando o conteúdo entre a compilação e a entrega do arquivo. Para investigar isso:

• Examine a cadeia de ferramentas de compilação e o mecanismo de implantação caso eles estejam modificando arquivos depois que os arquivos forem criados. Um exemplo disso é quando o Git transforma terminações de linha de arquivo, conforme descrito anteriormente.
• Examine a configuração do servidor Web ou da CDN caso eles estejam configurados para modificar respostas dinamicamente (por exemplo, tentando reduzir o HTML). Não há problema em o servidor Web implementar a compactação HTTP (por exemplo, retornar content-encoding: br ou content-encoding: gzip), já que isso não afeta o resultado após a descompressão. No entanto, não é adequado para o servidor web modificar os dados não compactados.

Solucionar problemas de integridade do script PowerShell

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

O script verifica os ficheiros na pasta publish e os que foram baixados do aplicativo implantado para detetar problemas nos diferentes manifests que contêm hashes de integridade. Essas verificações devem detetar 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 mudou no ambiente do destino de implantação.
• Existem diferenças entre a aplicação implementada e o resultado da publicação da aplicação.

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 executado localmente 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. É necessária uma barra final (/).
• {PUBLISH OUTPUT FOLDER}: O caminho para a pasta publish do aplicativo ou local onde o aplicativo é publicado para implantação.

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

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

Desativar a verificação de integridade para aplicativos que não sejam PWA

Na maioria dos casos, não desative a verificação de integridade. Desativar 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 possa ser confiável para retornar respostas consistentes, e você não tem escolha a não ser desativar temporariamente as verificações de integridade até que o problema subjacente seja resolvido.

Para desativar 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 Blazorde armazenar em cache os arquivos .dll, .wasme outros com base em seus hashes SHA-256 porque a propriedade indica que os hashes SHA-256 não podem ser considerados para correção. Mesmo com essa configuração, o cache HTTP normal do navegador ainda pode armazenar esses arquivos em cache, mas se isso acontece ou não depende da configuração do seu servidor Web e dos cabeçalhos cache-control que ele serve.

Não podemos fornecer uma lista exaustiva de cenários em que a desativação da verificação de integridade é necessária. 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 ao custo de perder uma garantia de integridade que o aplicativo pode fornecer. Mais uma vez, não recomendamos desativar 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 seu processo de implantação modifica os arquivos após a publicação de qualquer forma.
• Se o seu anfitrião modificar os ficheiros de alguma forma.

Desativar a verificação de integridade para PWAs

O modelo de Aplicação Web Progressiva (PWA) do Blazorcontém um arquivo service-worker.published.js sugerido que é responsável por buscar e armazenar ficheiros da aplicação para uso offline. Este é 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 desativar a verificação de integridade, remova o parâmetro integrity alterando a linha para o seguinte:

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

Mais uma vez, desativar a verificação de integridade significa que você perde as garantias de segurança oferecidas pela verificação de integridade. Por exemplo, há um risco de que, se o navegador do usuário estiver armazenando o aplicativo em cache no momento exato em que você implanta uma nova versão, ele poderá armazenar em cache alguns arquivos da implantação antiga e alguns da nova implantação. Se isso acontecer, o aplicativo ficará preso em um estado quebrado até que você implante uma nova atualização.