Compartilhar via

Dependências nativas do ASP.NET Core Blazor WebAssembly

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 9 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, consulte a Política de Suporte do .NET e do .NET Core. Para a versão atual, consulte a versão .NET 9 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para a versão atual, consulte a versão .NET 9 deste artigo.

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.

Observação

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

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 fatores de computação.

Test.c:

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

Adicione um NativeFileReference item do MS Build 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 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++

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 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 o [DllImport] atributo deve usar um ponteiro de função (C# 9 ou posterior) em vez de um tipo delegado para o argumento de callback.

Observação

Para tipos de ponteiro de função C# em métodos [DllImport], use IntPtr na assinatura do método no lado gerenciado em vez de delegate *unmanaged<int, void>. Para obter mais informações, consulte [WASM] retorno de chamada de código nativo para .NET: não há suporte para analisar tipos de ponteiro de função em assinaturas (dotnet/runtime nº 56145).

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

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

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 com a opção --prerelease.

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.

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);
    }
}

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