Universal FetchXML para estender o Universal Resource Scheduling

O Universal FetchXML (UFX) é uma linguagem de consulta avançada que permite consultar dados usando FetchXML dinâmico, formatar e preparar os dados resultantes para consumo pela solução Universal Resource Scheduling (URS). Essa linguagem de consulta permite que você crie consultas personalizadas para personalizar e estender o painel de agendamento e os filtros do assistente de agendamento para atender às necessidades comerciais exclusivas da organização.

O UFX consiste em dois componentes: UFX bag e UFX query.

Bolsa UFX simples

Uma bolsa UFX contém dados de tipo estático. Na memória, ele modela um dicionário com chaves e valores. Ele pode ser serializado para JSON e XML. Ter os dados digitados permite que uma consulta UFX consulte dados dele e a interface do usuário do cliente se associe a ele.

Por motivos práticos e de desempenho, o pacote na memória é implementado sobre o objeto SDK Entity dos aplicativos do Dynamics 365.

Saco de amostras contendo dois valores.

Na memória:

chave	valor	tipo
nome	John	cadeia
idade	36	int

Em JSON:

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

Em XML:

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

Tipos suportados pela UFX

Uma bolsa UFX pode conter valores de vários tipos. Eles são categorizados em três classes de tipo:

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

Aqui está um exemplo de pacote JSON contendo mais 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 saco em 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>

Consultas UFX

As consultas UFX são gravadas como UFX Bags baseadas em XML. As propriedades no repositório podem conter diretivas UFX para consultar dados dinamicamente. Uma consulta UFX é executada em objetos na memória, não em XML. Somente as diretivas são escritas em XML. Sua saída pode ser serializada para JSON ou XML.

A consulta UFX a seguir define a accounts propriedade no recipiente com a source diretiva UFX. Como resultado, o Dynamics 365 executa o FetchXML embutido, preenchendo a accounts propriedade com uma lista de recipientes. Um EntityCollection em que cada recipiente representa um registro de conta individual do 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>

Uma consulta UFX é processada sequencialmente e pode conter muitas consultas FetchXML.

Aqui está um trecho do resultado da consulta UFX anterior serializada para XML. Observe que alguns valores têm metadados que os descrevem melhor.

<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 select diretiva UFX usa uma expressão XPath que seleciona valores do recipiente atual.

<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 saco resultante em XML:

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

Certamente, o aspecto mais poderoso de uma consulta UFX é sua capacidade de gerar dinamicamente FetchXML com base nos dados de entrada.

No exemplo a seguir, pesquisamos contas por um valor fornecido pelo usuário e disponível como uma bolsa UFX por meio da variável XPath $input . Observe as diretivas if e value da UFX no condition elemento.

<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 NameFilter propriedade no recipiente de entrada contivesse %city% a condição FetchXML produzida executada pelo Dynamics 365, teria esta aparência.

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

Chaves, valores e metadados

Um saco UFX contém chaves e valores, onde alguns valores têm mais metadados para descrevê-los.

Um exemplo pode ser um valor do tipo lookup (EntityReference). Quando consultado do Dynamics 365 por meio do FetchXML, ele retorna o nome lógico da entidade e o nome de exibição formatado do registro. O saco UFX preserva essas informações adicionais como metadados anexados ao valor primário.

Serializado para JSON, um lookup com metadados tem esta aparência:

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

Em XML:

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

XPath sobre dados do Dynamics 365

Ter os dados em um UFX Bag digitados permite que uma consulta UFX os veja em um formato estruturado e use XPath para percorrer os dados e selecionar valores deles.

Uma expressão XPath especificada em uma diretiva UFX vê os dados no repositório semelhante à estrutura do repositório no formato serializado em XML. No entanto, os dados são armazenados em objetos .NET na memória (em instâncias de Entity e EntityCollection tipos) e não em documentos XML.

Referência de tipo UFX

Todos os tipos UFX suportam os ufx-type metadados e ufx-formatvalue . Metadados adicionais são descritos ao lado de cada tipo.

Nome UFX	Código do tipo de atributo	Nome do .NET	Metadados UFX
Bool	booleano	booleano
int	Número Inteiro	Int32
Longas	BigInt	Int64
duplo	Duplo	Duplo
decimal	Decimal	Decimal
datetime	Data e Hora	Data e Hora
Guid	Identificador exclusivo	GUID
cadeia	Memorando	fio
dinheiro	Quantia	Quantia
Opção	Lista de seleção	Valor do Conjunto de Opções
pesquisa	Busca	EntityReference	`ufx-logicalname`
saco	Não aplicável	Entidade	`ufx-id` `ufx-logicalname`
lista	Não aplicável	Coleção de entidades
Não aplicável	Não aplicável	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Diretivas de consulta UFX

As diretivas UFX podem ser usadas em propriedades de recipiente e em elementos XML de uma consulta FetchXML.

Diretivas de bolsas UFX

Atributo	Valor	Descrição
`ufx:if`	XPath	Testa a expressão XPath e só processa a propriedade se o teste retornar true
`ufx:source`	`fetch`	Executa o elemento XML embutido `<fetch>` e atribui o resultado à propriedade
`ufx:select`	XPath	Executa a expressão XPath e atribui o resultado à propriedade Ao consultar um `bag` ou `list` um filho `bag` opcional no formato XML pode ser especificado para transformar o resultado da expressão XPath

Diretivas UFX FetchXML

Elemento	Atributo	Valor	Descrição
Todos os elementos	`ufx:if`	XPath	Testa a expressão XPath e só emite o elemento XML se os testes forem bem-sucedidos
`ufx:apply`	`select`	XPath	Executa loops sobre o conjunto de nós retornado pela expressão XPath e gera os elementos XML filho uma vez para cada nó
`ufx:value`	`select`	XPath	Executa a expressão XPath e gera o resultado no elemento XML atual
`ufx:value`	`attribute`	nome do atributo	Atribui o resultado da expressão XPath ao nome do atributo especificado no elemento XML atual

Funções do UFX XPath

O UFX adiciona muitas novas funções além das disponíveis nativamente no XPath.

datetime()

datetime(): Retorna a hora atual em UTC

lista()

lista(saco | lista, ... [bag | list]): Pega um número de valores or baglist como entrada e os nivela em um único list

procurar-para-lista()

procurar-para-list(pesquisar, ... [lookup]): pega vários lookup valores, converte cada um deles em um bag com o ufx-id conjunto de metadados e ufx-logicalname os nivela em um único list

opção para listar()

opção para listar(opção, ... [option]): pega vários option valores, converte cada um deles em um bag com uma única option propriedade e os nivela em um único list

ordem()

order(list, string, bool): ordena uma lista por uma propriedade em cada saco. A propriedade é especificada no argumento 2, a decrescente é especificada no argumento 3.
order(list, list): ordene uma lista por várias ordens de classificação especificadas como uma lista no argumento 2. Cada bag um na segunda lista pode ter uma name propriedade e descending

iif()

iif(qualquer, qualquer, qualquer): Se o argumento 1 for verdadeiro, retorna o argumento 2, caso contrário, retorna o argumento 3

Variáveis UFX XPath

Nome	Descrição
$input	A `bag` disponível para a consulta UFX com valores de entrada
$null	Uma constante nula. Selecionar `$null` uma propriedade remove a propriedade do recipiente
$current	Referência ao recipiente atual que a consulta UFX está processando

Recursos adicionais

Noções básicas e personalização da correspondência de recursos no Universal Resource Scheduling

Comentários

Esta página foi útil?

Last updated on 2025-10-10

Compartilhar via

Universal FetchXML para estender o Universal Resource Scheduling

Bolsa UFX simples

Tipos suportados pela UFX

Consultas UFX

Chaves, valores e metadados

XPath sobre dados do Dynamics 365

Referência de tipo UFX

Diretivas de consulta UFX

Diretivas de bolsas UFX

Diretivas UFX FetchXML

Funções do UFX XPath

datetime()

lista()

procurar-para-lista()

opção para listar()

ordem()

iif()

Variáveis UFX XPath

Recursos adicionais

Comentários

Recursos adicionais