Construtor de consultas FetchXML

<FetchXmlBuilder> edita uma consulta FetchXML sem que ninguém escreva FetchXML. Ela cobre as partes da linguagem que as pessoas realmente buscam — a tabela, as colunas que ela retorna, como as linhas são ordenadas e uma árvore de filtros de condições e grupos aninhados — e junta tabelas relacionadas, agrega e executa o que construiu.

Não é a mesma coisa que FetchXMLBuilder

Esta página é sobre o componente. FetchXMLBuilder é a classe C# que compõe o mesmo XML em código, para um chamador do lado do servidor que constrói uma consulta manualmente. Eles produzem a mesma coisa e nenhum precisa do outro.

Metadados são obrigatórios, não são opcionais

Cada tabela, coluna e relacionamento é escolhido a partir do que o ambiente realmente tem. Isso é deliberado: um nome lógico digitado manualmente produz FetchXML que analisa perfeitamente e depois falha no Dataverse, que é o pior tipo de erro para alguém entregar. O usePowerPortalsProFetchXmlMetadata gancho conecta o construtor aos endpoints de metadados cacheados do framework, então os selecionadores compartilham tudo o que as grades na mesma página já buscaram.

Blazor não precisa de fiação: <FetchXmlBuilder> resolve o próprio serviço de metadados do portal e lê os mesmos endpoints em cache, então seus selecionadores também compartilham o que as grades na página já foram buscadas.

As idas e voltas de consultas

O construtor analisa o FetchXML em um modelo de documento e o grava novamente. Qualquer coisa para a qual ele não tenha editor — um atributo de uma versão mais recente da plataforma, um elemento escrito por outra ferramenta — é executada sem ser tocada, em vez de ser descartada no carregamento, então abrir uma consulta no editor e salvá-la nunca custa silenciosamente parte dela.

O que isso significa para uma consulta salva

A formatação não é preservada. Indentação e citação de atributos são normalizadas na saída, então uma consulta re-salva pelo construtor é a mesma consulta e não o mesmo texto.

Fornecendo uma consulta

Existem três formas de entrar, e todas passam pelo mesmo leitor:

• A value hélice. Forneça para onChange um componente controlado, ou use defaultValue e deixe o construtor ser dono do estado.
• O painel FetchXML. Cole ou digite uma consulta e o editor se reconstrói a partir dela cerca de um segundo depois que você para de digitar.
• Uma visualização salva. Comece a partir de uma visualização no cabeçalho Filtros que lista as visualizações da tabela e pega toda a consulta da que você escolheu. É uma cópia — nada é escrito de volta na visualização.

O que chegar é verificado primeiro. XML malformado é reportado com sua linha e coluna, assim como qualquer coisa que faça o editor mostrar algo diferente do que foi escrito — um operador ou tipo de link que ele não conhece, uma consulta que não nomeia nenhuma tabela. Esses são recusados imediatamente e a consulta já na tela é deixada como está. Todo o resto é reportado e ainda aplicado: um elemento ou atributo com erros ortográficos, duas tabelas compartilhando um alias, uma leitura de condição de um alias que nada declara.

Tabelas relacionadas

Uma junção é adicionada a partir do seletor de relacionamento, então as from colunas e to vêm da relação em vez da memória. O que uma junção pode então contribuir depende do seu tipo:

• Retornando tipos — inner, outer e matchfirstrowusingcrossapply — trazem as colunas da tabela relacionada de volta, para que suas colunas possam ser projetadas, ordenadas e comparadas.
• Tipos de filtragem — exists, in, any, not any e all — retornam a linha no máximo uma vez e nenhuma das colunas relacionadas. O editor elimina o alias quando você muda para um, então o nome fica livre para outra junção.
• Não tem linha relacionada como um preset em vez de um tipo de link: o FetchXML não tem nenhum para ele, então o editor escreve a junção externa e o teste nulo na chave unida que a plataforma espera, mantendo os dois em sintonia.

Sobre "todos"

O all FetchXML não significa o que seu nome sugere — ele corresponde a linhas que têm linhas relacionadas das quais nenhuma satisfaz o filtro, e not all é documentado como equivalente a any. Cada tipo é rotulado pelo que faz, e não pelo nome, e uma ação Invert condições em um grupo de filtro expressa a leitura que as pessoas geralmente desejam.

Trabalhando com a árvore de filtros

Um filtro é um grupo de condições combinadas com e / ou ou, e grupos se encaixam uns dentro dos outros até a profundidade que a consulta precisar. Quatro coisas na árvore valem a pena saber, porque cada uma responde a uma pergunta que o FetchXML torna estranha de fazer:

• Inverter substitui toda condição em um grupo por seu oposto e troca e para ou. Existe para um tipo de link: all não significa "toda linha relacionada corresponde" — ele corresponde a linhas cujas linhas relacionadas nenhuma satisfaz o filtro — então expressar a leitura intuitiva significa inverter primeiro. É oferecido apenas quando toda condição abaixo tem um verdadeiro oposto; a maioria dos operadores de data não tem nenhuma, e inverter parte de um filtro pareceria invertida e corresponderia às linhas erradas.
• Compare com uma coluna testa uma coluna contra outra em vez de contra um valor — o . do valueofFetchXML Seis operadores permitem isso e a plataforma recusa o restante completamente, então a lista de operadores se estreita enquanto a linha está nesse modo. Candidatos vêm de todas as tabelas juntas, já que uma condição chega a uma coluna relacionada nomeando o alias da junção.
• A dica de união executa um grupo de OR como uma união de consultas separadas, em vez de uma consulta única com um OR entre tabelas — uma forma SQL não consegue indexar bem. Vale a pena definir quando as condições no grupo testam colunas em tabelas relacionadas diferentes. Uma consulta pode carregar apenas uma.
• Comece a partir de uma visualização e copia a consulta de uma visualização salva para o editor — sua tabela, colunas, ordenações e condições. Nada é escrito de volta na própria visualização.

Linhas que ainda não estão finalizadas

Uma condição que não corresponde ao valor que seu operador precisa é delineada, assim como um alias que é exigido e em branco, ou compartilhado com outra coluna. Os três produzem FetchXML que analisa perfeitamente e depois falha — ou retorna silenciosamente as linhas erradas — então o editor diz isso, em vez de deixá-lo para ser encontrado quando a consulta é executada. Operadores que não precisam de valor, como Contains data e Today, são completos por si só e nunca são marcados.

Consultas agregadas

Ative o Agregado na seção Colunas e cada coluna diz o que contribui — um valor calculado entre as linhas, ou o que as agrupa. As funções oferecidas se restringem ao tipo da coluna, aliases se tornam necessários e preenchidos para você, uma coluna de data agrupada ganha uma parte de data, e a ordenação muda para os aliases, porque as linhas de uma consulta agregada são grupos e valores calculados sem colunas para ordenar.

allowAggregate={false} retira o switch, para um host que lê linhas em vez de totais — uma regra avaliada um registro de cada vez, um filtro salvo, em qualquer lugar onde uma única linha de valores calculados não seria uma resposta. Ela está ausente em vez de desativada, porque nenhuma alteração na consulta a traria de volta. A única exceção é uma consulta que já agrega: ela mantém seus controles independentemente do prop configurado, então uma colada no painel FetchXML ainda pode ser editada de volta para uma consulta comum.

AllowAggregate="false" faz o mesmo no Blazor, com a mesma exceção: uma consulta que já agrega mantém seus controles, então uma colada na aba FetchXML ainda pode ser editada de volta para uma consulta comum.

Montar parte dele

Cada seção pode ser desligada, e as seções são exportadas individualmente para um layout que precisa delas em outro lugar — monte <FetchXmlBuilderProvider> e posicione os FetchXml*Section componentes você mesmo. Omitir uma seção remove sua interface, nunca o FetchXML subjacente: as colunas de uma consulta sobrevivem intactas com columns: false.

Blazor pega o mesmo conjunto de Sections registro, e as seções são componentes por si só — cascata a FetchXmlBuilderState e coloque os FetchXml*Section componentes onde o layout precisar. Esconder um remove seu editor e nunca a consulta por trás dele.

Restrição das tabelas

allowedTables Reduz o seletor de tabelas aos nomes lógicos que você listou — para uma superfície que não tem motivo para consultar todo o ambiente, como um construtor de relatórios sobre o punhado de tabelas que um portal expõe. Omita-o e todas as tabelas são oferecidas. Ele restringe o que pode ser escolhido, não o que pode ser mostrado: uma consulta que já nomeia uma tabela fora da lista mantém essa tabela em vez de ser silenciosamente reescrita, e uma tabela relacionada ainda é nomeada pelo nome de exibição sempre que uma junção a menciona. As próprias joins não são restritas, porque seguem relações — uma propriedade da tabela já escolhida.

AllowedTables é o equivalente de Blazor, e restringe o que pode ser escolhido em vez do que pode ser mostrado exatamente da mesma forma.

Executando a consulta

Fornece renderResults e o construtor faz crescer um painel de Resultados com um botão Executar, e decide quando ele pode ser pressionado: uma vez que a consulta nomeia uma tabela e suas colunas, e nenhum campo está marcado em vermelho. Exibir linhas consome um cliente de dados que o construtor deliberadamente não tem nenhum, então o resultado é seu — em um portal isso geralmente significa o próprio <MainGrid> framework sobre a consulta que ele devolve. Deixe o prop desligado e o painel não está lá.

No Blazor, o mesmo painel aparece assim que um RenderResults fragmento é fornecido, e a consulta executável que ele devolve carrega a tabela, o FetchXML e os nomes sob os quais as colunas voltam. Deixe o fragmento de fora e não há painel.

API