Delen via

Universal FetchXML om Universal Resource Scheduling uit te breiden

Universal FetchXML (UFX) is een geavanceerde querytaal waarmee u query's kunt uitvoeren op gegevens met behulp van dynamische FetchXML, vorm en de resulterende gegevens kunt voorbereiden voor gebruik door de Universal Resource Scheduling (URS) -oplossing. Met deze querytaal kunt u aangepaste query's maken om het planbord en de planningsassistentfilters aan te passen en uit te breiden om te voldoen aan de unieke zakelijke behoeften van de organisatie.

UFX bestaat uit twee componenten: UFX, bag en UFX-query.

Eenvoudige UFX tas

Een UFX-tas bevat statisch getypeerde gegevens. In het geheugen modelleert het een woordenboek met sleutels en waarden. Het kan worden geserialiseerd naar JSON en XML. Als de gegevens worden getypt, kan een UFX-query er gegevens uit opvragen en kan de gebruikersinterface van de client eraan binden.

Om praktische en prestatieredenen is de in-memory bag geïmplementeerd bovenop het Dynamics 365 apps SDK-object Entity .

Monsterzakje met twee waarden.

Ter nagedachtenis:

sleutel waarde soort
naam John touw
leeftijd 36 int (integer)

In JSON:

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

In XML:

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

UFX ondersteunde typen

Een UFX-tas kan vele soorten waarden bevatten. Ze zijn onderverdeeld in drie typeklassen:

Categorie Waarde
Eenvoudige typen bool (Boolean), , int (Int32)long (Int64), double (Double), , decimal (Decimal), , datetime (DateTime)guid (Guid)string (String)
Dynamics 365-specifieke eenvoudige typen: money (Money), option (OptionSet), lookup (EntityReference)
Andere tassen bag (Entity)
Lijst van tassen list (EntityCollection)

Hier is een voorbeeld van een JSON-tas met meer soorten:

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

Dezelfde tas in 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-query's

UFX-query's worden geschreven als XML-gebaseerde UFX-tassen. Eigenschappen in de tas kunnen UFX-richtlijnen bevatten om gegevens dynamisch op te vragen. Een UFX-query wordt uitgevoerd op objecten in het geheugen, niet op XML. Alleen de directives zijn geschreven in XML. De uitvoer kan worden geserialiseerd naar JSON of XML.

De volgende UFX-query definieert de accounts eigenschap in de tas met de source UFX-richtlijn. Als gevolg hiervan voert Dynamics 365 de inline FetchXML uit, waarbij de accounts eigenschap wordt gevuld met een lijst met tassen. Een EntityCollection waarbij elke zak een individuele accountrecord van Dynamics 365 vertegenwoordigt.

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

Een UFX-query wordt opeenvolgend verwerkt en kan veel FetchXML-query's bevatten.

Hier is een fragment van het resultaat van de vorige UFX-query die is geserialiseerd naar XML. Merk op dat sommige waarden metagegevens hebben die ze verder beschrijven.

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

De select UFX-richtlijn neemt een XPath-expressie aan die waarden uit de huidige tas selecteert.

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

De resulterende zak in XML:

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

Het krachtigste aspect van een UFX-query is ongetwijfeld de mogelijkheid om dynamisch FetchXML te genereren op basis van invoergegevens.

In het volgende voorbeeld zoeken we naar accounts op basis van een waarde die door de gebruiker is opgegeven en beschikbaar is als een UFX-tas via de XPath-variabele $input . Let op de UFX als en waarderichtlijnen op het condition element.

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

Als de NameFilter eigenschap in de invoerzak de geproduceerde FetchXML-voorwaarde bevatte %city% die door Dynamics 365 werd uitgevoerd, ziet deze er als volgt uit.

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

Sleutels, waarden en metagegevens

Een UFX-tas bevat sleutels en waarden, waarbij sommige waarden meer metadata hebben om ze te beschrijven.

Een voorbeeld hiervan is een waarde van het type lookup (EntityReference). Wanneer er vanuit Dynamics 365 via FetchXML wordt opgevraagd, worden de logische naam van de entiteit en de opgemaakte weergavenaam van de record geretourneerd. De UFX-tas bewaart deze aanvullende informatie als metagegevens die aan de primaire waarde zijn gekoppeld.

Geserialiseerd naar JSON, ziet een lookup met metagegevens er als volgt uit:

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

In XML:

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

XPath over Dynamics 365-gegevens

Als u de gegevens in een UFX-tas typt, kan een UFX-query deze in een gestructureerd formaat bekijken en XPath gebruiken om de gegevens te doorkruisen en er waarden uit te selecteren.

Een XPath-expressie die is opgegeven in een UFX-instructie, ziet de gegevens in de zak die vergelijkbaar zijn met de structuur van de zak in XML-geserialiseerde vorm. De gegevens worden echter opgeslagen in .NET-objecten in het geheugen (in instanties van Entity en EntityCollection typen) en niet in XML-documenten.

Referentie UFX-type

Alle UFX-typen ondersteunen de ufx-type en ufx-formatvalue metadata. Aanvullende metagegevens worden naast elk type beschreven.

UFX-naam Attribuut Type Code .NET-naam UFX-metagegevens
Bool Booleaan Booleaan
int (integer) Geheel getal Int32
lang Groot Int64
dubbel Dubbel Dubbel
decimaal Decimaal Decimaal
datum/tijd Datum/tijd Datum/tijd
Richtlijn Unieke identificatiecode Guid
touw Notitie Snaar / Touwtje
geld Geld Geld
optie Keuzelijst OptionSetValue
Lookup Opzoeken EntityReference ufx-logicalname
zak Niet van toepassing. Entiteit ufx-id
ufx-logicalname
lijst Niet van toepassing. Entiteit Collectie
Niet van toepassing. Niet van toepassing. AliasedValue ufx-aliasentity
ufx-aliasattribute

UFX-query-instructies

UFX-richtlijnen kunnen worden gebruikt voor zakeigenschappen en voor XML-elementen van een FetchXML-query.

Richtlijnen voor UFX-tassen

Eigenschap Waarde Beschrijving
ufx:if XPath Test de XPath-expressie en verwerkt de eigenschap alleen als de test true retourneert
ufx:source fetch Voert het inline <fetch> XML-element uit en wijst het resultaat toe aan de eigenschap
ufx:select XPath Voert de XPath-expressie uit en wijst het resultaat toe aan de eigenschap
Wanneer een query wordt uitgevoerd op een bag of list een optioneel onderliggend element bag in XML-vorm kan worden opgegeven om het resultaat van de XPath-expressie te transformeren

UFX FetchXML-richtlijnen

Onderdeel Eigenschap Waarde Beschrijving
Alle elementen ufx:if XPath Test de XPath-expressie en zendt het XML-element alleen uit als de tests slagen
ufx:apply select XPath Loops over de nodeset die wordt geretourneerd door de XPath-expressie en voert de onderliggende XML-elementen één keer uit voor elk knooppunt
ufx:value select XPath Voert de XPath-expressie uit en voert het resultaat uit in het huidige XML-element
ufx:value attribute Naam van het kenmerk Wijst het resultaat van de XPath-expressie toe aan de opgegeven kenmerknaam op het huidige XML-element

UFX XPath-functies

UFX voegt veel nieuwe functies toe naast de functies die native beschikbaar zijn in XPath.

datum/tijd()

  • datetime(): geeft als resultaat de huidige tijd in UTC

lijst()

  • lijst(tas | lijst, ... [bag | lijst]): Neemt een aantal bag of-waarden list als invoer en vlakt ze af tot één list

opzoeken-naar-lijst()

  • opzoeken-naar-lijst(opzoeken, ... [opzoeken]): Neemt een aantal lookup waarden, converteert elk van deze waarden naar een bag met de ufx-id en ufx-logicalname metagegevens set, en vlakt ze af tot één list

optie-naar-lijst()

  • optie-naar-lijst(optie, ... [optie]): Neemt een aantal option waarden, converteert elk van deze naar een bag met een enkele option eigenschap en vlakt ze af tot één list

orde()

  • order(list, string, bool): Ordent een lijst op basis van een eigenschap in elke zak. De eigenschap wordt gespecificeerd in argument 2, aflopend wordt gespecificeerd in argument 3.
  • order(lijst, lijst): Rangschik een lijst op meerdere sorteervolgordes die zijn opgegeven als een lijst in argument 2. Elk bag in de tweede lijst kan een name en descending eigenschap hebben

iif()

  • iif(elke, elke, elke): Als argument 1 waar is, geeft argument 2 terug, anders geeft argument 3 terug

UFX XPath-variabelen

Naam Beschrijving
$input A bag beschikbaar voor de UFX-query met invoerwaarden
$null Een nulconstante. Als u op een eigenschap selecteert $null , wordt de eigenschap uit de zak verwijderd
$current Verwijzing naar de huidige tas die de UFX-query verwerkt

Aanvullende bronnen

Resourcevergelijking begrijpen en aanpassen in Universal Resource Scheduling

  • Last updated on