Partager via

Créer et empaqueter le code de plug-in

  • Article

Cet article décrit les contraintes et les limitations que vous devez connaître lorsque vous configurez et créez un assembly pour votre plug-in Microsoft Dataverse.

Contraintes de l’assembly du plug-in

Lorsque vous créez un projet de plug-in, gardez à l’esprit les contraintes suivantes de l’assembly de sortie.

Utiliser .NET Framework 4.6.2

Les projets d’assemblage de plug-in et d’activité de workflow personnalisés doivent cibler .NET Framework 4.6.2. Les assemblys créés avec des versions ultérieures du .NET Framework devraient généralement fonctionner. Cependant, si le code du plug-in utilise des fonctionnalités introduites après la version 4.6.2, une erreur d’exécution se produit.

Limiter les assemblys à 16 Mo

Votre assembly peut inclure plusieurs classes ou types de plug-in et même des activités de workflow personnalisées, mais sa taille ne peut pas dépasser 16 Mo. Comme meilleure pratique, nous vous recommandons de consolider les plug-ins et les assemblys de workflow en un seul assembly, tant que la taille reste inférieure à 16 Mo.

Signer les assemblys avant de les enregistrer

Si vous n’utilisez pas la fonctionnalité d’assemblys dépendants, les assemblys doivent être signés avant de pouvoir les enregistrer dans Dataverse. Pour signer l’assembly, utilisez l’onglet Signature de Visual Studio dans les propriétés de votre projet ou la commande Sn.exe (Outil de nom fort)

Les CoreAssemblies NuGet se trouvent dans le bac à sable

Si vous ajoutez le package NuGet Microsoft.CrmSdk.CoreAssemblies à votre projet, les références d’assembly Dataverse requises sont également ajoutées, mais les assemblys eux-mêmes ne sont pas chargés avec votre assembly de plug-in. Ils existent déjà dans le runtime du bac à sable du serveur où votre code s’exécute

Assemblys dépendants

Important

La fonctionnalité d’assembly dépendant est si importante pour le développement de plug-in que vous devriez envisager de l’utiliser dès le début, même si vous n’en avez pas un besoin immédiat. Ajouter la prise en charge des assemblys dépendants à votre projet de plug-in est beaucoup plus difficile plus tard dans le cycle de développement.

Nous ne prenons pas en charge ILMerge. La fonctionnalité d’assemblys dépendants offre les mêmes fonctionnalités qu’ILMerge et bien plus encore.

Utilisez la fonctionnalité d’assembly dépendant pour inclure d’autres ressources ou assemblys .NET requis, tels que des chaînes localisées, avec votre assembly de plug-in dans un seul package NuGet chargé sur le serveur Dataverse lors de l’enregistrement.

Le fichier du package NuGet est stocké dans la table PluginPackage. Le contenu du package est stocké dans le stockage de fichiers plutôt que dans la base de données 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 au package de plug-in. À mesure que vous développez et gérez votre projet, vous continuez à mettre à jour la ligne de table 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.

Important

Le nom et la version du package de plug-in ne peuvent pas être modifiés une fois créés. Toute tentative à l’aide d’un appel d’API entraîne une erreur.

Des assemblys signés ne sont pas obligatoires

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

Lorsque vous enregistrez des assemblys de plug-in individuels sans la capacité 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 un package de plug-in, les assemblys sont chargés sur le serveur de bac à sable à l’aide d’un mécanisme différent ; par conséquent, la signature n’est pas nécessaire.

Important

Si vous signez vos assemblys, sachez que les assemblys signés ne peuvent pas utiliser les ressources contenues dans les assemblys non signés. Si vous signez vos assemblys de plug-in ou tout assembly dépendant, tous les assemblys dont dépendent ces assemblys doivent être signés.

Si des assemblys signés dépendent d’assemblys non signés, vous obtenez une erreur similaire à celle-ci : « Impossible de charger le fichier ou l’assembly AssemblyName, Version=Version, Culture=neutral, PublicKeyToken=null ou l’une de ses dépendances. Un assembly avec un nom fort est requis. »

Limitations des assemblys dépendants

Les limitations suivantes s’appliquent lorsque vous utilisez des assemblys dépendants d’un plug-in :

  • Les extensions de workflow, également appelées activités de workflow personnalisées, ne sont pas prises en charge.
  • 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.

Considérations relatives aux performances lors de l’importation ou de l’enregistrement d’un package de plug-ins

Les packages de plug-ins contenant des assemblys avec un grand nombre (des centaines voire des milliers) de classes qui implémentent IPlugin nécessiteront un temps d’importation relativement long dans Dataverse.

Nous avons constaté des temps d’importation de quinze (15) minutes pour un millier de types de plug-ins. Cette durée s’applique que vous importiez une solution avec un appel d’API ou via l’interface utilisateur web, ou que vous enregistriez le package avec Plug-in Registration Tool.

Créer un package de plug-in

Vous pouvez placer votre assembly de plug-in et tous les assemblys dépendants ensemble dans un package NuGet, puis enregistrer et charger le package sur le serveur Dataverse. Si votre projet de plug-in ne nécessite aucun assembly dépendant au moment de l’exécution autre que ceux fournis dans le package NuGet Microsoft.CrmSdk.CoreAssemblies, il n’est pas nécessaire de créer un package.

Découvrez comment créer et enregistrer un package de plug-in à l’aide de PAC CLI et comment créer et enregistrer un package de plug-in à l’aide de Visual Studio.

Tous les projets doivent être dans le style SDK

Un package de plug-in doit uniquement contenir des assemblys personnalisés créés à partir d’un fichier de projet dans un format spécifique appelé Style SDK. Le non-respect de cette règle entraîne une erreur (« le fichier est introuvable ») lors de la tentative d’enregistrement du package à l’aide de Plug-in Registration Tool.

Important

Tous les projets MSBuild, dans lesquels l’assembly compilé résultant doit être ajouté à un package de plug-in, doivent être au format « Style SDK ».

Un projet de style SDK est un projet dans lequel le contenu du fichier .csproj du projet contient la ligne de code suivante : <Project Sdk="Microsoft.NET.Sdk">.

Lorsque vous créez un projet de plug-in à l’aide de l’un de nos outils, par exemple la commande pac plugin init de Power Platform CLI, le fichier de projet du plug-in est au format correct. Voici un exemple de ce fichier de projet.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net462</TargetFramework>
    <PowerAppsTargetsPath>$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\PowerApps</PowerAppsTargetsPath>
    <AssemblyVersion>1.0.0.0</AssemblyVersion>
    <FileVersion>1.0.0.0</FileVersion>
    <ProjectTypeGuids>{4C25E9B5-9FA6-436c-8E19-B395D2A65FAF};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>
  </PropertyGroup>
  ...
</Project>

Si vous ajoutez un autre projet à la solution Visual Studio, par exemple un projet de bibliothèque de classes, vous pouvez créer un projet de style SDK en suivant ces étapes.

  1. Dans Visual Studio, ajoutez le nouveau projet à votre solution à l’aide d’un modèle .NET ou .NET Standard. Ne ciblez pas .NET Framework.
  2. Modifiez le fichier du projet en cliquant avec le bouton droit sur le nom du projet dans l’explorateur de solutions et en sélectionnant Modifier le fichier du projet, ou ouvrez simplement le fichier .csproj du projet dans un éditeur distinct.
  3. Vous devriez voir la ligne <Project Sdk="Microsoft.NET.Sdk"> dans le fichier du projet. Modifiez la propriété TargetFramework en <TargetFramework>net462</TargetFramework> et enregistrez le fichier.
  4. Vérifiez que votre solution est générée et vous avez terminé.

Plus d’informations : SDK du projet .NET

Ne dépendez pas de System.Text.Json

É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. Cependant, le fichier System.Text.Json.dll dans le runtime du bac à sable peut ne pas être la même version que celle à laquelle vous faites référence dans votre projet. Si vous devez utiliser System.Text.Json, vous devez utiliser la fonctionnalité d’assembly dépendant et l’inclure explicitement dans votre package NuGet.

Étape suivante

Voir aussi

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).