É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 consiste à ce que le plug-in envoie un message à Azure pour récupérer des informations à partir 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 n’est pas recommandé qu’un plug-in synchrone utilise le Azure Service Bus pour mettre à jour les données avec un service externe. Des problèmes peuvent survenir si le service externe n’est plus disponible ou s’il y a 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. Cette restauration pourrait laisser Dataverse un service externe dans un état non synchronisé.

Il est possible pour les plug-ins enregistrés synchrones de publier le contexte d’exécution de la transaction en cours dans Azure Service Bus.

Écrire le code de plug-in

Dans l’exemple de plug-in suivant, du code a été ajouté pour obtenir le fournisseur de services Azure et lancer la publication du contexte d’exécution sur le Service Bus 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 existe quelques restrictions lorsque vous enregistrez un plug-in personnalisé compatible Azure. Le plug-in doit être inscrit pour s’exécuter dans le bac à sable. L’enregistrement Sandbox limite le plug-in à l’appel de méthodes, de méthodes de solution Azure ou à l’accès à un réseau à l’aide d’un client Web. IOrganizationService Aucun autre accès externe, tel que l’accès à un système de fichiers local, n’est autorisé.

Pour un plug-in enregistré pour s’exécuter en mode asynchrone, l’ordre d’exécution du plug-in par rapport aux autres plug-ins asynchrones n’est pas garanti. De plus, les plug-ins asynchrones s’exécutent toujours après l’opération principale. Dataverse

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

Intégration Azure
Travailler avec Microsoft Dataverse les données dans votre solution 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é).