目录表与 CatalogAssignment 表

使用 Catalog 和 CatalogAssignment 表创建结构,将解决方案中使用的操作作为业务事件公开。 Microsoft Dataverse 业务事件支持多种场景,可通过 Dataverse 与其他应用程序建立集成。 详细信息: Microsoft Dataverse 业务事件

您的目录将描述与您的解决方案相关的事件,以便用户能够使用它们。 如果不对与解决方案相关的事件进行编录,则这些事件对使用该解决方案的人员可能不可用。

使用 Catalog 表创建两个级别层次结构。 这将创建一个 目录 和 类别 组,其中第二级目录表示类别。

第一级目录必须代表您的解决方案。 使用与第一级目录相关的多个二级目录对解决方案中的不同功能类别进行分组。

对于表示解决方案中的类别的每个二级分类目录,你将使用该 CatalogAssignment 表来指定要作为事件提供的任何表、自定义 API 或自定义流程操作。

Important

具有 Environment Maker 安全角色的用户可以在 Power Automate Dataverse 连接器的 When an action is performed 触发器中查看目录数据。 其他安全角色必须对这些表具有适当的访问级别 读取 权限: 自定义 API、 进程、 SDK 消息。

详细信息:

示例:Contoso 客户管理

若要介绍目录的概念,让我们从一个示例开始。

Contoso 客户管理解决方案包含许多组件。 此处唯一相关的组件是:

  • Tables
  • 自定义 API
  • 自定义流程操作(工作流)

Tables

Contoso 客户管理是包含以下表的解决方案:

SchemaName 显示名称 Description
Account 客户 Dataverse 系统表
Contact 联系人 Dataverse 系统表
contoso_Membership Membership 自定义组织拥有的表

自定义 API

他们还创建了许多自定义 API 操作,这些操作由销售点系统、其网站和 ERP 系统调用,以将并非源自 Dataverse 的事件通知给 Dataverse:

UniqueName DisplayName
contoso_CustomerEnteredStore 进入应用商店
contoso_CustomerVisitWebSite 访问网站
contoso_CustomerPurchasedProduct 购买的产品
contoso_CustomerReturnedProduct 退货产品

目录结构

Contoso 客户管理解决方案目录如下所示:

Catalog Description
Contoso 客户管理 根目录
    Tables 第二级目录类别
            客户 CatalogAssignment:实体
            联系人 CatalogAssignment:实体
            Membership CatalogAssignment:实体
    客户活动 第二级目录类别
            进入应用商店 CatalogAssignment: CustomAPI
            访问网站 CatalogAssignment: CustomAPI
            购买产品 CatalogAssignment: CustomAPI
            返回商品 CatalogAssignment: CustomAPI

可用事件

当您对表进行 CatalogAssignment 操作时,该表的一些系统绑定操作将作为事件提供。

通过此目录,将提供以下事件:

Table 事件 为何可用
客户 Create
Update
删除
标准数据操作
客户 授予访问权限
ModifyAccess
撤销访问权限
可以共享用户拥有的实体。
联系人 Create
Update
删除
标准数据操作
联系人 授予访问权限
ModifyAccess
撤销访问权限
可以共享用户拥有的实体。
Membership Create
Update
删除
标准数据操作
N/A contoso_CustomerEnteredStore 显式目录分配
N/A contoso_CustomerVisitWebSite 显式目录分配
N/A contoso_CustomerPurchasedProduct 显式目录分配
N/A contoso_CustomerReturnedProduct 显式目录分配

大多数表都支持 创建、 更新和 删除 事件。 有一些例外情况。 用户拥有的表将公开与共享更改相关的事件:GrantAccess、ModifyAccess 和 RevokeAccess

Note

还将包含绑定到表的任何自定义 API 或自定义进程操作。

将显示禁用的自定义进程操作,但在启用和使用这些操作之前,该事件永远不会发生。

在 Power Apps 中创建目录

您可以在 Power Apps (https://make.powerapps.com) 中创建目录和目录分配记录。

您应始终将目录作为解决方案的一部分进行创建。 使用以下说明创建目录记录:

  1. 登录到 Power Apps,

  2. 在左侧导航窗格中,选择解决方案。

  3. 创建或选择要使用的解决方案,然后单击“ 新建”。

  4. 从菜单中选择“产品目录”,将会打开一个新窗口。

  5. 输入以下字段:

    领域 Description
    上级目录 请勿为解决方案根目录设置父目录。 否则,请设置解决方案根目录。
    唯一名称 唯一名称必须具有自定义前缀,并且没有空格。 此前缀应与解决方案发布者的自定义前缀相同。
    名称 请输入目录名称。 通常与唯一名称相同,但不包含自定义前缀且包含空格。
    显示名称 通常与 名称相同。
    Description 输入目录的有意义说明。
  6. 保存并关闭窗体。

在 Power Apps 中创建目录分配

使用包含目录的同一 Power Apps 解决方案

  1. 单击 “新建” 。

  2. 从菜单中选择“目录分配”,随后将打开一个新窗口。

  3. 输入名称。 此值必须以自定义前缀开头,并且没有空格。 应使用为解决方案发布者定义的相同自定义前缀。

  4. 设置 目录分配对象。 此查找允许设置三种不同类型的记录:

    • 自定义 API
    • Entities
    • 过程

    应能够通过键入名称来发现要查找的类型。

  5. 选择目录

    Note

    选择的目录必须是表示类别的二级目录。

  6. 保存并关闭窗体

在受管解决方案中阻止目录项的自定义

除非您希望允许安装您的托管解决方案的人员可以自定义目录和目录分配,否则应确保将 IsCustomizable 属性设置为 false,因为默认值允许对它们进行自定义。

若要在 Power Apps UI 中设置此项,请执行以下操作:

  1. 选择解决方案中的每个目录或目录分配

  2. 在菜单中,单击省略号(...),然后选择 “托管属性”。

    单击省略号以查看“受管属性”按钮。

  3. 在打开的窗口中,取消选择 “允许自定义”。

    取消选中“允许自定义”。

  4. 单击“完成”

表图

下图显示了 Catalog 和 CatalogAssignment 表之间的关系

Catalog 和 CatalogAssignment 表关系图

使用 ParentCatalogId 的自引用关系可在一个解决方案目录和多个使用目录记录表示类别的目录之间创建两级层次结构。

目录表列

目录 表/实体引用中提供了所有可用的列和关系。

下表包括可以设置的 Catalog 表/实体的选定列/属性。

显示名称
SchemaName
LogicalName
类型 Description
Catalog
CatalogId
catalogid
唯一标识符 目录实例的唯一标识符。
Description
Description
description
String 目录实例的本地化说明。
必需
显示名称
DisplayName
displayname
String 目录实例的本地化显示名称。
必需
可自定义
IsCustomizable
iscustomizable
ManagedProperty 控制目录是否可以自定义或删除。
默认值为真。 更多信息:在受管解决方案中阻止目录项的自定义
必需
Name
Name
name
String 目录的主要名称。
必需
父目录
ParentCatalogId
parentcatalogid
查找 父目录的唯一标识符。
保存后无法更改。
唯一名称
UniqueName
uniquename
String 目录的唯一名称。
必需
必须以自定义前缀开头。

Note

将目录分配项关联到目录时,在删除目录分配项之前,将无法删除目录。

CatalogAssignment 表中的列

CatalogAssignment 表/实体引用中提供了所有可用的列和关系。

下表包含可设置的 CatalogAssignment 表/实体的选定列/属性。

显示名称
SchemaName
LogicalName
类型 Description
目录分配
CatalogAssignmentId
catalogassignmentid
唯一标识符 目录分配实例的唯一标识符。
目录
CatalogId
catalogid
查找 与目录分配关联的目录的唯一标识符。
必需
可自定义
IsCustomizable
iscustomizable
ManagedProperty 控制是否可以自定义或删除 CatalogAssignment。
默认值为真。 更多信息:在受管解决方案中阻止目录项的自定义
必需
Name
Name
name
String 目录分配的主要名称。
目录分配对象
Object
object
查找 与目录分配关联的对象的唯一标识符。
必需
保存后无法更改。
此多态查找可以链接到下表:
  customapi
  实体
  工作流

使用 Web API 关联此多态关系时,必须为每个关系使用单值导航属性名称。

这些名称为:
  CustomAPIId
  EntityId
  WorkflowId

在与表、自定义 API 或自定义流程操作建立关联时,您需要获取相应的 id 值。 有关详细信息,请参阅 “获取 CatalogAssignment 项的 Id”。

获取 CatalogAssignment 项的 ID

将实体、自定义 API 和自定义进程操作与 CatalogAssignment 相关联时,需要获取实体、自定义 API 和自定义进程操作的 ID。

获取表的 ID

“实体”表中为每个表包含一行。 可以使用 Web API 获取特定表(例如帐户表)的 ID:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=MetadataId
GET [Organization URI]/api/data/v9.2/entities?$select=entityid&$filter=name eq 'Account'

获取自定义 API 的 ID

这是使用 Web API 最容易完成的。 以下示例将返回自定义 API 的 customapiid,其中 uniquename 为 your_CustomAPIName。

GET [Organization URI]/api/data/v9.2/customapis?$select=customapiid&$filter=uniquename eq 'your_CustomAPIName'

获取自定义进程操作的 ID

这是使用 Web API 最容易完成的。 以下示例将返回具有 的 的自定义进程操作的 。

GET [Organization URI]/api/data/v9.2/workflows?$select=workflowid,uniquename&$filter=category eq 3 and type eq 1 and endswith(uniquename,'ExampleCustomProcessAction')

Note

工作流的 uniquename 不包含 Web API 中自定义流程操作名称前缀的自定义前缀。 如果从 Web API 调用的操作名为 new_ExampleCustomProcessAction,则工作流唯一名称将为 ExampleCustomProcessAction。

请确保访问类型为1的行。 这是工作流定义。

自定义进程操作工作流的 类别 值为 3.

检索现有的目录分配

可以使用以下 OData 查询检索有关目录分配、分配类型、与其关联的目录以及父目录的信息。

GET [Organization URI]/api/data/v9.2/catalogassignments?$select=name
    &$expand=CatalogId($select=uniquename;$expand=ParentCatalogId($select=uniquename)),
    EntityId($select=entityid),
    CustomAPIId($select=uniquename),
    WorkflowId($select=uniquename)
    &$filter=name ne null

使用代码创建目录和 CatalogAssignments

可以使用 Web API 或 SDK for .NET创建目录和目录分配记录。

使用 Web API

Note

目前无法使用“深度插入”创建目录和目录分配记录。

可以使用“深度插入”创建目录记录的层次结构,但必须单独创建目录分配。

以下一系列 Web API 操作将在 UniqueName 为 ContosoCustomerManagement 的解决方案中创建目录层次结构和 CatalogAssignment。 请注意,在创建记录时,需使用 MSCRM.SolutionUniqueName 请求头来设置与解决方案的关联。

有关详细信息,请参阅使用 Web API 创建记录部分:基本创建和创建时关联表行。

创建根目录

请求:

POST [Organization URI]/api/data/v9.2/catalogs HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
    "name": "Contoso Customer Management",
    "uniquename": "contoso_CustomerManagement",
    "displayname": "Contoso Customer Management",
    "description": "The root catalog for the Contoso Customer Management solution",
    "iscustomizable": {
        "Value": false
    }
}

响应:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogs(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)

创建“表事件”子目录

请求:

POST [Organization URI]/api/data/v9.2/catalogs HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
    "name": "Contoso Customer Management Table Events",
    "uniquename": "contoso_TableEvents",
    "displayname": "Tables",
    "description": "Groups Table events for the Contoso Customer Management Solution",
    "iscustomizable": {
        "Value": false
    },
    "ParentCatalogId@odata.bind": "catalogs(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)"
}

响应:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2)

在“表”目录上创建“账户”目录分配

有关表 ID 的信息,请参阅 获取表的 ID 。

请求:

POST [Organization URI]/api/data/v9.2/catalogassignments HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
    "name": "Account",
    "EntityId@odata.bind": "entities(70816501-edb9-4740-a16c-6a5efbc05d84)",
    "iscustomizable": {
        "Value": false
    },
    "CatalogId@odata.bind": "catalogs(b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2)"
}

响应:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3)

使用 .NET 的 SDK

以下代码演示如何在具有 UniqueName 的解决方案中创建目录层次结构和目录分配: ContosoCustomerManagement

Note

将 SolutionUniqueName 可选参数与 CreateRequest 类 一起使用,以在该解决方案的上下文中创建记录。 详细信息: 使用请求传递可选参数

string conn = $@"
Url = {url};
AuthType = OAuth;
UserName = {userName};
Password = {password};
AppId = 51f81489-12ee-4a9e-aaae-a2591f45987d;
RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97;
LoginPrompt=Auto;
RequireNewInstance = True";

var service = new CrmServiceClient(conn);
// var service = new ServiceClient(conn);

var solutionUniqueName = " ContosoCustomerManagement ";

//Create the root catalog
Catalog rootCatalog = new Catalog
{
    Name = "Contoso Customer Management",
    UniqueName = "contoso_CustomerManagement",
    DisplayName = "Contoso Customer Management",
    Description = "The root catalog for the Contoso Customer Management solution",
    IsCustomizable = new BooleanManagedProperty(false)
};

CreateRequest rootCatalogReq = new CreateRequest {
    Target = rootCatalog
};
rootCatalogReq["SolutionUniqueName"] = solutionUniqueName;

Guid rootCatalogId = ((CreateResponse)service.Execute(rootCatalogReq)).id;

//Create the Table Events Sub-catalog
Catalog tableEvents = new Catalog
{
    Name = "Contoso Customer Management Table Events",
    UniqueName = "contoso_TableEvents",
    DisplayName = "Tables",
    Description = "Groups Table events for the Contoso Customer Management Solution",
    IsCustomizable = new BooleanManagedProperty(false),
    ParentCatalogId = new EntityReference("catalog", rootCatalogId)
};

CreateRequest tableEventsReq = new CreateRequest
{
    Target = tableEvents
};
tableEventsReq["SolutionUniqueName"] = solutionUniqueName;

Guid tableEventsId = ((CreateResponse)service.Execute(tableEventsReq)).id;

//Create the Account Catalog Assignment on the Tables catalog
CatalogAssignment accountAssignment = new CatalogAssignment
{
    Name = "Account",
    IsCustomizable = new BooleanManagedProperty(false),
    Object = new EntityReference("entity",new Guid("70816501-edb9-4740-a16c-6a5efbc05d84")),
    CatalogId = new EntityReference("catalog", tableEventsId)

};

CreateRequest accountAssignmentReq = new CreateRequest
{
    Target = accountAssignment
};
accountAssignmentReq["SolutionUniqueName"] = solutionUniqueName;

Guid accountAssignmentId = ((CreateResponse)service.Execute(accountAssignmentReq)).id;

通过编辑解决方案文件创建目录和目录分配

在解决方案文件中,您可以编辑文件来创建目录和目录分配。

使用 SolutionPackager 工具 将解决方案提取到可在源代码管理中管理的文件。 然后,可以编辑文件。 然后,可以使用 SolutionPackager 将提取的文件打包回解决方案。 更多信息:使用解决方案文件的源代码控制

Tip

在解决方案中创建一些产品目录和产品目录分配,然后导出并解压该解决方案以查看一些示例。

请确保使用最新版本的Microsoft.CrmSdk.CoreTools NuGet 包

使用解决方案文件创建目录

在解决方案中,所有目录都将位于 catalogs 文件夹中。 可以通过编辑此文件夹中的文件夹和文件,并在使用解决方案包装器打包解决方案后导入解决方案来创建、修改或删除目录。

每个目录都将包含在一个与该目录 uniquename 相匹配的文件夹中,例如 contoso_CustomerManagement。

该文件夹内包含一个 catalog.xml 文件,其中包含该目录的定义。

例如:

<catalog uniquename="contoso_CustomerManagement">
    <description default="The root catalog for the Contoso Customer Management solution">
        <label description="The root catalog for the Contoso Customer Management solution" languagecode="1033" />
    </description>
    <displayname default="Contoso Customer Management">
        <label description="Contoso Customer Management" languagecode="1033" />
    </displayname>
    <iscustomizable>0</iscustomizable>
    <name>Contoso Customer Management</name>
</catalog>

catalog元素uniquename属性必须与包含该文件的文件夹的名称匹配。

该 catalog 元素包括以下元素:

Element Description
description 该文件具有一个 default 属性,其值为默认描述。
包含一个或多个带有用于 description 和 languagecode 的属性的 label 元素,当定义了多种语言时。
displayname default具有一个属性,其值为默认显示名称。
包含一个或多个带有用于 description 和 languagecode 的属性的 label 元素,当定义了多种语言时。
iscustomizable 目录是否可自定义。 0 = false,1 = true。
name 目录的名称。

如果目录表示一个类别,则会使用一个 parentcatalogid 元素包含其与父目录的关系,其中该元素包含一个 uniquename 元素,而该 uniquename 元素中包含父目录的唯一名称。

例如:

<catalog uniquename="contoso_TableEvents">
    <description default="Groups Table events for the Contoso Customer Management Solution">
        <label description="Groups Table events for the Contoso Customer Management Solution" languagecode="1033" />
    </description>
    <displayname default="Tables">
        <label description="Tables" languagecode="1033" />
    </displayname>
    <iscustomizable>0</iscustomizable>
    <name>Contoso Customer Management Table Events</name>
    <parentcatalogid>
        <uniquename>contoso_CustomerManagement</uniquename>
    </parentcatalogid>
</catalog>

使用解决方案文件创建 CatalogAssignment

在解决方案的 Assets 文件夹中,你将找到一个 catalogassignments.xml 文件。 所有目录分配均包含在该文件中。 可以通过编辑此文件并在使用解决方案打包程序打包解决方案后导入解决方案来创建或修改目录分配。

例如:

<catalogassignments>
    <catalogassignment object.logicalname="account" catalogid.uniquename="contoso_TableEvents" objectidtype="entity">
        <iscustomizable>0</iscustomizable>
        <name>Account</name>
    </catalogassignment>
    <catalogassignment catalogid.uniquename="contoso_CustomerEvents" object.uniquename="contoso_CustomerEnteredStore" objectidtype="customapi">
        <iscustomizable>0</iscustomizable>
        <name>Customer Entered Store</name>
  </catalogassignment>
</catalogassignments>

每个 catalogassignment 元素都有以下属性:

Attribute Description
catalogid.uniquename 该目录分配所针对的子目录的唯一名称。
objecttypeid 对象的类型。 有效值是:
entity
customapi
workflow

根据 objectypeid,每个 catalogassignment 元素必须具有以下相应属性之一:

Attribute Description
object.uniquename 自定义 API 的唯一名称。
object.logicalname 实体的逻辑名称。
object.workflowid 自定义流程操作的唯一 ID 值。

该 catalogassignment 元素包括以下元素:

Element Description
iscustomizable 目录分配是否可自定义。 0 = false,1 = true。
name 目录分配项的名称

另请参阅

Microsoft Dataverse 业务事件
使用 Web API 创建实体记录
使用 Web API 检索实体记录
使用 SDK for .NET 创建实体
使用 SDK for .NET 检索实体