Power BI Advanced Series · Custom Visuals Development · by Raushan Ranjan, MCT
Welcome to your roadmap as a budding Power BI Developer! This module is designed to simplify the world of developer tools, explaining what they are and how they fit into the real work you'll do, especially for embedding Power BI content, automating tasks, and creating custom visuals.
🎯 Goal of This Module:
🧑💻 As a Power BI Developer, you may:
- Embed Power BI reports/dashboards in a website or app.
- Build custom visuals for Power BI.
- Automate tasks like publishing reports or refreshing datasets.
- Connect on-premises data to cloud Power BI using a gateway.
To do that, you need a developer setup with:
- Editors (VS Code / Visual Studio)
- Runtimes (Node.js)
- SDKs/APIs (Power BI Client, .NET SDK)
- Gateway (for on-prem data)
🔹1. Visual Studio Code (VS Code)
🧠 What is it?
A lightweight, free, and open-source code editor developed by Microsoft. Think of it like a highly versatile digital notebook for writing code.
💼 Used For:
- Creating custom visuals: You'll write JavaScript/TypeScript code for custom visuals, and VS Code is the primary editor for this, often used with the
pbivizcommand-line tool. - Writing scripts for automation: Ideal for Python or PowerShell scripts that interact with the Power BI REST API to automate tasks like dataset refreshes or report publishing.
- Creating Node.js web apps: If you're building a simple web application to embed Power BI reports using the Power BI JavaScript client SDK, VS Code is your go-to editor for HTML, CSS, and JavaScript.
✅ Setup:
- Install from https://code.visualstudio.com/.
- Install these recommended extensions from the Extensions view (Ctrl+Shift+X):
- REST Client: Great for testing API calls directly within VS Code.
- Power BI Custom Visual Tools: (Optional, but useful if focusing on custom visuals) Provides specific tools for custom visual development.
- Node.js Extension Pack: Essential for JavaScript/TypeScript development.
🔹2. Visual Studio 2019 / 2022 (Full IDE)
🧠 What is it?
A powerful, full-featured Integrated Development Environment (IDE) from Microsoft. It's like a complete workshop with all the tools needed for large-scale software development, especially for .NET-based applications.
💼 Used For:
- Embedding Power BI in ASP.NET MVC / Blazor apps: When building robust, enterprise-grade web applications with C# and .NET, Visual Studio is the standard. It provides rich debugging, project management, and integration with various .NET SDKs.
- Creating internal dashboards: For secure, internal applications that host Power BI content using the "App Owns Data" embedding model, Visual Studio is used to build the backend authentication and embedding logic.
- Using Power BI SDK (C#): Programmatically interacting with Power BI (e.g., publishing reports, managing datasets, setting refresh schedules) can be done using the C# Power BI SDK, which is best utilized within Visual Studio.
- Managing Azure AD login: Essential for handling user authentication and authorization when embedding Power BI content, especially in "App Owns Data" scenarios.
✅ Setup:
- Download from https://visualstudio.microsoft.com/.
- During installation, choose these workloads:
- ASP.NET and Web Development: For building web applications.
- .NET Desktop Development: If you plan to build desktop applications that embed Power BI.
🔹3. Node.js and npm
🧠 What is Node.js?
Node.js is a runtime environment that allows you to run JavaScript code outside of a web browser (e.g., on your local machine or a server). It's crucial for many modern web development tools.
🧠 What is npm?
npm (Node Package Manager) is the default package manager for Node.js. It helps you discover, install, and manage JavaScript libraries and command-line tools, including those specific to Power BI development.
💼 Used For:
- Creating Power BI Custom Visuals: The
pbivizcommand-line interface (CLI) tool, which is used to scaffold, develop, and package custom visuals, runs on Node.js and is installed via npm. - Embedding Power BI into websites: The
powerbi-clientJavaScript SDK, used for embedding Power BI reports and dashboards into web pages, is installed and managed via npm. - Automating tasks with JS scripts: You can write JavaScript scripts to interact with the Power BI REST API (e.g., for report refresh automation), and these scripts are executed using Node.js.
✅ Setup:
- Install from https://nodejs.org. This typically installs both Node.js and npm.
- To verify installation, open your terminal and run:
node -v npm -v - Install essential CLI tools globally (the
-gflag):npm install -g powerbi-visuals-tools
🔹4. Data Gateway
🧠 What is it?
The Data Gateway acts as a secure bridge between your on-premises data sources (like a SQL Server database on your company's network) and cloud-based Power BI Service. It allows Power BI to securely access data that isn't directly exposed to the internet.
💼 Used For:
- Refreshing reports with on-prem data: Enables scheduled refreshes for Power BI reports and dashboards that source data from databases or files located within your private network.
- Embedding a report that uses your company’s internal database: If your embedded report relies on on-premises data, the gateway facilitates the secure connection.
🔌 Two types:
- Personal Gateway: Designed for individual users to refresh reports and can only be used by the person who installed it.
- Enterprise Gateway: A more robust, shared gateway that can be used by multiple users and reports across an organization, offering centralized management and higher availability.
✅ Setup:
- Download from the Power BI website: https://powerbi.microsoft.com/gateway/.
- Install it on a machine that has access to your local database or data sources. This machine needs to be running when scheduled refreshes occur.
- Log in with your Power BI Pro account during setup.
- Configure Data Sources within the Gateway settings in Power BI Service and bind them to your reports/datasets.
📚 Let’s Relate to the Power BI Developer Journey
Here's how these tools come together for common Power BI developer activities:
| Developer Activity | Tools Required |
|---|---|
| Embed a report into an ASP.NET Web App | Visual Studio + .NET SDK + Azure AD |
| Build a web page to show Power BI report using JS | VS Code + Node.js + powerbi-client |
| Create a new Power BI custom visual | VS Code + pbiviz + Node.js |
| Automate dataset refresh | VS Code + Power BI REST API + token auth (Python/JS scripts) |
| Use on-prem SQL in your report on cloud | Install and configure Data Gateway |
🔧 Summary: Easy Table for Each Tool
| Tool | Use Case | Why You Need It |
|---|---|---|
| VS Code | Custom visuals, API calls, JS code | Lightweight, versatile for many dev tasks |
| Visual Studio | Web apps (Blazor, ASP.NET) | For embedding via .NET, enterprise-grade development |
| Node.js + npm | JS runtime + package manager | Required for CLI tools like pbiviz and JS SDKs |
| Data Gateway | Refresh on-prem data on Power BI Service | Securely bridges on-prem to cloud data |
✅ What Should You Do Practically?
To solidify your understanding, try these hands-on steps:
- Install All Tools:
- 🔹 VS Code
- 🔹 Visual Studio (Community Edition is free for individuals)
- 🔹 Node.js
- 🔹 Data Gateway
- Try a Scenario (Data Gateway):
- Create a simple Power BI report using a local SQL Server database (or even an Excel file on your PC).
- Publish it to Power BI Service.
- Install and configure the Data Gateway.
- Setup a scheduled refresh for your published report to ensure it pulls new data from your local source.
- Create a Sample App (Embedding):
- Option 1 (.NET Blazor App): Use Visual Studio to create a new Blazor Server App and try to embed a Power BI report into one of its pages using the Power BI .NET SDK.
- Option 2 (HTML+JS Page): Use VS Code to create a simple HTML file with a JavaScript block. Embed a Power BI report into this page using the
powerbi-clientJavaScript SDK. You'll need to serve this HTML file (e.g., using a simple Node.js web server).
- Extra: Explore
pbiviz(Custom Visuals):- Open your terminal and run
pbiviz new MyCustomVisual. - Then
cd MyCustomVisualandpbiviz start. This will open a blank custom visual in Power BI Desktop, showing you the development environment.
- Open your terminal and run
By actively engaging with these tools, you'll gain practical experience and a much deeper understanding of the Power BI developer ecosystem. Happy coding!
Quick Knowledge Check
Q1. What does the pbiviz new MyVisual command generate, and what must you do immediately after to resolve dependencies?
Show Answer
It scaffolds a new custom visual project folder with the required TypeScript, JSON, and CSS files. Immediately after, run npm install in the project folder to download all declared Node.js dependencies (D3.js, Power BI visuals API types, etc.). Without npm install, pbiviz start and pbiviz package will fail because the node_modules folder is absent.
Q2. A developer runs pbiviz start successfully but cannot see the Developer Visual in Power BI Service. What is the most likely missing step?
- A) The TypeScript compiler is not installed
- B) "Developer mode" for custom visuals must be enabled in Power BI Service settings
- C) The visual must be packaged with
pbiviz package before it appears in Service
- D) Node.js LTS version must be uninstalled and replaced with the latest version
Show Answer
B. In Power BI Service, go to Settings → Developer settings → Enable the custom visual developer toggle. Only then can you add a "Developer Visual" tile and connect it to your local pbiviz start server. Option C is wrong — pbiviz start is specifically for testing WITHOUT packaging.
Q3. What is the purpose of the capabilities.json file in a custom visual project?
Show Answer
It declares the visual's contract with Power BI: data roles (field wells), data view mappings, and the property pane settings. Power BI reads capabilities.json to know which fields the visual accepts (e.g., "Category" and "Measure"), how to transform the data model into the structure the visual expects, and what user-configurable properties appear in the Format panel. Without an accurate capabilities.json, the visual cannot receive data or expose format options.
5 Things to Remember
pbiviz new scaffolds the project — always follow with npm install to download dependencies into node_modules.pbiviz start for development, pbiviz package for distribution — start runs a live dev server; package creates the .pbiviz file for deployment.- Enable Developer mode in Service — without toggling the developer visual setting in Power BI Service settings, you cannot test locally running visuals.
capabilities.json is the visual's contract — data roles, field mappings, and property pane configuration all live here, not in TypeScript.- Use Node.js LTS — the Power BI visuals tools CLI (powerbi-visuals-tools) requires a compatible Node.js LTS version. Using the latest non-LTS can break the build pipeline.
Quick Knowledge Check
Q1. What does the pbiviz new MyVisual command generate, and what must you do immediately after to resolve dependencies?
Show Answer
It scaffolds a new custom visual project folder with the required TypeScript, JSON, and CSS files. Immediately after, run npm install in the project folder to download all declared Node.js dependencies (D3.js, Power BI visuals API types, etc.). Without npm install, pbiviz start and pbiviz package will fail because the node_modules folder is absent.
Q2. A developer runs pbiviz start successfully but cannot see the Developer Visual in Power BI Service. What is the most likely missing step?
- A) The TypeScript compiler is not installed
- B) "Developer mode" for custom visuals must be enabled in Power BI Service settings
- C) The visual must be packaged with
pbiviz packagebefore it appears in Service - D) Node.js LTS version must be uninstalled and replaced with the latest version
Show Answer
B. In Power BI Service, go to Settings → Developer settings → Enable the custom visual developer toggle. Only then can you add a "Developer Visual" tile and connect it to your local pbiviz start server. Option C is wrong — pbiviz start is specifically for testing WITHOUT packaging.
Q3. What is the purpose of the capabilities.json file in a custom visual project?
Show Answer
It declares the visual's contract with Power BI: data roles (field wells), data view mappings, and the property pane settings. Power BI reads capabilities.json to know which fields the visual accepts (e.g., "Category" and "Measure"), how to transform the data model into the structure the visual expects, and what user-configurable properties appear in the Format panel. Without an accurate capabilities.json, the visual cannot receive data or expose format options.
pbiviz newscaffolds the project — always follow withnpm installto download dependencies intonode_modules.pbiviz startfor development,pbiviz packagefor distribution — start runs a live dev server; package creates the.pbivizfile for deployment.- Enable Developer mode in Service — without toggling the developer visual setting in Power BI Service settings, you cannot test locally running visuals.
capabilities.jsonis the visual's contract — data roles, field mappings, and property pane configuration all live here, not in TypeScript.- Use Node.js LTS — the Power BI visuals tools CLI (powerbi-visuals-tools) requires a compatible Node.js LTS version. Using the latest non-LTS can break the build pipeline.