Écrire un plug-in compatible Azure personnalisé

Écrire un plug-in compatible avec Azure est similaire à écrire un autre plug-in Dataverse. Toutefois, en plus d’appeler les méthodes de service Web voulues, le plug-in doit inclure du code pour lancer la publication du contexte d’exécution de la transaction actuelle sur Azure Service Bus.

Considérations en matière de conception de plug-in

Pour un plug-in qui s’exécute de manière synchrone, la conception recommandée est que le plug-in envoie un message à Azure pour récupérer les informations issues d’une application d’écoute ou d’un autre service externe. L’utilisation d’un contrat bidirectionnel ou REST sur le point de terminaison Azure Service Bus permet de retourner une chaîne de données au plug-in.

Il est déconseillé qu’un plug-in synchrone utilise Azure Service Bus pour mettre à jour des données avec un service externe. Des problèmes peuvent surgir si le service externe est indisponible ou s’il existe beaucoup de données à mettre à jour. Les plug-ins synchrones doivent s’exécuter rapidement et ne pas retarder tous les utilisateurs connectés d’une organisation lorsqu’une opération prolongée est effectuée. En outre, si une restauration de l’opération principale en cours qui a appelé le plug-in est effectuée, toutes les modifications de données apportées par le plug-in sont annulées. Cela peut laisser Dynamics 365 et un service externe à un état non synchronisé.

Notez qu’il est possible que les plug-ins inscrits synchrones publient le contexte d’exécution de la transaction actuelle sur Azure Service Bus.

Écrire le code de plug-in

Dans l’exemple suivant, du code de plug-in a été ajouté pour obtenir le fournisseur de services Azure et lancer la publication du contexte d’exécution sur le bus de services en appelant Execute(EntityReference, IExecutionContext). Le code de traçage a été ajouté pour simplifier le débogage du plug-in car le plug-in doit s’exécuter dans le bac à sable.

Notes

Le serviceEndpointId transmis au constructeur dans ce code est celui que vous obtenez en créant un point de terminaison de service comme décrit dans Guide pas à pas : Configurer Azure (SAS) pour l’intégration avec Dataverse

Vous pouvez interroger les points de terminaison de service disponibles pour votre environnement à l’aide d’une demande GET à l’API web à l’aide de votre navigateur avec une requête comme suit : [organization Uri]/api/data/v9.0/serviceendpoints?$select=name,description,serviceendpointid

using System;
using System.Diagnostics;
using System.Threading;
using System.Runtime.Serialization;

using System.ServiceModel;
using System.ServiceModel.Channels;
using System.ServiceModel.Description;

using Microsoft.Xrm.Sdk;

namespace Microsoft.Crm.Sdk.Samples
{
    /// <summary>
    /// A custom plug-in that can post the execution context of the current message to the Windows
    /// Azure Service Bus. The plug-in also demonstrates tracing which assist with
    /// debugging for plug-ins that are registered in the sandbox.
    /// </summary>
    /// <remarks>This sample requires that a service endpoint be created first, and its ID passed
    /// to the plug-in constructor through the unsecure configuration parameter when the plug-in
    /// step is registered.</remarks>
    public sealed class SandboxPlugin : IPlugin
    {
        private Guid serviceEndpointId; 

        /// <summary>
        /// Constructor.
        /// </summary>
        public SandboxPlugin(string config)
        {
            if (String.IsNullOrEmpty(config) || !Guid.TryParse(config, out serviceEndpointId))
            {
                throw new InvalidPluginExecutionException("Service endpoint ID should be passed as config.");
            }
        }

        public void Execute(IServiceProvider serviceProvider)
        {
            // Retrieve the execution context.
            IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

            // Extract the tracing service.
            ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
            if (tracingService == null)
                throw new InvalidPluginExecutionException("Failed to retrieve the tracing service.");

            IServiceEndpointNotificationService cloudService = (IServiceEndpointNotificationService)serviceProvider.GetService(typeof(IServiceEndpointNotificationService));
            if (cloudService == null)
                throw new InvalidPluginExecutionException("Failed to retrieve the service bus service.");

            try
            {
                tracingService.Trace("Posting the execution context.");
                string response = cloudService.Execute(new EntityReference("serviceendpoint", serviceEndpointId), context);
                if (!String.IsNullOrEmpty(response))
                {
                    tracingService.Trace("Response = {0}", response);
                }
                tracingService.Trace("Done.");
            }
            catch (Exception e)
            {
                tracingService.Trace("Exception: {0}", e.ToString());
                throw;
            }
        }
    }
}

Dans votre code de plug-in, vous pouvez mettre à jour les données accessibles en écriture dans le contexte avant de lancer la publication. Par exemple, vous pouvez ajouter une paire clé/valeur aux variables partagées dans le contexte.

Inscription des plug-ins

Il y a certaines restrictions pour inscrire un plug-in personnalisé compatible Azure. Le plug-in doit être inscrit pour s’exécuter dans le bac à sable. Ainsi, le plug-in se limite à appeler les méthodes IOrganizationService, les méthodes de solution Azure ou à accéder à un réseau avec un client web. Aucun autre accès externe, tel que l’accès à un système de fichiers local, n’est autorisé.

Pour un plug-in inscrit pour s’exécuter en mode asynchrone, cela signifie aussi que l’ordre d’exécution du plug-in n’est pas garanti par rapport à d’autres plug-ins asynchrones. En outre, les plug-ins asynchrones s’exécutent toujours après l’opération principale de Dynamics 365.

Gérer un échec de publication du bus de services

Le comportement attendu issue de l’échec d’une publication du bus de services dépend de l’inscription ou non du plug-in pour une exécution synchrone ou asynchrone. Pour les plug-ins asynchrones, la tâche système qui publie en fin de compte le contexte d’exécution sur le bus de services réessaie la publication. Pour un plug-in inscrit synchrone, une exception est retournée. Pour plus d’informations, Gestion et notification des erreurs d’exécution

Important

Pour les plug-ins inscrits asynchrones uniquement, lorsque la tâche asynchrone qui publie sur Azure Service Bus est réessayée après un échec de publication, la logique de plug-in entière est exécutée à nouveau. Aussi, n’ajoutez pas d’autre logique au plug-in compatible Azure personnalisé pour autre chose que de modifier le contexte et publier sur le bus de services.

Pour un plug-in inscrit pour s’exécuter de manière asynchrone, le RemoteExecutionContext contenu dans le corps du message envoyé via le bus de services comprend une propriété OperationId et une propriété OperationCreatedOn. Ces propriétés contiennent les mêmes données que les colonnes AsyncOperationId et CreatedOn de l’enregistrement de la tâche système associée (AsyncOperation). Ces propriétés supplémentaires facilitent l’ordonnancement et la détection des doublons si la publication Azure Service Bus doit être tentée à nouveau.

Voir aussi

Extensions Azure pour Dynamics 365
Envoyer des données Dynamics 365 via le Bus des services Microsoft Azure
Exemple : Plug-in personnalisé compatible Azure
Écrire un plug-in
Pipeline d’exécution des événements
Inscrire et déployer des plug-ins

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