ASP.NET Core Blazor WebAssembly dependências nativas

Blazor WebAssembly aplicativos podem usar dependências nativas criadas para serem executadas no WebAssembly. Pode ligar estaticamente dependências nativas no runtime do .NET WebAssembly usando as ferramentas de compilação .NET WebAssembly, as mesmas ferramentas usadas para compilação antecipada (AOT) de uma aplicação Blazor para WebAssembly e para religar o runtime para remover recursos não utilizados.

Este artigo aplica-se apenas a Blazor WebAssembly.

Ferramentas de compilação .NET WebAssembly

As ferramentas de compilação .NET WebAssembly baseiam-se no Emscripten, uma cadeia de ferramentas de compiladores para plataforma web. Para mais informações sobre as ferramentas de compilação, incluindo instalação, veja ASP.NET Core Blazor WebAssembly ferramentas de compilação e compilação antecipada (AOT).

Adicione dependências nativas a um aplicativo Blazor WebAssembly adicionando itens de NativeFileReference no arquivo de projeto do aplicativo. Quando o projeto é construído, cada NativeFileReference é passado para o Emscripten pelas ferramentas de compilação .NET WebAssembly para que seja compilado e ligado ao tempo de execução. De seguida, p/invoke para o código nativo do código .NET da aplicação.

Geralmente, 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 Emscripten:

• Arquivos de objeto (.o)
• Ficheiros de arquivo (.a)
• Bitcode (.bc)
• Módulos WebAssembly autónomos (.wasm)

Dependências pré-construídas normalmente têm de ser construídas usando a mesma versão do Emscripten usada para construir o runtime WebAssembly .NET.

Usar código nativo

Esta seção demonstra como adicionar uma função C nativa simples a um Blazor WebAssembly aplicativo.

Crie um novo projeto Blazor WebAssembly.

Adicione um Test.c arquivo ao projeto com uma função C para calcular fatoriais.

Test.c:

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

Adicione um NativeFileReference item do MSBuild para Test.c no arquivo de projeto do aplicativo (.csproj):

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

Em um componente Razor, adicione um atributo [DllImport] para a função fact na biblioteca gerada Test 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 constróis a aplicação com as ferramentas de compilação .NET WebAssembly instaladas, o código C nativo é compilado e ligado ao runtime .NET WebAssembly (dotnet.wasm). Depois que o aplicativo for criado, execute o aplicativo para ver o valor fatorial renderizado.

Retornos de chamada do método gerenciado C++

Rotule métodos gerenciados que são passados para C++ com o [UnmanagedCallersOnly] atributo. O método marcado com o atributo deve ser static. Para chamar um método de instância em um componente Razor, passe um GCHandle da instância para C++ e depois devolva-o para o código nativo. Como alternativa, use algum outro método para identificar a instância do componente.

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

Empacotar 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 ficam disponíveis para qualquer aplicativo Blazor WebAssembly. Os arquivos para as dependências nativas devem ser criados para WebAssembly e empacotados na pasta específica da arquitetura browser-wasm. As dependências específicas do WebAssembly não são referenciadas automaticamente e devem ser referenciadas manualmente como NativeFileReferences. Os autores do pacote podem optar por adicionar as referências nativas incluindo um arquivo de .props no pacote com as referências.

Uso da biblioteca de exemplo SkiaSharp

SkiaSharp é uma biblioteca gráfica 2D multiplataforma para .NET baseada na biblioteca gráfica nativa Skia com suporte para Blazor WebAssembly.

A seção demonstra como implementar o SkiaSharp em um Blazor WebAssembly aplicativo.

Adicione uma referência para o pacote SkiaSharp.Views.Blazor num projeto Blazor WebAssembly. Use o processo do Visual Studio para adicionar pacotes a uma aplicação (Gerenciar Pacotes NuGet com Incluir prerelease selecionado) ou execute o comando dotnet add package numa shell de comandos com a opção --prerelease:

dotnet add package –-prerelease SkiaSharp.Views.Blazor

Adicione um componente SKCanvasView ao aplicativo com o seguinte:

• SkiaSharp e SkiaSharp.Views.Blazor namespaces.
• Lógica para desenhar na vista de tela do componente 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);
    }
}

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

Recursos adicionais

• .NET Ferramentas de compilação WebAssembly
• Propriedades e destinos do MSBuild de Mono/WebAssembly (WasmApp.targets, repositório do GitHub dotnet/runtime)