Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
By using the Microsoft Dataverse Data SDK, .NET developers can create custom virtual table data providers to help integrate external data source types that aren't supported by an existing data provider. Each data provider is composed of a reusable set of Dataverse plug-ins that implement the supported CRUD operations. For each virtual table, also known as a virtual entity, developers can create plug-ins and register them representing each of the Create, Update, Retrieve, RetrieveMultiple, and Delete operations. This section provides fundamental information about data providers and approaches to developing custom providers, including example code.
Note
Instead of creating a custom data source provider, consider adapting your data source to an existing data provider. For example, if you create an OData v4 interface to your external data source, you can directly access it by using the supplied standard OData v4 Data Provider, which supports CRUD operations. The mechanism for 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.
- Dataverse definition schema: More information: Work with table and column definitions using code.
- Dataverse event framework: More information: Event Framework.
- Dataverse plug-in architecture and development: More information: Use plug-ins to extend business processes.
The Microsoft.Xrm.Sdk.Data.dll assembly is available as a NuGet package: Microsoft.CrmSdk.Data
Categories of providers
You can create two general categories of data providers by using the virtual table data SDK assemblies: generic or targeted. The following table describes these approaches and matches them to the data provider development model best suited for each approach.
| Category | Dev Model | Description |
|---|---|---|
| Generic | "Bare metal" provider | These providers flexibly translate FetchXML query expressions to the associated request to the external data source, and then return the resulting records. You can reuse such a provider 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, you only need to remap the affected virtual tables. |
| Targeted | LINQ provider for known schema | Such a provider 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 article 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, you must update and rebuild the data provider. |
The standard OData v4 Data Provider and the Azure Cosmos DB Data Provider are examples of generic providers.
Steps to use a custom data provider
To create a virtual table data provider solution that you can import into your Dataverse applications, complete the following steps:
- Develop the custom data provider plug-in DLL or set of DLLs.
- Register the custom data provider with your Dataverse service by using the Plug-in Registration Tool (PRT).
- Create a data provider solution.
- Customize the data source table to reflect your data type or specific instance.
- Export the custom data provider solution.
For more information, see Sample: Custom virtual table provider with CRUD operations.
Plug-in development
Because virtual tables support CRUD operations, write the data provider as a plug-in that you register on the Create, Update, Retrieve, RetrieveMultiple, and Delete events. Each event includes information in the execution context that describes the kind of data to return.
| Event | Execution Context |
|---|---|
| Retrieve | Describes which table to retrieve as well as the columns and any related tables 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 works 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. Dataverse returns this result through to the user executing the query.
The classes in the Microsoft.Xrm.Sdk.Data namespace provide a framework to assist in mapping the Dataverse query information from the execution context into a query in the format appropriate for your external data source. This framework helps you convert the data returned into the appropriate Entity or EntityCollection types expected by the Dataverse platform.
Data provider exceptions
If your code can't achieve the expected result, 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 |
|---|---|
| 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 doesn't have proper privileges or the connection information in the associated EntityDataSource is incorrect. |
| EndpointException | The endpoint configuration in the data source table is invalid or the endpoint doesn't exist. |
| GenericDataAccessException | A general data access error, used when the error doesn't map to a more specific exception. |
| InvalidMetadataException | |
| InvalidQueryException | The specified query is invalid; for example, it contains an invalid clause combination or unsupported comparison operator. |
| ObjectNotFoundException | The specified record in the external data source doesn't exist. |
| TimeoutException | The external operation didn't complete within the allowed time; for example, the result of an HTTP status 408 from the external data service. |
Plug-in registration
Unlike an ordinary plug-in, use the Plug-in Registration Tool (PRT) to register the assembly and the plug-ins for each event. Don't register specific steps. Your plug-in runs in stage 30, the main core transaction stage for the operation that isn't available for ordinary plug-in steps. Instead of registering steps, configure your data provider by using the following table.
| Table | Description |
|---|---|
| EntityDataProvider | Defines the plug-ins to use for each event and the logical name of the data source. |
When you configure the definitions for your virtual table, register your plug-ins by using the PRT and set the correct configuration data in the EntityDataProvider table. Your virtual table starts to respond to requests.
For more information, see Creating data provider and adding plug-ins to the provider.
Debugging plug-ins
A custom virtual table provider is a type of plug-in. Use the information in these articles to debug plug-ins for custom virtual table providers: Debug plug-ins and Tutorial: Debug a plug-in.
See also
Get started with virtual tables
API considerations of virtual tables
Sample: Generic virtual table data provider plug-in