Éléments à prendre en compte pour les API s’appliquant aux entités virtuelles
Il existe deux grandes catégories de modifications du système de métadonnées qui sont associées à l’introduction des entités virtuelles dans les applications Dynamics 365 for Customer Engagement version 9.0 :
- Ajout d’un nouvel assembly, d’espaces de noms, de classes et d’autres types pour prendre en charge le développement de fournisseurs personnalisés de données d’entités virtuelles
- Modifications de la plateforme principale, notamment quelques propriétés supplémentaires pour prendre en charge le mappage de la source de données externe, et modifications du comportement des propriétés d’entité et d’attribut existantes qui reflètent les limitations de l’implémentation initiale de cette fonctionnalité
Nouvel assembly du SDK des données Dynamics 365 Customer Engagement
L’assembly Kit de développement logiciel (SDK) des données Dynamics 365 Customer Engagement (on-premises), Microsoft.Xrm.Sdk.Data.dll, contient des types pour aider à la création de fournisseurs personnalisés de données d’entités virtuelles. Il est composé des espaces de noms suivants :
| Espace de noms | Description |
|---|---|
| Microsoft.Xrm.Sdk.Data | Espace de noms de base qui contient quelques types courants, comme l’énumération AllowedQueryOptions |
| Microsoft.Xrm.Sdk.Data.CodeGen | Contient les classes et interfaces qui prennent en charge la réflexion dynamique, la correspondance de type et la génération de code. Principalement utilisé par le moteur de fournisseur interne. |
| Microsoft.Xrm.Sdk.Data.Converters | Ensemble de classes pour convertir les types XRM standard en types fondamentaux .NET correspondants |
| Microsoft.Xrm.Sdk.Data.Exceptions | Ensemble de classes d’exception qui représentent les erreurs qui peuvent se produire lors de la résolution des valeurs au moment de l’exécution. Toutes sont dérivées de Microsoft.Xrm.Sdk.SdkExceptionBase. |
| Microsoft.Xrm.Sdk.Data.Expressions | Classes pour aider à l’implémentation des transformations de requête prises en charge, telles que FILTER, JOIN et ORDER. |
| Microsoft.Xrm.Sdk.Data.Infra | Quelques classes diverses qui prennent en charge le traitement central des requêtes. |
| Microsoft.Xrm.Sdk.Data.Mappings | Classes et interfaces qui créent le mappage des types de métadonnées d’entités virtuelles en types externes. |
| Microsoft.Xrm.Sdk.Data.Visitors | Classes qui implémentent le modèle de visiteur pour effectuer des opérations spécifiques sur le paramètre QueryExpression transmis au fournisseur de données pendant les requêtes RetrieveMultiple. Fournit une prise en charge spécifique de la requête générique et du traitement LINQ. Ces classes sont dérivées de Microsoft.Xrm.Sdk.Query.QueryExpressionVisitorBase. |
Cet assembly est distribué avec le Kit de développement logiciel (SDK) des données Dynamics 365 Customer Engagement (on-premises), qui est également disponible en tant que package NuGet.
Modifications de la plateforme principale
Les modifications suivantes des types de référence Dynamics 365 standard ont été introduites pour prendre en charge les entités virtuelles.
Nouveaux types d’API web
L’API Web Dynamics 365 Customer Engagement expose les fournisseurs et sources de données d’entités virtuelles comme les nouveaux types d’entités suivants : EntityDataProvider et EntityDataSource.
Nouvelles propriétés de métadonnées
Quatre nouvelles propriétés ont été ajoutées à la classe Microsoft.Xrm.Sdk.Metadata.EntityMetadata :
- DataProviderId - GUID qui identifie le fournisseur de données d’entité virtuelle associé
- DataSourceId - GUID qui identifie la source de données d’entité virtuelle associée
- ExternalName - Nom de ce type dans la source de données externe
- ExternalCollectionName - Nom pluriel de ce type, utilisé dans l’interface utilisateur et pour prendre en charge l’accès OData
Deux nouvelles propriétés ont été ajoutées à la classe Microsoft.Xrm.Sdk.Metadata.AttributeMetadata :
- ExternalName - Nom du type dans la source de données externe
- IsDataSourceSecret - Indique si le champ contient des informations confidentielles
La propriété ExternalName a également été ajoutée aux classes Option et OptionSetMetadata. Ces noms externes aident au mappage de la source de données externe, en spécifiant le nom du type associé à la source de données externe. Ces propriétés sont uniquement utilisées pour les entités virtuelles ; pour un type d’entité personnalisée intégrée ou standard, ces noms externes doivent avoir la valeur null.
Création d’une entité virtuelle
L’approche pour créer par programme un type d’entité virtuelle diffère légèrement de la création d’un type d’entité personnalisée standard :
- Si le fournisseur de données associé (et éventuellement la source de données) sont connus au moment de la création, ils sont spécifiés.
- Si le fournisseur de données pour ce type n’est pas connu, au minimum,
EntityMetadata.DataProviderIdest défini sur7015A531-CC0D-4537-B5F2-C882A1EB65AD, etEntityMetadata.DataSourceIdest défini surnull. Des valeurs appropriées doivent être attribuées à ces propriétés avant que les instances de ce type soient utilisées au moment de l’exécution.
Deux nouveaux types d’entités, EntityDataProvider et éventuellement EntityDataSource, sont créés lorsque vous enregistrez un plug-in, et leurs ID respectifs, entitydataproviderid et entitydatasourceid, représentent les GUID requis. (Sinon, les développeurs ont rarement besoin d’accéder directement à ces types personnalisés.) Notez que DataSource contient la propriété entitydataproviderid qui doit correspondre au type DataProvider correspondant, sinon une exception est levée au moment de l’exécution.
Avertissement
Les ID EntityMetadata.DataProviderId et EntityMetadata.DataSourceId des entités standard (non virtuelles) doivent être définis sur leurs valeurs par défaut (null), sinon une exception est levée au moment de l’exécution. Une fois créé, vous ne pouvez pas convertir un type non virtuel en type virtuel, ou inversement.
Modifications du comportement des propriétés de métadonnées d’entité
Le tableau suivant décrit comment le comportement des Propriétés EntityMetadata standard est modifié pour les entités virtuelles. Certaines propriétés ne sont pas valides pour les entités virtuelles, tandis que d’autres sont limitées en étendue ou valeur.
| Propriété de métadonnées | S’applique ? | Remarques |
|---|---|---|
| ActivityTypeMask | non valide | Toujours 0 |
| Attributs | valide | |
| AutoCreateAccessTeams | non valide | Toujours false |
| AutoRouteToOwnerQueue | non valide | Toujours false, les files d’attente ne sont pas prises en charge. |
| CanBeInManyToMany | valide | |
| CanBePrimaryEntityInRelationship | valide | |
| CanBeRelatedEntityInRelationship | valide | |
| CanChangeHierarchicalRelationship | non valide | Toujours false, les relations hiérarchiques ne sont pas prises en charge. |
| CanChangeTrackingBeEnabled | non valide | Toujours false, les valeurs de suivi des modifications et d’audit ne sont pas prises en charge. |
| CanCreateAttributes | valide | |
| CanCreateCharts | non valide | Toujours false |
| CanCreateForms | valide | |
| CanCreateViews | valide | |
| CanEnableSyncToExternalSearchIndex | non valide | Toujours false |
| CanModifyAdditionalSettings | valide | |
| CanTriggerWorkflow | non valide | Toujours false, les workflows ne peuvent pas être déclenchés. |
| ChangeTrackingEnabled | non valide | Toujours false |
| CollectionSchemaName | valide | |
| DaysSinceRecordLastModified | non valide | Toujours null ou 0 |
| Description | valide | |
| DisplayCollectionName | valide | |
| DisplayName | valide | |
| EnforceStateTransitions | non valide | StateCode et Status ne sont pas pris en charge. |
| EntityColor | valide | |
| EntityHelpUrl | valide | |
| EntityHelpUrlEnabled | valide | |
| EntitySetName | valide | |
| ExtensionData | non valide | Propriété déconseillée |
| HasChanged | valide | |
| IconLargeName | valide | |
| IconMediumName | valide | |
| IconSmallName | valide | |
| IntroducedVersion | valide | |
| IsActivity | non valide | Toujours false, les activités ne sont pas prises en charge. |
| IsActivityParty | non valide | Toujours false |
| IsAIRUpdated | non valide | Déconseillé |
| IsAuditEnabled | non valide | Toujours false, l’audit n’est pas pris en charge. |
| IsAvailableOffline | non valide | Toujours false, l’utilisation hors connexion n’est pas prise en charge. |
| IsBusinessProcessEnabled | non valide | Toujours false, les processus d’entreprise ne sont pas pris en charge. |
| IsChildEntity | non valide | Toujours false, toutes les entités virtuelles appartiennent à l’organisation. |
| IsConnectionsEnabled | valide | |
| IsCustomEntity | valide | |
| IsCustomizable | valide | |
| IsDocumentManagementEnabled | valide | |
| IsDocumentRecommendationsEnabled | non valide | Toujours false, cette nouvelle fonctionnalité n’est pas prise en charge. |
| IsDuplicateDetectionEnabled | non valide | Toujours false, mais la détection des doublons peut être effectuée sur la source de données. |
| IsEnabledForCharts | limité | Uniquement pour les clauses Fetch prises en charge. |
| IsEnabledForTrace | valide | |
| IsImportable | valide | |
| IsInteractionCentricEnabled | valide | |
| IsIntersect | valide | |
| IsKnowledgeManagementEnabled | non valide | Toujours false, l’intégration de la gestion des connaissances n’est pas prise en charge. |
| IsMailMergeEnabled | valide | |
| IsManaged | valide | |
| IsMappable | valide | |
| IsOfflineInMobileClient | non valide | Toujours false, les valeurs des entités virtuelles ne sont pas mises en cache pour l’utilisation hors connexion. |
| IsOneNoteIntegrationEnabled | valide | |
| IsOptimisticConcurrencyEnabled | non valide | Toujours false, la concurrence doit être implémentée dans la source de données. |
| IsPrivate | valide | |
| IsQuickCreateEnabled | valide | |
| IsReadOnlyInMobileClient | valide | |
| IsRenameable | valide | |
| IsSLAEnabled | non valide | Toujours false |
| IsStateModelAware | non valide | |
| IsValidForAdvancedFind | valide | |
| IsValidForQueue | valide | |
| IsVisibleInMobile | valide | |
| IsVisibleInMobileClient | valide | |
| Clés | non valide | Les clés secondaires ne sont pas prises en charge |
| LogicalCollectionName | valide | |
| LogicalName | valide | |
| ManyToManyRelationships | valide | |
| ManyToOneRelationships | valide | Non pris en charge entre deux entités virtuelles. |
| MetadataId | valide | |
| MobileOfflineFilters | non valide | Toujours false, l’utilisation hors connexion n’est pas prise en charge. |
| ObjectTypeCode | valide | |
| OneToManyRelationships | valide | |
| OwnershipType | non valide | Toujours OrganizationOwned |
| PrimaryIdAttribute | valide | |
| PrimaryImageAttribute | valide | |
| PrimaryNameAttribute | valide | |
| Privilèges | non valide | |
| RecurrenceBaseEntityLogicalName | non valide | |
| ReportViewName | non valide | |
| SchemaName | valide | |
| SyncToExternalSearchIndex | non valide | |
Modifications du comportement des propriétés de métadonnées d’attribut
Le tableau suivant explique comment le comportement des Propriétés AttributeMetadata standard est modifié pour les entités virtuelles. Certaines propriétés ne sont pas valides pour les entités virtuelles, tandis que d’autres sont limitées en étendue ou valeur.
| Propriété de métadonnées | S’applique ? | Remarques |
|---|---|---|
| ColumnNumber | non valide | |
| DeprecatedVersion | valide | |
| Description | valide | |
| DisplayName | valide | |
| EntityLogicalName | valide | |
| ExtensionData | non valide | |
| HasChanged | valide | |
| InheritsFrom | valide | |
| IntroducedVersion | valide | |
| IsAuditEnabled | non valide | Toujours false, l’audit n’est pas pris en charge. |
| IsCustomAttribute | valide | |
| IsCustomizable | valide | |
| IsFilterable | valide | |
| IsGlobalFilterEnabled | valide | |
| IsLogical | valide | |
| IsManaged | valide | |
| IsPrimaryId | valide | |
| IsPrimaryName | valide | |
| IsRenameable | valide | |
| IsSearchable | valide | |
| IsSecured | non valide | Toujours false, la sécurité au niveau des champs n’est pas prise en charge. |
| IsSortableEnabled | valide | |
| IsValidForAdvancedFind | valide | |
| IsValidForCreate | valide | |
| IsValidForRead | valide | |
| IsValidForUpdate | valide | |
| LinkedAttributeId | valide | |
| LogicalName | valide | |
| MetadataId | valide | |
| RequiredLevel | valide | |
| SchemaName | valide | |
| SourceType | non valide | Toujours 0, les valeurs calculées ou de cumul ne sont pas prises en charge. |