Consideraciones sobre API para entidades virtuales
Hay dos grandes categorías de cambios en el sistema de metadatos que están asociadas con la introducción de entidades virtuales en aplicaciones de Dynamics 365 for Customer Engagement, versión 9.0:
- Adición de un nuevo ensamblado, espacios de nombres, clases y otros tipos para admitir el desarrollo de proveedores de datos de entidad virtuales personalizados
- Cambios a la plataforma principal, incluidas algunas propiedades adicionales para admitir la asignación de origen de datos externos y modificación de comportamientos de propiedades de entidad y atributo existentes que reflejan las limitaciones de la implementación inicial de esta característica
Nuevo ensamblado de SDK de datos Dynamics 365 Customer Engagement
El ensamblado de SDK de datos de Dynamics 365 Customer Engagement (on-premises), Microsoft.Xrm.Sdk.Data.dll, contiene tipos que le ayudarán en la creación de proveedores de datos de entidad virtuales personalizados. Consta de los siguientes espacios de nombres:
| Espacio de nombres | Descripción |
|---|---|
| Microsoft.Xrm.Sdk.Data | Espacio de nombres base que contiene algunos tipos comunes, como la enumeración AllowedQueryOptions |
| Microsoft.Xrm.Sdk.Data.CodeGen | Contiene clases e interfaces que admiten reflexión dinámica, correspondencia de tipos y generación de código. Utilizado principalmente por el motor del proveedor interno. |
| Microsoft.Xrm.Sdk.Data.Converters | Un conjunto de clases para convertir a tipos XRM estándar a sus correspondientes tipos fundamentales de .NET |
| Microsoft.Xrm.Sdk.Data.Exceptions | Un conjunto de clases de excepciones que representan errores que se pueden producir durante la resolución del valor de ejecución. Todos se derivan de Microsoft.Xrm.Sdk.SdkExceptionBase. |
| Microsoft.Xrm.Sdk.Data.Expressions | Clases para ayudar en la implementación de las transformaciones de consultas admitidas como FILTER, JOIN y ORDER. |
| Microsoft.Xrm.Sdk.Data.Infra | Algunas clases diferentes que admiten el procesamiento de consultas central. |
| Microsoft.Xrm.Sdk.Data.Mappings | Clases e interfaces que crean la asignación de tipos de metadatos de entidades virtuales a tipos externos. |
| Microsoft.Xrm.Sdk.Data.Visitors | Clases que implementan el patrón de visitantes para realizar operaciones específicas en el parámetro QueryExpression que se pasa al proveedor de datos durante las solicitudes RetrieveMultiple. Proporciona compatibilidad específica tanto para consulta genérica como para procesamiento basado en LINQ. Estas clases se derivan de Microsoft.Xrm.Sdk.Query.QueryExpressionVisitorBase. |
Este ensamblado se distribuye con el SDK de datos de Dynamics 365 Customer Engagement (on-premises), que también está disponible como paquete NuGet.
Cambios en la plataforma principal
Los siguientes cambios a los tipos de referencia de Dynamics 365 estándar se introdujeron para poder admitir entidades virtuales.
Nuevos tipos de API web
La API web de Dynamics 365 Customer Engagement expone orígenes y proveedores de datos de entidad virtuales como los siguientes nuevos tipos de entidad: EntityDataProvider y EntityDataSource.
Nuevas propiedades de metadatos
Se han agregado cuatro propiedades nuevas a la clase Microsoft.Xrm.Sdk.Metadata.EntityMetadata:
- DataProviderId: GUID que identifica el proveedor de datos de entidad virtual asociado.
- DataSourceId: GUID que identifica el origen de datos de entidad virtual asociado.
- ExternalName: nombre de este tipo en el origen de datos externo
- ExternalCollectionName: nombre plural para este tipo, que se usa en la interfaz de usuario y para admitir el acceso a OData
Se han agregado dos propiedades nuevas a la clase Microsoft.Xrm.Sdk.Metadata.AttributeMetadata:
- ExternalName: nombre del tipo en el origen de datos externo
- IsDataSourceSecret: indica si el campo contiene información confidencial
La propiedad ExternalName también se ha agregado a las clases Option y OptionSetMetadata. Estos nombres externos ayudan en la asignación de orígenes de datos externos, mediante la especificación del nombre del tipo asociado en el origen de datos externos. Estas propiedades solo se usan para entidades virtuales; para un tipo de entidad personalizada estándar o integrada, estos nombres externos deben ser null.
Creación de una entidad virtual
El método para crear mediante programación un tipo de entidad virtual difiere ligeramente de la creación de un tipo de entidad personalizada estándar en que:
- Si el proveedor de datos asociados (y, opcionalmente, el origen de datos) se conoce en el momento de la creación, entonces se debe especificar.
- Si no se conoce el proveedor de datos para este tipo, entonces, como mínimo,
EntityMetadata.DataProviderIdse establece en7015A531-CC0D-4537-B5F2-C882A1EB65ADyEntityMetadata.DataSourceIdse establece ennull. Antes de que las instancias de este tipo se usen en tiempo de ejecución, se deben asignar valores adecuados a estas propiedades.
Se crearán dos tipos de entidad nuevos, EntityDataProvider y opcionalmente EntityDataSource, al registrar un complemento y sus respectivos ID, entitydataproviderid y entitydatasourceid, representan estos GUID necesarios. (De lo contrario, los desarrolladores rara vez necesitan obtener acceso a estos tipos personalizados directamente). Tenga en cuenta que DataSource contiene la propiedad entitydataproviderid que debe coincidir con el tipo DataProvider correspondiente o se iniciará un excepción de tiempo de ejecución.
Advertencia
Las entidades (no virtuales) estándar deben tener los valores de sus entidades asociadas EntityMetadata.DataProviderId y EntityMetadata.DataSourceId establecidos en los valores predeterminados (null), de lo contrario se producirá una excepción de tiempo de ejecución. Una vez creado, no puede convertir un tipo no virtual en un tipo virtual, ni viceversa.
Cambios de comportamiento de las propiedades de metadatos de entidades
La tabla siguiente muestra cómo se modifica el comportamiento de las propiedades de EntityMetadata estándar cuando se aplican a entidades virtuales. Algunas propiedades no son válidas para entidades virtuales, mientras que otras están limitadas en el ámbito o el valor.
| Propiedad de metadatos | ¿Se aplica? | Notas |
|---|---|---|
| ActivityTypeMask | no válido | Siempre 0 |
| Atributos | válido | |
| AutoCreateAccessTeams | no válido | Siempre false |
| AutoRouteToOwnerQueue | no válido | Siempre false, no se admiten las colas. |
| CanBeInManyToMany | válido | |
| CanBePrimaryEntityInRelationship | válido | |
| CanBeRelatedEntityInRelationship | válido | |
| CanChangeHierarchicalRelationship | no válido | Siempre false, no se admiten relaciones jerárquicas. |
| CanChangeTrackingBeEnabled | no válido | Siempre false, no se admiten valores de auditoría y seguimiento de cambios. |
| CanCreateAttributes | válido | |
| CanCreateCharts | no válido | Siempre false |
| CanCreateForms | válido | |
| CanCreateViews | válido | |
| CanEnableSyncToExternalSearchIndex | no válido | Siempre false |
| CanModifyAdditionalSettings | válido | |
| CanTriggerWorkflow | no válido | Siempre false, no se pueden desencadenar flujos de trabajo. |
| ChangeTrackingEnabled | no válido | Siempre false |
| CollectionSchemaName | válido | |
| DaysSinceRecordLastModified | no válido | Siempre nulo o 0 |
| Descripción | válido | |
| DisplayCollectionName | válido | |
| DisplayName | válido | |
| EnforceStateTransitions | no válido | No se admiten StateCode y Status. |
| EntityColor | válido | |
| EntityHelpUrl | válido | |
| EntityHelpUrlEnabled | válido | |
| EntitySetName | válido | |
| ExtensionData | no válido | Propiedad obsoleta |
| HasChanged | válido | |
| IconLargeName | válido | |
| IconMediumName | válido | |
| IconSmallName | válido | |
| IntroducedVersion | válido | |
| IsActivity | no válido | Siempre false, no se admiten actividades. |
| IsActivityParty | no válido | Siempre false |
| IsAIRUpdated | no válido | Obsoleto |
| IsAuditEnabled | no válido | Siempre false, no se admite la auditoría. |
| IsAvailableOffline | no válido | Siempre false, no se admite el uso sin conexión. |
| IsBusinessProcessEnabled | no válido | Siempre false, no se admiten procesos de negocio. |
| IsChildEntity | no válido | Siempre false, todas las entidades virtuales son propiedad de la organización. |
| IsConnectionsEnabled | válido | |
| IsCustomEntity | válido | |
| IsCustomizable | válido | |
| IsDocumentManagementEnabled | válido | |
| IsDocumentRecommendationsEnabled | no válido | Siempre false, no se admite esta característica nueva. |
| IsDuplicateDetectionEnabled | no válido | Siempre false, pero la detección de duplicados se puede realizar en el origen de datos. |
| IsEnabledForCharts | limitado | Solo para cláusulas de Fetch admitidas. |
| IsEnabledForTrace | válido | |
| IsImportable | válido | |
| IsInteractionCentricEnabled | válido | |
| IsIntersect | válido | |
| IsKnowledgeManagementEnabled | no válido | Siempre false, no se admite la integración de la administración del conocimiento. |
| IsMailMergeEnabled | válido | |
| IsManaged | válido | |
| IsMappable | válido | |
| IsOfflineInMobileClient | no válido | Siempre false, los valores de la entidad virtual no se almacenan en caché para su uso sin conexión. |
| IsOneNoteIntegrationEnabled | válido | |
| IsOptimisticConcurrencyEnabled | no válido | Siempre false, la simultaneidad se debe implementar en el origen de datos. |
| IsPrivate | válido | |
| IsQuickCreateEnabled | válido | |
| IsReadOnlyInMobileClient | válido | |
| IsRenameable | válido | |
| IsSLAEnabled | no válido | Siempre false |
| IsStateModelAware | no válido | |
| IsValidForAdvancedFind | válido | |
| IsValidForQueue | válido | |
| IsVisibleInMobile | válido | |
| IsVisibleInMobileClient | válido | |
| Claves | no válido | No se admiten claves alternativas. |
| LogicalCollectionName | válido | |
| LogicalName | válido | |
| ManyToManyRelationships | válido | |
| ManyToOneRelationships | válido | No se admite entre dos entidades virtuales. |
| MetadataId | válido | |
| MobileOfflineFilters | no válido | Siempre false, no se admite el uso sin conexión. |
| CódigoDeTipoDeObjeto | válido | |
| OneToManyRelationships | válido | |
| OwnershipType | no válido | Siempre OrganizationOwned |
| PrimaryIdAttribute | válido | |
| PrimaryImageAttribute | válido | |
| PrimaryNameAttribute | válido | |
| Privilegios | no válido | |
| RecurrenceBaseEntityLogicalName | no válido | |
| ReportViewName | no válido | |
| SchemaName | válido | |
| SyncToExternalSearchIndex | no válido | |
Cambios de comportamiento de las propiedades de metadatos de atributos
La tabla siguiente explica cómo se modifica el comportamiento de las propiedades de AttributeMetadata estándar cuando se aplican a entidades virtuales. Algunas propiedades no son válidas para entidades virtuales, mientras que otras están limitadas en el ámbito o el valor.
| Propiedad de metadatos | ¿Se aplica? | Notas |
|---|---|---|
| ColumnNumber | no válido | |
| DeprecatedVersion | válido | |
| Descripción | válido | |
| DisplayName | válido | |
| EntityLogicalName | válido | |
| ExtensionData | no válido | |
| HasChanged | válido | |
| InheritsFrom | válido | |
| IntroducedVersion | válido | |
| IsAuditEnabled | no válido | Siempre false, no se admite la auditoría. |
| IsCustomAttribute | válido | |
| IsCustomizable | válido | |
| IsFilterable | válido | |
| IsGlobalFilterEnabled | válido | |
| IsLogical | válido | |
| IsManaged | válido | |
| IsPrimaryId | válido | |
| IsPrimaryName | válido | |
| IsRenameable | válido | |
| IsSearchable | válido | |
| IsSecured | no válido | Siempre false, no se admite la seguridad de nivel de campo. |
| IsSortableEnabled | válido | |
| IsValidForAdvancedFind | válido | |
| IsValidForCreate | válido | |
| IsValidForRead | válido | |
| IsValidForUpdate | válido | |
| LinkedAttributeId | válido | |
| LogicalName | válido | |
| MetadataId | válido | |
| RequiredLevel | válido | |
| SchemaName | válido | |
| SourceType | no válido | Siempre 0, no se admiten valores calculados o de resumen. |