虚拟表的 API 注意事项

表定义系统有两大类别的更改,这些更改与 Microsoft Dataverse 中虚拟表(也称为虚拟实体)的引入相关联:

  • 添加了新的程序集、命名空间、类和其他类型以支持开发自定义虚拟表数据提供程序
  • 对核心平台的更改,包括支持外部数据源映射的一些附加属性,以及修改现有表和列属性的行为,这些行为反映了此功能初始实现的限制

Dynamics 365 Data SDK 程序集

Dynamics 365 Data SDK 程序集 Microsoft.Xrm.Sdk.Data.dll包含有助于创建自定义虚拟表数据提供程序的类型。 它由以下命名空间组成:

Namespace Description
Microsoft.Xrm.Sdk.Data 包含一些常见类型的基本命名空间,如 AllowedQueryOptions 枚举
Microsoft.Xrm.Sdk.Data.CodeGen 包含支持动态反射、类型匹配和代码生成的类和接口。 主要用于内部提供程序引擎。
Microsoft.Xrm.Sdk.Data.Converters 一组类,用于将标准 XRM 类型转换为其相应的 .NET 基本类型
Microsoft.Xrm.Sdk.Data.Exceptions 一组异常类,表示在运行时值解析过程中可能发生的错误。 全部派生自 Microsoft.Xrm.Sdk.SdkExceptionBase。
Microsoft.Xrm.Sdk.Data.Expressions 帮助实现支持的查询转换的类,如 FILTER、JOIN 和 ORDER。
Microsoft.Xrm.Sdk.Data.Mappings 生成从虚拟表定义类型到外部类型的映射的类和接口。
Microsoft.Xrm.Sdk.Data.Visitors 实现访问者模式的类,目的是在 RetrieveMultiple 请求期间对传递给数据提供程序的 QueryExpression 参数执行特定操作。 提供对通用查询和基于 LINQ 的处理的特定支持。 这些类派生自 Microsoft.Xrm.Sdk.Query.QueryExpressionVisitorBase。

此程序集作为 NuGet 包分发: Microsoft.CrmSdk.Data

核心平台更改

引入了对标准 Dataverse 引用类型的以下更改以支持虚拟表。

新表

Dataverse 以以下表格式公开虚拟表数据提供程序和来源:EntityDataProviderEntityDataSource

新的表定义属性

向类添加了 EntityMetadata 四个新属性:

资产 Description
DataProviderId 标识关联的虚拟表数据提供程序的 GUID
DataSourceId 标识关联的虚拟表数据源的 GUID
ExternalName 外部数据源中该类型的名称
ExternalCollectionName 此类型的复数名称,用于用户界面及支持 OData 访问

向类添加了 AttributeMetadata 两个新属性:

资产 Description
ExternalName 外部数据源中类型的名称
IsDataSourceSecret 指示字段是否包含敏感信息

ExternalName 属性也已添加到 OptionMetadataOptionSetMetadata 类。 这些外部名称通过指定外部数据源中相关类型的名称来实现外部数据源的映射。 这些属性仅用于虚拟表;对于内置或标准自定义实体类型,这些外部名称必须是 null

虚拟表创建

以编程方式创建虚拟表类型的方法与在其中创建标准自定义实体类型的方法略有不同:

  • 如果在创建时已知关联的数据提供程序(以及数据源(可选)),将指定这些提供程序。
  • 如果此类型的数据提供程序未知,至少会将 DataProviderId 设置为 7015A531-CC0D-4537-B5F2-C882A1EB65AD,将 DataSourceId 设置为 null。 在运行时使用此类型的实例之前,必须为这些属性分配适当的值。

当你注册一个插件时,将会创建两个新表 EntityDataProvider 和(EntityDataSource,可选),它们各自的 ID,如 entitydataprovideridentitydatasourceid,表示这些必需的 GUID。 (否则,开发人员很少需要直接访问这些自定义类型。请注意,DataSource 包含 entitydataproviderid 必须与相应的 DataProvider 类型匹配的属性,否则将引发运行时异常。

警告

标准(非虚拟)表必须具有其关联的 DataProviderId 值并将其 DataSourceId 设置为默认值(null),否则将引发运行时异常。 创建后,将无法从非虚拟类型转换为虚拟类型或反向转换。

表定义属性行为更改

下表详细介绍了在应用于虚拟表时如何修改标准 EntityMetadata 属性 的行为。 某些属性对虚拟表无效,而其他属性在范围或值中受到限制。

元数据属性 适用? 备注
ActivityTypeMask 无效 始终为 0
特性 有效的
AutoCreateAccessTeams 无效 始终为 false
AutoRouteToOwnerQueue 无效 始终为 false,不支持队列。
CanBeInManyToMany 有效的
可以作为关系中的主要实体 有效的
CanBeRelatedEntityInRelationship 有效的
CanChangeHierarchicalRelationship 无效 始终为 false,不支持分层关系。
CanChangeTrackingBeEnabled 无效 始终为 false,不支持更改跟踪和审核值。
可以创建属性 有效的
可以创建图表 无效 始终为 false
CanCreateForms 有效的
可以创建视图 有效的
CanEnableSyncToExternalSearchIndex 无效 始终为 false
可以修改额外设置 有效的
CanTriggerWorkflow 无效 始终为 false,无法触发工作流。
ChangeTrackingEnabled 无效 始终为 false
CollectionSchemaName 有效的
DaysSinceRecordLastModified 无效 始终为 null 或 0
Description 有效的
DisplayCollectionName 有效的
DisplayName 有效的
EnforceStateTransitions 无效 不支持 StateCode 和 Status。
EntityColor 有效的
EntityHelpUrl 有效的
EntityHelpUrlEnabled 有效的
EntitySetName 有效的
ExtensionData 无效 已弃用属性
HasChanged 有效的
IconLargeName 有效的
IconMediumName 有效的
IconSmallName 有效的
IntroducedVersion 有效的
IsActivity 无效 始终为 false,不支持活动。
IsActivityParty 无效 始终为 false
IsAIRUpdated 无效 Deprecated
IsAuditEnabled 无效 始终为 false,不支持审核。
IsAvailableOffline 无效 始终为 false,不支持脱机使用。
IsBusinessProcessEnabled 无效 始终为 false,不支持业务流程。
IsChildEntity 无效 始终为 false,所有虚拟表均由组织拥有。
IsConnectionsEnabled 有效的
IsCustomEntity 有效的
IsCustomizable 有效的
IsDocumentManagementEnabled 有效的
IsDocumentRecommendationsEnabled 无效 始终为 false,不支持此新功能。
IsDuplicateDetectionEnabled 无效 始终为 false,但可以对数据源执行重复检测。
IsEnabledForCharts 有限 仅适用于支持的 Fetch 子句。
IsEnabledForTrace 有效的
IsImportable 有效的
IsInteractionCentricEnabled 有效的
IsIntersect 有效的
IsKnowledgeManagementEnabled 无效 始终为 false,不支持知识管理集成。
IsMailMergeEnabled 有效的
IsManaged 有效的
IsMappable 有效的
IsOfflineInMobileClient 无效 始终为 false,虚拟表值不会被缓存用于脱机使用。
IsOneNoteIntegrationEnabled 有效的
IsOptimisticConcurrencyEnabled 无效 始终为 false,必须在数据源中实现并发。
IsPrivate 有效的
IsQuickCreateEnabled 有效的
IsReadOnlyInMobileClient 有效的
IsRenameable 有效的
IsSLAEnabled 无效 始终为 false
IsStateModelAware 无效
IsValidForAdvancedFind 有效的
IsValidForQueue 有效的
IsVisibleInMobile 有效的
IsVisibleInMobileClient 有效的
Keys 无效 不支持备用键
LogicalCollectionName 有效的
LogicalName 有效的
ManyToManyRelationships 有效的
ManyToOneRelationships 有效的 不支持两个虚拟表之间的操作。
MetadataId 有效的
MobileOfflineFilters 无效 始终为 false,不支持脱机使用。
ObjectTypeCode 有效的
OneToManyRelationships 有效的
OwnershipType 无效 始终 OrganizationOwned
PrimaryIdAttribute 有效的
PrimaryImageAttribute 有效的
PrimaryNameAttribute 有效的
特权 无效
RecurrenceBaseEntityLogicalName 无效
ReportViewName 无效
SchemaName 有效的
SyncToExternalSearchIndex 无效

列定义属性行为更改

下表说明在应用于虚拟表时如何修改标准 AttributeMetadata 属性 的行为。 某些属性对虚拟表无效,而其他属性在范围或值中受到限制。

元数据属性 适用? 备注
ColumnNumber 无效
DeprecatedVersion 有效的
Description 有效的
DisplayName 有效的
EntityLogicalName 有效的
ExtensionData 无效
HasChanged 有效的
InheritsFrom 有效的
IntroducedVersion 有效的
IsAuditEnabled 无效 始终为 false,不支持审核。
IsCustomAttribute 有效的
IsCustomizable 有效的
IsFilterable 有效的
IsGlobalFilterEnabled 有效的
IsLogical 有效的
IsManaged 有效的
IsPrimaryId 有效的
IsPrimaryName 有效的
IsRenameable 有效的
IsSearchable 有效的
IsSecured 无效 始终为 false,不支持字段级安全性。
IsSortableEnabled 有效的
IsValidForAdvancedFind 有效的
IsValidForCreate 有效的
IsValidForRead 有效的
IsValidForUpdate 有效的
LinkedAttributeId 有效的
LogicalName 有效的
MetadataId 有效的
RequiredLevel 有效的
SchemaName 有效的
来源类型 无效 始终为 0,不支持计算或汇总值。

另请参阅

虚拟实体入门
自定义虚拟表数据提供程序
示例:通用虚拟表数据提供程序插件