Compartilhar via

Provedores de dados de tabela virtual personalizados

Usando o SDK de Dados do Microsoft Dataverse, os desenvolvedores do .NET têm a opção de criar provedores de dados de tabela virtual personalizados para ajudar a integrar tipos de fonte de dados externos que não têm suporte por um provedor de dados existente. Cada provedor de dados é composto por um conjunto reutilizável de plug-ins do Dataverse que implementam as operações CRUD com suporte. Para cada tabela virtual, também conhecida como uma entidade virtual, os desenvolvedores podem criar plug-ins e registrá-los representando cada uma das operações Create, Update, Retrieve, RetrieveMultiple e Delete . Esta seção fornece informações fundamentais sobre provedores de dados e abordagens para o desenvolvimento de provedores personalizados, incluindo código de exemplo.

Observação

Como alternativa à criação de um provedor de fonte de dados personalizado, você deve considerar a adaptação da fonte de dados a um provedor de dados existente. Por exemplo, se você criar uma interface OData v4 para sua fonte de dados externa, poderá acessá-la diretamente com o Provedor de Dados OData v4 padrão fornecido, que também dá suporte a operações CRUD. O mecanismo de adição dessa interface REST varia de acordo com a tecnologia do serviço de dados subjacente, por exemplo, consulte WCF Data Services 4.5. O OData tem amplo suporte do setor, com uma ampla gama de ferramentas dedicadas e tecnologias compatíveis.

Pré-requisitos

Os provedores de dados personalizados exigem recursos de desenvolvimento substanciais para criar e manter. Você deve ter conhecimento fundamental das seguintes áreas:

O Microsoft.Xrm.Sdk.Data.dll assembly está disponível como um pacote NuGet: Microsoft.CrmSdk.Data

Categorias de provedores

Há duas categorias gerais de provedores de dados que você pode criar usando os conjuntos de SDK de dados de tabela virtual: genéricos ou específicos. A tabela a seguir descreve essas abordagens e as compara com o modelo de desenvolvimento do provedor de dados mais adequado para essa abordagem.

Categoria Modelo de desenvolvimento Descrição
Genérico Provedor "Bare metal" Esses provedores podem converter expressões de consulta FetchXML de maneira flexível para a solicitação associada à fonte de dados externa e retornar os registros resultantes. Esse provedor pode ser reutilizado para todas as instâncias desse tipo da fonte de dados. Essa abordagem é a mais geral, mas é mais complicada de desenvolver. Se o esquema da fonte de dados for alterado, as tabelas virtuais afetadas só deverão ser remapeadas.
Direcionado Provedor LINQ para esquema conhecido Esse provedor converte apenas consultas na chamada LINQ associada para uma instância da fonte de dados conhecida e existente. A fonte de dados deve ser um provedor LINQ, conforme descrito no tópico Habilitação de uma fonte de dados para consulta LINQ. Essa abordagem é limitada a uma instância da fonte de dados específica, mas requer muito menos codificação. Se o esquema da fonte de dados for alterado, o provedor de dados deverá ser atualizado e recompilado.

O Provedor de Dados OData v4 padrão e o Provedor de Dados do Azure Cosmos DB são exemplos de provedores genéricos.

Etapas para usar um provedor de dados personalizado

Há várias etapas necessárias para criar uma solução de provedor de dados de tabela virtual que pode ser importada para seus aplicativos do Dataverse:

  1. Desenvolva a DLL de plug-in do provedor de dados personalizado (ou conjunto de DLLs).
  2. Registre o provedor de dados personalizado com o seu serviço Dataverse usando a Ferramenta de Registro de Plug-in (PRT).
  3. Crie uma nova solução do provedor de dados.
  4. Personalize a tabela de fonte de dados para refletir seu tipo de dados ou instância específica.
  5. Exporte a solução do provedor de dados personalizada.

Mais informações: Exemplo: provedor de tabela virtual personalizado com operações CRUD

Desenvolvimento do plug-in

Como as tabelas virtuais dão suporte a operações CRUD, você escreverá o provedor de dados na forma de um plug-in registrado nos eventos Create, Update, Retrieve, RetrieveMultiple e Delete . Cada evento respectivo incluirá informações no contexto de execução que descreve o tipo de dados a serem retornados.

Acontecimento Contexto de execução
Recuperar Descreve qual tabela recuperar, bem como as colunas e quaisquer tabelas relacionadas a serem incluídas.
RetrieveMultiple Contém um QueryExpression objeto que define a consulta. A estrutura contém uma classe QueryExpressionVisitor projetada para inspecionar diferentes partes da árvore de expressão da consulta.

Para ambos os eventos, você deve:

  1. Converta as respectivas informações no contexto de execução em uma consulta que funcionará para sua fonte de dados externa.
  2. Recupere os dados do sistema externo.
  3. Para Recuperar, converta os dados em um Entity; caso contrário, para RetrieveMultiple, converta-os em um EntityCollection. Esse resultado é retornado por meio da plataforma Dataverse para o usuário que executa a consulta.

As classes no Microsoft.Xrm.Sdk.Data namespace fornecem uma estrutura para ajudar a mapear as informações de consulta do Dataverse do contexto de execução em uma consulta no formato apropriado para sua fonte de dados externa. Essa estrutura ajudará você a converter os dados retornados nos tipos apropriados Entity ou EntityCollection esperados pela plataforma Dataverse.

Exceções do provedor de dados

Se, por qualquer motivo, seu código não puder alcançar o resultado esperado, você deverá lançar o erro apropriado. O Microsoft.Xrm.Sdk.Data.Exceptions namespace contém as seguintes classes de exceção, derivadas de SdkExceptionBase, que você pode usar para esta finalidade:

Classe Exception Descrição
AuthenticationException Ocorreu um erro durante a autenticação de segurança para o serviço da fonte de dados externa; por exemplo, o status HTTP 401 recebido do serviço de dados externo. Normalmente ocorre porque o usuário atual não tem privilégios adequados ou as informações de conexão no EntityDataSource associado estão incorretas.
EndpointException A configuração do ponto de extremidade na tabela de fonte de dados é inválida ou o ponto de extremidade não existe.
GenericDataAccessException Um erro geral de acesso a dados, usado quando o erro não é mapeado para uma exceção mais específica.
InvalidMetadataException
InvalidQueryException A consulta especificada é inválida; por exemplo, uma combinação de cláusula inválida ou um operador de comparação incompatível.
ObjectNotFoundException O registro especificado na fonte de dados externa não existe.
TimeoutException A operação externa não foi concluída dentro do tempo permitido; por exemplo, o resultado de um status HTTP 408 do serviço de dados externo.

Registro do plug-in

Diferente de um plug-in comum, você usará exclusivamente a Ferramenta de Registro de Plug-in (PRT) para registrar o conjunto e os plug-ins para cada evento. Você não registrará etapas específicas. O plug-in será executado no estágio 30, o estágio principal da transação principal da operação que não está disponível para etapas comuns de plug-in. Em vez de registrar etapas, você configurará seu provedor de dados usando as tabelas a seguir.

Tabela Descrição
EntityDataProvider Define os plug-ins a serem usados para cada evento e o nome lógico da fonte de dados.

Quando as definições da tabela virtual estiverem configuradas, seus plug-ins serão registrados usando o PRT e os dados de configuração corretos forem definidos na tabela EntityDataProvider , sua tabela virtual começará a responder às solicitações.

Mais informações: Criando um provedor de dados e adicionando plug-ins ao provedor

Depuração de plug-ins

Um provedor de tabela virtual personalizado é um tipo de plug-in. Use as informações nestes tópicos para depurar plug-ins para provedores de tabelas virtuais personalizados: Depurar plug-ins e Tutorial: Depurar um plug-in.

Consulte também

Introdução às tabelas virtuais
Considerações de API de tabelas virtuais
Exemplo: plug-in genérico do provedor de dados para tabela virtual

  • Last updated on