Universal FetchXML for at udvide Universal Resource Scheduling

Universal FetchXML (UFX) er et avanceret forespørgselssprog, som du kan bruge til at forespørge data ved at bruge dynamisk FetchXML. Den former og forbereder de resulterende data til forbrug af Universal Resource Scheduling (URS) -løsningen. Dette forespørgselssprog giver dig mulighed for at oprette brugerdefinerede forespørgsler for at tilpasse og udvide filtrene i planlægningsområdet og planlægningsassistenten, så de opfylder organisationens unikke forretningsbehov.

UFX består af to komponenter: UFX bag og UFX query.

Enkel UFX taske

En UFC-pose indeholder statisk typede data. I hukommelsen modellerer den en ordbog med nøgler og værdier. Du kan serialisere det til JSON og XML. Når dataene er typet, kan en UFX-forespørgsel forespørge data fra dem, og klientens UI kan binde til den.

Af praktiske og ydelsesmæssige årsager er in-memory-tasken implementeret oven på Dynamics 365 apps SDK-objektetEntity.

Prøvesæk indeholdende to værdier.

Til minde om:

I JSON:

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

I XML:

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

UFX-understøttede typer

En UFX-pose kan indeholde værdier af mange typer. De er kategoriseret i tre typeklasser:

Her er et eksempel på en JSON-pose, der indeholder flere 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" }
    ]
}

Den samme pose 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>

UFX-forespørgsler

Skriv UFX-forespørgsler som XML-baserede UFC-poser. Egenskaber i posen kan indeholde UFX-direktiver til dynamisk forespørgsler på data. En UFX-forespørgsel udføres på objekter i hukommelsen, ikke XML. Det er kun direktiverne, der er skrevet i XML. Du kan serialisere dens output til JSON eller XML.

Følgende UFX-forespørgsel definerer egenskaben accounts i posen med UFX-direktivet source . Som følge heraf udfører Dynamics 365 den indbyggede FetchXML og udfylder accounts egenskaben med en liste over poser. En EntityCollection situation, hvor hver pose repræsenterer en individuel firmapost fra 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-forespørgsel behandles sekventielt og kan indeholde mange FetchXML-forespørgsler.

Her er et uddrag af resultatet af den forrige UFX-forespørgsel, der er serialiseret til XML. Nogle værdier har metadata, der yderligere 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-direktivet tager et XPath-udtryk, der vælger værdier fra den aktuelle pose.

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

Den resulterende pose i XML:

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

Det mest kraftfulde aspekt af en UFX-forespørgsel er bestemt dens evne til dynamisk at generere FetchXML baseret på inputdata.

I det følgende eksempel søg efter konti efter en værdi, som brugeren har oplyst og som er tilgængelig som en UFF-pose via XPath-variablen $input . Læg mærke til UFX if og værdidirektiverne 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>

Hvis egenskaben NameFilter i inputposen indeholdt %city%, ville den producerede FetchXML-betingelse, der udføres af Dynamics 365, se sådan ud.

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

Nøgler, værdier og metadata

En UFX-pose indeholder nøgler og værdier, hvor nogle værdier har flere metadata til at beskrive dem.

Et eksempel kan være en værdi af typen lookup (EntityReference). Når der forespørges fra Dynamics 365 via FetchXML, returneres det logiske navn på objektet og det formaterede viste navn på posten. UFX-posen bevarer denne ekstra information som metadata, der er knyttet til den primære værdi.

Serialiseret til JSON ser en lookup med metadata sådan ud:

{
    "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 over Dynamics 365-data

Når du indtaster data i en UFF-pose, kan en UFF-forespørgsel se dem i et struktureret format og bruge XPath til at gennemgå dataene og vælge værdier.

Et XPath-udtryk, der er angivet i et UFX-direktiv, ser dataene i posen svarende til strukturen af posen i XML-serialiseret form. Dataene gemmes dog i .NET-objekter i hukommelsen (i forekomster af Entity og EntityCollection typer) og ikke i XML-dokumenter.

UFX-typereference

Alle UFX-typer understøtter og ufx-typeufx-formatvalue metadata. Følgende tabel beskriver yderligere metadata for hver type.

UFX-forespørgselsdirektiver

Brug UFX-direktiver på bag-egenskaber og på XML-elementer i en FetchXML-forespørgsel.

UFX taske direktiver

UFX FetchXML-direktiver

UFX XPath-funktioner

UFX tilføjer mange nye funktioner ud over dem, der er tilgængelige indbygget i XPath.

datetime()

• datetime(): Returnerer den aktuelle tid i UTC.

liste()

• list(bag | list, ...[bag | list]): Tager et antal bag af eller-værdier list som input og flader dem ud til en enkelt list.

opslag til liste()

• lookup-to-list(lookup, ...[lookup]): Tager flere lookup værdier, konverterer hver værdi til en bag med ufx-id og ufx-logicalname metadatasættet og flader dem ud til en enkelt list.

mulighed-til-liste()

• option-to-list(option, ...[option]): Tager flere option værdier, konverterer hver værdi til en bag med én option egenskab og flader dem ud til en enkelt list.

rækkefølge()

• order(list, string, bool): Ordner en liste efter en egenskab i hver bag. Angiv egenskaben i det andet argument, og angiv faldende rækkefølge i det tredje argument.
• order(list, list): Ordner en liste efter flere sorteringsrækkefølger, specificeret som en liste i det andet argument. Hver bag i den anden liste kan have en name og descending egenskab.

iif()

• iif(any, any, any): Hvis det første argument er sandt, returnerer det andet argument. Ellers returnerer det tredje argument.

UFX XPath-variabler

Yderligere ressourcer

Forstå og tilpasse ressourcematchning i Universal Resource Scheduling