API considerations of virtual tables


Unsure about entity vs. table? See Developers: Understand terminology in Microsoft Dataverse.

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 to null. 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.


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