Compartir a través de


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.DataProviderId se establece en 7015A531-CC0D-4537-B5F2-C882A1EB65AD y EntityMetadata.DataSourceId se establece en null. 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.