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:

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:

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

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

Richtlinien für UFX-Beutel

UFX FetchXML-Direktiven

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

Weitere Ressourcen

Verstehen und Anpassen des Ressourcenabgleichs in Universal Resource Scheduling