Universal FetchXML per estendere Universal Resource Scheduling

Universal FetchXML (UFX) è un linguaggio di query avanzato che puoi utilizzare per interrogare i dati utilizzando FetchXML dinamico. Modella e prepara i dati risultanti per il consumo tramite la soluzione Universal Resource Scheduling (URS ). Questo linguaggio di query consente di creare query personalizzate per personalizzare ed estendere la scheda di pianificazione e i filtri dell'assistente di pianificazione per soddisfare le esigenze aziendali specifiche dell'organizzazione.

UFX è composto da due componenti: UFX bag e UFX query.

Semplice borsa UFX

Una borsa UFX contiene dati tipizzati staticamente. In memoria, modella un dizionario con chiavi e valori. Puoi serializzare la versione su JSON e XML. Quando i dati vengono digitati, una query UFX può interrogare i dati da essi e l'interfaccia client può associarsi ad essa.

Per ragioni pratiche e di prestazioni, il sacco in memoria è implementato sopra l'oggetto SDK Entity delle applicazioni Dynamics 365.

Sacchetto di campionamento contenente due valori.

In memoria:

In JSON:

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

In XML:

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

Tipi supportati da UFX

Un sacchetto UFX può contenere valori di molti tipi. Sono suddivisi in tre classi di tipi:

Di seguito è riportato un esempio di borsa JSON contenente altri tipi:

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

La stessa borsa 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>

Query UFX

Scrivi query UFX come UFX Bags basati su XML. Le proprietà nel contenitore possono contenere direttive UFX per eseguire query sui dati in modo dinamico. Una query UFX viene eseguita sugli oggetti in memoria, non su XML. Solo le direttive sono scritte in XML. Puoi serializzare l'output in JSON o XML.

La query UFX seguente definisce la accounts proprietà nel contenitore con la source direttiva UFX. Di conseguenza, Dynamics 365 esegue l'operazione FetchXML in linea, popolando la accounts proprietà con un elenco di contenitori. E EntityCollection dove ogni contenitore rappresenta un singolo record di account da Dynamics 365.

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

Una query UFX viene elaborata in sequenza e può contenere molte query FetchXML.

Di seguito è riportato un frammento del risultato della query UFX precedente serializzato in XML. Alcuni valori hanno metadati che li descrivono ulteriormente.

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

La select direttiva UFX accetta un'espressione XPath che seleziona i valori dal contenitore corrente.

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

Il sacchetto risultante in XML:

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

Sicuramente l'aspetto più potente di una query UFX è la sua capacità di generare dinamicamente FetchXML in base ai dati di input.

Nel seguente esempio, cerca account tramite un valore fornito dall'utente e disponibile come borsa UFX tramite la variabile XPath $input . Si notino le direttive if e value UFX sull'elemento condition .

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

Se la NameFilter proprietà nella borsa di input contenesse %city%, la condizione FetchXML prodotta eseguita da Dynamics 365 apparirebbe così.

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

Chiavi, valori e metadati

Un contenitore UFX contiene chiavi e valori, in cui alcuni valori hanno più metadati per descriverli.

Un esempio potrebbe essere un valore di tipo lookup (EntityReference). Quando viene eseguita una query da Dynamics 365 tramite FetchXML, restituisce il nome logico dell'entità e il nome visualizzato formattato del record. La borsa UFX conserva queste informazioni aggiuntive come metadati associati al valore primario.

Serializzato in JSON, un lookup con metadati è simile al seguente:

{
    "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 sui dati di Dynamics 365

Quando digiti dati in una borsa UFX, una query UFX può vederli in un formato strutturato e usare XPath per attraversare i dati e selezionare i valori.

Un'espressione XPath specificata in una direttiva UFX vede i dati nel contenitore in modo simile alla struttura del contenitore in formato serializzato XML. Tuttavia, i dati vengono archiviati in oggetti .NET in memoria (in istanze di Entity e EntityCollection tipi) e non in documenti XML.

Riferimento al tipo UFX

Tutti i tipi UFX supportano i ufx-type metadati e ufx-formatvalue di . La tabella seguente descrive metadati aggiuntivi per ogni tipo.

Direttive di query UFX

Usa le direttive UFX sulle proprietà del bag e sugli elementi XML di una query FetchXML.

Direttive UFX bag

Direttive FetchXML UFX

Funzioni di UFX XPath

UFX aggiunge molte nuove funzioni oltre a quelle disponibili nativamente in XPath.

data/ora()

• datetime(): Restituisce l'ora corrente in UTC.

lista()

• list(bag | list, ...[bag | list]): Prende un numero di bag valori o list come input e li appiattisce in un singolo list.

lookup-to-list()

• lookup-to-list(lookup, ...[lookup]): Prende diversi lookup valori, converte ciascun valore in a bag con il ufx-id set di metadati e ufx-logicalname e li appiattisce in un unico list.

opzione-da-list()

• option-to-list(option, ...[option]): Prende diversi option valori, converte ogni valore in un bag con una sola option proprietà e li appiattisce in un unico list.

ordine()

• order(list, string, bool): Ordina una lista tramite una proprietà in ciascun bag. Specificare la proprietà nel secondo argomento e specificare l'ordine discendente nel terzo argomento.
• order(list, list): Ordina una lista tramite più ordini di ordinamento specificati come lista nel secondo argomento. Ognuno bag nella seconda lista può avere una name proprietà e descending .

iif()

• iif(any, any, any): Se il primo argomento è vero, restituisce il secondo argomento. Altrimenti, restituisce il terzo argomento.

Variabili XPath UFX

Risorse aggiuntive

Informazioni e personalizzazione della corrispondenza delle risorse in Universal Resource Scheduling