Universal FetchXML zur Erweiterung von Universal Resource Scheduling

Universal FetchXML (UFX) ist eine fortschrittliche Abfragesprache, die es Ihnen ermöglicht, Daten mit dynamischem FetchXML abzufragen, die resultierenden Daten für die Nutzung durch die URS-Lösung (Universal Resource Scheduling) zu formen und vorzubereiten. 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: UFX bag und UFX query.

Einfache UFX-Tasche

Ein UFX-Beutel enthält statisch typisierte Daten. Im Arbeitsspeicher modelliert es ein Wörterbuch mit Schlüsseln und Werten. Es kann in JSON und XML serialisiert werden. Wenn die Daten typisiert sind, kann eine UFX-Abfrage Daten von ihr abfragen, und die Client-Benutzeroberfläche kann an sie gebunden werden.

Aus praktischen Gründen und aus Leistungsgründen wird der In-Memory-Behälter zusätzlich zum Dynamics 365 Apps SDK-Objekt 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 Typklassen 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

UFX-Abfragen werden als XML-basierte UFX Bags geschrieben. 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. Die Ausgabe kann in JSON oder XML serialisiert werden.

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. Beachten Sie, dass einige Werte Metadaten haben, 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 wir nach Konten anhand eines Werts, der vom Benutzer bereitgestellt wird und über die XPath-Variable $input als UFX-Beutel 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 Eingabebehälter die erzeugte FetchXML-Bedingung enthält %city% , die von Dynamics 365 ausgeführt wird, würde dies wie folgt aussehen.

<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 behält diese zusätzlichen Informationen als Metadaten bei, die an den Primärwert angehängt 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 die Daten in einem UFX-Bag typisiert sind, kann eine UFX-Abfrage sie in einem strukturierten Format anzeigen und XPath verwenden, um die Daten zu durchlaufen und Werte daraus 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-typeufx-formatvalue und-Metadaten. Zusätzliche Metadaten werden neben jedem Typ beschrieben.

UFX-Abfrage-Direktiven

UFX-Direktiven können für Beuteleigenschaften und XML-Elemente einer FetchXML-Abfrage verwendet werden.

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 Uhrzeit in UTC zurück

liste()

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

Nachschlage-nach-Liste()

• lookup-to-list(Nachschlagen, ... [lookup]): Nimmt eine Reihe von lookup Werten, konvertiert jeden von ihnen in a bag mit dem ufx-id Metadatensatz und ufx-logicalname und reduziert sie zu einem einzigen list

Option-zur-Liste()

• option-to-list(Option, ... [option]): Nimmt eine Reihe von option Werten an, konvertiert jeden von ihnen in a bag mit einer einzelnen option Eigenschaft und reduziert sie in eine einzelne list

Reihenfolge()

• order(list, string, bool): Sortiert eine Liste nach einer Eigenschaft in jedem Beutel. Die Eigenschaft wird in Argument 2 angegeben, absteigend wird in Argument 3 angegeben.
• order(list, list): Sortiert eine Liste nach mehreren Sortierreihenfolgen, die in Argument 2 als Liste angegeben sind. Jede bag in der zweiten Liste kann eine und-Eigenschaft namedescending haben

iif()

• iif(any, any, any): Wenn Argument 1 wahr ist, gibt es Argument 2 zurück, andernfalls wird Argument 3 zurückgegeben

UFX XPath-Variablen

Weitere Ressourcen

Verstehen und Anpassen des Ressourcenabgleichs in Universal Resource Scheduling