Contexte d’exécution des plug-ins
Chaque fois qu’un plug-in (ou une extension de flux de travail personnalisée) s’exécute, une multitude de données est mise à disposition par Microsoft Dataverse, qui contiennent des informations sur le contexte dans lequel réside l’opération en cours. Les plug-ins et les assemblages de flux de travail personnalisés ont accès à une classe IWorkflowContext, accessible au moyen de différentes méthodes.
Dans les plug-ins, le IPluginExecutionContext est accessible au moyen du paramètre IServiceProvider de la méthode Execute en appelant la méthode GetService.
public class SamplePlugin : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));
}
}
Dans les extensions de flux de travail personnalisées, le IPluginExecutionContext est transmis en tant que paramètre de la méthode Execute de type CodeActivityContext.
public class SampleWorkflowExtension : CodeActivity
{
protected override void Execute(CodeActivityContext context)
{
// Obtain the execution context from the code activity context.
IWorkflowContext workflowContext = context.GetExtension();
}
}
IPluginExecutionContext et IWorkflowContext mettent en œuvre l’interface IExecutionContext. Chacun expose également des informations spécifiques à leur type. Pour en savoir plus, consultez Comprendre le contexte d’exécution.
Propriétés d’IExecutionContext
Deux des propriétés les plus remarquables de l’interface IExecutionContext sont InputParameters et OutputParameters. D’autres propriétés fréquemment utilisées sont PreEntityImages, PostEntityImages et SharedVariables.
InputParameters
La propriété InputParameters est contenue dans la collection InputParameters du contexte d’exécution et les paramètres d’entrée sont de type Entité. Cette propriété vous permet de savoir quelles valeurs d’entité ont été présentées au plug-in avant la mise en œuvre d’une opération donnée.
Par exemple, si vous souhaitez valider vos données et empêcher qu’elles ne soient enregistrées si la validation échoue, la procédure à suivre serait similaire à celle-ci :
Enregistrez votre plug-in pour l’exécuter à la phase Pre-Validation lors de la création et/ou mise à jour de l’entité à valider.
Validez les données de votre plug-in en lisant les valeurs de la collection InputParameters. Lors de la création, vous allez souhaiter récupérer la collection Cible.
Levez une méthode InvalidPluginExecutionException si les données fournies ne sont pas valides.
Sinon, vous souhaitez peut-être mettre à jour les valeurs de votre entité (comme supprimer les caractères spéciaux d’un numéro de téléphone) avant d’enregistrer les données. Pour gérer cette situation, procédez comme suit :
Enregistrez votre plug-in pour l’exécuter à la phase Pre-Operation lors de la création et/ou mise à jour de l’entité à mettre à jour.
Mettez à jour les données de votre plug-in en modifiant les valeurs de la collection InputParameters. Lors de la création, vous allez souhaiter récupérer la collection Cible.
OutputParameters
Les paramètres de sortie sont contenus dans la collection OutputParameters du contexte d’exécution et sont de type Entité. Les paramètres de sortie ne sont fournis qu’une fois que l’opération donnée s’est produite. Par conséquent, vous pouvez utiliser cette collection seulement si vous gérez des événements à la phase PostOperation.
Par exemple, si vous souhaitez modifier les valeurs renvoyées par l’opération, procédez comme suit :
Enregistrez votre plug-in pour l’exécuter à la phase PostOperation lors de la création et/ou de la mise à jour de l’entité à mettre à jour.
Mettez à jour les données de votre plug-in en modifiant les valeurs de la collection OutputParameters. Lors de la création, vous allez souhaiter récupérer la collection Cible.
PreEntityImages et PostEntityImages
Lorsque vous enregistrez des plug-ins pour qu’ils s’exécutent dans l’infrastructure de l’événement, vous pouvez fournir une copie immuable, ou un instantané, des données. Ceci est idéal, en particulier lorsque vous devez référencer des valeurs des données avant ou après une opération, par exemple à des fins de journalisation ou d’audit personnalisé.
Bien que vous puissiez récupérer des valeurs d’entité à l’aide du contexte d’organisation à partir d’un plug-in avec une requête de récupération, effectuer cette tâche à l’aide d’images d’entité est bien plus efficace et fortement conseillé.
SharedVariables
Les variables partagées vous permettent de configurer les données qui peuvent être transmises d’un plug-in à une étape qui se produit plus tard dans le pipeline de mise en œuvre. Bien que nous vous recommandons vivement de configurer les plug-ins pour qu’ils soient sans état et sans aucune dépendance vis-à-vis des événements externes, il existe parfois des exceptions à cette règle.
Une exception pourrait être lorsque vous souhaitez vous assurer que vous n’avez pas de plug-ins « échappé » dans votre environnement. Autrement dit, ils s’activent dans un scénario de récursivité infinie. En outre, le contexte d’exécution vous permet de déterminer la profondeur d’exécution de votre plug-in, mais dans certaines situations, il peut être approprié d’effectuer un suivi manuel. Par exemple, votre plug-in démarre peut-être par erreur la logique de mise à jour dans un plug-in configuré pour s’exécuter à la mise à jour de l’entité, ce qui entraîne son exécution à l’infini. Pour résoudre ce problème, vous pouvez créer un modèle permettant de compter le nombre d’exécutions de ce plug-in. Par exemple, vous pouvez configurer une limite de cinq exécutions sur un plug-in avec les étapes suivantes :
Dans le plug-in, vérifiez si la variable partagée RunCount existe, et si ce n’est pas le cas, créez-en une initialisée à zéro.
Vérifiez si la valeur de la variable RunCount est supérieure à cinq et si c’est le cas, levez une exception InvalidPluginExecutionException.
À la fin de votre plug-in, incrémentez la variable RunCount de 1.
Remarque
Ceci n’est qu’une protection supplémentaire contre un bogue qui provoque accidentellement le dépassement de vos ressources par vos plug-ins. Vous devez vous assurer que vous créez vos plug-ins afin que ce scénario ne se produise jamais. Dataverse fournit également des protections pour empêcher de tels plug-ins « échappés », mais leurs méthodes de récupération sont beaucoup plus gourmandes en ressources que cette méthode et plus difficiles à diagnostiquer.