API considerations of virtual tables
There are two broad categories of changes to the table definition system that 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 additional 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 is comprised of 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 assist in 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. |
This assembly is distributed as a NuGet package: Microsoft.CrmSdk.Data
Changes to the core platform
The following changes to the standard Dataverse reference types were introduced to support virtual tables.
New tables
The 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 assist in 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 builtin 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 the associated data provider (and optionally data source) is known at creation time, then these are specified.
- If the data provider for this type is not known, then at minimum, DataProviderId is set to
7015A531-CC0D-4537-B5F2-C882A1EB65AD, and the DataSourceId is set tonull. Before instances of this type are used at runtime, these properties must be assigned appropriate values.
Two new tables, EntityDataProvider and optionally EntityDataSource, will be created when you register a plugin, and their respective ID's, 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 will be thrown.
Warning
Standard (non-virtual) tables must have the values of their associated DataProviderId and DataSourceId set to their default values (null), otherwise a runtime exception will be thrown. Once created, you cannot convert from a non-virtual type to a virtual type, or the reverse.
Table definition property behavior changes
The following table details how the behavior of standard EntityMetadata properties are modified when applied to virtual tables. Some properties are not 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 are not supported. |
| CanBeInManyToMany | valid | |
| CanBePrimaryEntityInRelationship | valid | |
| CanBeRelatedEntityInRelationship | valid | |
| CanChangeHierarchicalRelationship | invalid | Always false, hierarchical relationships are not supported. |
| CanChangeTrackingBeEnabled | invalid | Always false, change tracking and auditing values are not supported. |
| CanCreateAttributes | valid | |
| CanCreateCharts | invalid | Always false |
| CanCreateForms | valid | |
| CanCreateViews | valid | |
| CanEnableSyncToExternalSearchIndex | invalid | Always false |
| CanModifyAdditionalSettings | valid | |
| CanTriggerWorkflow | invalid | Always false, workflows cannot 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 are not 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 are not supported. |
| IsActivityParty | invalid | Always false |
| IsAIRUpdated | invalid | Deprecated |
| IsAuditEnabled | invalid | Always false, auditing is not supported. |
| IsAvailableOffline | invalid | Always false, offline use is not supported. |
| IsBusinessProcessEnabled | invalid | Always false, business processes are not 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 is not 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 is not supported. |
| IsMailMergeEnabled | valid | |
| IsManaged | valid | |
| IsMappable | valid | |
| IsOfflineInMobileClient | invalid | Always false, virtual table values are not 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 are not supported |
| LogicalCollectionName | valid | |
| LogicalName | valid | |
| ManyToManyRelationships | valid | |
| ManyToOneRelationships | valid | Not supported between two virtual tables. |
| MetadataId | valid | |
| MobileOfflineFilters | invalid | Always false, offline use is not 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 are modified when applied to virtual tables. Some properties are not valid for virtual tables, whereas others are limited in 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 is not 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 is not 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 not supported. |
See also
Get started with virtual entities
Custom virtual table data providers
Sample: Generic virtual table data provider plug-in