使用通用 FetchXML 來擴充 Universal Resource Scheduling

發行項
06/06/2024

UFX 是進階查詢語言，可讓您使用動態 FetchXML 查詢資料、塑造和準備結果資料以供 Universal Resource Scheduling (URS) 解決方案取用。此查詢語言可讓您建立自訂查詢，以自訂和擴充排程面板與排程小幫手篩選來滿足組織的獨特業務需求。

UFX 包含 UFX 包和 UFX 查詢這兩個元件。

簡單 UFX 包

UFX 包內含靜態具類型資料。在記憶體中，其表示為具有索引鍵和值的字典。這可以序列化為 JSON 和 XML。含有具類型的資料可讓 UFX 查詢從其中及從用戶端 UI 查詢資料來進行繫結。

基於實用與效能考量，記憶體內部包的實作是建立在 Dynamics 365 應用程式 SDK Entity 物件的基礎上。

含有兩個值的範例包。

在記憶體中：

key	值	類型
名稱	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 包可以含有許多類型的值。這些類型分為三個類型類別：

類別	值
簡單類型	`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>
    <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 包。包中的屬性可以含有用於動態查詢資料的 UFX 指示詞。 UFX 查詢 (而非 XML) 會在記憶體內部物件上執行。只有指示詞是以 XML 所撰寫。可以將其輸出序列化至 JSON 或 XML。

下列 UFX 查詢使用 source UFX 指示詞來定義包中的 accounts 屬性。這會導致內置 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>
    <first_account_name ufx-type="string">Fourth Coffee (sample)</first_acount_name>
</bag>

當然，UFX 查詢最強大的能力是根據輸入資料動態產生 FetchXML 的功能。

在以下範例中，我們依據使用者所提供的值 (而此值可透過 XPath $input變數當做 UFX 包來取得) 搜尋客戶。注意 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%，則 Dynamics 365 所執行的已產生 FetchXML 條件看起來像這樣。

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

索引鍵、值和中繼資料

UFX 包內含索引鍵和值，而某些值還有進一步描述這些值的額外中繼資料。

例如，值的類型可能會是 lookup (EntityReference)。透過 FetchXML 從 Dynamics 365 進行查詢時，它會傳回實體的邏輯名稱，以及記錄的格式化顯示名稱。 UFX 包會保存這些額外資訊做為附加至主要值的中繼資料。

序列化為 JSON 後，含有中繼資料的 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 包中，可讓 UFX 查詢以結構化格式查看資料，使用 XPath 周遊資料並從中選取資料。

UFX 指示詞指定的 XPath 運算式會在結構類似於 XML 序列化表單之包的包中查看資料。不過，資料是儲存於記憶體內部 .NET 物件 (在 Entity 和 EntityCollection 類型的執行個體中)，而非 XML 文件。

附錄 A：UFX 類型參照

注意：所有 UFX 類型都支援 ufx-type 和 ufx-formatvalue 中繼資料。下表中每個類型旁邊會說明額外的中繼資料。

UFX 名稱	屬性類型代碼	.NET 名稱	UFX 中繼資料
bool	Boolean	Boolean
int	整數	Int32
long	BigInt	Int64
double	Double	Double
十進位	Decimal	Decimal
datetime	DateTime	DateTime
guid	Uniqueidentifier	Guid
字串	備忘	String
money	金額	金額
選項	挑選清單	OptionSetValue
lookup	查詢	EntityReference	`ufx-logicalname`
包	不適用	實體	`ufx-id` `ufx-logicalname`
list	不適用	EntityCollection
不適用	不適用	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

附錄 B：UFX 查詢指示詞

UFX 指示詞可在包屬性以及在 FetchXML 查詢的 XML 元素上使用。

UFX 包指示詞

屬性	Value	描述
`ufx:if`	XPath	測試 XPath 運算式，如果測試傳回 true，則僅處理屬性
`ufx:source`	`fetch`	執行內置 `<fetch>` XML 元素，然後將結果指派給屬性
`ufx:select`	XPath	執行 XPath 運算式，然後將結果指派給屬性查詢 `bag` 或 `list` 時，可以指定 XML 表單中的選擇性下層 `bag` 以轉換 XPath 運算式的結果

UFX FetchXML 指示詞

項目	屬性	Value	描述
所有元素	`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()

datetime()：傳回目前的 UTC 時間

list()

list(bag | list, ...[bag | list])：接受數個 bag 或 list 值做為輸入，並將這些值壓平合併成單一 list

lookup-to-list()

lookup-to-list(lookup, ...[lookup])：接受數個 lookup 值、將其中每個值轉換為含有 ufx-id 及 ufx-logicalname 中繼資料集的 bag，然後將這些值壓平合併成單一 list

option-to-list()

option-to-list(option, ...[option])：接受數個 option 值、將其中每個值轉換為含有單一 option 屬性的 bag，然後將這些值壓平合併成單一 list

order()

order(list, string, bool)：依據每個包中屬性排序清單。屬性是在引數 2 中指定，而遞減順序是引數 3 中指定。
order(list, list)：依據引數 2 中以清單方式指定的多個排序順序來排序清單。第二個清單中的每個 bag 都可以有 name 和 descending 屬性

iif()

iif(any, any, any)：如果引數 1 為 true，傳回引數 2，否則傳回引數 3

附錄 D：UFX XPath 變數

名字	描述
$input	`bag` 適用於有多個輸入值的 UFX 查詢
$null	null 常數。在屬性上選取 `$null` 會從包中移除該屬性
$current	UFX 查詢所處理之目前包的參照

請參閱

了解和自訂 Universal Resource Scheduling 中的資源比對

Universal Resource Scheduling 擴充性版本資訊

共用方式為