Universelles FetchXML zum Erweitern von Universal Resource Scheduling

Artikel
06/06/2024

UFX ist eine erweiterte Abfragesprache, die es Ihnen ermöglicht, Daten mit dem dynamischen FetchXML abzufragen, die resultierenden Daten aufzubereiten und für die Nutzung durch die Universal Resource Scheduling (URS)-Lösung vorzubereiten. Mit dieser Abfragesprache können Sie benutzerdefinierte Abfragen erstellen, um die Zeitplanübersicht und die Filter des Zeitplan-Assistenten anzupassen und zu erweitern, um die individuellen Geschäftsanforderungen zu erfüllen.

UFX umfasst zwei Komponenten: UFX-Behälter und UFX-Abfrage.

Einfacher UFX-Behälter

Ein UFX-Behälter enthält typisierte statische Daten. Speicherintern wird er als Wörterbuch mit Schlüsseln und Werten angezeigt. Er kann zu JSON und XML serialisiert werden. Durch typisiere Daten kann eine UFX-Abfrage Daten davon abfragen und eine Client-UI kann eine Bindung damit vornehmen.

Aus praktischen und Leistungsgründen ist der In-Memory-Bag auf dem Dynamics 365 Apps SDK Entity Objekt implementiert.

Beispielbehälter mit zwei Werten.

Speicherintern:

Schlüssel	Wert	typ
Name	Erwin	Zeichenfolge
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>

UFX-unterstützte Typen

Ein UFX-Behälter kann Werte vieler Typen enthalten. Sie werden in 3 Typklassen kategorisiert:

Kateg.	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)`
Weitere Behälter	`bag (Entity)`
Liste der Behälter	`list (EntityCollection)`

Im Folgenden finden Sie ein Beispiel JSON-Behälter, der weitere Typen enthält:

{
    "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 Behälter 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>

Einführung in UFX-Abfragen

UFX-Abfragen werden als XML-basierte UFX-Behälter geschrieben. Eigenschaften im Behälter können UFX-Direktiven enthalten, um Daten dynamisch abzufragen. Eine UFX-Abfrage wird auf speicherinterne Objekte nicht auf XML ausgeführt. Nur die Direktiven werden in XML erstellt. Die Ausgabe kann zu JSON oder XML serialisiert werden.

Die folgende UFX-Abfrage definiert die accounts-Eigenschaft im Behälter mit den source-UFX-Direktiven. Dadurch wird das Inline-FetchXML von Dynamics 365 ausgeführt und die accounts-Eigenschaft wird zu einer Liste der Behälter oder ein EntityCollection, wobei jeder Behälter eine Instanz eines Firmendatensatzes von Dynamics 365 ist.

<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 ist ein Ausschnitt des Ergebnisses der vorherigen UFX-Abfrage, die zu XML serialisiert wurde. Beachten Sie, dass einige Werte über Metadaten verfügen, die sie weiter beschrieben.

<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 übernimmt einen XPath-Ausdruck, der Werte aus dem aktuellen Behälter 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 sich ergebende Behälter in XML:

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

Zweifellos ist der leistungsfähigste Aspekte einer UFX-Abfrage die Fähigkeit, FetchXML anhand von Eingabedaten dynamisch zu generieren.

Im Beispiel unten suchen wir durch die XPath-Variable $input mithilfe eines Werts nach Firmen, der vom Benutzer angegeben wird und als UFX-Behälter verfügbar ist. Beachten Sie die UFX-Direktiven if und value im 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 %city% enthielt, würde die erzeugte FetchXML-Bedingung, die von Dynamics 365 ausgeführt wurde, wie folgt aussehen.

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

Schlüssel, Werte und Metadaten

Ein UFX-Behälter enthält Schlüssel und Werte, wobei einige über Werte weitere Metadaten verfügen, die sie weiter beschreiben.

Ein Beispiel kann der Wert vom Typ lookup (EntityReference) sein. Bei einer Abfrage von Dynamics 365 über FetchXML wird er den logischen Namen der Entität sowie den formatierten Anzeigenamen des Datensatzes zurückgeben. Der UFX-Behälter bewahrt diese zusätzlichen Informationen als Metadaten, die dem primären Wert angefügt sind.

Serialisiert zu JSON, sieht ein lookup mit 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 zu Dynamics 365-Daten

Mit typisierten Daten in einem UFX-Behälter kann eine UFX-Abfrage diese Daten in einem strukturierten Format anzeigen und die Daten mit XPath durchlaufen und Werte daraus auswählen.

Ein XPath-Ausdruck, der in einer UFX-Direktive angegeben wird, zeigt die Daten im Behälter mit einer Struktur an, die der des Behälters in serialisierter XML-Form ähnlich sieht. Allerdings werden die Daten in speicherinternen .NET-Objekten (in Instanzen des Typs Entity und EntityCollection) und nicht in XML-Dokumenten gespeichert.

Anhang A: UFX-Typ-Verweis

Hinweis: Alle UFX-Typen unterstützen die Metadaten ufx-type und ufx-formatvalue. Zusätzliche Metadaten werden neben jedem Typ in der Tabelle unten beschrieben.

UFX-Name	Attributtypcode	.NET-Name	UFX-Metadaten
bool	Boolean	Boolean
int	Integer	Int32
long	BigInt	Int64
double	Double	Double
Dezimalzahl	Dezimal	Dezimal
datetime	DateTime	DateTime
guid	Uniqueidentifier	Guid
Zeichenfolge	Memo	String
Zahlung	Geld	Geld
option	Picklist	OptionSetValue
Suche	Suche	EntityReference	`ufx-logicalname`
Behälter	Nicht zutreffend	Entity	`ufx-id` `ufx-logicalname`
Liste	Nicht zutreffend	EntityCollection
Nicht zutreffend	Nicht zutreffend	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Anhang B: UFX-Abfrage-Direktiven

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

UFX-Behälterdirektiven

Attribut	Value	Beschreibung
`ufx:if`	XPath	Testet den XPath-Ausdruck und verarbeitet die Eigenschaft nur, wenn der Test "wahr" zurückgibt
`ufx:source`	`fetch`	Führt das Inline `<fetch>`-XML-Element aus und weist das Ergebnis der Eigenschaft zu
`ufx:select`	XPath	Führt den XPath-Ausdruck aus und weist das Ergebnis der Eigenschaft zu Wenn das Abfragen einer `bag` eine `list` kann ein optionales untergeordnetes `bag` in XML-Form angegeben werden, um das Ergebnis des XPath-Ausdrucks zu transformieren

UFX FetchXML-Direktiven

Element	Attribut	Value	Beschreibung
Alle Elemente	`ufx:if`	XPath	Testet den XPath-Ausdruck und gibt das XML-Element nur aus, wenn die Tests erfolgreich sind
`ufx:apply`	`select`	XPath	Führt eine Schleife vom Nodeset durch, das vom XPath-Ausdruck zurückgegeben wird und gibt die untergeordneten XML-Elemente für jeden Knoten einmal 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 die XPath-Ausdrucksergebnisse dem angegebenen Attributnamen auf den aktuellen XML-Element zu

Anhang C: UFX XPath-Funktionen

UFX fügt eine Reihe neuer Funktionen zusätzlich zu denen hinzu, die systemintern in XPath verfügbar sind.

datetime()

datetime(): Gibt die aktuelle Uhrzeit in UTC zurück

list()

list(bag | list, ...[bag | list]): Nimmt eine Anzahl von bag oder list Werten als Eingabe und glättet sie zu einer einzigen list.

lookup-to-list()

lookup-to-list(lookup, ...[lookup]): Nimmt eine Anzahl von lookup-Werten, wandelt jeden von ihnen in eine bag mit dem Metadatensatz ufx-id und ufx-logicalname um und glättet sie zu einer einzigen list.

option-to-list()

option-to-list(option, ...[option]): Nimmt eine Anzahl von option-Werten, wandelt jeden von ihnen in eine bag mit einer einzigen option-Eigenschaft um und glättet sie in eine einzige list.

order()

order(list, string, bool): Sortiert eine Liste nach einer Eigenschaft in jedem Behälter. Die Eigenschaft wird in Argument 2 angegeben. Die absteigende Reihenfolge wird in Argument 3 angegeben.
order(list, list): Sortieren Sie eine Liste nach mehreren Sortierreihenfolgen, die als eine Liste in Argument 2 angegeben werden. Jedes bag in der zweiten Liste kann eine descending und name Eigenschaft haben

iif()

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

Anhang D: UFX XPath-Variablen

Name	Beschreibung
$input	Ein `bag`, der für die UFX-Abfrage mit Eingabewerten verfügbar ist
$null	Eine NULL-Konstante. Das Auswählen von `$null` für eine Eigenschaft entfernt die Eigenschaft aus dem Behälter
$current	Verweisen Sie auf den aktuellen Behälter, der von der UFX-Abfrage verarbeitet wird

Siehe auch

Verstehen und Anpassen der Ressourcenanpassung in Universal Resource Scheduling

Universal Resource Scheduling Erweiterbarkeit Versionenhinweise

Freigeben über