Universal FetchXML zur Erweiterung von Universal Resource Scheduling

Universal FetchXML (UFX) ist eine fortgeschrittene Abfragesprache, mit der Sie Daten mithilfe dynamischer FetchXML abfragen können. Es formt und bereitet die resultierenden Daten für den Verbrauch durch die Universal Resource Scheduling (URS)- Lösung vor. Mit dieser Abfragesprache können Sie benutzerdefinierte Abfragen erstellen, um die Filter der Zeitplanübersicht und des Zeitplan-Assistenten anzupassen und zu erweitern, um die individuellen Geschäftsanforderungen der Organisation zu erfüllen.

UFX besteht aus zwei Komponenten: UFC-Bag und UFC-Abfrage.

Einfache UFX-Tasche

Ein UFX-Beutel enthält statisch typisierte Daten. Im Arbeitsspeicher modelliert es ein Wörterbuch mit Schlüsseln und Werten. Du kannst es in JSON und XML serialisieren. Wenn die Daten getippt sind, kann eine UFX-Abfrage die Daten daraus abfragen, und die Client-UI kann sich darauf binden.

Aus praktischen und leistungstechnischen Gründen ist die In-Memory-Tasche auf dem SDK-Objekt der Dynamics 365 Apps Entity implementiert.

Probenbeutel mit zwei Werten.

In Erinnerung:

Schlüssel Wert Typ
Name John Schnur
Alter 36 INT

In JSON:

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

In XML:

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

Von UFX unterstützte Typen

Ein UFX-Beutel kann Werte vieler Typen enthalten. Sie werden in drei Typenklassen eingeteilt:

Kategorie Wert
Einfache Typen bool (Boolean), int (Int32), long (Int64), double (Double), decimal (Decimal), , datetime (DateTime), , guid (Guid)string (String)
Dynamics 365-spezifische einfache Typen: money (Money), option (OptionSet), lookup (EntityReference)
Andere Taschen bag (Entity)
Liste der Taschen list (EntityCollection)

Hier ist ein JSON-Beispielbeutel mit weiteren Typen:

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

Der gleiche Beutel 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-Abfragen

Schreiben Sie UFC-Abfragen als XML-basierte UFX-Bags. Eigenschaften im Beutel können UFX-Direktiven enthalten, um Daten dynamisch abzufragen. Eine UFX-Abfrage wird für In-Memory-Objekte und nicht für XML ausgeführt. Nur die Direktiven sind in XML geschrieben. Sie können die Ausgabe in JSON oder XML serialisieren.

Die folgende UFX-Abfrage definiert die accounts Eigenschaft im Bag mit der source UFX-Direktive. Infolgedessen führt Dynamics 365 das Inline-FetchXML aus und füllt die accounts Eigenschaft mit einer Liste von Behältern auf. Ein EntityCollection Punkt, an dem jeder Beutel einen einzelnen Kontodatensatz aus Dynamics 365 darstellt.

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

Eine UFX-Abfrage wird sequenziell verarbeitet und kann viele FetchXML-Abfragen enthalten.

Hier sehen Sie einen Ausschnitt aus dem Ergebnis der vorherigen UFX-Abfrage, die in XML serialisiert wurde. Einige Werte enthalten Metadaten, die sie weiter beschreiben.

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

Die select UFX-Direktive verwendet einen XPath-Ausdruck, der Werte aus dem aktuellen Bag auswählt.

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

Der resultierende Beutel in XML:

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

Der leistungsstärkste Aspekt einer UFX-Abfrage ist sicherlich ihre Fähigkeit, FetchXML basierend auf Eingabedaten dynamisch zu generieren.

Im folgenden Beispiel suchen Sie nach Konten nach einem vom Benutzer angegebenen Wert, der als UFX-Beutel über die XPath-Variable $input verfügbar ist. Beachten Sie die UFX if- und value-Direktiven für das 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>

Wenn die NameFilter Eigenschaft im Eingabebeutel enthält%city%, sieht die von Dynamics 365 ausgeführte FetchXML-Bedingung so aus.

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

Schlüssel, Werte und Metadaten

Ein UFX-Beutel enthält Schlüssel und Werte, wobei einige Werte mehr Metadaten haben, um sie zu beschreiben.

Ein Beispiel könnte ein Wert vom Typ .lookup (EntityReference) Bei der Abfrage von Dynamics 365 über FetchXML wird der logische Name der Entität und der formatierte Anzeigename des Datensatzes zurückgegeben. Der UFX-Beutel bewahrt diese zusätzlichen Informationen als Metadaten, die dem Primärwert zugeordnet sind.

Serialisiert in JSON sieht ein mit lookup Metadaten wie folgt aus:

{
    "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 über Dynamics 365-Daten

Wenn Sie Daten in eine UFOX-Packung eingeben, kann eine UXX-Abfrage sie in einem strukturierten Format sehen und XPath verwenden, um die Daten zu durchlaufen und Werte auszuwählen.

Ein XPath-Ausdruck, der in einer UFX-Direktive angegeben wird, sieht die Daten im Beutel ähnlich wie die Struktur des Behälters in XML-serialisierter Form. Die Daten werden jedoch in .NET-Objekten im Arbeitsspeicher (in Instanzen von Entity und EntityCollection Typen) und nicht in XML-Dokumenten gespeichert.

UFX-Typen-Referenz

Alle UFX-Typen unterstützen die ufx-type und ufx-formatvalue Metadaten. Die folgende Tabelle beschreibt zusätzliche Metadaten für jeden Typ.

UFX-Name Code für den Attributtyp .NET-Name UFX-Metadaten
Boolesch Boolescher Typ (Boolean) Boolescher Typ (Boolean)
INT Ganze Zahl Int32
lang BigInt Int64
doppelt Doppelt Doppelt
Decimal Dezimalzahl Dezimalzahl
Datum/Uhrzeit Datum/Uhrzeit Datum/Uhrzeit
GUID Eindeutiger Bezeichner Leitfaden
Schnur Mitteilung Schnur
Geld Geld Geld
Option Auswahlliste OptionSetValue
nachschlagen Suche EntityReference ufx-logicalname
Tasche Nicht verfügbar Entität ufx-id
ufx-logicalname
Liste Nicht verfügbar EntityCollection
Nicht verfügbar Nicht verfügbar AliasedValue ufx-aliasentity
ufx-aliasattribute

UFX-Abfrage-Direktiven

Verwenden Sie UFX-Direktiven auf Bag-Eigenschaften und auf XML-Elementen einer FetchXML-Abfrage.

Richtlinien für UFX-Beutel

Merkmal Wert BESCHREIBUNG
ufx:if XPath Testet den XPath-Ausdruck und verarbeitet die Eigenschaft nur, wenn der Test true zurückgibt
ufx:source fetch Führt das Inline-XML-Element <fetch> aus und weist der Eigenschaft das Ergebnis zu.
ufx:select XPath Führt den XPath-Ausdruck aus und weist das Ergebnis der Eigenschaft zu
Bei der Abfrage nach einem bag oder listkönnen Sie ein optionales Kind bag in XML-Form angeben, um das Ergebnis des XPath-Ausdrucks zu transformieren.

UFX FetchXML-Direktiven

Element Merkmal Wert BESCHREIBUNG
Alle Elemente ufx:if XPath Testet den XPath-Ausdruck und gibt das XML-Element nur aus, wenn der Test erfolgreich ist
ufx:apply select XPath Führt eine Schleife über das vom XPath-Ausdruck zurückgegebene Nodeset durch und gibt die untergeordneten XML-Elemente einmal für jeden Knoten aus
ufx:value select XPath Führt den XPath-Ausdruck aus und gibt das Ergebnis im aktuellen XML-Element aus
ufx:value attribute Attributname Weist das Ergebnis des XPath-Ausdrucks dem angegebenen Attributnamen im aktuellen XML-Element zu.

UFX XPath-Funktionen

UFX fügt viele neue Funktionen hinzu, zusätzlich zu denen, die nativ in XPath verfügbar sind.

Datum/Uhrzeit()

  • datetime(): Gibt die aktuelle Zeit in UTC zurück.

liste()

  • list(bag | list, ...[bag | list]): Nimmt eine Anzahl von bag oder-Werten list als Eingabe und flacht sie zu einem einzigen list.

Nachschlage-nach-Liste()

  • lookup-to-list(lookup, ...[lookup]): Nimmt mehrere lookup Werte, wandelt jeden Wert mit bag dem und ufx-logicalname Metadatensatz ufx-id um und flacht sie zu einem einzigen list.

Option-zur-Liste()

  • option-to-list(option, ...[option]): Nimmt mehrere option Werte, wandelt jeden Wert in ein bag mit einer einzigen option Eigenschaft um und flacht sie zu einem einzigen list.

Reihenfolge()

  • order(list, string, bool): Ordnet eine Liste nach einer Eigenschaft in jedem bag. Spezifizieren Sie die Eigenschaft im zweiten Argument und geben Sie im dritten Argument die absteigende Reihenfolge an.
  • order(list, list): Ordnet eine Liste nach mehreren Sortierreihenfolgen, die im zweiten Argument als Liste angegeben sind. Jede bag in der zweiten Liste kann eine name Eigenschaft und descending haben.

iif()

  • iif(any, any, any): Wenn das erste Argument wahr ist, gibt das zweite Argument zurück. Andernfalls gibt er das dritte Argument zurück.

UFX XPath-Variablen

Name BESCHREIBUNG
$input A bag , der für die UFX-Abfrage mit Eingabewerten verfügbar ist
$null Eine NULL-Konstante. Die Auswahl $null einer Eigenschaft entfernt die Eigenschaft aus der bag
$current Verweis auf den aktuellen Bereich bag , den die UFX-Abfrage verarbeitet

Weitere Ressourcen

Verstehen und Anpassen des Ressourcenabgleichs in Universal Resource Scheduling

  • Last updated on