使用 Universal FetchXML 扩展 Universal Resource Scheduling

2025-05-07

UFX 是一种高级查询语言，允许您使用动态 FetchXML 查询数据、调整和准备结果数据以供 Universal Resource Scheduling （URS） 解决方案使用。通过此查询语言，您可以创建自定义查询，以自定义和扩展日程安排板和日程安排助理筛选器，以满足组织的独特业务需求。

UFX 由两个组件组成：UFX Bag 和 UFX Query。

简单的 UFX 袋

UFX Bag 包含静态类型数据。在内存中，它表示为具有键和值的字典。它可以序列化为 JSON 和 XML。数据类型允许 UFX 查询 从中查询数据，并允许客户端 UI 绑定到它。

出于实际和性能原因，内存中包是在 Dynamics 365 应用 SDK Entity 对象之上实现的。

包含两个值的示例包。

在内存中：

钥匙	价值	类型
姓名	John	字符串
年龄	36	整数 (int)

在 JSON 中：

{
    "name": "John",
    "age": 36
}

在 XML 中：

<bag>
    <name ufx-type="string">John</name>
    <age ufx-type="int">36</age>
</bag>

UFX 支持的类型

UFX Bag 可以包含多种类型的值。它们分为三个类型类：

类别	价值
简单类型	`bool (Boolean)`、`int (Int32)`、`long (Int64)`、`double (Double)`、`decimal (Decimal)`、`datetime (DateTime)`、`guid (Guid)`、`string (String)` 特定于 Dynamics 365 的简单类型： `money (Money)`、 `option (OptionSet)`、 `lookup (EntityReference)`
其他包袋	`bag (Entity)`
包袋清单	`list (EntityCollection)`

下面是一个包含更多类型的示例 JSON 包：

{
    "citizen": true,          // implicit bool
    
    "age": 36,                // explicit int
    "age@ufx-type": "int",

    "name": {                 // nested bag
        "first": "John",
        "last": "Doe"
    },

    "children": [             // list of bags
        { "name": "Sam" },
        { "name": "Judy" }
    ]
}

XML 中的相同 bag：

<bag>
    <citizen ufx-type="bool">true</citizen>

    <age ufx-type="int">36</age>

    <name ufx-type="bag">
        <first ufx-type="string">John</first>
        <last ufx-type="string">Doe</last>
    </name>

    <children ufx-type="list">
        <bag>
            <name ufx-type="string">Sam</name>
        </bag>
        <bag>
            <name ufx-type="string">Judy</name>
        </bag>
    </children>
</bag>

UFX 查询简介

UFX 查询编写为基于 XML 的 UFX 包。 bag 中的属性可以包含用于动态查询数据的 UFX 指令 。 UFX 查询在内存中对象上执行，而不是在 XML 上执行。只有指令是用 XML 编写的。其输出可以序列化为 JSON 或 XML。

下面的 UFX 查询使用 source UFX 指令定义 accounts bag 中的属性。这会导致内联 FetchXML 由 Dynamics 365 执行， accounts 并且该属性将成为包列表或 EntityCollection，其中每个包都是 Dynamics 365 中客户记录的实例。

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account" />
        </fetch>
    </accounts>
</bag>

UFX 查询按顺序处理，可以包含许多 FetchXML 查询。

下面是上一个序列化为 XML 的 UFX 查询的结果片段。观察某些值具有进一步描述它们的元数据。

<bag>
  <accounts ufx-type="list">
    <bag ufx-id="166e39dd-34a1-e611-8111-00155d652f01" ufx-logicalname="account">
      <accountid ufx-type="guid">166e39dd-34a1-e611-8111-00155d652f01</accountid>
      <accountnumber ufx-type="string">ABSS4G45</accountnumber>
      <name ufx-type="string">Fourth Coffee (sample)</name>
      <statecode ufx-type="option" ufx-formatvalue="Active">0</statecode>
      <websiteurl ufx-type="string">https://www.fourthcoffee.com/</websiteurl>
      <primarycontactid ufx-type="lookup" ufx-formatvalue="Yvonne McKay (sample)" ufx-logicalname="contact">7c6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>
      ...
    </bag>
    <bag ufx-type="bag" ufx-id="186e39dd-34a1-e611-8111-00155d652f01" ufx-logicalname="account">
      <accountid ufx-type="guid">186e39dd-34a1-e611-8111-00155d652f01</accountid>
      <accountnumber ufx-type="string">ACTBBDC3</accountnumber>
      <name ufx-type="string">Litware, Inc. (sample)</name>
      <statecode ufx-type="option" ufx-formatvalue="Active">0</statecode>
      <websiteurl ufx-type="string">https://www.litwareinc.com/</websiteurl>
      <primarycontactid ufx-type="lookup" ufx-formatvalue="Susanna Stubberod (sample)" ufx-logicalname="contact">7e6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>
      ...
    </bag>
    ...
  </accounts>
</bag>

select UFX 指令采用 XPath 表达式，该表达式从当前包中选择值。

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account" />
        </fetch>
    </accounts>

    <first_account_name ufx:select="accounts/bag[1]/name" />

    <!-- null values remove properties from the bag -->
    <accounts ufx:select="$null" />
</bag>

生成的 XML 格式的 bag：

<bag>
    <first_account_name ufx-type="string">Fourth Coffee (sample)</first_acount_name>
</bag>

当然，UFX 查询最强大的方面是它能够根据输入数据动态生成 FetchXML。

在下面的示例中，我们按用户提供的值搜索帐户，并通过 XPath $input 变量作为 UFX Bag 提供。请注意元素上的 condition UFX if 和 value 指令。

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account">
                <filter>
                    <condition attribute="name" operator="like" ufx:if="$input/NameFilter">
                        <ufx:value select="$input/NameFilter" attribute="value" />
                    </condition>
                </filter>
            </entity>
        </fetch>
    </accounts>
</bag>

NameFilter如果输入包中的属性包含%city%生成的 FetchXML 条件，则由 Dynamics 365 执行，则如下所示。

<condition attribute="name" operator="like" value="%city%" />

键、值和元数据

UFX Bag 包含键和值，其中一些值具有进一步描述它们的附加元数据。

例如，类型为 lookup (EntityReference)的值。通过 FetchXML 从 Dynamics 365 查询时，它将返回实体的逻辑名称以及记录的格式化显示名称。 UFX Bag 将这些附加信息保留为附加到主值的元数据。

序列化为 JSON，带有元数据的 a lookup 如下所示：

{
    "primarycontactid": "7e6e39dd-34a1-e611-8111-00155d652f01",
    "primarycontactid@ufx-type": "lookup",
    "primarycontactid@ufx-logicalname": "contact",
    "primarycontactid@ufx-formatvalue": "Susanna Stubberod (sample)"
}

在 XML 中：

<primarycontactid ufx-type="lookup" ufx-formatvalue="Susanna Stubberod (sample)" ufx-logicalname="contact">7e6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>

基于 Dynamics 365 数据的 XPath

键入 UFX Bag 中的数据后，UFX 查询可以以结构化格式查看数据，并使用 XPath 遍历数据并从中选择值。

在 UFX 指令中指定的 XPath 表达式将看到 bag 中的数据，类似于 XML 序列化形式的 bag 的结构。但是，数据存储在内存中的 .NET 对象中（在和 EntityCollection 类型的实例Entity中），而不是存储在 XML 文档中。

附录 A：UFX 类型参考

注意： 所有 UFX 类型都支持 ufx-type and ufx-formatvalue 元数据。下表中每种类型的旁边描述了其他元数据。

UFX 名称	属性类型代码	.NET 名称	UFX 元数据
布尔	布尔型	布尔型
整数 (int)	整数	国际 32
长整型	BigInt 的	Int64 系列
翻倍	加倍	加倍
十进制	十进制	十进制
datetime	DateTime	DateTime
GUID	唯一标识符	Guid
字符串	备忘录	字符串
钱	金钱	金钱
选项	选择列表	OptionSetValue （选项集值）
查找	查找	EntityReference	`ufx-logicalname`
袋	无	实体	`ufx-id` `ufx-logicalname`
列表	无	实体集合
无	无	别名值	`ufx-aliasentity` `ufx-aliasattribute`

附录 B：UFX 查询指令

UFX 指令可用于 bag 属性和 FetchXML 查询的 XML 元素。

UFX 袋指令

特征	价值	DESCRIPTION
`ufx:if`	XPath	测试 XPath 表达式，并且仅在测试返回 true 时处理属性
`ufx:source`	`fetch`	执行内联 `<fetch>` XML 元素并将结果分配给属性
`ufx:select`	XPath	执行 XPath 表达式并将结果分配给属性 `bag` `list`查询 XML 格式中的可选子项`bag`时，可以指定 XPath 表达式的结果

UFX FetchXML 指令

元素	特征	价值	DESCRIPTION
所有元素	`ufx:if`	XPath	测试 XPath 表达式，并且仅在测试成功时发出 XML 元素
`ufx:apply`	`select`	XPath	循环访问 XPath 表达式返回的节点集，并为每个节点输出一次子 XML 元素
`ufx:value`	`select`	XPath	执行 XPath 表达式并在当前 XML 元素中输出结果
`ufx:value`	`attribute`	属性名称	将 XPath 表达式结果分配给当前 XML 元素上的指定属性名称

附录 C：UFX XPath 函数

除了 XPath 中本机提供的函数之外，UFX 还添加了许多新函数。

日期时间（）

datetime（）：返回以 UTC 为单位的当前时间

列表（）

list（bag | list， ...[bag | list]）：将多个 bag or list 值作为输入，并将它们展平为单个 list

lookup-to-list（）（）

lookup-to-list（lookup， ...[lookup]）：获取多个lookup值，将每个值转换为具有和元数据集的 ufx-id a bagufx-logicalname，并将它们展平为单个list

选项到列表（）

option-to-list（option， ...[option]）：获取多个option值，将每个值转换为具有单个option属性的 abag，然后将它们展平为单个list

订单（）

order（list， string， bool）：按每个 bag 中的属性对列表进行排序。属性在参数 2 中指定，降序在参数 3 中指定。
order（list， list）：按参数 2 中指定为列表的多个排序顺序对列表进行排序。第二个列表中的每个 bag API 都可以具有 name and descending 属性

iif ()

iif（any， any， any）：如果参数 1 为 true，则返回参数 2，否则返回参数 3

附录 D：UFX XPath 变量

名称	DESCRIPTION
$input	可用于 `bag` 具有输入值的 UFX 查询
$null	一个 null 常量。选择属性会 `$null` 从包中删除该属性
$current	对 UFX 查询正在处理的当前包的引用

另请参阅

了解和自定义 Universal Resource Scheduling 中的资源匹配

Universal Resource Scheduling 可扩展性发行说明