Dela via

Utöka Universal Resource Scheduling med universell FetchXML

  • Artikel

UFX är ett avancerat frågespråk som gör att du kan hämta frågedata med hjälp av dynamisk FetchXML-form och förbereda resultatet för förbrukning av lösningen Universal Resource Scheduling (URS). Den här frågespråket låter dig skapa anpassade frågor för att anpassa och utöka schematavlan och schemaläggningsassistentfilter för att tillgodose unika affärsbehov i organisationen.

UFX består av två komponenter UFX uppsättning och UFX frågan.

Enkel UFX uppsättning

En UFX uppsättning innehåller statiska skrivna data. I minnet visas den som en ordlista med nycklar och värden. Den kan serialiseras till JSON och XML. Om du skriver data tillåter detta att en UFX fråga frågar data från den och klientens användargränssnitt för att koppla till den.

Av praktiska och prestandaskäl kan den minnesinterna uppsättningen implementeras ovanför Dynamics 365 SDK-appar Entity-objekt.

Exempeluppsättningen innehåller två värden.

Minnesintern:

Nyckel värde typ
namn John sträng
ålder 36 heltal

I JSON:

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

I XML:

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

UFX-typer som stöds

En UFX uppsättning kan innehålla värden av olika typer. De kategoriseras i 3 typklasser:

Kategori Värde
Enkla typer bool (Boolean), int (Int32), long (Int64), double (Double), decimal (Decimal), datetime (DateTime), guid (Guid), string (String)
Dynamics 365-specifika enkla typer: money (Money), option (OptionSet), lookup (EntityReference)
Övriga uppsättningar bag (Entity)
Lista över uppsättningar list (EntityCollection)

Här följer en JSON exempeluppsättning som innehåller flera typer:

{
    "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" }
    ]
}

Samma uppsättning i 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>

Introduktion till UFX frågor

UFX frågor skrivs som XML-baserade UFX uppsättningar. Egenskaper i uppsättningen kan innehålla UFX direktiv för att fråga data dynamiskt. En UFX fråga kör på minnesinterna objekt, inte XML. Endast direktiv skrivs i XML-format. Dess utdata kan serialiseras till JSON eller XML.

Följande UFX-fråga definierar egenskapen accounts i uppsättningen med source UFX-direktivet. Detta resulterar i att inline FetchXML körs av Dynamics 365 och egenskapen accounts blir en lista över uppsättningar, eller en EntityCollection, med varje uppsättning som en instans av en kontopost från 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>

En UFX fråga bearbetas efter varandra och kan innehålla många FetchXML-frågor.

Här är ett kodavsnitt av resultatet av föregående UFX fråga serialiserad till XML. Observera att vissa värden har metadata som ytterligare beskriver dem.

<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 direktiv tar ett XPath-uttrycket som väljer värden från aktuell uppsättning.

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

Resulterande uppsättning i XML:

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

Den mest kraftfulla aspekten av en UFX fråga är möjligheten att dynamisk generera FetchXML baserat på indata.

I exemplet nedan söker vi efter konton med ett värde som tillhandahålls av användaren och är tillgänglig som en UFX uppsättning via XPath $input variabeln. Observera UFX-direktiven om och värde på elementet 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>

Om egenskapen NameFilter i indatauppsättningen innehåller %city% skulle det producerade FetchXML-villkoret som körs av Dynamics 365 se ut så här.

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

Nycklar, värden och metadata

En UFX uppsättning innehåller nycklar och vissa värden med ytterligare metadata som beskriver dem.

Ett exempel kan vara ett värde av typen lookup (EntityReference). När en förfrågan från Dynamics 365 görs via FetchXML returneras det logiska namnet på entiteten och det formaterade visningsnamnet för posten. UFX uppsättningen bevarar denna ytterligare information som metadata kopplad till det primära värdet.

Serialiseras till JSON, en lookup med metadata ser ut så här:

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

I XML:

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

XPath över Dynamics 365-data

Om du har data skriven i ett UFX uppsättning kan en UFX fråga se den i ett strukturerat format och använda XPath till att bläddra över data och välja värden från den.

Ett XPath-uttryck som anges i ett UFX-direktiv ser data i uppsättningen mycket liknande strukturen i uppsättningen i XML-serialiserade formulär. Men data lagras även i minnesinterna .NET-objekt (i instanser av Entity och EntityCollection-typer) och inte i XML-dokument.

Bilaga A: UFX typreferens

Obs! Alla UFX-typer stöder metadata ufx-type och ufx-formatvalue. Ytterligare metadata beskrivs bredvid varje typ i tabellen nedan.

UFX-namn Attributtypkod .NET namn UFX-metadata
bool Boolesk Boolesk
heltal Heltal Int32
lång BigInt Int64
dubbel Dubbel Dubbel
decimaltal Decimaltal Decimaltal
datum och tid DatumTid DatumTid
guid Uniqueidentifier Guid
sträng Anteckning Sträng
belopp Belopp Belopp
alternativ Plocklista OptionSetValue
slå upp Slå upp EntityReference ufx-logicalname
uppsättning Saknas Entitet ufx-id
ufx-logicalname
list Saknas EntityCollection
Saknas Saknas AliasedValue ufx-aliasentity
ufx-aliasattribute

Bilaga B: UFX fråga direktiv

UFX direktiv kan användas på uppsättningsegenskaper och på XML-element i en FetchXML-fråga.

UFX uppsättning direktiv

Attribut Value Beskrivning
ufx:if XPath Testar XPath-uttrycket och hanterar bara egenskapen bara om testet returnerar sant
ufx:source fetch Kör inline <fetch> XML-element och tilldelar resultatet till egenskapen
ufx:select XPath Kör XPath-uttrycket och tilldelar resultatet till egenskapen
När du hämtar en bag eller list kan en valfri underordnad bag i XML-formulär anges för att omvandla resultatet av XPath-uttrycket

UFX FetchXML direktiv

Element Attribut Value Beskrivning
Alla element ufx:if XPath Testar XPath-uttrycket och avger endast XML-elementet om dessa tester lyckas
ufx:apply select XPath Går genom över noduppsättningen som returneras av XPath-uttrycket och visar underordnade XML-element för varje nod
ufx:value select XPath Kör XPath-uttrycket och visar resultatet i det aktuella XML-elementet
ufx:value attribute attributnamn Tilldelar resultatet för XPath-uttryck till det angivna attributnamnet på det aktuella XML-elementet

Bilaga C: UFX XPath-funktioner

UFX lägger till ett antal nya funktioner förutom de som finns inbyggda i XPath.

datetime()

  • datetime(): Returnerar aktuell tid i UTC

list()

  • list(bag | list, ...[uppsättning | lista]): Tar ett antal bag- eller list-värden som indata och lägger samman dem till en enda list

lookup-to-list()

  • lookup-to-list(lookup, ...[slå upp]): Tar ett antal lookup-värden, konverterar dem till en bag med ufx-id och ufx-logicalname metadatauppsättning och lägger samman dem till en enda list

option-to-list()

  • option-to-list(option, ...[alternativ]): Tar ett antal option-värden och konverterar dem till en bag med en enda option-egenskap och lägger samman dem till en enda list

order()

  • order(list, string, bool): Beställer en lista med en egenskap i varje uppsättning. Egenskapen anges i argument 2, fallande anges i argument 3.
  • order(list, list): Beställer en lista med flera sorteringsorder som anges som en lista i argument 2. Varje bag i andra listan kan ha en name och descending egenskap

iif()

  • iif(any, any, any): Om argument 1 är sant, returneras argument 2, annars returneras argument 3

Bilaga D: UFX XPath-variabler

Namn Beskrivning
$input En bag finns för UFX frågan med inmatningsvärden
$null En konstant null. Välja $null på en egenskap tar bort egenskapen från uppsättningen
$current Referens till aktuell uppsättning bearbetas av UFX-frågan

Se även

Förstå och anpassa resursmatchning i Universal Resource Scheduling

Universal Resource Scheduling utökningsbarhet – Viktig information