Proveedores de datos de entidad virtuales personalizados
Al utilizar el SDK de datos de Dynamics 365 for Customer Engagement (on-premises), los desarrolladores de .NET tienen la opción de crear proveedores de datos de entidad virtuales personalizados con el fin de integrar los tipos de orígenes de datos externos que no admite un proveedor de datos existente. Cada proveedor de datos consta de un conjunto reutilizable de complementos de Dynamics 365 for Customer Engagement (on-premises) que implementan las operaciones CRUD admitidas. (La versión inicial está limitada a las operaciones de lectura Retrieve y RetrieveMultiple.) En esta sección se ofrece información fundamental sobre los proveedores de datos y enfoques para desarrollar proveedores personalizados, incluido el código de ejemplo.
Nota
Como alternativa a la creación de un proveedor de origen de datos personalizado, debe considerar adaptar el origen de datos a un proveedor de datos existente. Por ejemplo, si crea una interfaz de OData v4 con el origen de datos externo entonces podrá acceder directamente a él con el proveedor de datos OData v4 estándar proporcionado. El mecanismo para agregar esta interfaz REST varía con la tecnología de servicio de datos subyacente, por ejemplo consulte Servicios de datos de WCF 4.5. OData es ampliamente compatible en el sector gracias a una gran variedad de herramientas dedicadas y tecnologías compatibles.
Requisitos previos
Los proveedores de datos personalizados requieren recursos de desarrollo importantes para crear y mantener. Debe tener conocimiento fundamental de las áreas siguientes:
- El esquema de origen de datos externos y las técnicas de acceso a datos asociadas. Este conocimiento de dominio es específico del tipo de origen de datos externos.
- Esquema de metadatos de Dynamics 365 for Customer Engagement (on-premises); para obtener más información, consulte Metadatos y modelos de datos en Microsoft Dynamics 365 Customer Engagement (on-premises).
- Sistema de eventos Dynamics 365 for Customer Engagement (on-premises). Para obtener más información, consulte Marco de trabajo de eventos.
- Arquitectura y desarrollo de complementos de Dynamics 365 for Customer Engagement (on-premises). Para obtener más información, consulte Desarrollo de complementos.
También se debe descargar manualmente el SDK de datos de Dynamics 365 for Customer Engagement (on-premises) o incluir el paquete de NuGet correspondiente en sus proyectos. Este SDK es compatible con Visual Studio 2015 o 2017.
Categorías de proveedores
Puede crear dos categorías generales de proveedor de datos con los ensamblados del SDK de datos de entidad virtual: genérico o específico. La tabla siguiente describe estos métodos y los enlaza con el modelo de desarrollo de proveedor de datos más adecuado para cada método.
| Categoría | Modelo de desarrollo | Descripción |
|---|---|---|
| Genérico | Proveedor "básico" | Estos proveedores pueden traducir con flexibilidad las expresiones de la consulta de FetchXML a la solicitud asociada al origen de datos externos y luego volver a las instancias de la entidad resultantes. Este tipo de proveedor puede volver a utilizarse para todas las instancias de este tipo de origen de datos. Este método es el más general, pero es más difícil de desarrollar. Si cambia el esquema del origen de datos, solo deberán reasignarse las entidades virtuales afectadas. |
| Específico | Proveedor LINQ para esquemas conocidos | Un proveedor de este tipo solo traduce las consultas de forma limitada a la llamada LINQ asociada a una instancia de origen de datos existente y conocida. El origen de datos debe ser un proveedor LINQ, tal como se explica en el tema Habilitar un origen de datos para las consultas LINQ. Este método está limitado a una instancia de origen de datos específica, pero requiere mucho menos código. Si cambia el esquema del origen de datos, el proveedor de datos debe actualizarse y generarse de nuevo. |
El proveedor de datos Odata v4 estándar y el proveedor de datos Cosmos DB son ejemplos de proveedores genéricos.
Pasos para usar un proveedor de datos personalizado
Hay varios pasos que se deben seguir para crear una solución de proveedor de datos de entidad virtual que se pueda importar a las aplicaciones de Dynamics 365 for Customer Engagement (on-premises):
- Desarrolle el complemento DLL de proveedor de datos personalizado (o conjunto de DLL).
- Registre el proveedor de datos personalizado con el servicio de Dynamics 365 for Customer Engagement (on-premises) mediante la herramienta de registro de complementos (PRT).
- Cree una solución de proveedor de datos.
- Personalice la entidad de origen de datos para reflejar el tipo de datos o instancia específica.
- Exporte la solución de proveedor de datos personalizada.
Desarrollo de complementos
Puesto que las entidades virtuales en esta versión son de solo lectura, escribirá el proveedor de datos en forma de complemento registrado en los eventos Retrieve y RetrieveMultiple. Cada evento respectivo incluye información en el contexto de ejecución que describe el tipo de datos a devolver.
| Evento | Contexto de ejecución |
|---|---|
| Recuperar | Describe qué entidad recuperar, así como los atributos y cualquier entidad relacionada que desee incluir. |
| RetrieveMultiple | Contiene un objeto QueryExpression que define la consulta. El marco contiene una clase QueryExpressionVisitor diseñada para comprobar diferentes partes del árbol de expresión de consulta. |
Para ambos eventos, debe:
- Convertir la información respectiva en el contexto de ejecución en una consulta compatible con el origen de datos externos.
- Recuperar los datos del sistema externo.
- Para Retrieve, convierta los datos en una Entity; en caso contrario, para RetrieveMultiple, conviértalos en una EntityCollection. Este resultado se devuelve a través de la plataforma de Dynamics 365 Customer Engagement (on-premises) al usuario que ejecuta la consulta.
Las clases en el espacio de nombres Microsoft.Xrm.Sdk.Data proporcionan un marco para ayudarle a asignar la información de la consulta de Dynamics 365 Customer Engagement (on-premises) desde el contexto de ejecución a una consulta en el formato adecuado para el origen de datos externos. Este marco le ayudará a convertir los datos que se devuelven a los tipos Entity o EntityCollection adecuados que espera la plataforma de Dynamics 365 Customer Engagement (on-premises).
Excepciones del proveedor de datos
Si por cualquier motivo, el código no logra el resultado previsto, deberá lanzar el error correspondiente. El espacio de nombres Microsoft.Xrm.Sdk.Data.Exceptions contiene las siguientes clases de excepción, que se derivan de SdkExceptionBase, que puede usar para este fin:
| Clase de excepción | Descripción |
|---|---|
| AttributeNotFoundException | La consulta especifica un atributo que no se encontró en el registro de datos externos asociado. Normalmente, se produce como resultado de una asignación de tipo errónea o por un cambio de esquema del origen de datos externos. |
| AuthenticationException | Se ha producido un error durante la autenticación de seguridad en el servicio de origen de datos externos. Por ejemplo: estado HTTP 401 recibido del servicio de datos externos. Normalmente, se produce porque el usuario actual no tiene privilegios adecuados o la información de conexión del EntityDataSource asociado no es correcta. |
| EndpointException | La configuración del extremo en la entidad de origen de datos no es válida o el extremo no existe. |
| EntityNotFoundException | La consulta está dirigida a una entidad que no existe. Normalmente, se produce como resultado de una asignación de tipo errónea o por un cambio de esquema del origen de datos externos. |
| GenericDataAccessException | Error de acceso de datos general utilizado cuando el error no encaja con una excepción más específica. |
| InvalidMetadataException | |
| InvalidQueryException | La consulta especificada no es válida. Por ejemplo, una combinación de cláusulas no válida u operador de comparación no compatible. |
| ObjectNotFoundException | El registro especificado en el origen de datos externos no existe. |
| TimeoutException | No se ha completado la operación externa en el tiempo permitido. Por ejemplo, el resultado de un estado HTTP 408 del servicio de datos externos. |
Registro de complementos
A diferencia de un complemento normal, solo usará la herramienta de registro de complementos (PRT) para registrar el ensamblado y los complementos para cada evento. No registrará pasos específicos. El complemento se ejecutará en la fase 30, la fase de transacciones centrales principal de la operación que no está disponible para los pasos de complemento normales. En lugar de registrar pasos, configurará el proveedor de datos con las entidades Microsoft.Dynamics.CRM.EntityDataProvider y Microsoft.Dynamics.CRM.EntityDataSource.
| Entidad | Descripción |
|---|---|
| EntityDataProvider | Define los complementos a utilizar para cada evento y el nombre lógico del origen de datos. |
| EntityDataSource | Proporciona el contexto de la entidad y cualquier información de conexión necesaria para el origen de datos externos, incluidos los secretos necesarios para autenticar. |
Una vez configurados los metadatos de la entidad virtual, los complementos se registran con el PRT y los datos de configuración correctos se establecen en las entidades EntityDataProvider y EntityDataSource, y la entidad virtual empieza a responder a las solicitudes.