Creating A New Power BI Custom Visual Project

Creating A New Power BI Custom Visual Project

This video explains how to create a new custom visual project for Power BI. This is video #6 of the Power BI Custom Visual Development Fundamentals series, please check the playlist below for the set.

Video Transcript:

Now that everything’s setup, it’s time to create your first project. To do so, you can open a command-line and navigate to a folder where you’d like to store your project files in. If you’re planning on committing to GIT or TFS, your usual working folder is a good place to start with.

Once there, you can type pbiviz, followed by the new command and then give it the display of your intended visual. If you haven’t decided on a name yet, don’t worry too much about it, you can change it later. Just pick something and go. For this example, I’m using My Little Bar Chart as a name, as that’s exactly what it’s going to be.

Now let’s open up a File Explorer and see what happened.

As you can see, the pbiviz command created a new folder with a number of files in it. These files form a very basic template for a new visual and are good to go the moment you create them. Now while you can open and edit these files by hand, it’s far more pleasant to use a code editor to do so. In this course, I’m going to use Visual Studio Code to edit this project. Visual Studio Code is the younger sibling of Full-On Visual Studio and it is a lightweight text editor that runs on Windows, Mac and Linux just the same. If you don’t have it yet, you can get Visual Studio Code from

Installation is a piece of cake and you’ll get up and running in no time. Now you don’t have to use the same text editor as this course. Any editor that can highlight TypeScript will make your life easier but you can use whatever you like.

Back to Visual Studio Code, the next step is to open the folder you just created.

When you open it, you’ll see all the files in the explorer pane. A Power BI Custom Visual project is comprised of several code and configuration files. The first file you should take note of is the pbiviz.json file.

This is the main configuration file for the project and it has a number of settings you can fiddle with. Most importantly, this is where you can define the display name of your visual if you change your mind later.

This is also where you can add references to external libraries and you will make use of this later.

You can also add author information here if you’d like.

The next file you should take note of is the visual.ts file.

This is the main code file for the custom visual, and where most of the code will go during this course. If this is your first time looking at code like this, let me welcome you to typescript. TypeScript is a superset of JavaScript developed by Microsoft and it adds neat things like static typing and classes and interfaces to the javascript language. It is also fully compatible with javascript itself, so you don’t need to write TypeScript if you don’t know it, even on a ts file like this. Now if you haven’t come across TypeScript before, don’t worry too much about it. While this course does not cover the TypeScript language itself, you will only make light use of it and I’ll explain things as we go along. However, this course does assume you have working knowledge of JavaScript, so if you’ve never used JavaScript before, I recommend you stop here and use another course to learn some javascript basics first.

Now, the way TypeScript works, is that it compiles ts files like the one you see here to regular javascript files behind the scenes. To do this in the best way, the typescript compiler needs a little bit of information on what to do. And that is the point of the tsconfig.json file.

This file holds different settings that tell the typescript compiler and the editor how to handle your code files. Namely, it tells what typescript files to compile and you can see the visual.ts file right here, along with the typescript file for the Power BI Visual API. You can also see other compiler options here, though you won’t have to worry about these at all.

There’s a couple of other folders in this project you can check out.

The dot API folder contains the code files for the Power BI Custom Visual API itself.

You can see I’m currently on version 1.6 of the API but yours may be different depending on when you’re watching this course. As a general rule, you don’t need to fiddle with these files. There’s also a way to upgrade and downgrade these api files, and we’ll take a look at it in a later video.

The dot vscode folder contains configuration files specific to visual studio code. You don’t need to worry about these, especially if you’re using another editor.

The assets folder is where you can put any non-code resources such as text resources and images. For example, you can an icon file here, this is the default icon of your new visual.

Finally, the style folder is where you can put any stylesheet files to format your visual. You can already see a less file here, as a default for the project.

And that’s it for the file structure in this project.

This may seem like a lot of stuff but most of it is pre-baked scafollding for the project.

There are only a couple of files you need to care about, namely the visual.ts file and a couple of json configuration files you may to tweak every now and then.

In the next video, you’ll get this project running over the Power BI service and understand what’s going on behind the covers.

Jorge Candeias's Picture

About Jorge Candeias

Jorge helps organizations build high-performing solutions on the Microsoft tech stack.

London, United Kingdom