Custom virtual entity data providers
Using the Dynamics 365 for Customer Engagement (on-premises) Data SDK, .NET Developers have the option of creating custom virtual entity data providers to help integrate external data source types that are not supported by an existing data provider. Each data provider is composed of a reusable set of Dynamics 365 for Customer Engagement (on-premises) plug-ins that implement the supported CRUD operations. (The initial release is limited to the Retrieve and RetrieveMultiple read operations.) This section provides fundamental information about data providers and approaches to developing custom providers, including example code.
Note
As an alternative to creating a custom data source provider, you should consider adapting your data source to an existing data provider. For example, if you create an OData v4 interface to your external data source, then you can directly access it with the supplied standard OData v4 Data Provider. The mechanism of adding this REST interface varies with the underlying data service technology, for example see WCF Data Services 4.5. OData has broad industry support, with a wide range of dedicated tools and compatible technologies.
Prerequisites
Custom data providers require substantial development resources to create and maintain. You must have fundamental knowledge of the following areas:
- The external data source schema and associated data access techniques. This domain knowledge is specific to the external data source type.
- Dynamics 365 for Customer Engagement (on-premises) metadata schema; for more information see The metadata and data models in Microsoft Dynamics 365 Customer Engagement (on-premises).
- Dynamics 365 for Customer Engagement (on-premises) event system; for more information see Event Framework.
- Dynamics 365 for Customer Engagement (on-premises) plug-in architecture and development; for more information see Plug-in development.
You will also need to manually download the Dynamics 365 for Customer Engagement (on-premises) Data SDK, or include the corresponding NuGet package in your projects. This SDK is compatible with Visual Studio 2015 or 2017.
Categories of providers
There are two general categories of data provider you can create using the virtual entity data SDK assemblies: generic or targeted. The table below describes these approaches and matches them to the data provider development model best suited for that approach.
| Category | Dev Model | Description |
|---|---|---|
| Generic | "Bare metal" provider | These providers can flexibly translate FetchXML query expressions to the associated request to the external data source, then return the resulting entity instances. Such a provider can be reused for all instances of this data source type. This approach is the most general but is more complicated to develop. If the schema of the data source changes, the affected virtual entities must only be remapped. |
| Targeted | LINQ provider for known schema | Such a provider only narrowly translates queries into the associated LINQ call to a known, existing data source instance. The data source must be a LINQ provider as described in the topic Enabling a Data Source for LINQ Querying. This approach is limited to a specific data source instance, but requires much less coding. If the schema of the data source changes, the data provider must be updated and rebuilt. |
The standard Odata v4 Data Provider and the Cosmos DB Data Provider are examples of generic providers.
Steps to use a custom data provider
There are several steps that are required to create a virtual entity data provider solution that can be imported into your Dynamics 365 for Customer Engagement (on-premises):
- Develop the custom data provider plug-in DLL (or set of DLLs).
- Register the custom data provider with your Dynamics 365 for Customer Engagement (on-premises) service using the Plug-in Registration Tool (PRT).
- Create a data provider solution.
- Customize the data source entity to reflect your data type or specific instance.
- Export the custom data provider solution.
Plug-in development
Because virtual entities in this release are read-only, you will write the data provider in the form of a plug-in registered on the Retrieve and RetrieveMultiple events. Each respective event will include information in the execution context which describes the kind of data to return.
| Event | Execution Context |
|---|---|
| Retrieve | Describes which entity to retrieve as well as the attributes and any related entities to include. |
| RetrieveMultiple | Contains a QueryExpression object defining the query. The framework contains a QueryExpressionVisitor class designed to inspect different parts of the query expression tree. |
For both events, you must :
- Convert the respective information in the execution context into a query that will work for your external data source.
- Retrieve the data from the external system.
- For Retrieve, convert the data into an Entity; otherwise, for RetrieveMultiple, convert it to an EntityCollection. This result is returned through the Dynamics 365 Customer Engagement (on-premises) platform to the user executing the query.
The classes in the Microsoft.Xrm.Sdk.Data namespace provide a framework to assist in mapping the Dynamics 365 Customer Engagement (on-premises) query information from the execution context into a query in the format appropriate for your external data source. This framework will help you convert the data returned in to the appropriate Entity or EntityCollection types expected by the Dynamics 365 Customer Engagement (on-premises) platform.
Data provider exceptions
If for any reason your code cannot achieve the expected result, you must throw the appropriate error. The Microsoft.Xrm.Sdk.Data.Exceptions namespace contains the following exception classes, derived from SdkExceptionBase, that you can use for this purpose:
| Exception Class | Description |
|---|---|
| AttributeNotFoundException | The query specifies an attribute that was not found in the associated external data record. Typically occurs as a result of faulty type mapping or a external data source schema change. |
| AuthenticationException | An error occurred during security authentication to the external data source service; for example HTTP status 401 received from the external data service. Typically occurs because the current user does not have proper privileges or the connection information in the associated EntityDataSource is incorrect. |
| EndpointException | The endpoint configuration in the data source entity is invalid or the endpoint does not exist. |
| EntityNotFoundException | The query targets an entity which does not exist. Typically occurs as a result of faulty type mapping or a external data source schema change. |
| GenericDataAccessException | A general data access error, used when the error does not map to a more specific exception. |
| InvalidMetadataException | |
| InvalidQueryException | The specified query is invalid; for example it an invalid clause combination or unsupported comparison operator. |
| ObjectNotFoundException | The specified record in the external data source does not exist. |
| TimeoutException | The external operation did not complete within the allowed time; for example, the result of a HTTP status 408 from the external data service. |
Plug-in registration
Unlike an ordinary plugin, you will only use the Plugin Registration Tool (PRT) to register the assembly and the plugins for each event. You will not register specific steps. Your plugin will run in stage 30, the main core transaction stage for the operation that is not available for ordinary plugin steps. Instead of registering steps, you will configure your data provider using the Microsoft.Dynamics.CRM.EntityDataProvider and Microsoft.Dynamics.CRM.EntityDataSource entities.
| Entity | Description |
|---|---|
| EntityDataProvider | Defines the plugins to use for each event and the logical name of the data source. |
| EntityDataSource | Provides the entity context and any connection information required for the external data source, including any secrets required to authenticate. |
When the metadata for your virtual entity is configured, your plugins are registered using the PRT and the correct configuration data is set in the EntityDataProvider and EntityDataSource entities, your virtual entity will start to respond to requests.