Getting Started with Data Connectors

Data Connectors for Power BI enables users to connect to and access data from your application, service, or data source, providing them with rich business intelligence and robust analytics over multiple data sources. By integrating seamlessly into the Power Query connectivity experience in Power BI Desktop, Data Connectors make it easy for power users to query, shape and mashup data from your app to build reports and dashboards that meet the needs of their organization.

Data Connectors are created using the M language. This is the same language used by the Power Query user experience found in Power BI Desktop and Excel 2016. Extensions allow you to define new functions for the M language, and can be used to enable connectivity to new data sources. While this document will focus on defining new connectors, much of the same process applies to defining general purpose M functions. Extensions can vary in complexity, from simple wrappers that essentially just provide "branding" over existing data source functions, to rich connectors that support Direct Query.

Please see the Data Connector technical reference, and TripPin tutorial samples for more information.

Quickstart

Note: The steps to enable extensions changed in the June 2017 version of Power BI Desktop.

Install the Power Query SDK from the Visual Studio Marketplace
Create a new Data Connector project
Define your connector logic
Build the project to produce an extension file
Create a [My Documents]\Power BI Desktop\Custom Connectors directory
Copy the extension file into this directory
Enable the Custom data connectors preview feature in Power BI Desktop (under File | Options and settings | Custom data connectors)
Restart Power BI Desktop

Gateway Support

Custom Connector support was added to the April 2018 release of the Personal On-Premises Gateway. Please see the technical documentation for more information on the TestConnection handler, and the TripPin Sample for an example of how to add gateway support to your connector.

Distribution of Data Connectors

Power BI Desktop users can download extension files and place them in a known directory (steps described above). Power BI Desktop will automatically load the extensions on restart.

We are hard at work on Office Store integration to make it easy for users to discover and install data connectors you build. During this preview phase, developers interested in distributing their connectors for use with Power BI can contact us at DataConnectors (at) microsoft.com. Currently, we are only distributing connectors by vendors and by third party developers acting with permission and on behalf of vendors, not unrelated third party developers.

Additional Links and Resources

The recording of the Creating a Custom Data Connector session from the Microsoft Data Insights Summit 2017 can be found by clicking the image below:

Hello World Sample

The following code sample defines a simple "Hello World" data source. See the full sample for more information.

section HelloWorld;
 
[DataSource.Kind="HelloWorld", Publish="HelloWorld.Publish"]
shared HelloWorld.Contents = (optional message as text) =>
    let
        message = if (message <> null) then message else "Hello world"
    in
        message;
 
HelloWorld = [
    Authentication = [
        Implicit = []
    ],
    Label = Extension.LoadString("DataSourceLabel")
];
 
HelloWorld.Publish = [
    Beta = true,
    ButtonText = { Extension.LoadString("FormulaTitle"), Extension.LoadString("FormulaHelp") },
    SourceImage = HelloWorld.Icons,
    SourceTypeImage = HelloWorld.Icons
];
 
HelloWorld.Icons = [
    Icon16 = { Extension.Contents("HelloWorld16.png"), Extension.Contents("HelloWorld20.png"), Extension.Contents("HelloWorld24.png"), Extension.Contents("HelloWorld32.png") },
    Icon32 = { Extension.Contents("HelloWorld32.png"), Extension.Contents("HelloWorld40.png"), Extension.Contents("HelloWorld48.png"), Extension.Contents("HelloWorld64.png") }
];

What You Can Do With a Data Connector

Data Connectors allow you to create new data sources, or customize and extend an existing source. Common use cases include:

Creating a business analyst friendly view for a REST API
Providing branding for a source that Power Query supports with an existing connector (such as an OData service, or ODBC driver)
Implementing an OAuth v2 authentication flow for a SaaS offering
Exposing a limited/filtered view over your data source to improve usability
Supporting different authentication modes when creating a Power BI Content Pack
Enabling Direct Query for a data source via an ODBC driver

Currently, Data Connectors are only supported in Power BI Desktop.

Upcoming Changes

Data Connectors are currently in preview. We plan to incrementally roll out a number of enhancements prior to general availability, including:

File extension changes (.mez to .pqx)
Improved tracing and diagnostics for developing Direct Query capable connectors
Versioning of extensions, and support for dependencies
Improved support for Library extensions (for reusable utility functions)
Integration and support for API Connectors for Microsoft Flow and PowerApps
Integration with the Office Store
Development experience improvements

Please report issues and feature requests through our Github issues page.

lidongsjtu / DataConnectors