Share via


Enhanced connector sample

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

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:

  1. The first time you run the sample you might see the following dialog:

    Trust ASP.NET Core SSL Certificate dialog

    Select Yes to trust the ASP.NET Core SSL Certificate. Then another dialog opens:

    Security Warning dialog

    Select Yes to install the certificate.

  2. 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 or http://localhost:5008

  3. 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 the CdpSampleWebApi\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.

Showing the CdpSampleWebApi.http file

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

Process

  1. Clone this sample and run it to verify it works for you.

  2. Create your own data provider in the DataSource folder that implements the ITableProviderFactory and ITableProvider interfaces. Learn more about the ITableProvider interface

  3. Create your own controller in the Controllers folder that implements the five endpoints that defined the enhanced connector protocol.

  4. Update the CdpSampleWebApi\Program.cs to replace the use of the TrivialTableProviderFactory with the data provider you created.

  5. 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.

  6. Implement create, update, and delete operations suitable for your data.

  7. Test your endpoint locally to confirm it handles requests correctly.

  8. Deploy your Web API to a hosting environment of your choice. For example, you can use Azure or Amazon Web Services (AWS).

  9. Create the custom connector.

    1. 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
    2. 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 the capabilities of the apiProperties.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"],.

  10. Configure authentication

    Take these steps to configure authentication:

    1. Add authentication mechanisms to your web API to secure the endpoints (based on your requirements).
    2. 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.

  11. Share and test the connector

    Take these steps to share and test your connector:

    1. Share the custom connector in Power Platform.

    2. 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.

Create enhanced data connectors (preview)
Learn more about working with Web APIs and Azure API Management
Learn more about creating custom connectors