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.
This sample implements the enhanced connector protocol described in Enhanced connectors (preview). This sample is located at github.com/microsoft/power-fx-enhanced-connector.
This sample is a Visual Studio solution that contains the following .NET 8 C# projects:
Project | Description |
---|---|
CdpHelpers |
This class library project contains classes in the Microsoft.PowerFx.Connectors namespace that aren't currently included in the Microsoft.PowerFx.Connectors NuGet package. In the future these types will become available as a NuGet package. |
CdpSampleWebApi |
An ASP.NET Core Web API project that implements the enhanced connector protocol described in Create enhanced connectors (preview). This project has a project dependency on the CdpHelpers project. |
CdpValidator |
This console application project that receives an endpoint to an enhanced connector and tests it. It calls known endpoints, verifies results, and provides rich diagnostic errors. Use this project to help verify the connector is correctly implemented. This project has a project dependency on the CdpHelpers project. Learn more about CdpValidator in the README |
Prerequisites
- Visual Studio 2022 version 17.8 or later with the ASP.NET and web development workload installed.
- .NET 8.0
Run this sample
After you clone the power-fx-enhanced-connector GitHub repository, open the CdpSampleWebApi.sln
file using Visual Studio 2022.
The CdpSampleWebApi
project is set as the StartUp project. Press F5 to run the program in debug mode. You can expect the following to happen:
The first time you run the sample you might see the following dialog:
Select Yes to trust the ASP.NET Core SSL Certificate. Then another dialog opens:
Select Yes to install the certificate.
A console window opens and outputs the following text:
info: Microsoft.Hosting.Lifetime[14] Now listening on: https://localhost:7157 info: Microsoft.Hosting.Lifetime[14] Now listening on: http://localhost:5008 info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down. info: Microsoft.Hosting.Lifetime[0] Hosting environment: Development info: Microsoft.Hosting.Lifetime[0] Content root path: E:\GitHub\power-fx-enhanced-connector\CdpSampleWebApi
This text is just some logging information to indicate that the ASP.NET Core Web API project started successfully and is listening on
https://localhost:7157
orhttp://localhost:5008
A browser window opens to this URL:
https://localhost:7157/$metadata.json/datasets
.The browser displays the following JSON:
{ "tabular": { "source": "mru", "displayName": "site", "urlEncoding": "double", "tableDisplayName": "DisplayName1", "tablePluralName": "DisplayNames1" }, "blob": null, "datasetFormat": null, "parameters": null, "isDoubleEncoding": true }
This URL opens because it's set as the
launchUrl
property in theCdpSampleWebApi\Properties\launchSettings.json
file. You can edit the URL in the browser to test different urls, but there's a better way to test.
Use the CdpSampleWebApi.http file to test
The CdpSampleWebApi\CdpSampleWebApi.http
file included in this sample is a .http
file that provides a convenient way to test ASP.NET Core projects, especially API apps. It's available only in Visual Studio 2022 version 17.8 or later. Learn more about using .http files in Visual Studio 2022
Use the five requests configured in CdpSampleWebApi.http
to debug the project. These requests demonstrate the enhanced connector protocol described in Create enhanced connectors (preview). Above each request, select Debug to start the debugging the project. While debugging select Send request to test the configured routes.
Note
While debugging the sample in Visual Studio, you can also use the CdpSampleWebApi.http
file with Visual Studio Code when you install the REST Client extension.
How it works
The CdpSampleWebApi
project includes a /DataSource/TrivialTableProvider.cs that implements a minimum viable example to show how to implement the ITableProviderFactory
and ITableProvider
interfaces. These classes provide the details about a data source that is exposed via the Controllers/CdpController.cs with the five endpoints that define the tabular data protocol as described in Create enhanced connectors (preview)
Develop your own enhanced connector with this sample
You can use this solution as starting point to develop your own an enhanced connector.
Prerequisites
- Install the
paconn
command line tool - Access to a Power Platform environment. A trial environment works.
Process
Clone this sample and run it to verify it works for you.
Create your own data provider in the
DataSource
folder that implements theITableProviderFactory
andITableProvider
interfaces. Learn more about the ITableProvider interfaceCreate your own controller in the
Controllers
folder that implements the five endpoints that defined the enhanced connector protocol.Update the
CdpSampleWebApi\Program.cs
to replace the use of theTrivialTableProviderFactory
with the data provider you created.Implement a transpiler to enable retrieving data from the tables with OData query options to control what data is returned and how it's sorted.
Implement create, update, and delete operations suitable for your data.
Test your endpoint locally to confirm it handles requests correctly.
Deploy your Web API to a hosting environment of your choice. For example, you can use Azure or Amazon Web Services (AWS).
Create the custom connector.
- Modify the PowerPlatformArtifacts/apiDefinition.swagger.json and PowerPlatformArtifacts/apiProperties.json files in the sample to align with your data source. Learn more about how to create an OpenAPI (swagger) file that describes your Web API
- Use the paconn CLI tool to create the connector.
Note
If you want to enable this connector to be a knowledge source for agents, don't remove the
federatedKnowledgeSource
setting in thecapabilities
of theapiProperties.json
file.The value of the
capabilities
node should be"capabilities": ["tabular", "federatedKnowledgeSource"],
when the connector should be a knowledge source for agents, otherwise it should be just"capabilities": ["tabular"],
.Configure authentication
Take these steps to configure authentication:
- Add authentication mechanisms to your web API to secure the endpoints (based on your requirements).
- Configure the custom connector to use the appropriate authentication method to access the web API.
Go to Authenticate with Microsoft Entra ID to learn how to enable authentication in Microsoft Entra ID.
Share and test the connector
Take these steps to share and test your connector:
Test the connector by creating sample applications or flows that use the connector to interact with your backend API. To help you get started, go to:
Reference
There are a group of types used in this sample that aren't defined in the Microsoft.PowerFx.Connectors and Microsoft.PowerFx.Core NuGet packages. You can find them in the Power Fx enhanced connector sample power-fx-enhanced-connector/CdpHelpers/Protocol folder using the same Microsoft.PowerFx.Connectors
namespace. The following table describes these types.
Type | Description |
---|---|
CapabilitiesPoco | Describes table capabilities for OData and Power Fx connectors, including filtering, sorting, and server paging options. |
ColumnCapabilitiesPoco | Describes column-level capabilities for OData and Power Fx connectors, such as supported filter functions. |
ColumnInfo | Describes a column in the table schema, including title, description, type, sort, and capabilities. |
DatasetResponse | Represents a response containing a list of datasets for OData and Power Fx connectors. |
ErrorResponse | Represents a standard error response payload for connectors. |
GetItemsResponse | Represents the response for a GetItems operation, containing a list of item values. |
GetTableResponse | Represents the response for a GetTable operation, including table name, permissions, capabilities, and schema. |
GetTablesResponse | Represents the response for a GetTables operation, containing a list of raw table information. |
Item | Represents a response containing a list of datasets for OData and Power Fx connectors. |
Items | Describes the schema of a table, including its type and column definitions. |
RawTablePoco | Represents the response for a GetTables operation, containing a list of raw table information. |
TableSchemaPoco | Describes the schema of a table, including its type and column definitions. |
Share feedback
The repository is open source to encourage you to use it and share feedback so we can continually learn and make improvements. For questions, issues, or discussion, use the Issues or Discussions pages on the GitHub site.
Related articles
Create enhanced data connectors (preview)
Learn more about working with Web APIs and Azure API Management
Learn more about creating custom connectors