dépendances natives ASP.NET Core Blazor WebAssembly

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.

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.

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 créés pour WebAssembly et regroupés dans le browser-wasm dossier 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