Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Two broad categories of changes to the table definition system are associated with the introduction of virtual tables (also known as virtual entities) in Microsoft Dataverse:
- Addition of a new assembly, namespaces, classes, and other types to support development of custom virtual table data providers
- Changes to the core platform, including a few other properties to support external data source mapping, and modification of behaviors of existing table and column properties that reflect the limitations of the initial implementation of this feature
Dynamics 365 Data SDK assembly
The Dynamics 365 Data SDK assembly, Microsoft.Xrm.Sdk.Data.dll, contains types to aid in the creation of custom virtual table data providers. It comprises the following namespaces:
| Namespace | Description |
|---|---|
| Microsoft.Xrm.Sdk.Data | Base namespace that contains a few common types, such as the AllowedQueryOptions enumeration |
| Microsoft.Xrm.Sdk.Data.CodeGen | Contains classes and interfaces that support dynamic reflection, type matching, and code generation. Mainly used by the internal provider engine. |
| Microsoft.Xrm.Sdk.Data.Converters | A set of classes to convert standard XRM types to their corresponding .NET fundamental types |
| Microsoft.Xrm.Sdk.Data.Exceptions | A set of exception classes that represent errors that can occur during runtime value resolution. All are derived from Microsoft.Xrm.Sdk.SdkExceptionBase. |
| Microsoft.Xrm.Sdk.Data.Expressions | Classes to help implementing the supported query transformations, such as FILTER, JOIN, and ORDER. |
| Microsoft.Xrm.Sdk.Data.Mappings | Classes and interfaces that build the mapping from virtual table definition types to external types. |
| Microsoft.Xrm.Sdk.Data.Visitors | Classes that implement the visitor pattern to perform specific operations on the QueryExpression parameter passed to the data provider during RetrieveMultiple requests. Provides specific support for both generic query and LINQ-baseed processing. These classes are derived from Microsoft.Xrm.Sdk.Query.QueryExpressionVisitorBase. |
Distribute this assembly as a NuGet package: Microsoft.CrmSdk.Data.
Changes to the core platform
The following changes to the standard Dataverse reference types support virtual tables.
New tables
Dataverse exposes virtual table data providers and sources as the following tables: EntityDataProvider and EntityDataSource.
New table definition properties
Four new properties were added to the EntityMetadata class:
| Property | Description |
|---|---|
| DataProviderId | GUID that identifies the associated virtual table data provider |
| DataSourceId | GUID that identifies the associated virtual table data source |
| ExternalName | Name for this type in the external data source |
| ExternalCollectionName | Plural name for this type, used in the UI and to support OData access |
Two new properties were added to the AttributeMetadata class:
| Property | Description |
|---|---|
| ExternalName | Name of the type in the external data source |
| IsDataSourceSecret | Indicates whether the field contains sensitive information |
The ExternalName property was also added to the OptionMetadata and OptionSetMetadata classes. These external names help the external data source mapping, by specifying the name of the associated type in the external data source. These properties are only used for virtual tables. For a built-in or standard custom entity type, these external names must be null.
Virtual table creation
The approach to programmatically creating a virtual table type differs slightly from a standard custom entity type creation in that:
- If you know the associated data provider (and optionally data source) at creation time, specify these values.
- If you don't know the data provider for this type, set DataProviderId to
7015A531-CC0D-4537-B5F2-C882A1EB65ADand set DataSourceId tonull. Before you use instances of this type at runtime, assign these properties appropriate values.
When you register a plugin, you create two new tables, EntityDataProvider and optionally EntityDataSource. Their respective IDs, entitydataproviderid and entitydatasourceid, represent these required GUIDs. (Otherwise, developers rarely need to access these custom types directly.) Note that DataSource contains the property entitydataproviderid that must match the corresponding DataProvider type or a runtime exception is thrown.
Warning
Standard (nonvirtual) tables must have the values of their associated DataProviderId and DataSourceId set to their default values (null), otherwise a runtime exception is thrown. Once created, you can't convert from a nonvirtual type to a virtual type, or the reverse.
Table definition property behavior changes
The following table details how the behavior of standard EntityMetadata properties changes when you apply them to virtual tables. Some properties aren't valid for virtual tables, whereas others are limited in scope or value.
| Metadata Property | Applies? | Notes |
|---|---|---|
| ActivityTypeMask | invalid | Always 0 |
| Attributes | valid | |
| AutoCreateAccessTeams | invalid | Always false |
| AutoRouteToOwnerQueue | invalid | Always false, queues aren't supported. |
| CanBeInManyToMany | valid | |
| CanBePrimaryEntityInRelationship | valid | |
| CanBeRelatedEntityInRelationship | valid | |
| CanChangeHierarchicalRelationship | invalid | Always false, hierarchical relationships aren't supported. |
| CanChangeTrackingBeEnabled | invalid | Always false, change tracking, and auditing values aren't supported. |
| CanCreateAttributes | valid | |
| CanCreateCharts | invalid | Always false |
| CanCreateForms | valid | |
| CanCreateViews | valid | |
| CanEnableSyncToExternalSearchIndex | invalid | Always false |
| CanModifyAdditionalSettings | valid | |
| CanTriggerWorkflow | invalid | Always false, workflows can't be triggered. |
| ChangeTrackingEnabled | invalid | Always false |
| CollectionSchemaName | valid | |
| DaysSinceRecordLastModified | invalid | Always null or 0 |
| Description | valid | |
| DisplayCollectionName | valid | |
| DisplayName | valid | |
| EnforceStateTransitions | invalid | StateCode and Status aren't supported. |
| EntityColor | valid | |
| EntityHelpUrl | valid | |
| EntityHelpUrlEnabled | valid | |
| EntitySetName | valid | |
| ExtensionData | invalid | Deprecated property |
| HasChanged | valid | |
| IconLargeName | valid | |
| IconMediumName | valid | |
| IconSmallName | valid | |
| IntroducedVersion | valid | |
| IsActivity | invalid | Always false, activities aren't supported. |
| IsActivityParty | invalid | Always false |
| IsAIRUpdated | invalid | Deprecated |
| IsAuditEnabled | invalid | Always false, auditing isn't supported. |
| IsAvailableOffline | invalid | Always false, offline use isn't supported. |
| IsBusinessProcessEnabled | invalid | Always false, business processes aren't supported. |
| IsChildEntity | invalid | Always false, all virtual tables are organizationally owned. |
| IsConnectionsEnabled | valid | |
| IsCustomEntity | valid | |
| IsCustomizable | valid | |
| IsDocumentManagementEnabled | valid | |
| IsDocumentRecommendationsEnabled | invalid | Always false, this new feature isn't supported. |
| IsDuplicateDetectionEnabled | invalid | Always false, but duplicate detection can be performed at the data source. |
| IsEnabledForCharts | limited | Only for supported Fetch clauses. |
| IsEnabledForTrace | valid | |
| IsImportable | valid | |
| IsInteractionCentricEnabled | valid | |
| IsIntersect | valid | |
| IsKnowledgeManagementEnabled | invalid | Always false, knowledge management integration isn't supported. |
| IsMailMergeEnabled | valid | |
| IsManaged | valid | |
| IsMappable | valid | |
| IsOfflineInMobileClient | invalid | Always false, virtual table values aren't cached for offline use. |
| IsOneNoteIntegrationEnabled | valid | |
| IsOptimisticConcurrencyEnabled | invalid | Always false, concurrency must be implemented in the data source. |
| IsPrivate | valid | |
| IsQuickCreateEnabled | valid | |
| IsReadOnlyInMobileClient | valid | |
| IsRenameable | valid | |
| IsSLAEnabled | invalid | Always false |
| IsStateModelAware | invalid | |
| IsValidForAdvancedFind | valid | |
| IsValidForQueue | valid | |
| IsVisibleInMobile | valid | |
| IsVisibleInMobileClient | valid | |
| Keys | invalid | Alternate keys aren't supported |
| LogicalCollectionName | valid | |
| LogicalName | valid | |
| ManyToManyRelationships | valid | |
| ManyToOneRelationships | valid | Not supported between two virtual tables. |
| MetadataId | valid | |
| MobileOfflineFilters | invalid | Always false, offline use isn't supported. |
| ObjectTypeCode | valid | |
| OneToManyRelationships | valid | |
| OwnershipType | invalid | Always OrganizationOwned |
| PrimaryIdAttribute | valid | |
| PrimaryImageAttribute | valid | |
| PrimaryNameAttribute | valid | |
| Privileges | invalid | |
| RecurrenceBaseEntityLogicalName | invalid | |
| ReportViewName | invalid | |
| SchemaName | valid | |
| SyncToExternalSearchIndex | invalid |
Column definition property behavior changes
The following table explains how the behavior of standard AttributeMetadata properties changes when you apply them to virtual tables. Some properties aren't valid for virtual tables, whereas others have limited scope or value.
| Metadata Property | Applies? | Notes |
|---|---|---|
| ColumnNumber | invalid | |
| DeprecatedVersion | valid | |
| Description | valid | |
| DisplayName | valid | |
| EntityLogicalName | valid | |
| ExtensionData | invalid | |
| HasChanged | valid | |
| InheritsFrom | valid | |
| IntroducedVersion | valid | |
| IsAuditEnabled | invalid | Always false, auditing isn't supported. |
| IsCustomAttribute | valid | |
| IsCustomizable | valid | |
| IsFilterable | valid | |
| IsGlobalFilterEnabled | valid | |
| IsLogical | valid | |
| IsManaged | valid | |
| IsPrimaryId | valid | |
| IsPrimaryName | valid | |
| IsRenameable | valid | |
| IsSearchable | valid | |
| IsSecured | invalid | Always false, field-level security isn't supported. |
| IsSortableEnabled | valid | |
| IsValidForAdvancedFind | valid | |
| IsValidForCreate | valid | |
| IsValidForRead | valid | |
| IsValidForUpdate | valid | |
| LinkedAttributeId | valid | |
| LogicalName | valid | |
| MetadataId | valid | |
| RequiredLevel | valid | |
| SchemaName | valid | |
| SourceType | invalid | Always 0, calculated or rollup values aren't supported. |
See also
Get started with virtual entities
Custom virtual table data providers
Sample: Generic virtual table data provider plug-in