Dépendances natives ASP.NET Core Blazor WebAssembly

Blazor WebAssemblyLes applications peuvent utiliser des dépendances natives conçues pour s’exécuter sur WebAssembly. Vous pouvez lier statiquement des dépendances natives au runtime .NET WebAssembly à l’aide des outils de compilation .NET WebAssembly, les mêmes outils utilisés pour compiler à l’avance (AOT) une application Blazor vers WebAssembly et pour relier le runtime afin de supprimer les fonctionnalités inutilisées.

Cet article s’applique uniquement à Blazor WebAssembly.

.NET WebAssembly Build Tools

Les outils de génération .NET WebAssembly sont basés sur Emscripten, une chaîne d’outils de compilateur pour la plateforme web. Pour plus d’informations sur les outils de compilation, y compris leur installation, consultez Outils de compilation ASP.NET Core Blazor WebAssembly et compilation anticipée (AOT).

Ajoutez des dépendances natives à une application Blazor WebAssembly en ajoutant des éléments NativeFileReference dans le fichier de projet de l’application. Lorsque le projet est compilé, chaque NativeFileReference est transmis à Emscripten par les outils de compilation WebAssembly .NET afin d’être compilé et lié au runtime. Ensuite, p/invoke dans le code natif à partir du code .NET de l’application.

En règle générale, tout code natif portable peut être utilisé comme dépendance native avec Blazor WebAssembly. Vous pouvez ajouter des dépendances natives au code C/C++ ou au code précédemment compilé à l’aide d’Emscripten :

• Fichiers objet (.o)
• Fichiers d’archive (.a)
• Bitcode (.bc)
• Modules WebAssembly autonomes (.wasm)

Les dépendances précompilées doivent généralement être compilées à l’aide de la même version d’Emscripten que celle utilisée pour compiler le runtime WebAssembly .NET.

Utiliser du code natif

Cette section montre comment ajouter une fonction C native simple à une Blazor WebAssembly application.

Créez un projet Blazor WebAssembly.

Ajoutez un Test.c fichier au projet avec une fonction C pour l’informatique des factorials.

Test.c :

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

Ajoutez un élément NativeFileReference MSBuild pour Test.c dans le fichier de projet de l’application (.csproj) :

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

Dans un Razor composant, ajoutez un [DllImport] attribut pour la fact fonction dans la bibliothèque générée Test et appelez la fact méthode à partir du code .NET dans le composant.

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

Lorsque vous compilez l’application avec les outils de compilation .NET WebAssembly installés, le code C natif est compilé et lié au runtime .NET WebAssembly (dotnet.wasm). Une fois l’application compilée, exécutez-la pour voir la valeur factorielle rendue.

Rappels de méthode gérée C

Marquer les méthodes gérées transmises à C++ avec l'attribut [UnmanagedCallersOnly]. La méthode marquée avec l’attribut doit être static. Pour appeler une méthode d’instance dans un composant Razor, transmettez un GCHandle pour l’instance à C++, puis renvoyez-le vers le code natif. Vous pouvez également utiliser une autre méthode pour identifier l’instance du composant.

La méthode marquée avec l’attribut[DllImport] doit utiliser un pointeur de fonction (C# 9 ou version ultérieure) plutôt qu’un type délégué pour l’argument de rappel.

Package des dépendances natives dans un package NuGet

Les packages NuGet peuvent contenir des dépendances natives à utiliser sur WebAssembly. Ces bibliothèques et leurs fonctionnalités natives sont alors disponibles pour toute application Blazor WebAssembly. Les fichiers des dépendances natives doivent être compilés pour WebAssembly et packagés dans le browser-wasmdossier spécifique à l’architecture. Les dépendances spécifiques à WebAssembly ne sont pas référencées automatiquement et doivent être référencées manuellement en tant que NativeFileReferences. Les auteurs de packages peuvent choisir d’ajouter les références natives en incluant un fichier .props dans le package avec les références.

Exemple d’utilisation de la bibliothèque SkiaSharp

SkiaSharp est une bibliothèque graphique 2D multiplateforme pour .NET basée sur la bibliothèque graphique native Skia avec prise en charge de Blazor WebAssembly.

La section montre comment implémenter SkiaSharp dans une Blazor WebAssembly application.

Ajoutez une référence de package au package SkiaSharp.Views.Blazor dans un projet Blazor WebAssembly. Utilisez le processus de Visual Studio pour ajouter des packages à une application (Gérer les packages NuGet avec inclure la préversion sélectionnée) ou exécutez la dotnet add package commande dans un interpréteur de commandes avec l’option --prerelease :

dotnet add package –-prerelease SkiaSharp.Views.Blazor

Ajoutez un composant SKCanvasView à l’application avec les éléments suivants :

• SkiaSharp et les espaces de noms SkiaSharp.Views.Blazor.
• Logique pour dessiner dans le composant 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);
    }
}

Compilez l’application, ce qui peut prendre plusieurs minutes. Exécutez l’application et accédez au composant NativeDependencyExample dans /native-dependency-example.

Ressources supplémentaires

• Outils de compilation WebAssembly .NET
• Propriétés et cibles Mono/WebAssembly MSBuild (WasmApp.targets, référentiel GitHub dotnet/runtime)