Fournisseurs personnalisés de données d’entité virtuelles
À l'aide du SDK des données Dynamics 365 for Customer Engagement (on-premises), les développeurs .NET peuvent créer des fournisseurs personnalisés de données d'entités virtuelles afin d'intégrer les types de sources de données externes qui ne sont pas pris en charge par un fournisseur de données existant. Chaque fournisseur de données est constitué d'un ensemble réutilisable de plug-ins Dynamics 365 for Customer Engagement (on-premises) qui implémentent les opérations CRUD prises en charge. (La version initiale est limitée aux opérations de lecture Retrieve et RetrieveMultiple). Cette section fournit des informations fondamentales sur les fournisseurs de données, ainsi que les approches permettant de développer des fournisseurs personnalisés, y compris un exemple de code.
Note
Comme alternative à la création d’un fournisseur de source de données personnalisé, vous devez envisager d’adapter votre source de données à un fournisseur de données existant. Par exemple, si vous créez une interface OData v4 pour votre source de données externe, vous pouvez y accéder directement avec le fournisseur de données OData v4 standard fourni. Le mécanisme d’ajout de cette interface REST dépend de la technologie de service de données sous-jacente ; par exemple, voir WCF Data Services 4.5. OData assure une large prise en charge du secteur, avec un large éventail d’outils dédiés et de technologies compatibles.
Configuration requise
Les fournisseurs de données personnalisés nécessitent de créer et de gérer d’importantes ressources de développement. Vous devez avoir des connaissances fondamentales des domaines suivants :
- Le schéma de la source de données externe et les techniques d’accès aux données associées. Ces connaissances du domaine sont spécifiques au type de source de données externe.
- Le schéma des métadonnées de Dynamics 365 for Customer Engagement (on-premises) ; pour plus d’informations, voir Métadonnées et modèles de données dans Microsoft Dynamics 365 Customer Engagement (on-premises).
- Le système d’événements Dynamics 365 for Customer Engagement (on-premises) ; pour plus d’informations voir Infrastructure d’événements.
- L’architecture et le développement de plug-ins Dynamics 365 for Customer Engagement (on-premises) ; pour plus d’informations voir Développement de plug-ins.
Vous devrez également télécharger manuellement le Kit de développement logiciel (SDK) des données Dynamics 365 for Customer Engagement (on-premises), ou inclure le package NuGet correspondant dans vos projets. Ce SDK est compatible avec Visual Studio 2015 ou 2017.
Catégories de fournisseurs
Deux grandes catégories de fournisseur de données peuvent être créées à l’aide des assemblys du SDK des données d’entités virtuelles : générique ou ciblé. Le tableau ci-dessous décrit ces approches et les met en correspondance avec le modèle de développement de fournisseur de données qui convient le mieux à cette approche.
| Catégorie | Modèle de développement | Description |
|---|---|---|
| Générique | Fournisseur complet | Ces fournisseurs peuvent traduire en toute flexibilité les expressions de requête FetchXML en demande associée à la source de données externe, puis renvoient les instances d’entité obtenues. Ce fournisseur peut être réutilisé pour toutes les instances de ce type de source de données. Cette approche est la plus générale mais est plus complexe à développer. Si le schéma de la source de données est modifié, les entités virtuelles affectées doivent uniquement être mappées à nouveau. |
| Ciblé | Fournisseurs LINQ pour un schéma connu | Ce fournisseur traduit de manière limitée les requêtes en appel LINQ associé à une instance de source de données existante connue. La source de données doit être un fournisseur LINQ, comme décrit dans la rubrique Activer une source de données pour les requêtes LINQ. Cette approche est limitée à une instance de source de données spécifique, mais elle nécessite beaucoup moins de codage. Si le schéma de la source de données est modifié, le fournisseur de données doit être mis à jour et régénéré. |
Le fournisseur de données Odata v4 standard et le fournisseur de données Cosmos DB sont des exemples de fournisseurs génériques.
Étapes pour utiliser un fournisseur de données personnalisé
Plusieurs étapes sont nécessaires pour créer une solution de fournisseur de données d’entités virtuelles qui peut être importée dans vos applications Dynamics 365 for Customer Engagement (on-premises) :
- Développez la DLL du plug-in de fournisseur de données personnalisé (ou un ensemble de DLL).
- Enregistrez le fournisseur de données personnalisé auprès de votre service Dynamics 365 for Customer Engagement (on-premises) au moyen de l’outil Plug-in Registration (PRT).
- Créez une solution de fournisseur de données.
- Personnalisez l’entité de source de données pour refléter votre type de données ou votre instance spécifique.
- Exportez la solution de fournisseur de données personnalisé.
Développement de plug-ins
Comme les entités virtuelles dans cette version sont en lecture seule, vous écrivez le fournisseur de données sous la forme d’un plug-in enregistré dans les événements Retrieve et RetrieveMultiple. Chaque événement respectif contient des informations dans le contexte d’exécution qui décrivent le type de données à renvoyer.
| Événement | Contexte d’exécution |
|---|---|
| Récupérer | Décrit l’entité à récupérer ainsi que les attributs et les entités associées à inclure. |
| RetrieveMultiple | Contient un objet QueryExpression définissant la requête. La structure contient une classe QueryExpressionVisitor conçue pour inspecter les différentes parties de l’arborescence d’expressions de requête. |
Pour les deux événements, vous devez :
- Convertir les informations respectives du contexte d’exécution en une requête appropriée pour votre source de données externe.
- Récupérer les données du système externe.
- Pour Retrieve, convertissez les données en Entity ; sinon, pour RetrieveMultiple, convertissez-les en EntityCollection. Ce résultat est renvoyé via la plateforme Dynamics 365 Customer Engagement (on-premises) à l’utilisateur exécutant la requête.
Les classes de l’espace de noms Microsoft.Xrm.Sdk.Data fournissent une structure d’aide au mappage des informations de requête Dynamics 365 Customer Engagement (on-premises) du contexte d’exécution en une requête au format approprié pour votre source de données externe. Cette structure vous permet de convertir les données renvoyées en types Entity ou EntityCollection appropriés attendus par la plateforme Dynamics 365 Customer Engagement (on-premises).
Exceptions de fournisseur de données
Si pour une raison quelconque votre code ne peut pas atteindre le résultat attendu, vous devez générer l’erreur appropriée. L’espace de noms Microsoft.Xrm.Sdk.Data.Exceptions contient les classes d’exception suivantes, dérivées de SdkExceptionBase, que vous pouvez utiliser aux fins suivantes :
| Classe d’exception | Description |
|---|---|
| AttributeNotFoundException | La requête spécifie un attribut qui est introuvable dans l’enregistrement de données externes associé. Se produit généralement suite à un mappage de type incorrect ou à une modification du schéma de la source de données externe. |
| AuthenticationException | Une erreur s’est produite lors de l’authentification de sécurité du service de source de données externe ; par exemple le statut HTTP 401 est reçu du service de données externe. Se produit généralement car l’utilisateur actuel ne dispose pas des privilèges adéquats ou les informations de connexion dans le EntityDataSource associé ne sont pas valides. |
| EndpointException | La configuration du point de terminaison dans l’entité de source de données n’est pas valide ou le point de terminaison n’existe pas. |
| EntityNotFoundException | La requête cible une entité qui n’existe pas. Se produit généralement suite à un mappage de type incorrect ou à une modification du schéma de la source de données externe. |
| GenericDataAccessException | Erreur générale d’accès aux données, utilisée lorsque l’erreur ne correspond pas à une exception plus spécifique. |
| InvalidMetadataException | |
| InvalidQueryException | La requête spécifiée n’est pas valide ; par exemple une combinaison de clauses non valide ou un opérateur de comparaison non pris en charge. |
| ObjectNotFoundException | L’enregistrement spécifié dans la source de données externe n’existe pas. |
| TimeoutException | L’opération externe ne s’est pas terminée dans le temps imparti ; par exemple, le résultat d’un statut HTTP 408 du service de données externe. |
Inscription des plug-ins
Contrairement à un plug-in ordinaire, vous utilisez uniquement l’outil Plug-in Registration (PRT) pour enregistrer l’assembly et les plug-ins pour chaque événement. Vous n’enregistrez pas des étapes spécifiques. Votre plug-in s’exécute à la phase 30, la principale phase de transaction pour l’opération qui n’est pas disponible pour les étapes du plug-in ordinaire. Au lieu d’enregistrer les étapes, vous configurez votre fournisseur de données à l’aide des entités Microsoft.Dynamics.CRM.EntityDataProvider et Microsoft.Dynamics.CRM.EntityDataSource.
| Entité | Description |
|---|---|
| EntityDataProvider | Définit les plug-ins à utiliser pour chaque événement et le nom logique de la source de données. |
| EntityDataSource | Fournit le contexte d’entité et les informations de connexion requises pour la source de données externe, y compris les secrets nécessaires pour s’authentifier. |
Lorsque les métadonnées de votre entité virtuelle sont configurées, les plug-ins sont enregistrés à l’aide de l’outil PRT et les données de configuration correctes sont définies dans les entités EntityDataProvider et EntityDataSource, votre entité virtuelle commence à répondre aux demandes.