dipendenze native di ASP.NET Core Blazor WebAssembly

  • Articolo

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Blazor WebAssembly le app possono usare le dipendenze native create per l'esecuzione in WebAssembly. È possibile collegare in modo statico le dipendenze native al runtime .NET WebAssembly usando gli strumenti di compilazione .NET WebAssembly, gli stessi strumenti usati per compilare un'app Blazor in webAssembly (AOT) e ricollegare il runtime per rimuovere le funzionalità inutilizzate.

Questo articolo si applica solo a Blazor WebAssembly.

Strumenti di compilazione WebAssembly .NET

Gli strumenti di compilazione .NET WebAssembly sono basati su Emscripten, una toolchain del compilatore per la piattaforma Web. Per altre informazioni sugli strumenti di compilazione, inclusa l'installazione, vedere ASP.NET Core Blazor WebAssembly build tools and ahead-of-time (AOT).

Aggiungere dipendenze native a un'app Blazor WebAssembly aggiungendo NativeFileReference elementi nel file di progetto dell'app. Quando il progetto viene compilato, ognuno NativeFileReference viene passato a Emscripten dagli strumenti di compilazione WebAssembly .NET in modo che vengano compilati e collegati al runtime. Quindi, p/invoke nel codice nativo dal codice .NET dell'app.

In genere, qualsiasi codice nativo portabile può essere usato come dipendenza nativa con Blazor WebAssembly. È possibile aggiungere dipendenze native al codice C/C++ o al codice compilato in precedenza usando Emscripten:

  • File oggetto (.o)
  • File di archiviazione (.a)
  • Bitcode (.bc)
  • Moduli WebAssembly autonomi (.wasm)

Le dipendenze predefinite devono in genere essere compilate usando la stessa versione di Emscripten usata per compilare il runtime WebAssembly .NET.

Nota

Per le proprietà e le destinazioni di MSBuild mono/WebAssembly, vedere WasmApp.targets (dotnet/runtime repository GitHub). La documentazione ufficiale per le proprietà comuni di MSBuild è pianificata per le opzioni di configurazione msbuild di Blazor document (dotnet/docs #27395)..

Usare il codice nativo

Aggiungere una semplice funzione C nativa a un'app Blazor WebAssembly :

  1. Creare un nuovo progetto Blazor WebAssembly .

  2. Aggiungere un Test.c file al progetto.

  3. Aggiungere una funzione C per i fattoriali di calcolo.

    Test.c:

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

  4. Aggiungere un oggetto NativeFileReference per Test.c nel file di progetto dell'app:

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

  5. In un Razor componente aggiungere un DllImportAttribute per la fact funzione nella libreria generata Test e chiamare il fact metodo dal codice .NET nel 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 si compila l'app con gli strumenti di compilazione .NET WebAssembly installati, il codice C nativo viene compilato e collegato al runtime .NET WebAssembly (dotnet.wasm). Dopo aver compilato l'app, eseguire l'app per visualizzare il valore fattoriale di cui è stato eseguito il rendering.

Callback del metodo gestito C++

Etichettare i metodi gestiti passati a C++ con l'attributo [UnmanagedCallersOnly] .

Il metodo contrassegnato con l'attributo [UnmanagedCallersOnly] deve essere static. Per chiamare un metodo di istanza in un Razor componente, passare un GCHandle oggetto per l'istanza a C++ e quindi passarlo di nuovo a nativo. In alternativa, usare un altro metodo per identificare l'istanza del componente.

Il metodo contrassegnato con [DllImport] deve usare un puntatore a funzione C# 9.0 anziché un tipo delegato per l'argomento di callback.

Nota

Per i tipi di puntatore a funzione C# nei [DllImport] metodi, usare IntPtr nella firma del metodo sul lato gestito anziché delegate *unmanaged<int, void>. Per altre informazioni, vedere callback [WASM] dal codice nativo a .NET: l'analisi dei tipi di puntatore di funzione nelle firme non è supportata (dotnet/runtime #56145).

Creare un pacchetto di dipendenze native in un pacchetto NuGet

I pacchetti NuGet possono contenere dipendenze native da usare in WebAssembly. Queste librerie e le relative funzionalità native sono quindi disponibili per qualsiasi Blazor WebAssembly app. I file per le dipendenze native devono essere compilati per WebAssembly e inseriti in un pacchetto nella cartella specifica dell'architetturabrowser-wasm. Le dipendenze specifiche di WebAssembly non vengono a cui viene fatto riferimento automaticamente e devono essere referenziate manualmente come NativeFileReferences. Gli autori di pacchetti possono scegliere di aggiungere i riferimenti nativi includendo un .props file nel pacchetto con i riferimenti.

Uso della libreria di esempio SkiaSharp

SkiaSharp è una libreria grafica 2D multipiattaforma per .NET basata sulla libreria grafica Skia nativa con supporto per Blazor WebAssembly.

Per usare SkiaSharp in un'app Blazor WebAssembly :

  1. Aggiungere un riferimento al SkiaSharp.Views.Blazor pacchetto in un Blazor WebAssembly progetto. Usare il processo di Visual Studio per aggiungere pacchetti a un'app (Gestire pacchetti NuGet con Includi versione preliminare selezionata) oppure eseguire il dotnet add package comando in una shell dei comandi:

    dotnet add package –-prerelease SkiaSharp.Views.Blazor

    Nota

    Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli sotto Installare e gestire pacchetti in Flusso di lavoro dell'utilizzo di pacchetti (documentazione di NuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

  2. Aggiungere un SKCanvasView componente all'app con quanto segue:

    • SkiaSharp spazi dei nomi e SkiaSharp.Views.Blazor .
    • Logica da disegnare nel componente SkiaSharp Canvas View (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. Compilare l'app, che potrebbe richiedere alcuni minuti. Eseguire l'app e passare al NativeDependencyExample componente in /native-dependency-example.

Risorse aggiuntive

Strumenti di compilazione WebAssembly .NET