Commentaires

Écrire un plug-in

  • Article
  • 4 minutes de lecture

Notes

Vous n’êtes pas sûr de l’entité par rapport à la table ? Voir Développeurs : Comprendre la terminologie dans Microsoft Dataverse.

Vous pouvez utiliser Power Platform Tools pour Visual Studio pour créer et déployer (inscrire) rapidement des plug-ins. Pour savoir comment faire, consultez l’article Démarrage rapide .

Il existe un processus plus manuel d′écriture, d′enregistrement et de débogage d′un plug-in :

  1. Créer un projet de bibliothèque de classes .NET Framework dans Visual Studio
  2. Ajouter le package Microsoft.CrmSdk.CoreAssemblies NuGet au projet
  3. Implémentez l′interface IPlugin sur les classes qui seront enregistrées comme étapes.
  4. Ajoutez votre code à la méthode Execute requise par l′interface
    1. Obtenez des références aux services dont vous avez besoin
    2. Ajoutez votre logique métier
  5. Signez et générez l′assembly
  6. Testez l′assembly
    1. Enregistrez l′assembly dans un environnement de test
    2. Ajoutez votre assembly enregistré et les étapes à une solution non gérée
    3. Testez le comportement de l’assembly
    4. Vérifiez que les journaux de suivi prévus sont écrits
    5. Déboguez l’assembly si nécessaire

Le contenu de cette rubrique couvre les étapes 1 à 5 ci-dessus et prend en charge les didacticiels suivants :

Contraintes d’assembly

Lorsque vous créez des assemblys, gardez à l’esprit les contraintes suivantes.

Utiliser .NET Framework 4.6.2

Les plug-ins et les assemblys de workflow personnalisés doivent utiliser .NET Framework 4.6.2. Bien que les assemblys créés à l’aide de versions ultérieures devraient généralement fonctionner, s’ils utilisent une fonctionnalité introduite après la version 4.6.2, une erreur se produira.

Optimiser le développement de l’assembly

L’assembly doit contenir plusieurs classes (ou types) de plug-in, mais ne peut pas dépasser 16 Mo. Il est recommandé de consolider les plug-ins et les assemblys de workflow en un seul assembly tant que la taille reste inférieure à 16 Mo. Pour plus d’informations, voir : Optimiser le développement de l’assembly

Les assemblys doivent être signés

Tous les assemblys doivent être signés avant d’être enregistrés. Pour ce faire, utilisez l’onglet Signature Visual Studio dans le projet ou utilisez Sn.exe (outil Strong Name Tool).

Ne pas dépendre des assemblys .NET qui interagissent avec des API Windows de bas niveau

Les assemblys de plug-in doivent contenir toute la logique nécessaire dans leur DLL respectif. Les plug-ins peuvent faire référence à certains assemblys .Net. Toutefois, nous ne prenons pas en charge les dépendances aux assemblys .NET qui interagissent avec des API Windows de bas niveau, telles que l’interface de conception graphique.

Ne dépendre d’aucun autre assembly

L’ajout du package Microsoft.CrmSdk.CoreAssembliesNuGet inclura ces assemblys dans le dossier de génération de votre assembly, mais vous ne chargerez pas ces assemblys avec l’assembly qui inclut votre logique. Ces assemblys sont déjà présents dans l’environnement bac à sable d’exécution.

N’incluez aucun autre package NuGet ou assembly dans le dossier de construction de votre projet. Vous ne pouvez pas inclure ces assemblys lorsque vous inscrivez l’assembly avec votre logique. Vous ne pouvez pas supposer que les assemblys autres que ceux inclus dans le package Microsoft.CrmSdk.CoreAssembliesNuGet seront présents et compatibles avec votre code.

Interface IPlugin

Un plug-in est une classe au sein d’un assembly créé à l’aide d’un projet de bibliothèque de classes .NET Framework qui utilise .NET Framework 4.6.2 dans Visual Studio. Chaque classe du projet qui sera enregistrée comme étape doit implémenter l’interface IPlugin qui nécessite la méthode Execute.

Important

Lors de l’implémentation de l’interface IPlugin, la classe doit être sans état car la plateforme met en cache une instance de classe et la réutilise pour des raisons de performances. En termes simples, vous ne devez ajouter aucune propriété ou méthode à la classe et tout doit être inclus dans la méthode Execute. Voici quelques exceptions à cela. Par exemple, vous pouvez avoir une propriété qui représente une constante et vous pouvez avoir des méthodes qui représentent des fonctions appelées à partir de la méthode Execute. L’important est de ne jamais stocker une instance de service ou des données de contexte en tant que propriété dans votre classe. Celles-ci changent avec chaque appel et vous ne voulez pas que les données soient mises en cache et appliquées aux appels suivants. Pour plus d’informations, voir : Développer les implémentations IPlugin en mode sans état

La méthode Execute accepte un seul paramètre IServiceProvider. L’interface IServiceProvider a une seule méthode : GetService. Vous utiliserez cette méthode pour obtenir plusieurs types de services que vous pouvez utiliser dans votre code. Pour plus d’informations, voir : Services que vous pouvez utiliser dans votre code

Transmettre des données de configuration à votre plug-in

Lorsque vous enregistrez un plug-in, vous avez la possibilité de lui transmettre des données de configuration. Les données de configuration vous permettent de définir le comportement d’une instance spécifique d’un plug-in enregistré. Ces informations sont transmises en tant que données de chaîne aux paramètres dans le constructeur de votre classe. Il existe deux paramètres : unsecure et secure. Utilisez le premier paramètre unsecure pour les données qui peuvent être visualisées par les utilisateurs. Utilisez le deuxième paramètre secure pour les données sensibles.

Le code suivant présente les trois signatures possibles pour une classe de plug-in nommée SamplePlugin.

public SamplePlugin()  
public SamplePlugin(string unsecure)  
public SamplePlugin(string unsecure, string secure)

Les données de configuration sécurisées sont stockées dans une table distincte que seuls les administrateurs système peuvent lire. Plus d’informations : Enregistrer une étape de plug-in > Définir des données de configuration

Services que vous pouvez utiliser dans votre code

Dans votre plug-in, vous devrez :

  • Accéder aux informations contextuelles sur ce qui se produit si votre plug-in a été enregistré pour les gérer. Ceci est appelé le contexte d’exécution.
  • Accéder au service Web de l’organisation pour pouvoir écrire du code pour rechercher des données, utiliser des enregistrements de table, utiliser des messages pour effectuer des opérations.
  • Écrire des messages au service de suivi pour pouvoir évaluer l’exécution de votre code.

La méthode IServiceProvider.GetService vous permet d’accéder à ces services si nécessaire. Pour obtenir une instance du service, appelez la méthode GetService en passant le type de service.

Notes

Lorsque vous écrivez un plug-in qui utilise l’intégration Azure Service Bus, vous utilisez un service de notification qui implémente l’interface IServiceEndpointNotificationService, mais cette approche ne sera pas décrite ici. Pour plus d’informations, voir : Intégration d’Azure

Service d’organisation

Pour utiliser les données d’un plug-in, utilisez le service d’organisation. N’essayez pas à d’utiliser l’API Web. Les plug-ins ne peuvent être écrits qu’à l’aide de l’API SDK et compilés en tant qu’assemblys .NET.

Pour accéder à une variable svc qui implémente l’interface IOrganizationService, utilisez le code suivant :

// Obtain the organization service reference which you will need for  
// web service calls.  
IOrganizationServiceFactory serviceFactory =
    (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService svc = serviceFactory.CreateOrganizationService(context.UserId);

La variable context.UserId utilisée avec IOrganizationServiceFactory.CreateOrganizationService(Nullable<Guid>) provient du contexte d’exécution de la propriété UserId, cet appel est donc effectué après avoir accédé au contexte d’exécution.

Pour plus d’informations :

Vous pouvez utiliser les types à liaison anticipée dans un plug-in. Incluez simplement le fichier des types généré dans votre projet. Mais sachez que tous les types de tables fournis par les paramètres d’entrée du contexte d’exécution sont des types à liaison tardive. Vous devrez les convertir en types à liaison anticipée. Par exemple, vous pouvez effectuer les opérations suivantes lorsque vous savez que le paramètre Target représente une table de compte.

Account acct = context.InputParameters["Target"].ToEntity<Account>();

Mais vous ne devez jamais essayer de définir la valeur avec un type à liaison anticipée. N’essayez pas de faire ceci :

context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.

Cela provquera une exception SerializationException.

Utiliser le service de suivi

Utilisez le service de suivi pour écrire des messages à la table PluginTraceLog afin de pouvoir examiner les journaux pour comprendre ce qui s’est produit pendant l’exécution du plug-in.

Pour écrire dans le journal de suivi, vous devez obtenir une instance du service de suivi. Le code suivant montre comment obtenir une instance du service de suivi à l’aide de la méthode IServiceProvider.GetService .

// Obtain the tracing service
ITracingService tracingService =
(ITracingService)serviceProvider.GetService(typeof(ITracingService));

Pour écrire dans le journal de suivi, utilisez la méthode ITracingService.Trace .

tracingService.Trace("Write {0} {1}.", "your", "message");

Informations complémentaires : Utiliser le suivi, Enregistrement et traçage.

Considérations de performances

Lorsque vous ajoutez la logique métier de votre plug-in, vous devez tenir compte de son impact sur les performances globales.

Important

La logique métier dans les plug-ins enregistrés pour les étapes synchrones ne doit pas prendre plus de 2 secondes.

Contraintes de temps et de ressources

La durée d’exécution des opérations de message est de 2 minutes. Il existe également des limitations quant à la quantité de ressources d’UC et de mémoire pouvant être utilisées par les extensions. Si les limites sont dépassées, une exception est générée et l’opération sera annulée.

Si la limite de temps est dépassée, une exception TimeoutException sera générée. Si une extension dépasse les limites d’UC, de mémoire ou de traitement ou n’est pas réactif d’une autre manière, ce processus est supprimé par la plateforme. À ce stade, toute extension actuelle de ce processus échouera avec des exceptions. Toutefois, la prochaine fois que l’extension sera exécutée, elle fonctionnera normalement.

Analyser les performances

Les informations d’exécution sur les plug-ins et les extensions de workflow personnalisées sont capturées et stockées dans la table PluginTypeStatistic. Ces enregistrements sont remplis au bout de 30 minutes à une heure suivant l’exécution du code personnalisé. Cette table fournit les points de données suivants :

Column Description
AverageExecuteTimeInMilliseconds Temps d’exécution moyen (en millisecondes) du type de plug-in.
CrashContributionPercent Pourcentage de contribution du type de plug-in aux incidents.
CrashCount Nombre de blocages du type de plug-in.
CrashPercent Pourcentage d’incidents pour le type de plug-in.
ExecuteCount Nombre d’exécutions du type de plug-in.
FailureCount Nombre d’échecs du type de plug-in.
FailurePercent Pourcentage d’échecs du type de plug-in.
PluginTypeIdName Identificateur unique de l’utilisateur qui a modifié les statistiques du type de plug-in pour la dernière fois.
TerminateCpuContributionPercent Pourcentage de contribution du type de plug-in aux terminaisons de processus de travail en raison d’une utilisation excessive du processeur.
TerminateHandlesContributionPercent Pourcentage de contribution du type de plug-in aux terminaisons de processus de travail en raison d’une manipulation excessive.
TerminateMemoryContributionPercent Pourcentage de contribution du type de plug-in aux terminaisons de processus de travail en raison d’une utilisation excessive de la mémoire.
TerminateOtherContributionPercent Pourcentage de contribution du type de plug-in aux terminaisons de processus de travail pour raison inconnue.

Ces données sont également disponibles pour que vous accédiez au Centre d’administration Power Platform. Sélectionnez Analyse > Dataverse > Plug-ins.

Étapes suivantes

Enregistrer un plug-in
Déboguer des plug-ins

Voir aussi

Écrire des plug-ins pour étendre les processus d’entreprise
Meilleures pratiques et directives concernant le développement de plug-ins et de workflows
Gérer les exceptions
Emprunter l’identité d’un utilisateur
Didacticiel : Entrez et enregistrez un plug-in
Didacticiel : Déboguer un plug-in
Didacticiel : Mettre à jour un plug-in

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é).