You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: powerapps-docs/developer/common-data-service/virtual-entities/custom-ve-data-providers.md
+25-19Lines changed: 25 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
-
title: "Custom virtual table data providers (Common Data Service) | Microsoft Docs"
3
-
description: "Using the Common Data Service Data SDK, .NET Developers have the option of creating custom virtual table data providers to help integrate external data source types that are not supported by an existing data provider."
4
-
ms.date: 11/09/2020
2
+
title: "Custom virtual entity data providers (Common Data Service) | Microsoft Docs"
3
+
description: "Using the Common Data Service 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."
Using the Common Data Service Data SDK, .NET Developers have the option of creating custom virtual table 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 Common Data Service 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.
24
+
Using the Common Data Service 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 Common Data Service 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.
25
25
26
26
> [!NOTE]
27
27
> 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](https://docs.microsoft.com/dotnet/framework/data/wcf/). OData has broad industry support, with a wide range of dedicated tools and compatible technologies.
@@ -40,23 +40,23 @@ The `Microsoft.Xrm.Sdk.Data.dll` assembly is available as a NuGet package: [Micr
40
40
41
41
## Categories of providers
42
42
43
-
There are two general categories of data provider you can create using the virtual table 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.
43
+
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.
44
44
45
45
|**Category**|**Dev Model**|**Description**|
46
46
|------------|-------------|---------------|
47
-
|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 table 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.|
47
+
|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.|
48
48
|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](/dotnet/csharp/programming-guide/concepts/linq/enabling-a-data-source-for-linq-querying1). 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.|
49
49
50
50
The standard Odata v4 Data Provider and the Cosmos DB Data Provider are examples of generic providers.
51
51
52
52
## Steps to use a custom data provider
53
53
54
-
There are several steps that are required to create a virtual table data provider solution that can be imported into your Common Data Service applications:
54
+
There are several steps that are required to create a virtual entity data provider solution that can be imported into your Common Data Service applications:
55
55
56
56
1. Develop the custom data provider plug-in DLL (or set of DLLs).
57
57
2. Register the custom data provider with your Common Data Service service using the Plug-in Registration Tool (PRT).
58
58
3. Create a data provider solution.
59
-
4. Customize the data source table to reflect your data type or specific instance.
59
+
4. Customize the data source entity to reflect your data type or specific instance.
60
60
5. Export the custom data provider solution.
61
61
62
62
@@ -66,7 +66,7 @@ Because virtual entities in this release are read-only, you will write the data
66
66
67
67
|**Event**|**Execution Context**|
68
68
|---------|---------------------|
69
-
|**Retrieve**|Describes which table to retrieve as well as the attributes and any related entities to include.|
69
+
|**Retrieve**|Describes which entity to retrieve as well as the attributes and any related entities to include.|
70
70
|**RetrieveMultiple**|Contains a <xref:Microsoft.Xrm.Sdk.Query.QueryExpression> object defining the query. The framework contains a **QueryExpressionVisitor** class designed to inspect different parts of the query expression tree.|
71
71
72
72
For both events, you must :
@@ -83,8 +83,8 @@ If for any reason your code cannot achieve the expected result, you must throw t
83
83
84
84
|**Exception Class**|**Description**|
85
85
|---------------|-----------|
86
-
|<xref:Microsoft.Xrm.Sdk.Data.Exceptions.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 is incorrect.|
87
-
|<xref:Microsoft.Xrm.Sdk.Data.Exceptions.EndpointException>|The endpoint configuration in the data source table is invalid or the endpoint does not exist.|
86
+
|<xref:Microsoft.Xrm.Sdk.Data.Exceptions.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.|
87
+
|<xref:Microsoft.Xrm.Sdk.Data.Exceptions.EndpointException>|The endpoint configuration in the data source entity is invalid or the endpoint does not exist.|
88
88
|<xref:Microsoft.Xrm.Sdk.Data.Exceptions.GenericDataAccessException>|A general data access error, used when the error does not map to a more specific exception.|
|<xref:Microsoft.Xrm.Sdk.Data.Exceptions.InvalidQueryException>|The specified query is invalid; for example it an invalid clause combination or unsupported comparison operator.|
@@ -94,19 +94,25 @@ If for any reason your code cannot achieve the expected result, you must throw t
94
94
95
95
### Plug-in registration
96
96
97
-
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 [EntityDataProvider](../reference/entities/entitydataprovider.md) table that defines the plug-ins to use for each event and the logical name of the data source.
97
+
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 following entities.
98
98
99
-
When the metadata for your virtual table is configured, your plug-ins are registered using the PRT and the correct configuration data is set in the **EntityDataProvider** table, your virtual table will start to respond to requests.
99
+
100
+
|**Entity**|**Description**|
101
+
|-----|-----|
102
+
|[EntityDataProvider](../reference/entities/entitydataprovider.md)|Defines the plugins to use for each event and the logical name of the data source.|
103
+
|[EntityDataSource](../reference/entities/entitydatasource.md)|Provides the entity context and any connection information required for the external data source, including any secrets required to authenticate.|
104
+
105
+
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.
100
106
101
107
### Debugging plug-ins
102
108
103
-
A custom virtual table provider is a type of plug-in. Use the information in these topics to debug plug-ins for custom virtual table providers: [Debug Plug-ins](../debug-plug-in.md) and [Tutorial: Debug a plug-in](../tutorial-debug-plug-in.md).
109
+
A custom virtual entity provider is a type of plug-in. Use the information in these topics to debug plug-ins for custom virtual entity providers: [Debug Plug-ins](../debug-plug-in.md) and [Tutorial: Debug a plug-in](../tutorial-debug-plug-in.md).
104
110
105
111
106
112
### See also
107
113
108
-
[Get started with virtual table](get-started-ve.md)<br />
109
-
[API considerations of virtual table](api-considerations-ve.md)<br />
110
-
[Sample: Generic virtual table data provider plug-in](sample-generic-ve-plugin.md)
114
+
[Get started with virtual entities](get-started-ve.md)<br />
115
+
[API considerations of virtual entities](api-considerations-ve.md)<br />
116
+
[Sample: Generic virtual entity data provider plug-in](sample-generic-ve-plugin.md)
0 commit comments