Estender Universal Resource Scheduling con Universal FetchXML

Artigo
02/25/2022

UFX é un idioma de consulta avanzada que lle permite consultar datos utilizando FetchXML dinámico, formular e preparar os datos resultantes para o seu consumo pola solución Universal Resource Scheduling (URS). Este idioma de consulta permítelle crear consultas personalizados para personalizar e estender o panel de programación e os filtros do asistente de programación para satisfacer as necesidades empresariais únicas da organización.

UFX consta de dous compoñentes do contedor UFX e a consulta UFX.

Contedor UFX simple

Un contedor UFX contén datos escritos estáticos. En memoria, está representado como un dicionario con claves e valores. Non se pode poñer en serie en JSON e XML. Escribir os datos permite que unha Consulta UFX consulte datos e que a IU do cliente se ligue a ela.

Por motivos de prácticos e de desempeño, o contedor en memoria aplícase enriba do obxecto Entity de SDK de aplicacións de Dynamics 365.

Contedor de exemplo que contén dous valores.

En memoria:

key	valor	tipo
Nome	Xoán	cadea
idade	36	ent

En JSON:

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

En XML:

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

Tipos de UFX admitidos

Un contedor UFX pode conter valores de varios tipos. Clasifícanse en tres clases de tipo:

Categoría	Valor
Tipos simples	`bool (Boolean)`, `int (Int32)`, `long (Int64)`, `double (Double)`, `decimal (Decimal)`, `datetime (DateTime)`, `guid (Guid)`, `string (String)` Tipos sinxelos específicos de Dynamics 365: `money (Money)`, `option (OptionSet)`, `lookup (EntityReference)`
Outros contedores	`bag (Entity)`
Lista de contedores	`list (EntityCollection)`

Este é un contedor JSON de exemplo que contén máis tipos:

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

O mesmo contedor en 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>

Introdución a consultas de UFX

As consultas de UFX escríbense como contedores UFX baseados en XML. As propiedades do contedor poden conter directivas de UFX para consultar datos dinamicamente. Unha Consulta de UFX execútase en obxectos en memoria, non XML. Só as directivas se escriben en XML. O seu resultado pode poñerse en serie en JSON ou XML.

A seguinte Consulta de UFX define a propiedade de accounts no contedor coa directiva de UFX source. Isto provoca que o FetchXML inserido sexa executado por Dynamics 365 e a propiedade accounts se converta nunha lista de contedores ou unha EntityCollection, sendo cada contedor unha instancia dun rexistro de conta de 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>

Unha consulta de UFX procésase de forma secuencial e pode conter moitos consultas de FetchXML.

Este é un fragmento do resultado da Consulta de UFX anterior posta en serie en XML. Observe que algúns valores teñen metadatos que os describen máis

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

A directiva select de UFX colle unha expresión XPath que selecciona valores do contedor actual.

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

O contedor resultante en XML:

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

O mellor aspecto dunha Consulta de UFX é súa capacidade para xerar dinamicamente FetchXML baseándose nos datos de entrada.

No exemplo que aparece a continuación, buscamos segundo un valor fornecido polo usuario e dispoñible como un contedor UFX a través de a variable $input de XPath. Observe as directivas de UFX se e valor no 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 a propiedade NameFilter no contedor de entrada incluía %city%, a condición de FetchXML producida executada por Dynamics 365 tería este aspecto.

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

Claves, valores e metadatos

Un contedor UFX contén claves e valores, e algúns valores teñen metadatos adicionais para describilo mellor.

Por exemplo pode ser un valor de tipo lookup (EntityReference). Cando Dynamics 365 recibe unha consulta a través FetchXML, devolverá o nome lóxico da entidade e tamén o nome para mostrar formatada do rexistro. O contedor de UFX conserva esta información adicional como metadatos anexar ao valor principal.

Serializado en JSON, un lookup con metadatos ten este aspecto:

{
    "primarycontactid": "7e6e39dd-34a1-e611-8111-00155d652f01",
    "primarycontactid@ufx-type": "lookup",
    "primarycontactid@ufx-logicalname": "contact",
    "primarycontactid@ufx-formatvalue": "Susanna Stubberod (sample)"
}

En XML:

<primarycontactid ufx-type="lookup" ufx-formatvalue="Susanna Stubberod (sample)" ufx-logicalname="contact">7e6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>

XPath sobre datos de Dynamics 365

Escribir os datos nun contedor de UFX, permite que unha Consulta de UFX o vexa nun formato estruturado e utilice XPath para atravesar os datos e seleccionar valores nel.

Unha expresión XPath especificada nunha directiva de UFX ve os datos nun contedor semellante á estrutura do contedor en forma serializada de XML. No entanto, os datos almacénanse en obxectos .NET en memoria (en instancias tipo Entity e EntityCollection) e non en documentos XML.

Apéndice A: referencia de tipo UFX

Nota: todos os tipos de UFX admiten os metadatos de ufx-type e ufx-formatvalue. Os metadatos adicionais están descritos xunto a cada tipo na táboa seguinte.

Nome do UFX	Código do tipo de atributo	Nome de .NET	Metadatos de UFX
booleano	Booleano	Booleano
ent	Enteiro	Int32
longo	BigInt	Int64
dobre	Dobre	Dobre
decimal	Decimal	Decimal
dataHora	Data e hora	Data e hora
guid	Uniqueidentifier	Guid
cadea	Memorando	Cadea
diñeiro	Diñeiro	Diñeiro
opción	Lista despregable	OptionSetValue
busca	Buscar	EntityReference	`ufx-logicalname`
contedor	N/D	Entidade	`ufx-id` `ufx-logicalname`
list	N/D	EntityCollection
N/D	N/D	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Apéndice B: Directivos da consulta de UFX

As directivas de UFX poden usarse en propiedades de contedor e nos elementos de XML dunha consulta de FetchXML.

Directivas de contedor de UFX

Atributo	Value	Descrición
`ufx:if`	XPath	Proba a expresión de XPath e só procesa a propiedade se proba devolve verdadeiro
`ufx:source`	`fetch`	Executa o elemento inserido de XML de `<fetch>` e atribúe o resultado á propiedade
`ufx:select`	XPath	Executa a expresión XPath e atribúe o resultado á propiedade A realizar consultas para un `bag` ou `list` un `bag` opcional secundario en forma de XML pode especificarse para transformar o resultado da expresión XPath

Directivas de FetchXML de UFX

Elemento	Atributo	Value	Descrición
Todos os elementos	`ufx:if`	XPath	Proba a expresión XPath e só emite o elemento de XML se a proba se realiza correctamente
`ufx:apply`	`select`	XPath	Repítese no conxunto de nós devoltos pola expresión XPath e produce os elementos de XML secundarios e unha vez para cada nó
`ufx:value`	`select`	XPath	Executa a expresión XPath e produce o resultado no elemento de XML actual
`ufx:value`	`attribute`	nome do atributo	Atribúe o resultado da expresión XPath ao nome de atributo especificado no elemento XML actual

Apéndice C: funcións de XPath de UFX

UFX engade varias funcións novas ademais das que xa están dispoñibles de maneira nativa en XPath.

datetime()

datetime(): Devolve á hora actual en UTC

list()

list(bag | list, ...[bag | list]): colle un número de valores de bag ou list como entrada e simplifícaos nunha list única

lookup-to-list()

lookup-to-list(lookup, ...[lookup]): colle varios valores de lookup, converte cada un deles a un bag co conxunto de metadatos ufx-id e ufx-logicalname e simplifícaos nunha list única

option-to-list()

option-to-list(option, ...[option]): colle varios valores de option, onverte cada un deles nun bag cunha propiedade de option e simplifícaos nunha list única

orde()

orde(lista, cadea, booleano): ordea unha lista por propiedade en cada contedor. A propiedade está especificada no argumento 2, a orde descendente esttá especificada no argumento 3.
pedido(lista, lista): ordea unha lista de por varias ordes de clasificación como unha lista no argumento 2. Cada bag na segunda lista pode ter unha propiedade name e descending

iif()

if(calquera, calquera, calquera): Se o argumento 1 é verdadeiro, devolve o argumento 2, en caso contrario devolve o argumento 3

Apéndice D: Variables de XPath de UFX

Nome	Descrición
$input	Un `bag` dispoñible para a Consulta de UFX con valores de entrada
$null	Unha constante nula. Seleccionar `$null` nunha propiedade elimina a propiedade do contedor
$current	A referencia ao contedor actual está a ser procesada pola Consulta de UFX

Consulte tamén

Comprensión e personalización da coincidencia de recursos en Universal Resource Scheduling

Notas da versión de extensibilidade de Universal Resource Scheduling

Hinweis

Pode indicarnos as súas preferencias para o idioma da documentación? Realice unha enquisa breve. (teña en conta que esa enquisa está en inglés)

Esta enquisa durará sete minutos aproximadamente. Non se recompilarán datos persoais (declaración de privacidade).

Compartir por