Partager via

Contourner la logique Dataverse personnalisée

  • Article

Vous souhaitez parfois pouvoir effectuer des opérations sur les données sans qu’une logique métier personnalisée soit appliquée dans Dataverse. Ces scénarios impliquent généralement des opérations de données en bloc où un grand nombre d’enregistrements sont créés, mis à jour ou supprimés.

Sans moyen de dire à Dataverse de ne pas appeler la logique métier, vous devez localiser et désactiver les plug-ins et workflows personnalisés individuels qui contiennent la logique métier. La désactivation des plug-ins et des workflows signifie que la logique est désactivée pour tous les utilisateurs pendant que ces plug-ins et workflows sont désactivés. Cela signifie également que vous devez veiller à désactiver uniquement les plug-ins et workflows appropriés et ne pas oublier de les réactiver lorsque vous avez terminé.

Au lieu de ce processus manuel, en tant que développeur d’une application cliente ou d’un plug-in, vous pouvez transmettre des paramètres facultatifs avec vos requêtes pour contrôler deux types de logique métier personnalisée, comme décrit dans le tableau suivant :

Type de logique Quand contourner
Mode synchrone Pour permettre à l’opération de données en masse d’être achevée aussi rapidement que possible. Contournez la logique synchrone lorsque les données que vous modifiez sont connues pour répondre aux exigences de l’organisation, ou si vous avez un plan pour atteindre cette logique par d’autres moyens. Contournez toute logique synchrone personnalisée afin que chaque opération puisse se terminer plus rapidement, ce qui raccourcit la durée totale de l’opération en bloc.
Logique asynchrone Quand un grand nombre de tâches système créées pour traiter la logique asynchrone entraînent une sauvegarde dans Dataverse qui peut affecter les performances. Vous pouvez atténuer ce problème de performances en ne déclenchant pas la logique asynchrone lors de l’exécution d’opérations en bloc.

Notes

Les flux Power Automate représentent un autre type de logique asynchrone qui peut être géré séparément. Voir Contourner les flux Power Automate

Paramètres facultatifs

Utilisez ces paramètres facultatifs pour contrôler la logique métier exécutée dans Dataverse :

Paramètre facultatif Description
BypassBusinessLogicExecution Transmettez les valeurs CustomSync, CustomAsync ou CustomSync,CustomAsync à ce paramètre facultatif pour contourner la logique synchrone, la logique asynchrone ou les deux.
BypassBusinessLogicExecutionStepIds Transmettez une liste séparée par des virgules d’enregistrements d’étapes de plug-in pour ignorer uniquement les étapes de plug-in spécifiées.
BypassCustomPluginExecution Contournez uniquement la logique synchrone. Ce paramètre facultatif est pris en charge, mais n’est pas recommandé. Utilisez BypassBusinessLogicExecution avec la valeur CustomSync pour obtenir le même résultat.

BypassBusinessLogicExecution

Le paramètre facultatif BypassBusinessLogicExecution fonctionne de la même manière que le paramètre facultatif BypassCustomPluginExecution, sauf que vous pouvez choisir de contourner la logique synchrone, la logique asynchrone ou les deux.

Ce paramètre facultatif cible la logique métier personnalisée appliquée à votre organisation. Lorsque vous envoyez des requêtes qui contournent la logique métier personnalisée, tous les plug-ins et workflows personnalisés sont désactivés, sauf :

  • Les plug-ins qui font partie du système Microsoft Dataverse de base ou qui font partie d’une solution dont Microsoft est l’éditeur.
  • Les workflows inclus dans une solution dont Microsoft est l’éditeur.

Les plug-ins système définissent les comportements de base pour des entités spécifiques. Sans ces plug-ins, vous rencontreriez des incohérences de données qui pourraient être difficiles à corriger.

Les solutions fournies par Microsoft qui utilisent Dataverse, telles que Microsoft Dynamics 365 Customer Service ou Dynamics 365 Sales, incluent également une logique métier critique qui ne peut pas être contournée avec cette option.

Important

Vous avez peut-être acheté et installé des solutions d’autres éditeurs de logiciels indépendants (ISV) qui incluent leur propre logique métier. La logique appliquée par ces solutions sera contournée. Vous devez consulter ces éditeurs de logiciels indépendants avant d’utiliser cette option pour comprendre quel peut être l’impact de cette option avec des données utilisées par leurs solutions.

Le tableau suivant décrit quand utiliser les valeurs des paramètres avec BypassBusinessLogicExecution.

Paramètre Description
CustomSync Contournez uniquement la logique personnalisée synchrone.
Le temps de calcul nécessaire à la logique synchrone correspond au temps total nécessaire pour effectuer chaque opération de données. Utilisez cette option pour réduire le temps nécessaire pour terminer les opérations en bloc.
CustomAsync Contournez uniquement la logique métier personnalisée asynchrone, en excluant les flux Power Automate.
Dataverse applique une logique asynchrone une fois une opération terminée. Lorsqu’un grand nombre d’opérations déclenchent la logique asynchrone, Dataverse nécessite plus de ressources pour traiter la logique personnalisée et cette consommation de ressources peut affecter les performances. Utilisez cette option pour éviter les problèmes généraux de performances qui peuvent se produire lorsqu’un grand nombre d’opérations déclenchent la logique asynchrone.
CustomSync,CustomAsync Contournez à la fois la logique métier synchrone et asynchrone, en excluant les flux Power Automate.

Conditions requises pour utiliser le paramètre facultatif BypassBusinessLogicExecution

Comment puis-je utiliser le paramètre facultatif BypassBusinessLogicExecution ?

Vous pouvez utiliser cette option avec l’API web ou le SDK pour .NET.

L’exemple suivant définit le paramètre facultatif BypassBusinessLogicExecution à la fois pour la logique personnalisée synchrone et asynchrone lors de la création d’un nouvel enregistrement de compte à l’aide de la classe CreateRequest du SDK pour .NET.

static void DemonstrateBypassBusinessLogicExecution(IOrganizationService service)
{
    Entity account = new("account");
    account["name"] = "Sample Account";

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("BypassBusinessLogicExecution", "CustomSync,CustomAsync");
    service.Execute(request);
}

BypassBusinessLogicExecutionStepIds

Utilisez le paramètre facultatif BypassBusinessLogicExecutionStepIds pour contourner les étapes de plug-in enregistrées spécifiées au lieu de toute la logique personnalisée synchrone et asynchrone. Transmettez les valeurs GUID des enregistrements d’étapes de plug-in enregistrés avec ce paramètre. Si l’ID d’étape transmis ne s’exécute pas dans la requête donnée, il est ignoré.

Comment utiliser l’option BypassBusinessLogicExecutionStepIds ?

Vous pouvez utiliser cette option avec l’API web ou le SDK pour .NET.

L’exemple suivant définit le paramètre facultatif BypassBusinessLogicExecutionStepIds lors de la création d’un nouvel enregistrement de compte avec la catégorie CreatRequest.

static void DemonstrateBypassBusinessLogicExecutionStepIds(IOrganizationService service)
{
   Entity account = new("account");
   account["name"] = "Sample Account";

   CreateRequest request = new()
   {
         Target = account
   };
   request.Parameters.Add("BypassBusinessLogicExecutionStepIds", "45e0c603-0d0b-466e-a286-d7fc1cda8361,d5370603-e4b9-4b92-b765-5966492a4fd7");
   service.Execute(request);
}

Identifier les étapes à contourner

Il existe plusieurs façons de localiser les valeurs GUID des enregistrements d’étapes de plug-in.

Utiliser Plug-in Registration Tool

  1. Dans le menu Afficher, sélectionnez Afficher par entité.

  2. Sélectionnez l’entité et le message

  3. Sélectionnez l’étape.

    Dans le volet des détails, l’onglet Propriétés affiche le StepId. Copiez la valeur à partir de là.

    Utilisez Plug-in Registration Tool pour trouver la valeur StepId

En savoir plus sur Plug-in Registration Tool

Interroger votre environnement avec l’API web

Utilisez une requête comme la suivante pour récupérer les enregistrements d’étapes de plug-in définis pour une table et un message donnés. L’exemple suivant spécifie la table account, en utilisant le nom logique de la table. Create est le nom du message. Remplacez ces valeurs par la table et le message nécessaires.

Requête

GET [Organization URI]/api/data/v9.2/sdkmessagefilters?$select=sdkmessagefilterid
&$filter=primaryobjecttypecode eq 'account' 
and sdkmessageid/name eq 'Create'
&$expand=sdkmessagefilterid_sdkmessageprocessingstep($select=name;
$filter=statecode eq 0 
and customizationlevel eq 1 
and iscustomizable/Value eq true)
Accept: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0

Response

Dans la réponse, recherchez les valeurs sdkmessageprocessingstepid. Utilisez la valeur name pour identifier le plug-in que vous souhaitez contourner.

Dans ce cas, il n’y en a qu’un seul : 4ab978b0-1d77-ec11-8d21-000d3a554d57

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#sdkmessagefilters(sdkmessagefilterid,sdkmessagefilterid_sdkmessageprocessingstep(name))",
   "value": [
      {
         "@odata.etag": "W/\"31434372\"",
         "sdkmessagefilterid": "c2c5bb1b-ea3e-db11-86a7-000a3a5473e8",
         "sdkmessagefilterid_sdkmessageprocessingstep": [
            {
               "@odata.etag": "W/\"115803276\"",
               "name": "BasicPlugin.FollowupPlugin: Create of account",
               "_sdkmessagefilterid_value": "c2c5bb1b-ea3e-db11-86a7-000a3a5473e8",
               "sdkmessageprocessingstepid": "4ab978b0-1d77-ec11-8d21-000d3a554d57"
            }
         ],
         "sdkmessagefilterid_sdkmessageprocessingstep@odata.nextLink": "[Organization URI]/api/data/v9.2/sdkmessagefilters(c2c5bb1b-ea3e-db11-86a7-000a3a5473e8)/sdkmessagefilterid_sdkmessageprocessingstep?$select=name&$filter=statecode%20eq%200%20and%20customizationlevel%20eq%201%20and%20iscustomizable/Value%20eq%20true"
      }
   ]
}

En savoir plus sur l’interrogation des données à l’aide de l’API Web

Interroger votre environnement avec FetchXml

Utilisez une requête comme la suivante pour récupérer les enregistrements d’étapes de plug-in définis pour une table et un message donnés. L’exemple suivant spécifie 1 pour représenter la table account, en utilisant le code du type d’objet de la table.

Notes

Pour les tables où le code du type d’objet est supérieur à 10000, la valeur ne sera pas la même dans tous les environnements, car cette valeur reçoit une valeur incrémentielle lors de la création de la table.

Si vous connaissez le nom logique de la table, vous pouvez obtenir le code du type d’objet à l’aide d’une requête de l’API web. Cette requête renvoie la valeur 1, le code du type d’objet pour la table account.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/ObjectTypeCode/$value

Create est le nom du message. Remplacez ces valeurs par la table et le message nécessaires.

Utilisez cette requête FetchXml pour renvoyer les valeurs step.sdkmessageprocessingstepid que vous pouvez utiliser avec le paramètre facultatif BypassBusinessLogicExecutionStepIds.

<fetch>
  <entity name='sdkmessagefilter'>
    <filter>
      <condition attribute='primaryobjecttypecode'
        operator='eq'
        value='1' />
    </filter>
    <link-entity name='sdkmessage'
      from='sdkmessageid'
      to='sdkmessageid'
      link-type='inner'
      alias='message'>
      <filter>
        <condition attribute='name'
          operator='eq'
          value='Create' />
      </filter>
    </link-entity>
    <link-entity name='sdkmessageprocessingstep'
      from='sdkmessagefilterid'
      to='sdkmessagefilterid'
      link-type='inner'
      alias='step'>
      <attribute name='name' />
      <filter>
        <condition attribute='statecode'
          operator='eq'
          value='0' />
        <condition attribute='customizationlevel'
          operator='eq'
          value='1' />
        <condition attribute='iscustomizable'
          operator='eq'
          value='1' />
      </filter>
    </link-entity>
  </entity>
</fetch>

En savoir plus sur la récupération de données à l’aide de FetchXml

Limite du nombre d’étapes

Pour garantir que la taille du paramètre n’est pas trop grande, la limite par défaut du nombre d’étapes que vous pouvez effectuer est de trois. La limite est contrôlée à l’aide des données de la colonne OrgDbOrgSettings de la table Organization. Utilisez l’outil OrgDBOrgSettings pour Microsoft Dynamics CRM ou l’application OrgDbOrgSettings pour modifier la valeur BypassBusinessLogicExecutionStepIdsLimit.

La taille maximale recommandée pour cette limite est de 10 étapes.

BypassCustomPluginExecution

Utilisez le paramètre facultatif BypassCustomPluginExecution pour contourner la logique synchrone personnalisée.

Notes

Il s’agissait du premier paramètre facultatif permettant de limiter la logique métier. Il reste pris en charge, mais nous vous recommandons d’utiliser BypassBusinessLogicExecution avec la valeur CustomSync pour obtenir le même résultat.

Utilisez ce paramètre facultatif de la même manière que vous utilisez BypassBusinessLogicExecution, sauf qu’il nécessite un privilège différent : prvBypassCustomPlugins

Comment utiliser l’option BypassCustomPluginExecution ?

Vous pouvez utiliser cette option avec l’API web ou le SDK pour .NET.

Il existe deux manières d’utiliser ce paramètre facultatif avec le SDK pour .NET.

Définir la valeur comme paramètre facultatif

L’exemple suivant définit le paramètre facultatif BypassCustomPluginExecution lors de la création d’un nouvel enregistrement de compte avec la catégorie CreatRequest.

static void DemonstrateBypassCustomPluginExecution(IOrganizationService service)
{
    Entity account = new("account");
    account["name"] = "Sample Account";

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("BypassCustomPluginExecution", true);
    service.Execute(request);
}

Vous pouvez utiliser cette méthode pour les opérations de données que vous lancez dans vos plug-ins lorsque l’utilisateur appelant a le privilège prvBypassCustomPlugins.

Définir la propriété CrmServiceClient.BypassPluginExecution

L’exemple suivant définit la propriété CrmServiceClient.BypassPluginExecution lors de la création d’un nouvel enregistrement de compte :

var service = new CrmServiceClient(connectionString);  

service.BypassPluginExecution = true;

var account = new Entity("account");
account["name"] = "Sample Account";

service.Create(account);

Étant donné que ce paramètre est appliqué au service, il restera défini pour toutes les requêtes envoyées à l’aide du service jusqu’à ce qu’il soit défini sur false.

Notes

Cette propriété n’est pas disponible dans le Dataverse.Client.ServiceClient, mais le reste dans les méthodes Dataverse.Client.Extensions.CRUDExtentions.

Ajout des privilèges requis à un autre rôle

Les paramètres facultatifs décrits dans cet article nécessitent des privilèges qui sont uniquement ajoutés au rôle de sécurité Administrateur système. Ces privilèges ne sont pas disponibles dans le concepteur de rôle de sécurité pour les ajouter à d’autres rôles de sécurité. Si vous devez accorder ce privilège à un autre rôle de sécurité, vous devez utiliser l’API. Par exemple, vous souhaiterez peut-être accorder ce privilège à un utilisateur doté du rôle de sécurité Personnalisateur du système.

Pour ajouter le privilège à un autre rôle de sécurité, l’ID du privilège est nécessaire.

Nom  ID Paramètre(s) facultatif(s)
prvBypassCustomBusinessLogic 0ea552b0-a491-4470-9a1b-82068deccf66 BypassBusinessLogicExecution
BypassBusinessLogicExecutionStepIds
prvBypassCustomPlugins 148a9eaf-d0c4-4196-9852-c3a38e35f6a1 BypassCustomPluginExecution

Ces valeurs d’ID sont les mêmes pour tous les environnements Dataverse.

Associez le privilège prvBypassCustomBusinessLogic à un rôle de sécurité en utilisant AddPrivilegesRoleRequest.

static void AddprvBypassCustomPluginsToRole(IOrganizationService service, Guid roleId)
{
    var request = new AddPrivilegesRoleRequest
    {
        RoleId = roleId,
        Privileges = new[]{
            new RolePrivilege{
                PrivilegeId = new Guid("0ea552b0-a491-4470-9a1b-82068deccf66"),
                Depth = PrivilegeDepth.Global
            }
        }
    };
    service.Execute(request);
}

Questions fréquentes pour contourner la logique métier (FAQ)

Voici les questions fréquentes sur l’utilisation des paramètres facultatifs pour contourner la logique métier synchrone.

Ces paramètres facultatifs contournent-ils les plug-ins pour les opérations de données effectuées par les plug-ins Microsoft ?

Non Si un plug-in ou un workflow dans une solution Microsoft exécute des opérations sur d’autres enregistrements, la logique de ces opérations n’est pas contournée. Seuls les plug-ins ou workflows qui s’appliquent à l’opération spécifique sont contournés.

Puis-je utiliser ces paramètres facultatifs pour les opérations de données que j’effectue dans un plug-in ?

Oui, mais uniquement lorsque le plug-in s’exécute dans le contexte d’un utilisateur qui dispose du privilège requis. Pour les plug-ins, définissez le paramètre facultatif sur la classe dérivée de la classe OrganizationRequest. Vous ne pouvez pas utiliser les classes CrmServiceClient ou ServiceClient dans un plug-in.

Voir aussi

Contourner les flux Power Automate
Utiliser des paramètres facultatifs

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