Plug-ins d’assembly dépendant (version préliminaire)

[Cette rubrique fait partie de la documentation en version préliminaire et peut faire l'objet de modifications.]

Il est souvent utile d’inclure un autre assembly ou un fichier de ressources dans un plug-in. Par exemple, vous pouvez utiliser Newtonsoft.Json.dll ou un autre assembly. Vous souhaiterez peut-être accéder à une liste de chaînes localisées.

Sans assemblys dépendants, tous les plug-ins sont enregistrés en tant qu’assemblys .NET Framework individuels. La seule façon d’inclure un autre assembly est de le combiner en un seul en utilisant ILMerge. Bien qu’ILMerge ait fonctionné pour de nombreux scénarios, il n’a jamais été pris en charge par Dataverse et n’a pas toujours fonctionné. ILMerge n’est plus maintenu.

Avec les assemblys dépendants, plutôt que d’enregistrer un assembly .NET individuel, vous chargez un package NuGet contenant votre assembly de plug-in ET tous les assemblys dépendants. Ce fichier de package NuGet est stocké dans une nouvelle table appelée PluginPackage. Le contenu du package NuGet est stocké dans le stockage de fichiers plutôt que dans SQL.

Lorsque vous chargez votre package NuGet, tous les assemblys contenant des classes qui implémentent l’interface IPlugin sont enregistrés dans la table PluginAssembly et associés à PluginPackage. À mesure que vous développez et gérez votre projet, vous continuez à mettre à jour PluginPackage et les modifications des assemblys de plug-in associés sont gérées sur le serveur.

Lors de l’exécution, Dataverse copie le contenu du package NuGet depuis la ligne PluginPackage et l’extrait dans l‘exécution du bac à sable. De cette façon, tous les assemblys dépendants nécessaires pour le plug-in sont disponibles.

Vous pouvez toujours enregistrer les assemblys de plug-in individuellement, mais l’utilisation de PluginPackage devient l’approche recommandée. Même si votre projet de plug-in actuel ne nécessite pas l’accès à un assembly dépendant, si vous démarrez avec un projet configuré pour prendre en charge les assemblys dépendants, vous pouvez ajouter un assembly dépendant ultérieurement, si nécessaire. Aucun travail n’est prévu pour convertir les projets d’assembly de plug-in existants pour utiliser PluginPackage.

Envoyer des commentaires

Si vous avez des questions ou des problèmes avec cette fonctionnalité, vous pouvez contacter le support technique. Si vous avez des suggestions, publiez-les sur le site Forum d’idées de Power Apps.

Limitations

Les limitations suivantes s’appliquent aux plug-ins d’assembly dépendants.

• Les Extensions de flux de travail, également appelées assemblys de flux de travail, activités de flux de travail ou activités de flux de travail personnalisées ne sont pas prises en charge.
• Les plug-ins pour les fournisseurs de données de table virtuelle ne sont pas pris en charge. L’importation d’une solution dans un environnement échoue si la solution contient des plug-ins (avec des assemblys dépendants) enregistrés dans des entités virtuelles.
• Les environnements locaux ne sont pas pris en charge.
• Le code non géré n’est pas pris en charge. Vous ne pouvez pas inclure de références à des ressources non gérées.

Signature d’assemblys

Il n’est pas nécessaire de signer les assemblys de plug-in utilisés dans les packages de plug-in.

Lorsque vous enregistrez des assemblys de plug-in individuels sans la fonctionnalité d’assemblys dépendants, la signature est requise car elle fournit un nom unique pour l’assembly. Mais avec les assemblys de plug-in dans le package de plug-in, les assemblys sont chargés sur le serveur de bac à sable à l’aide d’un mécanisme différent, la signature n’est donc pas nécessaire.

Options d’outils

Vous pouvez utiliser cette fonction avec deux options d’outils :

Utiliser PAC CLI et PRT

Utilisez PAC CLI pour créer un projet Visual Studio et PRT pour gérer vos packages et enregistrer les étapes.

Conditions préalables

Pour utiliser cette fonctionnalité avec PAC CLI et PRT, vous devez utiliser ces outils et applications.

Créer un projet Visual Studio

Utilisez la commande PAC CLI pac plugin init pour créer un projet Visual Studio qui rationalise votre processus de développement avec des assemblys dépendants.

1. Créez un dossier pour votre projet de plug-in. Le nom de ce dossier détermine le nom du projet de bibliothèque de classes Visual Studio .NET Framework pour votre plug-in.

2. Ouvrez une fenêtre de terminal PowerShell dans Visual Studio Code pour accéder au dossier et exécuter la commande pac plugin init. Pour les packages de plug-in, nous vous recommandons d’utiliser le paramètre --skip-signing afin que vos assemblys de plug-in ne soient pas signés.

   Exemple :

   PS E:\projects\mypluginproject> pac plugin init --skip-signing
   

Ces commandes créent un projet de bibliothèque de classes Visual Studio .NET Framework basé sur le nom du dossier dans lequel il a été créé.

Selon la configuration de votre solution Visual Studio, lorsque vous ouvrez le projet Visual Studio dans Visual Studio et le créez, un package NuGet est généré pour le projet dans le dossier bin\Debug ou bin\Release. Chaque fois que vous créez votre projet, ce package NuGet est mis à jour. Le package NuGet est le fichier que vous chargez à l’aide de Plug-in Registration Tool.

Ajouter un assembly dépendant à l’aide de NuGet

Vous pouvez ajouter un package NuGet à votre projet Visual Studio comme vous le faites normalement. Après avoir créé le projet, vous devriez trouver l’assembly dans le package NuGet.

Vous pouvez utiliser Explorateur de packages NuGet pour examiner le package NuGet.

Ajouter un assembly dépendant sans utiliser NuGet

Si un assembly n’est pas distribué en tant que package NuGet, vous pouvez l’ajouter à votre projet comme vous le faites normalement. Dans Explorateur de solution, clic-droit Dépendances et choisissez Ajouter une référence d’assembly.... Sélectionnez l’assembly à ajouter.

Utiliser Plug-in Registration Tool

Vous pouvez utiliser Plug-in Registration Tool (PRT) pour effectuer les tâches suivantes :

1. Afficher la liste des packages de plug-in disponibles.
2. Enregistrer un package NuGet en tant que package de plug-in.
3. Mettre à jour un package de plug-in.
4. Supprimer les packages de plug-in.

Afficher la liste des packages de plug-in disponibles

PRT a une nouvelle vue Afficher par package pour répertorier tous les packages de plug-in précédemment importés :

Enregistrer un package NuGet en tant que package de plug-in

PRT a une nouvelle commande pour sélectionner un package NuGet à importer/enregistrer en tant que package de plug-in.

Cette commande ouvre une boîte de dialogue pour sélectionner le package de plug-in.

Vous pouvez sélectionner une solution existante ou en créer une nouvelle.

Depuis la vue Afficher par package, vous pouvez sélectionner les étapes d’assembly et d’inscription.

L’assembly est également disponible dans la vue Afficher par assembly.

Mettre à jour un package de plug-in

Lors de l’affichage de la liste des packages de plug-in à l’aide de la vue Afficher par package, sélectionnez le package de plug-in et sélectionnez la commande Mettre à jour.

Cette commande ouvre une boîte de dialogue vous permettant de sélectionner le package NuGet avec les modifications.

Supprimer les packages de plug-in

Lors de l’affichage de la liste des packages de plug-in à l’aide de la vue Afficher par package, sélectionnez le package de plug-in et sélectionnez la commande Annuler l’enregistrement.

Utiliser Power Platform Tools pour Visual Studio

Utilisez Power Platform Tools pour que Visual Studio crée un projet Visual Studio, gère vos packages et enregistre les étapes.

Conditions préalables

Pour utiliser cette fonction avec Power Platform Tools pour Visual Studio, vous devez avoir Visual Studio 2019 et installer Power Platform Tools pour Visual Studio.

Consultez les articles suivants liés à l’installation et à l’utilisation de Power Platform Tools pour Visual Studio pour travailler avec des plug-ins.

• Installer Power Platform Tools
• Démarrage rapide : Créer un projet Power Platform Tools
• Démarrage rapide : créer un plug-in à l’aide de Power Platform Tools

Vous utilisez généralement le même processus pour créer et gérer des plug-ins à l’aide de Power Platform Tools pour Visual Studio ; toutefois, la signature des assemblys n’est plus nécessaire. Plus d’informations : Signature d’assemblys.

Activer les packages de plug-in pour Power Platform Tools

Power Platform Tools pour Visual Studio fournit plusieurs options de configuration comme décrit dans Power Platform Tools.

1. Dans Visual Studio, accédez à Outils > Options et cherchez Power Platform Tools.

2. Sélectionnez Utiliser un package NuGet pour déployer des plug-ins dans Dataverse.

   

Ajouter un assembly dépendant à l’aide de NuGet avec Power Platform Tools

Vous pouvez ajouter un package NuGet à votre projet Visual Studio comme vous le faites normalement. Après avoir créé le projet, vous devriez trouver l’assembly dans le package NuGet. Le package NuGet se trouve dans le dossier bin\outputPackages.

Vous pouvez utiliser Explorateur de packages NuGet pour examiner le package NuGet.

Ajouter un assembly dépendant sans utiliser NuGet avec Power Platform Tools

Si un assembly n’est pas distribué en tant que package NuGet, vous pouvez l’ajouter à votre projet comme vous le faites normalement. Dans Explorateur de solution, clic-droit Dépendances et choisissez Ajouter une référence d’assembly.... Sélectionnez l’assembly à ajouter.

Déployer les packages de plug-in pour Power Platform Tools

Pour déployer votre package de plug-in, dans Explorateur de solutions, cliquez avec le bouton droit sur le projet de plug-in et sélectionnez Déployer depuis le menu contextuel.

Pour tout premier déploiement, vous devez voir un message dans la fenêtre de sortie qui vous informe de la création du package de plug-in :

6/22/2022 3:03:17 PM : registration of Plugin Package sample_PowerPlatformVSSolution.ExamplePlugins, 
at E:\projects\PowerPlatformVSSolution\ExamplePlugins\bin\outputPackages\PowerPlatformVSSolution.ExamplePlugins.1.0.0.nupkg was successful. 
ID allotted was 06a20e15-77f2-ec11-bb3c-000d3a892245.

Pour chaque déploiement ultérieur, vous verrez un message dans la fenêtre de sortie qui vous informe que le package de plug-in a été mis à jour.

6/22/2022 3:20:14 PM : update of Plugin Package sample_PowerPlatformVSSolution.ExamplePlugins, at
E:\projects\PowerPlatformVSSolution\ExamplePlugins\bin\outputPackages\PowerPlatformVSSolution.ExamplePlugins.1.0.0.nupkg was successful.

Afficher les packages de plug-in avec Power Platform Tools

Au sein de Power Platform Explorer, vous pouvez afficher les packages de plug-in disponibles.

Supprimer un package de plug-in avec Power Platform Tools

Au sein de Power Platform Explorer, sélectionnez un package de plug-in et sélectionnez Supprimer depuis le menu contextuel.

Créer un package de plug-in avec Power Platform Tools

1. Au sein de Power Platform Explorer, sélectionnez Packages de plug-in et sélectionnez Créer depuis le menu contextuel.

   

2. Cette commande ouvre la boîte de dialogue Importer un nouveau package de plug-in.

   

   Sélectionnez le package NuGet et choisissez la solution à laquelle il doit être ajouté, ou créez une solution.

Mettre à jour un package de plug-in avec Power Platform Tools

Au sein de Power Platform Explorer, sélectionnez un package de plug-in, puis sélectionnez Mettre à jour depuis le menu contextuel.

Cette commande ouvre une boîte de dialogue vous permettant de sélectionner un package NuGet pour mettre à jour le package de plug-in.

Notes de conception

Voici quelques éléments à prendre en compte lors de la création de packages de plug-ins.

Génération du package NuGet

Le projet Visual Studio créé à l’aide de pac plugin init utilise les fonctionnalités de Visual Studio qui permettent de générer des packages NuGet. Cette méthode utilise le format de projet style Kit de développement logiciel forme de projet. Power Platform Tools pour Visual Studio utilise le format de projet style hors Kit de développement logiciel.

Il n’est pas nécessaire d’utiliser ces outils pour générer un package NuGet avec vos plug-ins. Vous pouvez utiliser les fonctionnalités de votre choix pour générer un package NuGet, mais vous devez utiliser les outils disponibles pour charger le package dans Dataverse.

Pour plus d′informations :

• Créer un package NuGet utilisant MSBuild
• Compresser et restaurer NuGet en tant que cibles MSBuild

Ce qu’il ne faut pas inclure dans votre forfait

Vous pouvez rencontrer un problème lors de la création et de l’enregistrement de packages de plug-ins Dataverse les assemblages sont inclus dans votre package, ce qui entraîne une erreur au moment de l’enregistrement du package.

L’inclusion de l’un de ces assemblys dans le package de plug-in entraîne le message d’erreur suivant lors de l’enregistrement du package de plug-in auprès de Dataverse :

"PluginPackage ne peut pas contenir d’assemblys inclus dans les packages nuget Microsoft.CrmSdk.CoreAssemblies ou Microsoft.CrmSdk.Workflow. »

Vous pouvez corriger cette situation en suivant les informations contenues dans cet article, Contrôler les actifs de dépendance, afin que ces actifs de dépendance ne soient pas inclus dans votre package. Vous devrez marquer la référence de l’assemblage à l’aide du <PrivateAssets> balise dans le fichier de configuration du projet (.csprog).

Utilisation de System.Text.Json

Si vous utilisez System.Text.Json, veillez tout particulièrement à ajouter explicitement une référence au package NuGet System.Text.Json.

Avec les assemblys dépendants, vous devez inclure les dépendances de package NuGet pour toutes les bibliothèques externes que vous utilisez. Vous devez procéder ainsi pour être en mesure de faire référence à ces types au moment de la conception. Votre projet de bibliothèque de classes doit également inclure une référence au package NuGet Microsoft.CrmSdk.CoreAssemblies afin que vous puissiez vous référer aux interfaces essentielles pour écrire votre plug-in.

Étant donné que le package NuGet Microsoft.CrmSdk.CoreAssemblies a une dépendance sur System.Text.Json, vous pouvez vous référer aux types System.Text.Json au moment de la conception sans ajouter explicitement le package NuGet System.Text.Json. Cependant, le package NuGet System.Text.Json n’est pas inclus dans votre package de plug-in en raison de cette dépendance indirecte. Vous devez l’ajouter explicitement en tant que dépendance de premier niveau pour votre package de plug-in.

Actuellement, System.Text.Json est la seule dépendance dans le package NuGet Microsoft.CrmSdk.CoreAssemblies. Ces conseils s’appliquent si d’autres nouvelles dépendances sont ajoutées à l’avenir.

FAQ

Q : Puis-je continuer à utiliser ILMerge ?

R : Nous n’avons jamais pris en charge ILMerge. Cette fonctionnalité d’assemblys dépendants fournit une solution que nous pouvons prendre en charge avec la même fonctionnalité et plus encore. Mais rien d’autre n’a changé. Si ILMerge fonctionne pour vous, vous pouvez continuer à l’utiliser. Nous vous recommandons d’utiliser des assemblys dépendants, car nous pouvons prendre en charge cette solution.

Problèmes connus

Les problèmes connus suivants doivent être résolus avant que les assemblys dépendants des plug-ins ne deviennent généralement disponibles.

Modifications de la clé d’exportation de l’API personnalisée

Lors de l’importation d’une solution contenant une API personnalisée qui utilise un package de plug-in, vous pouvez rencontrer l’erreur suivante :

Lookup value <plugintypeexportkey>{guid value}</plugintypeexportkey> is not resolvable.

Cette erreur se produit uniquement pour les solutions qui ont été exportées/générées avant mai 2023. La date exacte varie selon les régions. Le correctif de ce problème a été déployé dans la région Amérique du Nord le 26 mai 2023.

Pour résoudre ce problème, vous devez mettre à jour le package de plug-in, exporter/générer la solution et la réinstaller.

Pour plus d’informations : Définir une relation avec un type de plug-in (facultatif)

Profileur de plug-ins

Pour déboguer les plug-ins qui font partie d’un package de plug-ins, vous devez effectuer les opérations suivantes :

1. Utilisez la version la plus récente de Plug-in Registration Tool (PRT). Version 9.1.0.184 ou une version supérieure.

   Utilisez la commande CLI pac tool prt avec le commutateur --update pour la mise à jour.

2. Dans le dossier contenant l’outil PRT, modifiez le fichier appsettings.json. Définissez LegacyPluginProfiler sur false.

   Si vous avez effectué l’installation à l’aide de PAC CLI, le dossier doit être :

   C:\Users\<you>\AppData\Local\Microsoft\PowerPlatform\PRT\9.1.0.184\tools

Pour plus d’informations :

• pac tool prt
• Utiliser le profileur de plug-ins

Voir aussi

Utiliser des plug-ins pour étendre les processus d’entreprise
PAC CLI pac plugin init