Hospedar e implantar o ASP.NET Core Blazor WebAssembly

Este artigo explica como hospedar e implantar aplicativos Blazor WebAssembly.

Com o modelo de hospedagem Blazor WebAssembly:

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

Este artigo refere-se ao cenário de implantação no qual o aplicativo Blazor é colocado em um servidor Web ou serviço de hospedagem estática e o .NET não é utilizado para servir o aplicativo Blazor. Essa estratégia é abordada na seção de implantação autônoma e em outros artigos neste nó para IIS, serviços do Azure, Apache, Nginx e GitHub Pages.

Hospedagem de subdomínio e sub-aplicativo do IIS

A hospedagem de subdomínio não requer uma configuração especial do aplicativo. Você não precisa configurar o caminho básico do aplicativo (a tag <base> no wwwroot/index.html) para hospedar o aplicativo em um subdomínio.

A hospedagem do sub-aplicativo do IIS requer que você defina o caminho básico do aplicativo. Para obter mais informações e links cruzados para orientações adicionais sobre a hospedagem de subaplicativos no IIS, veja Hospedar e implantar aplicativos no ASP.NET CoreBlazor.

Diminuir o tamanho máximo do heap para alguns navegadores de dispositivo móvel

Ao criar um aplicativo Blazor que é executado no cliente (projeto .Client de um Blazor Web App ou aplicativo Blazor WebAssembly autônomo) e destina-se a navegadores de dispositivo móvel, especialmente o Safari no iOS, pode ser necessário diminuir a memória máxima do aplicativo com a propriedade MSBuild EmccMaximumHeapSize. O valor padrão é 2.147.483.648 bytes, o que pode ser muito grande e resultar no travamento do aplicativo se o aplicativo tentar alocar mais memória com o navegador falhando em concedê-la. O exemplo a seguir define o valor como 268.435.456 bytes no arquivo Program:

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Para mais informações sobre as propriedades e destinos do Mono/WebAssembly MSBuild, confira WasmApp.Common.targets (repositório GitHub dotnet/runtime).

Formato de empacotamento Webcil para assemblies .NET

O Webcil é um formato de empacotamento amigável para assemblies .NET projetado para possibilitar o uso do Blazor WebAssembly em ambientes de rede restritivos. Os arquivos Webcil usam um wrapper WebAssembly padrão, em que os assemblies são implantados como arquivos WebAssembly que usam a extensão de arquivo .wasm padrão.

O Webcil é o formato de empacotamento padrão quando você publica um aplicativo Blazor WebAssembly. Para desabilitar o uso do Webcil, defina a seguinte propriedade MSBuild no arquivo de projeto do aplicativo:

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

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

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

Compactação

Quando um aplicativo do 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 de runtime. Os seguintes algoritmos de compactação são usados:

• Brotli (nível mais alto)
• Gzip

Blazor depende do host para atender aos arquivos compactados apropriados. Ao hospedar um aplicativo autônomo Blazor WebAssembly, pode ser necessário um trabalho adicional para garantir que arquivos compactados estaticamente sejam servidos:

• Para configuração de compactação web.config do IIS, confira a seção IIS: compactação de Brotli e Gzip.
• Ao fazer a hospedagem em soluções de hospedagem estáticas que não dão suporte à negociação de conteúdo de arquivo compactado estaticamente, considere a configuração do aplicativo para buscar e decodificar arquivos compactados em Brotli:

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

Observação

Se a versão minimizada do script decode.js (decode.min.js) falhar, tente usar a versão não minimizada (decode.js).

Atualize o aplicativo para usar o decodificador.

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

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

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

Blazor Web App:

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

Blazor WebAssembly autônomo:

<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, confira Inicialização Blazor do AsP.NET Core.

Para desabilitar a compactação, adicione a propriedade do MSBuild CompressionEnabled ao arquivo de projeto do aplicativo e defina o valor como false:

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

A propriedade CompressionEnabled pode ser passada para o comando dotnet publish com a seguinte sintaxe em um shell de comando:

dotnet publish -p:CompressionEnabled=false

Reescrever as URLs para obter o roteamento correto

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

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

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

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

Na página principal, a seleção do link para o componente About funciona no cliente porque o roteador do Blazor impede que o navegador faça uma solicitação na Internet para o www.contoso.com no About e atende ao próprio componente About renderizado. Todas as solicitações de endpoints internos dentro do aplicativo Blazor WebAssembly funcionam da mesma maneira: as solicitações não geram requisições do navegador para recursos hospedados em servidores na Internet. O roteador trata das solicitações internamente.

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

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

Ao implantar em um servidor IIS, você pode usar o Módulo de Reescrita de URL com o arquivo web.config publicado do aplicativo. Para obter mais informações, consulte Hospedar e implantar ASP.NET Core Blazor WebAssembly com o IIS.

Implantação autônoma

Uma implantação autônoma atende ao aplicativo do Blazor WebAssembly como um conjunto de arquivos estáticos que são solicitados diretamente pelos clientes. Qualquer servidor de arquivos estático é capaz de atender ao aplicativo do 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, onde o espaço reservado {TARGET FRAMEWORK} é a estrutura de destino.

Serviço de Aplicativo do Azure

Blazor WebAssembly os aplicativos podem ser implantados nos Serviços de Aplicativo do Azure no Windows, que hospedam o aplicativo no IIS.

Atualmente, não há suporte para a implantação de um aplicativo autônomo Blazor WebAssembly no Serviço de Aplicativo do Azure para Linux. Recomendamos hospedar um aplicativo autônomo Blazor WebAssembly usando os Aplicativos Web Estáticos do Azure, que dão suporte a esse cenário.

Aplicativo autônomo com o Docker

Um aplicativo autônomo Blazor WebAssembly é 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 do Docker com suporte de servidor Web, como Nginx ou Apache.
• Copie os ativos da pasta publish para uma pasta de local definida no servidor Web para atender aos arquivos estáticos.
• Aplique a configuração adicional conforme necessário para atender ao aplicativo Blazor WebAssembly.

Para obter diretrizes de configuração, confira os seguintes recursos:

• Artigos do Nginx ou apache
• Documentação do Docker

Valores de configuração do host

Os aplicativos Blazor WebAssembly podem aceitar os seguintes valores de configuração do 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 ao arquivo launchSettings.json do aplicativo no perfil do IIS Express. Esta configuração é usada quando o aplicativo é executado com o Depurador do Visual Studio e em um prompt de comando com dotnet watch (ou dotnet run).

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

• No Visual Studio, especifique o argumento em Propriedades>Depurar>Argumentos de aplicativo. A configuração do argumento na página de propriedades do Visual Studio adiciona o argumento ao arquivo launchSettings.json.

  --contentroot=/content-root-path
  

Caminho base

O argumento --pathbase define o caminho base do aplicativo para um aplicativo executado localmente com um caminho de URL relativa não raiz (a marca <base> do href é definida como um caminho diferente de / para preparo e produção). Nos exemplos a seguir, /relative-URL-path é o caminho base do aplicativo. Para obter mais informações, consulte Caminho base do aplicativo ASP.NET CoreBlazor.

Importante

Ao contrário do caminho fornecido ao href da tag <base>, não inclua uma barra no final (/) ao passar o valor do argumento --pathbase. Se o caminho base do aplicativo for fornecido na tag <base> como <base href="/CoolApp/"> (inclui uma barra à direita), passe o valor do argumento da linha de comandos como --pathbase=/CoolApp (sem barra à direita).

• 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 launchSettings.json do aplicativo no perfil do IIS Express. Esta configuração é usada ao executar o aplicativo com o Depurador do Visual Studio e em 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 de aplicativo. A configuração do argumento na página de propriedades do Visual Studio adiciona o argumento ao arquivo launchSettings.json.

  --pathbase=/relative-URL-path
  

Para obter mais informações, consulte Caminho base do aplicativo ASP.NET CoreBlazor.

URLs

O argumento --urls define os endereços IP ou os endereços de host com portas e protocolos para atender 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 arquivo launchSettings.json do aplicativo no perfil do IIS Express. Esta configuração é usada ao executar o aplicativo com o Depurador do Visual Studio e em 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>Depurar>Argumentos de aplicativo. A configuração do argumento na página de propriedades do Visual Studio adiciona o argumento ao arquivo launchSettings.json.

  --urls=http://127.0.0.1:0
  

Configurar o cortador

O Blazor executa o filtro de IL (Linguagem Intermediária) em cada build de Versão para remover a IL desnecessária dos assemblies de saída. Para obter mais informações, consulte Configurar o Trimmer para ASP.NET Core Blazor.

Corrupção antes da implantação

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 lugar para serem usados pela nova implantação.

Em casos raros, os arquivos remanescentes de uma implantação anterior podem corromper uma nova implantação. Excluir completamente a implantação existente (ou aplicativo publicado localmente antes da implantação) pode resolver o problema com uma implantação corrompida. Geralmente, excluir a implantação existente uma vez é suficiente para resolver o problema, inclusive para um pipeline de build e implantação do DevOps.

Se você determinar que a limpeza de uma implantação anterior é sempre necessária quando um pipeline de build e implantação do DevOps está em uso, você pode adicionar temporariamente uma etapa ao pipeline de build para excluir a implantação anterior para cada nova implantação, até que você solucione a causa exata do dano.