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:

chiave valore tipo
nome John corda
età 36 Int

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:

Categoria Valore
Tipi semplici bool (Boolean), int (Int32), long (Int64), double (Double)decimal (Decimal), datetime (DateTime), , guid (Guid)string (String)
Tipi semplici specifici di Dynamics 365: money (Money), option (OptionSet), lookup (EntityReference)
Altre borse bag (Entity)
Elenco delle borse list (EntityCollection)

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.

Nome UFX Codice tipo di attributo Nome .NET Metadati UFX
Bool Booleano Booleano
Int Numero intero Int32
lungo BigInt Int64
doppio Doppio Doppio
decimale Decimale Decimale
data e ora Data e ora Data e ora
guida Identificatore univoco Guid
corda Memo Stringa
denaro Moneta Moneta
opzione Elenco di selezione OptionSetValue
Ricerca Ricerca EntityReference ufx-logicalname
sacco Non disponibile Entità ufx-id
ufx-logicalname
lista Non disponibile Collezione di entità
Non disponibile Non disponibile Valore aliased ufx-aliasentity
ufx-aliasattribute

Direttive di query UFX

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

Direttive UFX bag

Attributo Valore Descrizione
ufx:if XPath Verifica l'espressione XPath ed elabora la proprietà solo se il test restituisce true
ufx:source fetch Esegue l'elemento XML inline <fetch> e assegna il risultato alla proprietà
ufx:select XPath Esegue l'espressione XPath e assegna il risultato alla proprietà
Quando si interroga un bag o list, puoi specificare un figlio bag opzionale in forma XML per trasformare il risultato dell'espressione XPath

Direttive FetchXML UFX

Elemento Attributo Valore Descrizione
Tutti gli elementi ufx:if XPath Testa l'espressione XPath e emette l'elemento XML solo se il test ha successo
ufx:apply select XPath Esegue un ciclo sul set di nodi restituito dall'espressione XPath e restituisce gli elementi XML figlio una volta per ogni nodo
ufx:value select XPath Esegue l'espressione XPath e restituisce il risultato nell'elemento XML corrente
ufx:value attribute Nome attributo Assegna il risultato dell'espressione XPath al nome dell'attributo specificato nell'elemento XML corrente

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

Nome Descrizione
$input A bag disponibile per la query UFX con valori di input
$null Costante Null. Selezionare $null su una proprietà la rimuove dalla bag
$current Riferimento all'attuale bag che la query UFX sta elaborando

Risorse aggiuntive

Informazioni e personalizzazione della corrispondenza delle risorse in Universal Resource Scheduling

  • Last updated on