Ferramentas de build do ASP.NET Core Blazor WebAssembly e compilação antecipada (AOT)

Este artigo descreve as ferramentas de build para aplicativos Blazor WebAssembly autônomos e como compilar um aplicativo antes da implantação com compilação AOT (antecipada).

Embora o artigo foque principalmente em aplicativos Blazor WebAssembly autônomos, a seção sobre tamanho de heap de alguns navegadores de dispositivos móveis também se aplica ao projeto do lado do cliente (.Client) de um Blazor Web App.

Ferramentas de build do .NET WebAssembly

As ferramentas de build do .NET WebAssembly são baseadas no Emscripten, uma cadeia de ferramentas do compilador para a plataforma Web. Para instalar as ferramentas de build, use uma das seguintes abordagens:

• Para a carga de trabalho ASP.NET e desenvolvimento para a Web no instalador do Visual Studio, selecione a opção ferramentas de build do .NET WebAssembly na lista de componentes opcionais.
• Execute dotnet workload install wasm-tools em um shell de comando administrativo.

Observação

Ferramentas de build do .NET WebAssembly para projetos do .NET 6

A carga de trabalho wasm-tools instala as ferramentas de compilação para a versão mais recente. No entanto, a versão atual das ferramentas de compilação é incompatível com projetos existentes criados com o .NET 6. Os projetos que usam as ferramentas de compilação que devem dar suporte ao .NET 6 e a uma versão posterior devem usar vários direcionamentos.

Use a carga de trabalho wasm-tools-net6 para projetos do .NET 6 ao desenvolver aplicativos com o SDK do .NET 7. Para instalar a carga de trabalho wasm-tools-net6, execute o seguinte comando de um shell de comando administrativo:

dotnet workload install wasm-tools-net6

Compilação AOT (Ahead Of Time)

Blazor WebAssembly dá suporte à compilação AOT (Ahead Of Time), em que você pode compilar seu código do .NET diretamente no WebAssembly. A compilação AOT resulta em melhorias no desempenho de runtime em detrimento de um aplicativo maior.

Sem habilitar a compilação AOT, os aplicativos Blazor WebAssembly são executados no navegador usando um interpretador de IL (Linguagem Intermediária ) do .NET implementado no WebAssembly com suporte parcial de um runtime just-in-time (JIT), chamado informalmente de Jiterpreter. Como o código IL do .NET é interpretado, os aplicativos normalmente são executados mais lentamente do que em um runtime do .NET JIT do lado do servidor sem qualquer interpretação de IL. A compilação AOT resolve esse problema de desempenho compilando o código do .NET de um aplicativo diretamente no WebAssembly para execução nativa do WebAssembly pelo navegador. A melhoria no desempenho AOT pode gerar grandes melhorias para aplicativos que executam tarefas com uso intensivo de CPU. A desvantagem de usar a compilação AOT é que os aplicativos com compilação AOT geralmente são maiores do que seus equivalentes interpretados por IL. Portanto, geralmente levam mais tempo para serem baixados no cliente, quando solicitados pela primeira vez.

Para obter diretrizes sobre como instalar as ferramentas de build do .NET WebAssembly, consulte Ferramentas de criação e compilação antecipada (AOT) do Blazor WebAssembly no ASP.NET Core.

Para habilitar a compilação AOT do WebAssembly, adicione a propriedade <RunAOTCompilation> definida como true ao arquivo de projeto do aplicativo Blazor WebAssembly:

<PropertyGroup>
  <RunAOTCompilation>true</RunAOTCompilation>
</PropertyGroup>

Para compilar o aplicativo no WebAssembly, publique o aplicativo. Publicar a configuração do Release garante que a vinculação de IL (Linguagem Intermediária) do .NET também seja executada para reduzir o tamanho do aplicativo publicado:

dotnet publish -c Release

A compilação AOT do WebAssembly só é executada quando o projeto é publicado. A compilação AOT não é usada quando o projeto é executado durante o desenvolvimento (ambiente Development), pois a compilação AOT geralmente leva vários minutos em projetos pequenos e possivelmente muito mais tempo para projetos maiores. A redução no tempo de compilação AOT está em desenvolvimento para as próximas versões do ASP.NET Core.

Um aplicativo Blazor WebAssembly com compilação AOT geralmente é maior do que um aplicativo compilado na IL do .NET:

• Embora a diferença de tamanho dependa do aplicativo, a maioria dos aplicativos com compilação AOT tem cerca de duas vezes o tamanho das versões com compilação de IL. Isso significa que o uso da compilação AOT compensa o desempenho de tempo de carga para desempenho do runtime. Se essa compensação vale a pena ao usar a compilação AOT depende do seu aplicativo. Os aplicativos do Blazor WebAssembly que têm uso intensivo de CPU geralmente aproveitam melhor a compilação AOT.

• Um aplicativo com compilação AOT é maior devido a duas condições:

  • Mais código é necessário para representar as instruções de IL do .NET de alto nível no WebAssembly nativo.
  • A compilação AOT não corta as DLLs gerenciadas quando o aplicativo é publicado. O Blazor requer DLLs para metadados de reflexão e para dar suporte a determinados recursos de runtime do .NET. Exigir as DLLs no cliente aumenta o tamanho do download, mas proporciona uma experiência do .NET mais compatível.

Observação

Para propriedades e destinos do MSBuild Mono/WebAssembly, confira WasmApp.Common.targets (repositório do GitHub dotnet/runtime). A documentação oficial de propriedades comuns do MSBuild é planejada de acordo com as opções de configuração do documento do MSBuild do blazor (dotnet/docs nº 27395).

Cortar o .NET IL após a compilação antecipada (AOT)

A opção MSBuild WasmStripILAfterAOT permite a remoção da IL (Linguagem Intermediária do .NET) para métodos compilados depois de executar a compilação AOT no WebAssembly, o que reduz o tamanho da pasta _framework.

No arquivo de projeto do aplicativo:

<PropertyGroup>
  <RunAOTCompilation>true</RunAOTCompilation>
  <WasmStripILAfterAOT>true</WasmStripILAfterAOT>
</PropertyGroup>

Essa configuração corta o código IL para a maioria dos métodos compilados, incluindo métodos de bibliotecas e métodos no aplicativo. Nem todos os métodos compilados podem ser cortados, pois alguns ainda são exigidos pelo interpretador do .NET em runtime.

Para relatar um problema com a opção de corte, abra um problema no dotnet/runtimerepositório do GitHub.

Desabilite a propriedade de corte se ela impedir que seu aplicativo seja executado normalmente:

<WasmStripILAfterAOT>false</WasmStripILAfterAOT>

Tamanho de heap para alguns navegadores de dispositivos móveis

Ao criar um Blazor aplicativo que é executado no cliente e direcionado a navegadores de dispositivos móveis, especialmente Safari no iOS, pode ser necessário diminuir a memória máxima do aplicativo com a propriedade MSBuild EmccMaximumHeapSize. Para obter mais informações, confira Hospedar e implantar Blazor WebAssembly do ASP.NET Core.

Nova vinculação de runtime

Uma das maiores partes de um aplicativo do Blazor WebAssembly é o runtime do .NET baseado em WebAssembly (dotnet.wasm) que o navegador deve baixar quando o aplicativo é acessado pela primeira vez no navegador de um usuário. A nova vinculação de runtime do WebAssembly do .NET corta o código de runtime não utilizado e, portanto, melhora a velocidade de download.

A nova vinculação de runtime requer a instalação das ferramentas de build do WebAssembly do .NET. Para obter mais informações, confira Ferramentas para Blazor do ASP.NET Core.

Com as ferramentas de build do WebAssembly do .NET instaladas, a nova vinculação de runtime é executada automaticamente quando um aplicativo é publicado na configuração Release. A redução de tamanho é particularmente considerável ao desabilitar a globalização. Para obter mais informações, confira Globalização e localização Blazor do ASP.NET Core.

Importante

A nova vinculação de runtime corta os métodos do .NET que podem ser invocados pelo JavaScript da instância de classe, a menos que estejam protegidos. Para obter mais informações, confira Chamar métodos do .NET das funções JavaScript no Blazor do ASP.NET Core.

SIMD (Single Instruction, Multiple Data)

Blazor utiliza SIMD (Single Instruction, Multiple Data) do WebAssembly para melhorar a taxa de transferência de cálculos vetorizados ao executar uma operação em várias partes de dados em paralelo usando uma única instrução.

Para desabilitar o SIMD, por exemplo, ao direcionar a navegadores antigos ou navegadores em dispositivos móveis que não dão suporte ao SIMD, defina a propriedade <WasmEnableSIMD> como false no arquivo de projeto do aplicativo (.csproj):

<PropertyGroup>
  <WasmEnableSIMD>false</WasmEnableSIMD>
</PropertyGroup>

Para obter mais informações, veja Configurar e hospedar aplicativos .NET WebAssembly: SIMD – uma instrução, vários dados e observe que as diretrizes não têm controle de versão e se aplicam à versão pública mais recente.

Tratamento de exceções

O tratamento de exceção é habilitado por padrão. Para desabilitar o tratamento de exceção, adicione a propriedade <WasmEnableExceptionHandling> com um valor de false no arquivo de projeto do aplicativo (.csproj):

<PropertyGroup>
  <WasmEnableExceptionHandling>false</WasmEnableExceptionHandling>
</PropertyGroup>

Para saber mais, consulte os recursos a seguir:

• Configuração e hospedagem de aplicativos WebAssembly do .NET: EH – Tratamento de exceções
• Manuseio de exceção

Recursos adicionais

• Dependências nativas Blazor WebAssembly do ASP.NET Core
• Formato de empacotamento Webcil para assemblies .NET