Dependências nativas do ASP.NET Core Blazor WebAssembly

Os aplicativos Blazor WebAssembly podem usar dependências nativas criadas para serem executadas no WebAssembly. Você pode vincular estaticamente dependências nativas ao runtime do .NET WebAssembly usando as Ferramentas de build do .NET WebAssembly, as mesmas ferramentas usadas para compilação AOT (ahead-of-time) um Blazor aplicativo para o WebAssembly e para revincular o runtime para remover recursos não utilizados.

Este artigo só se aplica a Blazor WebAssembly.

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 obter mais informações sobre as ferramentas de compilação, incluindo a instalação, confira Ferramentas de criação e compilação antecipada (AOT) do Blazor WebAssembly no ASP.NET Core.

Adicione dependências nativas a um aplicativo Blazor WebAssembly adicionando itens NativeFileReference no arquivo de projeto do aplicativo. Quando o projeto é criado, cada NativeFileReference é passado para o Emscripten pelas ferramentas de build do .NET WebAssembly para que eles sejam compilados e vinculados ao runtime. Em seguida, p/invoke no código nativo do código .NET do aplicativo.

Em geral, qualquer código nativo portátil pode ser usado como uma dependência nativa com Blazor WebAssembly. Você pode adicionar dependências nativas ao código C/C++ ou código compilado anteriormente usando o Emscripten:

• Arquivos-objetos (.o)
• Arquivamento (.a)
• Bitcode (.bc)
• Módulos WebAssembly autônomos (.wasm)

As dependências predefinidas normalmente devem ser criadas usando a mesma versão do Emscripten usada para criar o runtime do .NET WebAssembly.

Usar código nativo

Adicione uma função C nativa simples a um aplicativo Blazor WebAssembly:

1. Crie um novo projeto Blazor WebAssembly.

2. Adicione o arquivo Test.c ao projeto.

3. Adicione uma função C para fatoriais de computação.

   Test.c:

   int fact(int n)
   {
       if (n == 0) return 1;
       return n * fact(n - 1);
   }
   

4. Adicione um NativeFileReference para Test.c no arquivo de projeto do aplicativo:

   <ItemGroup>
     <NativeFileReference Include="Test.c" />
   </ItemGroup>
   

5. Em um componente Razor, adicione um DllImportAttribute para a função fact na biblioteca Test gerada e chame o método fact do código .NET no componente.

   Pages/NativeCTest.razor:

   @page "/native-c-test"
   @using System.Runtime.InteropServices
   
   <PageTitle>Native C</PageTitle>
   
   <h1>Native C Test</h1>
   
   <p>
       @@fact(3) result: @fact(3)
   </p>
   
   @code {
       [DllImport("Test")]
       static extern int fact(int n);
   }
   

Quando você cria o aplicativo com as ferramentas de build do .NET WebAssembly instaladas, o código C nativo é compilado e vinculado ao runtime do .NET WebAssembly (dotnet.wasm). Depois que o aplicativo for criado, execute-o para ver o valor fatorial renderizado.

Retornos de chamada de método gerenciado do C++

Rotular métodos gerenciados que são passados para C++ com o atributo [UnmanagedCallersOnly].

O método marcado com o atributo [UnmanagedCallersOnly] deve ser static. Para chamar um método de instância em um componente Razor, passe um GCHandle para a instância para C++ e, em seguida, passe-o de volta para nativo. Como alternativa, use outro método para identificar a instância do componente.

O método marcado com [DllImport] deve usar um ponteiro de função C# 9.0 em vez de um tipo delegado para o argumento de retorno de chamada.

Dependências nativas em um pacote NuGet

Os pacotes NuGet podem conter dependências nativas para uso no WebAssembly. Essas bibliotecas e suas funcionalidades nativas estão disponíveis para qualquer aplicativo Blazor WebAssembly. Os arquivos das dependências nativas devem ser compilados para WebAssembly e empacotados na browser-wasm pasta específica da arquitetura. As dependências específicas do WebAssembly não são referenciadas automaticamente e devem ser referenciadas manualmente como NativeFileReferences. Os autores de pacote podem optar por adicionar as referências nativas incluindo um arquivo .props no pacote com as referências.

Uso da biblioteca de exemplos do SkiaSharp

SkiaSharp é uma biblioteca de elementos gráficos 2D multiplataforma para .NET com base na biblioteca de elementos gráficos do Skia nativa com suporte para Blazor WebAssembly.

Para usar o SkiaSharp em um aplicativo Blazor WebAssembly:

1. Adicione uma referência de pacote ao pacote SkiaSharp.Views.Blazor em um projeto Blazor WebAssembly. Use o processo do Visual Studio para adicionar pacotes a um aplicativo (Gerenciar Pacotes NuGet com Incluir pré-lançamento selecionado) ou execute o comando dotnet add package em um shell de comando:

   dotnet add package –-prerelease SkiaSharp.Views.Blazor
   

   Observação

   Para obter diretrizes sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes no Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas de pacote em NuGet.org.

2. Adicione um componente SKCanvasView ao aplicativo com o seguinte:

   • Namespaces SkiaSharp e SkiaSharp.Views.Blazor.
   • Lógica para desenhar no componente Exibição de Tela do SkiaSharp (SKCanvasView).

   Pages/NativeDependencyExample.razor:

   @page "/native-dependency-example"
   @using SkiaSharp
   @using SkiaSharp.Views.Blazor
   
   <PageTitle>Native dependency</PageTitle>
   
   <h1>Native dependency example with SkiaSharp</h1>
   
   <SKCanvasView OnPaintSurface="OnPaintSurface" />
   
   @code {
       private void OnPaintSurface(SKPaintSurfaceEventArgs e)
       {
           var canvas = e.Surface.Canvas;
   
           canvas.Clear(SKColors.White);
   
           using var paint = new SKPaint
           {
               Color = SKColors.Black,
               IsAntialias = true,
               TextSize = 24
           };
   
           canvas.DrawText("SkiaSharp", 0, 24, paint);
       }
   }
   

3. Crie o aplicativo, o que pode levar vários minutos. Execute o aplicativo e navegue para a componente NativeDependencyExample em /native-dependency-example.

Recursos adicionais

Ferramentas de build do .NET WebAssembly