通过使用 Microsoft Dataverse 数据 SDK,.NET开发人员可以创建自定义虚拟表数据提供程序,以帮助集成现有数据提供程序不支持的外部数据源类型。 每个数据提供程序都由一组可重用的 Dataverse 插件组成,这些插件实现支持的 CRUD 操作。 对于每个虚拟表(也称为虚拟实体),开发人员都可以创建插件,并针对 创建、更新、检索、检索多个 和 删除 这些操作分别注册这些插件。 本部分提供有关数据提供程序和开发自定义提供程序的方法的基本信息,包括示例代码。
注释
与其创建自定义数据源提供程序,不如考虑使您的数据源适配现有的数据提供程序。 例如,如果创建外部数据源的 OData v4 接口,则可以使用提供的标准 OData v4 Data Provider(支持 CRUD 操作)直接访问它。 添加此 REST 接口的机制因基础数据服务技术而异。 例如,请参阅 WCF Data Services 4.5。 OData 具有广泛的行业支持,提供广泛的专用工具和兼容技术。
先决条件
自定义数据提供程序需要大量的开发资源来创建和维护。 您必须具备以下方面的基础知识:
- 外部数据源架构和关联的数据访问技术。 此域知识特定于外部数据源类型。
- Dataverse 定义模式:更多信息:通过代码操作表和列定义。
- Dataverse 事件框架:详细信息: 事件框架。
- Dataverse 插件体系结构和开发:详细信息: 使用插件扩展业务流程。
该 Microsoft.Xrm.Sdk.Data.dll 程序集以 NuGet 包的形式提供: Microsoft.CrmSdk.Data
提供程序类别
可以使用虚拟表数据 SDK 程序集创建两个常规类别的数据提供程序:泛型或目标。 下表描述了这些方法,并将其与最适合每种方法的数据提供程序开发模型匹配。
| 类别 | 开发模型 | 说明 |
|---|---|---|
| 常规 | “裸机”提供程序 | 这些提供程序灵活地将 FetchXML 查询表达式转换为与外部数据源关联的请求,然后返回生成的记录。 您可以将此类提供程序复用于此数据源类型的所有实例。 这种方法最通用,但开发起来更为复杂。 如果数据源的架构发生更改,则只需重新映射受影响的虚拟表。 |
| 目标 | 已知架构的 LINQ 提供程序 | 此类提供程序仅将查询转换为针对已知现有数据源实例的相应 LINQ 调用。 数据源必须是 LINQ 提供程序,具体请参阅文章启用数据源以进行 LINQ 查询。 此方法仅限于特定的数据源实例,但需要的编码工作要少得多。 如果数据源的架构发生更改,则必须更新和重新生成数据提供程序。 |
标准 OData v4 数据提供程序和 Azure Cosmos DB 数据提供程序是泛型提供程序的示例。
使用自定义数据提供程序的步骤
若要创建可导入 Dataverse 应用程序的虚拟表数据提供程序解决方案,请完成以下步骤:
- 开发自定义数据提供程序插件 DLL 或 DLL 集。
- 使用插件注册工具(PRT)将自定义数据提供程序注册到 Dataverse 服务。
- 创建数据提供程序解决方案。
- 自定义数据源表以反映数据类型或特定实例。
- 导出自定义数据提供程序解决方案。
有关详细信息,请参阅 示例:使用 CRUD 操作的自定义虚拟表提供程序。
插件开发
由于虚拟表支持 CRUD 操作,因此请将数据提供程序编写为一个插件,并将其注册到 Create、Update、Retrieve、RetrieveMultiple 和 Delete 事件上。 每个事件都包含在执行上下文中描述要返回的数据类型的信息。
| Event | 执行上下文 |
|---|---|
| 取回 | 描述需检索的表、列及相关关联表。 |
| RetrieveMultiple | 包含定义 QueryExpression 查询的对象。 框架包含 QueryExpressionVisitor 类,用于在检查查询表达式树的不同部分。 |
对于这两个事件,您必须:
- 将执行上下文中的相应信息转换为适用于外部数据源的查询。
- 从外部系统检索数据。
- 对于 Retrieve,请将数据转换为 Entity;否则,对于 RetrieveMultiple,将其转换为 EntityCollection。 Dataverse 通过执行查询的用户返回此结果。
命名空间中的 Microsoft.Xrm.Sdk.Data 类提供一个框架,以帮助将 Dataverse 查询信息从执行上下文映射到适合外部数据源的格式的查询。 此框架可帮助你将返回的数据转换为 Dataverse 平台所需的适当 Entity 或 EntityCollection 类型。
数据提供程序异常
如果代码无法实现预期结果,请抛出相应的错误。 命名空间 Microsoft.Xrm.Sdk.Data.Exceptions 包含以下派生自 SdkExceptionBase的异常类,可用于此目的:
| 异常类 | 说明 |
|---|---|
| AuthenticationException | 对外部数据源服务进行安全身份验证期间出错;例如,从外部数据服务接收的 HTTP 状态 401。 通常,因为当前用户没有适当的权限,或者关联的 EntityDataSource 中的连接信息不正确。 |
| EndpointException | 数据源表中的终结点配置无效或终结点不存在。 |
| GenericDataAccessException | 一种通用的数据访问错误,当该错误无法映射到更具体的异常时使用。 |
| InvalidMetadataException | |
| InvalidQueryException | 指定的查询无效;例如,它包含无效的子句组合或不支持的比较运算符。 |
| ObjectNotFoundException | 外部数据源中的指定记录不存在。 |
| TimeoutException | 外部操作未在允许的时间内完成;例如,来自外部数据服务的 HTTP 状态 408 的结果。 |
插件注册
与普通插件不同,请使用插件注册工具(PRT)为每个事件注册程序集和插件。 不要注册特定步骤。 插件在第 30 阶段运行,这是该操作的主要核心事务处理阶段,普通插件步骤无法使用该阶段。 请使用下表配置数据提供程序,而不是注册步骤。
| 表 | 说明 |
|---|---|
| EntityDataProvider | 定义要用于每个事件的插件和数据源的逻辑名称。 |
配置虚拟表的定义时,请使用 PRT 注册插件,并在 EntityDataProvider 表中设置正确的配置数据。 虚拟表开始响应请求。
有关详细信息,请参阅 创建数据提供程序并将插件添加到提供程序。
调试插件
自定义虚拟表提供程序是一种插件。 使用这些文章中的信息来调试自定义虚拟表提供程序的插件: 调试插件 和 教程:调试插件。