dépendances natives ASP.NET Core Blazor WebAssembly

  • Article

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 8 de cet article.

Important

Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 8 de cet article.

Les applications Blazor WebAssembly peuvent utiliser des dépendances natives créées pour s’exécuter sur WebAssembly. Vous pouvez lier statiquement des dépendances natives au runtime WebAssembly .NET à l’aide des outils de génération WebAssembly .NET, les mêmes outils que ceux utilisés pour compiler une application Blazor à WebAssembly et pour lier à nouveau le runtime pour 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 obtenir plus d’informations sur les outils de génération, notamment l’installation, consultez Outils de génération ASP.NET Core Blazor WebAssembly et compilation AOT (ahead-of-time).

Ajoutez des dépendances natives à une application Blazor WebAssembly en ajoutant NativeFileReference éléments dans le fichier projet de l’application. Lorsque le projet est généré, chaque NativeFileReference est passée à Emscripten par les outils de génération .NET WebAssembly afin qu’ils soient compilés et liés 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)
  • Archiver des fichiers (.a)
  • Bitcode (.bc)
  • Modules WebAssembly autonomes (.wasm)

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

Remarque

Pour plus d’informations sur les propriétés et les cibles MSBuild Mono/WebAssembly, consultez WasmApp.targets (dépôt GitHub dotnet/runtime). La documentation officielle pour les propriétés MSBuild courantes est planifiée selon la page Document blazor msbuild configuration options dotnet/docs#27395 (Documenter les options de configuration msbuild blazor).

Utiliser du code natif

Ajoutez une fonction C native simple à une application Blazor WebAssembly :

  1. Créez un projet Blazor WebAssembly.

  2. Ajoutez un fichier Test.c au projet.

  3. Ajoutez une fonction C pour l’informatique des factorials.

    Test.c:

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

  4. Ajoutez un NativeFileReference pour Test.c dans le fichier projet de l’application :

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

  5. Dans un composant Razor, ajoutez un DllImportAttribute pour la fonction fact dans la bibliothèque de Test générée et appelez la méthode fact à 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 générez l’application avec les outils de génération WebAssembly .NET installés, le code C natif est compilé et lié au runtime WebAssembly .NET (dotnet.wasm). Une fois l’application générée, exécutez l’application pour voir la valeur factorielle rendue.

Rappels de méthode managée C++

Étiquetez les méthodes managées qui sont passées à C++ avec l’attribut [UnmanagedCallersOnly].

La méthode marquée avec l’attribut [UnmanagedCallersOnly] doit être static. Pour appeler une méthode d’instance dans un composant Razor, passez un GCHandle pour l’instance en C++, puis passez-la en mode natif. Vous pouvez également utiliser une autre méthode pour identifier le instance du composant.

La méthode marquée avec [DllImport] doit utiliser un pointeur de fonction C# 9.0 plutôt qu’un type délégué pour l’argument de rappel.

Remarque

Pour les types de pointeur de fonction C# dans les méthodes [DllImport], utilisez IntPtr dans la signature de méthode côté managé au lieu de delegate *unmanaged<int, void>. Pour plus d’informations, consultez Rappel [WASM] du code natif vers .NET : l’analyse des types de pointeurs de fonction dans les signatures n’est pas prise en charge (dotnet/runtime #56145).

Packager 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 ensuite disponibles pour n’importe quelle application Blazor WebAssembly. Les fichiers des dépendances natives doivent être générés pour WebAssembly et empaqueté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 package peuvent choisir d’ajouter les références natives en incluant un fichier .props dans le package avec les références.

Utilisation de l’exemple de bibliothèque SkiaSharp

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

Pour utiliser SkiaSharp dans une application Blazor WebAssembly :

  1. 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 commande dotnet add package dans un interpréteur de commandes :

    dotnet add package –-prerelease SkiaSharp.Views.Blazor

    Remarque

    Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions du package sur NuGet.org.

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

    • espaces de nomsSkiaSharp et SkiaSharp.Views.Blazor.
    • Logique à dessiner dans le composant Vue de canevas 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. Générez l’application, ce qui peut prendre plusieurs minutes. Exécutez l’application et accédez au composant NativeDependencyExample à /native-dependency-example.

Ressources supplémentaires

.NET WebAssembly Build Tools