Споделяне чрез

Разширяване на Universal Resource Scheduling с Универсален FetchXML

  • Статия

UFX е разширен език за заявки, който ви позволява да търсите данни с помощта на динамичен FetchXML, да оформяте и подготвяте получените данни за консумация от решението Universal Resource Scheduling (URS). Този език за заявки ви позволява да създавате персонализирани заявки, за да персонализирате и разширите филтрите на асистента на графика, за да отговорите на уникалните бизнес нужди на организацията.

UFX се състои от два компонента UFX набор и UFX заявка.

Обикновен UFX набор

UFX наборът съдържа статично въведени данни. В паметта той се представя като речник с ключове и стойности. Той може да бъде поредица на JSON и XML. Въвеждането на да данните позволява на UFX заявка да търси данни от тях и ПИ на клиент за обвързване.

От съображения за практичност и производителност в набора в паметта се прилага върху обекта SDK Entity на приложения на Dynamics 365.

Примерен набор, съдържащ две стойности.

В паметта:

ключ стойност тип
име John низ
възраст 36 целочислен

в 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 заявка определя свойството accounts в набора с UFX директива source. Това води до изпълнението на вграден 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 заявки.

Ето един фрагмент от резултата от предишната UFX заявката с поредица на XML. Обърнете внимание, че някои стойности имат метаданни, които ги описват допълнително.

<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>

UFX директивата selectвзема 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 въз основа на входните данни.

В извадката по-долу ние търсим клиенти по стойност, предоставена от потребителя и достъпна като UFX набор чрез променлива на XPath $input. Обърнете внимание на директивите UFX ако и стойност на елемента condition.

<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 наборът съдържа ключове и стойности, като някои стойности имат допълнителни метаданни, които допълнително ги описват.

Един пример може да бъде стойност от тип lookup (EntityReference). При заявка от Dynamics 365 чрез FetchXML, тя ще върне логическо име на обекта, както и форматираното показвано име на записа. 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>

XPath над данни на Dynamics 365

Въвеждането на данните в UFX набор позволява на UFX заявка да види техния структуриран формат и да използва XPath, за да прегледа данните и да избере стойности от тях.

Израз на XPath, указан в UFX директива, вижда данните в набора подобно на структурата на набора в подреден по XML формуляр. Въпреки това данните се съхраняват в .NET обекти в паметта (в случаи на типове Entity и EntityCollection), а не в XML документи.

Приложение А: Препратка от тип UFX

Забележка: Всички UFX типове поддържат метаданни ufx-type и ufx-formatvalue. Допълнителни метаданни са описани до всеки тип в таблицата по-долу.

UFX име Код на тип атрибут .NET име UFX метаданни
булево Булев Булев
целочислен Цяло число Int32
дълго BigInt Int64
двойно Двоен Двоен
десетично По десетичен знак По десетичен знак
дата час ДатаЧас ДатаЧас
guid Еднозначен идентификатор Guid
низ Паметна бележка Низ
пари Пари Пари
опция Падащ списък OptionSetValue
справочно поле Справка EntityReference ufx-logicalname
набор Няма Обект ufx-id
ufx-logicalname
списък Няма EntityCollection
Няма Няма AliasedValue ufx-aliasentity
ufx-aliasattribute

Приложение B: Директиви на UFX заявка

UFX директивите могат да бъдат използвани върху набор от свойства и XML елементи на FetchXML заявка.

Директиви на UFX набор

Атрибут Value Описание
ufx:if XPath Тества XPath израза и обработва свойството само ако тестът върне „true”
ufx:source fetch Изпълнява вградения <fetch> XML елемент и присвоява резултата на свойството
ufx:select XPath Изпълнява израза на XPath и присвоява резултата на свойството
При търсене на за bag или list допълнителен дъщерен bag в XML формат може да бъде указан за преобразуване на резултата от израз на 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 функции

UFX добавя определен брой нови функции освен тези, които са основни за XPath.

datetime()

  • datetime(): Връща текущото време в UTC

list()

  • list(bag | list, ...[bag | list]): Взема определен брой стойност и на bag или list като входящи и ги изравнява до единичен list

lookup-to-list()

  • lookup-to-list(lookup, ...[lookup]): Взема определен брой стойности за lookup, преобразува всяка от тях в bag с ufx-id и набор от метаданни на ufx-logicalname и ги изравнява до единичен list

option-to-list()

  • option-to-list(option, ...[option]): Взема определен брой стойности на option, преобразува всяка от тях в bag с едно свойство option и ги изравнява до единичен list

order()

  • order(list, string, bool): Подрежда списък по свойство във всеки набор. Свойството се указва в аргумент 2, низходящо е указано в аргумент 3.
  • order(list, list): Подрежда списък по множество подреждания на сортиране като списък в аргумент 2 Всеки bag във втория списък може да има name и свойство descending

iif()

  • iif(any, any, any): Ако аргумент 1 е верен, връща аргумент 2, в противен случай връща аргумент 3

Приложение D: UFX XPath променливи

Име Описание
$input bag, наличен за UFX заявката с входящи стойности
$null Нулева константа. Избирането на $null на свойство премахва свойството от набора
$current Препратка към текущия набор, обработван от UFX заявката

Вижте също

Разбиране и персонализиране на съпоставяне на ресурси в Universal Resource Scheduling

Бележки по изданието за разширяване на Universal Resource Scheduling

Hinweis

Можете ли да ни споделите повече за езиковите си предпочитания за документацията? Попълнете кратко проучване. (имайте предвид, че това проучване е на английски език)

Проучването ще отнеме около седем минути. Не се събират лични данни (декларация за поверителност).