Didacticiel : Mettre à jour un plug-in

Article
02/24/2023

Ce didacticiel est le troisième d’une série qui vous montrera comment utiliser des plug-ins.

Didacticiel : Entrez et enregistrez un plug-in
Didacticiel : Déboguer un plug-in
Didacticiel : Mettre à jour un plug-in (le présent didacticiel)

Pour une explication détaillée des concepts correspondants et des détails techniques, voir :

Objectif

Ce didacticiel décrira d’autres opérations courantes que vous exécuterez avec les plug-ins. Dans ce didacticiel, vous effectuerez les opérations suivantes :

Mettre à jour un assembly de plug-in
Créer et enregistrer un plug-in synchrone
Utiliser les données de configuration dans le plug-in
Générer une erreur à afficher à l’utilisateur
Configurer et utiliser une image de pré-entité dans votre code
Annuler l’enregistrement d’un assembly, d’un plug-in ou d’une étape

Ce didacticiel a pour objectif :

Créez un plug-in synchrone enregistré à l’étape de pré-validation du message de mise à jour de la table des comptes.
Le plug-in évalue un ensemble de valeurs de chaîne transmises en tant que données de configuration lors de l’enregistrement du plug-in.
Si le nom du compte est remplacé par une de ces valeurs et la valeur précédente ne contenait pas le nouveau nom, annulez l’opération et renvoyez un message d’erreur à l’utilisateur.

Configuration requise

Effectuez le Didacticiel : Entrer et enregistrer un plug-in
Le Didacticiel : Déboguer un plug-in est recommandé mais n’est pas obligatoire.

Notes

Comme de nombreuses étapes de base ont été décrites en détail dans le Didacticiel : Entrer et enregistrer un plug-in, le même niveau de détail n’est pas fourni pour les mêmes étapes dans ce didacticiel.

Créer une classe de plug-in

Dans Visual Studio, ajoutez une nouvelle classe au projet BasicPlugin nommée ValidateAccountName.cs

Notes

Lorsque vous apportez une modification significative à un assembly, vous devez mettre à jour la version de l’assembly. Ceci est particulièrement important si vous avez l’intention de mettre à jour un assembly qui fait partie d’un solution gérée. La version fait partie du nom complet de l’assembly qui est un identifiant unique de l’assembly. Le processus de mise à jour de la solution peut ne pas reconnaître que l’assembly a changé lorsque le nom complet de l’assembly n’a pas changé.
Ajoutez le code suivant à la classe et recréez l’assembly.

using Microsoft.Xrm.Sdk;
using System;
using System.Collections.Generic;
using System.Linq;

namespace BasicPlugin
{
  public class ValidateAccountName : IPlugin
  {
    //Invalid names from unsecure configuration
    private List<string> invalidNames = new List<string>();

    // Constructor to capture the unsecure configuration
    public ValidateAccountName(string unsecure)
    {
      // Parse the configuration data and set invalidNames
      if (!string.IsNullOrWhiteSpace(unsecure))
        unsecure.Split(',').ToList().ForEach(s =>
        {
          invalidNames.Add(s.Trim());
        });
    }
    public void Execute(IServiceProvider serviceProvider)
    {

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

        // Obtain the execution context from the service provider.  
        IPluginExecutionContext context = (IPluginExecutionContext)
            serviceProvider.GetService(typeof(IPluginExecutionContext));

        // Verify all the requirements for the step registration
        if (context.InputParameters.Contains("Target") && //Is a message with Target
            context.InputParameters["Target"] is Entity && //Target is an entity
            ((Entity)context.InputParameters["Target"]).LogicalName.Equals("account") && //Target is an account
            ((Entity)context.InputParameters["Target"])["name"] != null && //account name is passed
            context.MessageName.Equals("Update") && //Message is Update
            context.PreEntityImages["a"] != null && //PreEntityImage with alias 'a' included with step
            context.PreEntityImages["a"]["name"] != null) //account name included with PreEntityImage with step
        {
          // Obtain the target entity from the input parameters.  
          var entity = (Entity)context.InputParameters["Target"];
          var newAccountName = (string)entity["name"];
          var oldAccountName = (string)context.PreEntityImages["a"]["name"];

          if (invalidNames.Count > 0)
          {
            tracingService.Trace("ValidateAccountName: Testing for {0} invalid names:", invalidNames.Count);

            if (invalidNames.Contains(newAccountName.ToLower().Trim()))
            {
              tracingService.Trace("ValidateAccountName: new name '{0}' found in invalid names.", newAccountName);

              // Test whether the old name contained the new name
              if (!oldAccountName.ToLower().Contains(newAccountName.ToLower().Trim()))
              {
                tracingService.Trace("ValidateAccountName: new name '{0}' not found in '{1}'.", newAccountName, oldAccountName);

                string message = string.Format("You can't change the name of this account from '{0}' to '{1}'.", oldAccountName, newAccountName);

                throw new InvalidPluginExecutionException(message);
              }

              tracingService.Trace("ValidateAccountName: new name '{0}' found in old name '{1}'.", newAccountName, oldAccountName);
            }

            tracingService.Trace("ValidateAccountName: new name '{0}' not found in invalidNames.", newAccountName);
          }
          else
          {
            tracingService.Trace("ValidateAccountName: No invalid names passed in configuration.");
          }
        }
        else
        {
          tracingService.Trace("ValidateAccountName: The step for this plug-in is not configured correctly.");
        }
      }
      catch (Exception ex)
      {
        tracingService.Trace("BasicPlugin: {0}", ex.ToString());
        throw;
      }
    }
  }
}

À propos du code

Cette classe contient un constructeur pour capturer la configuration non sécurisée qui est définie lorsqu’une étape est configurée.
Cette classe nécessite que la configuration des étapes spécifiques fonctionne correctement :
- Message de mise à jour
- Sur la table account
- Avec le nom de compte inclus dans les attributs
- Avec PreEntityImage en utilisant un alias spécifique « a »
- Avec PreEntityImage, y compris les colonnes de nom.
Si la configuration de l’étape n’est pas correcte, le plug-in écrit dans le suivi uniquement qu’il n’est pas configuré correctement
Si aucun nom valide n’est défini dans la configuration, le plug-in écrit uniquement dans le journal de suivi qu’aucun nom valide n’a été transmis dans la configuration
Si le nouveau nom correspond aux noms non valides définis à l’aide de la configuration ET le nom d’origine ne contient pas le nouveau nom, une exception InvalidPluginExecutionException est levée avec le message à l’utilisateur pour indiquer que cette opération n’est pas autorisée.

Mettre à jour l’enregistrement de l’assembly de plug-in

L’assembly existant dans le Didacticiel : Entrer et enregistrer un plug-in devrait déjà être enregistré. Pour ajouter le nouveau plug-in ValidateAccountName sans annuler l’enregistrement de l’assembly existant, vous devez le mettre à jour.

Sélectionnez l’assembly (Assembly) Plug-in de base, puis sélectionnez Mettre à jour.
Dans la boîte de dialogue Mettre à jour l’assembly : Plug-in de base, spécifiez l’emplacement de l’assembly en cliquant sur les points de suspension (…) pour charger l’assembly.
Vérifiez que l’assembly et les deux plug-ins sont sélectionnés, puis cliquez sur Mettre à jour les plug-ins sélectionnés.

Configurer une nouvelle étape

Configurez le plug-in ValidateAccountName utilisant ces paramètres :

Paramètre	valeur
Message	Mise à jour
Entité principale	compte
Filtrage d’attributs	name
Phase d’exécution dans le pipeline d’événement	Validation préalable
Mode d’exécution	Synchrone
Configuration non sécurisée	test, foo, bar

Enregistrer une nouvelle étape.

Ajouter une image

Cliquez avec le bouton droit sur l’étape que vous venez d’enregistrer, puis sélectionnez Inscrire une nouvelle image.
Dans la boîte de dialogue Inscrire une nouvelle image, configurez l’image avec les paramètres suivants :

Paramètre Value

Type d’image Pré-image

Nom compte

Alias d’entité a

Paramètres nom
Lorsque l’image est enregistrée, vous la voyez dans le Plug-in Registration Tool.

Paramètre	Value
Type d’image	Pré-image
Nom	compte
Alias d’entité	a
Paramètres	nom

Important

Le comportement par défaut lors de la création d’une image d’entité consiste à sélectionner toutes les colonnes. Cependant, cela peut entraîner une réduction des performances du service Web. Les développeurs ne doivent inclure que les colonnes requises.

Test du plug-in

Ouvrez l’application et tentez de mettre à jour un nom de compte existant sur test, foo ou bar.
Lorsque vous tentez d’enregistrer, le message suivant devrait s’afficher :
Si vous mettez à jour un compte existant avec un nom contenant test, foo ou bar, puis mettez à jour le compte sur test, foo ou bar, le message ne devrait pas s’afficher.

Annuler l’enregistrement d’un assembly, d’un plug-in et d’une étape

Utilisez le Plug-in Registration Tool pour Annuler l’enregistrement (supprimer) d’un assembly, d’un plug-in ou d’une étape. En supprimant un assembly, vous supprimez également l’ensemble des plug-ins et étapes pour cet assembly.

annuler l’enregistrement d’un assembly.