Écrire un plug-in

  • Article

 

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Les plug-ins sont des classes personnalisées qui implémentent l’interface IPlugin. Vous pouvez écrire un plug-in dans tout langage compatible CLR .NET Framework 4.5.2 tel que Microsoft Visual C# et Microsoft Visual Basic .NET. Pour compiler du code de plug-in, vous devez ajouter les références d’assembly Microsoft.Xrm.Sdk.dll et Microsoft.Crm.Sdk.Proxy.dll à votre projet. Ces assemblys se trouvent dans le dossier SDK\Bin du Kit de développement logiciel (SDK).Téléchargez le package Kit de développement logiciel (SDK) de Microsoft Dynamics CRM.

Contenu de la rubrique

Conception d’un plug-in

Création d’un plug-in de base

Création d’un constructeur de plug-in

Prise en charge de l’exécution hors connexion

Web Access pour les plug-ins isolés (en bac à sable)

Utilisation des types à liaison anticipée

Assemblys du plug-in

Conception d’un plug-in

Votre conception de plug-in doit prendre en compte la fonctionnalité d’enregistrement automatique d’application Web introduite dans Microsoft Dynamics 365 (Online et local). L’enregistrement automatique est activé par défaut mais peut être désactivé au niveau d’une organisation. Lorsque l’enregistrement automatique est activé, le bouton Enregistrer n’apparaît pas. L’application Web enregistrera les données du formulaire automatiquement 30 secondes après la dernière modification non enregistrée. Vous pouvez appliquer des scripts de formulaire pour désactiver les comportements d’enregistrement automatique au niveau du formulaire. Selon la façon dont vous avez enregistré votre plug-in, l’enregistrement automatique peut provoquer un appel plus fréquent de votre plug-in pour les modifications de champ individuel au lieu d’un seul appel de plug-in pour toutes les modifications. Vous devez supposer que tout utilisateur peut sauvegarder un enregistrement à tout moment, que ce soit avec Ctrl+S, en appuyant sur un bouton d’enregistrement ou automatiquement avec la fonctionnalité d’enregistrement automatique.

Il est recommandé d’enregistrer votre plug-in ou workflow sur des entités et des champs spécifiques qui importent le plus. Évitez d’enregistrer un plug-in ou un workflow pour des modifications effectuées dans tous les champs d’entités. Si vous avez un plug-in ou workflow existant qui a été implémenté avant la disponibilité de la fonctionnalité d’enregistrement automatique, vous devez retester ce code pour vérifier qu’il fonctionne correctement. Pour plus d’informations, voir TechNet : gérer l'enregistrement automatique.

Création d’un plug-in de base

L’exemple suivant montre une partie du code commun figurant dans un plug-in. Dans cet exemple, le code omet toute logique métier personnalisée qui effectue la tâche planifiée du plug-in. Toutefois, le code affiche une classe de plug-in qui implémente l’interface IPlugin et la méthode Execute requise.

using System;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

public class MyPlugin: IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Extract the tracing service for use in debugging sandboxed plug-ins.
        // If you are not registering the plug-in in the sandbox, then you do
        // not have to add any tracing service related code.
        ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

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

        // The InputParameters collection contains all the data passed in the message request.
        if (context.InputParameters.Contains("Target") &&
            context.InputParameters["Target"] is Entity)
        {
            // Obtain the target entity from the input parameters.
            Entity entity = (Entity)context.InputParameters["Target"];

            // Verify that the target entity represents an entity type you are expecting. 
            // For example, an account. If not, the plug-in was not registered correctly.
            if (entity.LogicalName != "account")
                return;

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

            try
            {
                // Plug-in business logic goes here.
            }

            catch (FaultException<OrganizationServiceFault> ex)
            {
                throw new InvalidPluginExecutionException("An error occurred in MyPlug-in.", ex);
            }

            catch (Exception ex)
            {
                tracingService.Trace("MyPlugin: {0}", ex.ToString());
                throw;
            }
        }
    }
}

Le paramètre IServiceProvider de la méthode Execute est un conteneur pour plusieurs objets utiles de service qui sont accessibles dans un plug-in. Le fournisseur de services contient des références d’instance au contexte d’exécution, IOrganizationServiceFactory, ITracingService, etc. L’exemple de code montre comment obtenir des références au contexte d’exécution, IOrganizationServiceet ITracingService à partir du paramètre du fournisseur de services. Pour plus d’informations sur le service de traçage, voir Déboguer un plug-in.

Le contexte d’exécution contient une mine d’informations sur l’événement qui a provoqué l’exécution du plug-in et les données contenues dans le message en cours de traitement par le pipeline. Pour plus d’informations sur le contexte de données, voir Comprendre le contexte de données passé à un plug-in.

La plateforme fournit les URL des services Web et les informations d’identification du réseau lorsque vous obtenez du fournisseur de services la référence du service Web de l’organisation. L’instanciation du proxy de votre propre service Web n’est pas prise en charge car elle crée des problèmes d’interblocage et d’authentification. Après avoir obtenu la référence du service d’organisation, vous pouvez l’utiliser pour effectuer des appels de méthode sur le service Web d’organisation. Vous pouvez récupérer ou modifier des données commerciales dans une seule organisation Microsoft Dynamics 365 en publiant une ou plusieurs demandes de message sur le service Web. Pour plus d’informations sur les demandes de message, voir Utiliser les messages (classes de demande et de réponse) avec la méthode Execute.

Un plug-in standard doit accéder aux informations figurant dans le contexte, effectuer les opérations d’entreprise nécessaires et gérer les exceptions. Pour plus d’informations sur la gestion des exceptions dans un plug-in, voir Gérer les exceptions dans les plug-ins. Un exemple de plug-in plus complet est disponible dans la rubrique Exemple : Créer un plug-in de base.

Important

Pour améliorer les performances, Microsoft Dynamics 365 met les instances de plug-in en cache. La méthode Execute du plug-in doit être écrite pour être sans état car le constructeur n’est pas appelé pour chaque appel du plug-in. En outre, plusieurs threads système peuvent exécuter le plug-in simultanément. Toutes les informations d’état par appel sont stockées dans le contexte de sorte que vous ne devez pas utiliser de variables globales ou tenter de stocker des données dans les variables membres à utiliser durant le prochain appel de plug-in sauf si ces données ont été obtenues à partir du paramètre de configuration fourni au constructeur. Les modifications apportées à un enregistrement de plug-ins provoqueront la réinitialisation du plug-in.

Création d’un constructeur de plug-in

La plateforme Microsoft Dynamics 365 prend en charge un constructeur de plug-in facultatif qui accepte un ou deux paramètres de chaîne. Si vous créez un constructeur de ce genre, vous pouvez passer toutes les chaînes des informations au plug-in au moment de l’exécution.

L’exemple suivant montre le format du constructeur. Dans cet exemple, la classe de plug-in se nomme SamplePlugin.

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

Le premier paramètre de chaîne du constructeur contient des informations publiques (non sécurisées). Le second paramètre de chaîne contient les informations non publiques (sécurisées). Dans cette discussion, sécurisées fait référence à une valeur chiffrée et non sécurisées à une valeur non chiffrée. Lorsque Microsoft Dynamics 365 pour Microsoft Office Outlook avec accès hors connexion est utilisé, la chaîne sécurisée n’est pas passée à un plug-in qui s’exécute lorsque Dynamics 365 pour Outlook est hors connexion.

Les informations passées au constructeur de plug-in dans ces chaînes sont spécifiées lorsque le plug-in est inscrit dans Microsoft Dynamics 365. Lorsque vous utilisez l’outil Plug-in Registration (Inscription de plug-in) pour inscrire un plug-in, vous pouvez entrer des informations sécurisées et non sécurisées dans les champs Configuration sécurisée et Configuration non sécurisée du formulaire Inscrire une nouvelle étape. Lorsque vous inscrivez un plug-in par programme à l’aide de SDK de Microsoft Dynamics 365, SdkMessageProcessingStep.Configuration contient la valeur non sécurisée et SdkMessageProcessingStep.SecureConfigId fait référence à un enregistrement SdkMessageProcessingStepSecureConfig qui contient la valeur sécurisée.

Prise en charge de l’exécution hors connexion

Vous pouvez inscrire des plug-ins pour qu’ils s’exécutent en mode connexion, hors connexion ou les deux. Le mode hors connexion n’est pris en charge que sur Microsoft Dynamics 365 pour Microsoft Office Outlook avec accès hors connexion. Votre code de plug-in peut vérifier s’il est exécuté en mode hors connexion en vérifiant la propriété IsExecutingOffline.

Lorsque vous concevez un plug-in qui sera inscrit pour l’exécution en mode connexion et hors connexion, n’oubliez pas que le plug-in peut s’exécuter deux fois. La première fois Microsoft Dynamics 365 pour Microsoft Office Outlook avec accès hors connexion est hors connexion. Le plug-in s’exécute à nouveau lorsque Dynamics 365 pour Outlook est connecté et que la synchronisation entre Dynamics 365 pour Outlook et le serveur Microsoft Dynamics 365 a lieu. Vous pouvez vérifier la propriété IsOfflinePlayback pour déterminer si le plug-in s’exécute suite à cette synchronisation.

Web Access pour les plug-ins isolés (en bac à sable)

Si vous prévoyez d’inscrire votre plug-in dans le bac à sable, vous pouvez continuer à accéder aux adresses Web depuis votre code de plug-in. Vous pouvez utiliser n’importe quelle classe .NET Framework de votre code de plug-in qui autorise un accès Web dans les limites des restrictions décrites dans Isolement, approbations et statistiques des plug-ins. Par exemple, le code de plug-in suivant télécharge une page Web.


// Download the target URI using a Web client. Any .NET class that uses the
// HTTP or HTTPS protocols and a DNS lookup should work.
using (WebClient client = new WebClient())
{
    byte[] responseBytes = client.DownloadData(webAddress);
    string response = Encoding.UTF8.GetString(responseBytes);
System_CAPS_security Sécurité Remarque

Pour permettre aux plug-ins en bac à sable d’accéder aux services Web externes, le serveur sur lequel le rôle Service de traitement de bac à sable est installé doit être exposé au réseau Internet, et le compte sous lequel le service de bac à sable fonctionne doit avoir un accès Internet. Seules les connexions sortantes sur les ports 80 et 443 sont requises. L'accès aux connexions entrantes n'est pas obligatoire. Utilisez le panneau de configuration Pare-feu Windows pour activer les connexions sortantes pour l’application Microsoft.Crm.Sandbox.WorkerProcess située sur le serveur dans le dossier %PROGRAMFILES%\Microsoft Dynamics 365\Server\bin folder.

Utilisation des types à liaison anticipée

Pour utiliser les types Microsoft Dynamics 365 de votre code de plug-in, il vous suffit d’inclure le fichier de types, généré à l’aide du programme CrmSvcUtil, dans votre projet de plug-in Microsoft Visual Studio.

La conversion d’une entité à liaison tardive en une entité à liaison anticipée est gérée comme suit :

Account acct = entity.ToEntity<Account>();

Dans la ligne de code précédente, la variable acct est un type à liaison anticipée. Toutes les valeurs Entity qui sont attribuées à IPluginExecutionContext doivent être des types à liaison tardive. Si un type à liaison anticipée est attribué au contexte, une SerializationException se produit. Pour plus d'informations, voir Comprendre le contexte de données passé à un plug-in. Veillez à ne pas combiner les types et n’utilisez pas de type à liaison anticipée lorsqu’un type à liaison tardive est appelé comme le montre le code suivant.

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

Dans l’exemple ci-dessus, vous ne souhaitez pas stocker une instance à liaison anticipée dans le contexte de plug-in là où une instance à liaison tardive doit aller. Cela pour éviter de forcer la plateforme à convertir entre les types à liaison anticipée et les types à liaison tardive avant d’appeler un plug-in et lors du passage du plug-in à la plateforme.

Assemblys du plug-in

Un assembly peut contenir un ou plusieurs types de plug-in. Une fois l’assembly de plug-in inscrit et déployé, les plug-ins peuvent effectuer leur opération prévue en réponse à un événement d’exécution Microsoft Dynamics 365.

System_CAPS_security Sécurité Remarque

Dans Microsoft Dynamics 365, les assemblys de plug-in doivent être lisibles par tout le monde pour fonctionner correctement. Par conséquent, une meilleure pratique de sécurité consiste à développer du code de plug-in qui ne contient pas d’informations de connexion système, d’informations confidentielles ou de secrets commerciaux de société.

Chaque assembly de plug-in doit être connecté, via l’onglet Signature de la feuille de propriétés du projet dans Microsoft Visual Studio ou l’outil Strong Name Tool avant d’être inscrit et déployé dans Microsoft Dynamics 365. Pour plus d’informations sur l’outil Strong Name Tool, exécutez le programme sn.exe, sans aucun argument, dans une fenêtre d’invite de commandes Microsoft Visual Studio.

Si votre assembly contient un plug-in qui peut s’exécuter lorsque Dynamics 365 pour Outlook est en mode hors connexion, la plateforme Microsoft Dynamics 365 impose une sécurité supplémentaire sur les assemblys. Pour plus d'informations, voir Procédure pas-à-pas : configurer la sécurité d’assembly pour un plug-in hors connexion.

Voir aussi

Développement de plug-ins
Comprendre le contexte de données passé à un plug-in
Écrire un plug-in compatible Azure personnalisé
Inscrire et déployer des plug-ins
Gérer les exceptions dans les plug-ins
Exemple : Créer un plug-in de base
Exemple : accès Web d’un plug-in placé dans le bac à sable
Exécuter l’outil de génération de code
Blog : Utilisation de plug-ins pour modifier des vues

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright