Provedores de dados de tabela virtual personalizados

Usando o SDK de Dados do Microsoft Dataverse, os desenvolvedores de .NET podem 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 Criar, Atualizar, Recuperar, RecuperarMultipla e Excluir . 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

Em vez de criar um provedor de fonte de dados personalizado, considere adaptar sua 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 usando o Provedor de Dados OData v4 padrão fornecido, que dá suporte a operações CRUD. O mecanismo para adicionar essa interface REST varia de acordo com a tecnologia de 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

Você pode criar duas categorias gerais de provedores de dados usando os assemblies do SDK de dados de tabela virtual: genérico ou direcionado. A tabela a seguir descreve essas abordagens e as corresponde ao modelo de desenvolvimento do provedor de dados mais adequado para cada abordagem.

Categoria Modelo de desenvolvimento Descrição
Genérico Provedor "Bare metal" Esses provedores convertem expressões de consulta FetchXML com flexibilidade para a solicitação associada à fonte de dados externa e retornam os registros resultantes. Você pode reutilizar esse provedor para todas as instâncias desse tipo de fonte de dados. Essa abordagem é a mais geral, mas é mais complicada de desenvolver. Se o esquema da fonte de dados for alterado, você só precisará remapear as tabelas virtuais afetadas.
Direcionado Provedor LINQ para esquema conhecido Esse provedor se limita a traduzir consultas para a chamada LINQ associada a uma instância de fonte de dados conhecida e já existente. A fonte de dados deve ser um provedor LINQ, conforme descrito no artigo Habilitando 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, você deverá atualizar e recompilar o provedor de dados.

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

Para criar uma solução de provedor de dados de tabela virtual que você pode importar para seus aplicativos do Dataverse, conclua as seguintes etapas:

  1. Desenvolva a DLL de plug-in do provedor de dados personalizado ou o conjunto de DLLs.
  2. Registre o provedor de dados personalizado no seu serviço do 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.

Para obter mais informações, consulte 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, escreva o provedor de dados como um plug-in que você registra nos eventos Create, Update, Retrieve, RetrieveMultiple e Delete . Cada evento inclui informações no contexto de execução que descrevem 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 funcione 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. O Dataverse retorna esse resultado 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 ajuda você a converter os dados retornados nos tipos apropriados Entity ou EntityCollection esperados pela plataforma Dataverse.

Exceções do provedor de dados

Se o código não conseguir obter o resultado esperado, gere 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 de 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, ele contém uma combinação de cláusula inválida ou um operador de comparação sem suporte.
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

Ao contrário de um plug-in comum, use a ferramenta PRT (Ferramenta de Registro de Plug-in) para registrar o assembly e os plug-ins em cada evento. Não registre etapas específicas. Seu plug-in é executado no estágio 30, o estágio central da transação principal da operação, que não está disponível para etapas normais de plug-in. Em vez de registrar etapas, configure seu provedor de dados usando a tabela 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.

Ao configurar as definições para sua tabela virtual, registre seus plug-ins usando o PRT e defina os dados de configuração corretos na tabela EntityDataProvider . Sua tabela virtual começa a responder às solicitações.

Para obter mais informações, consulte Criando o 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 artigos 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