C#: End-to-End PowerBI Embedding - "App Owns Data"

In working with a number of developer-heavy customers, there seems to be a strong demand for taking the reports and dashboard developed in PowerBI and publishing them in either Intranet or Internet web pages.  This concept is currently known as PowerBI Embedded and comes in several different options for developers to implement.

Licensing and Disclaimer

Before we start, I will note that there are definitely licensing concerns and implications to choices made as a part of this tutorial.  While I could likely articulate the current rules surrounding PowerBI licensing, there are a variety of options and I am not truly qualified to explain all of these nuances. . . .so I won't even try.

PLEASE seek assistance from your Microsoft account team if you choose to Embed PowerBI in your applications to determine what licensing model works best for your organization.

Additionally, technologies frequently change.  I will make every attempt to update this tutorial as functionality and technology changes, however for the most current up-to-date information, you should always refer to the Microsoft PowerBI developer documentation, and never any individual tutorial (including this one).

Step 0: Make Some Choices

Before we begin, lets discuss some of the options available to developers who are trying to embed their report.  At it's simplest, developers can place their PowerBI reports in a web page by using an HTML IFRAME on their site and ensuring they have a pointer to the correct PowerBI report.  Here are a simplified list of options:

Option A - Publish to Web

The simplest way to get a PowerBI report into your website is to use the "Publish to Web" option in PowerBI.com.  Just publish your report from the PowerBI client application, and from the File Menu choose "Publish to Web".  This is an entirely public method of publishing though, and there is NO way to lock down ANYTHING.

Option B - User Owns Data

The second option is currently termed "User Owns Data", and in this model, each user who logs into your website with a valid Azure AD account will be allowed to see what they're permitted to in any given PowerBI Report.  Great for Intranet sharing where you know all of your users and trust their Azure AD sources.

Option C - App Owns Data - FOCUS OF THIS TUTORIAL

The third option is currently known as "App Owns Data" and leverages what is essentially a single service account to publish the report as that service account user.  Great for situations where you are publishing a report on a public website where users will not be logging in before they see your PowerBI report. 

Assuming you chose to go with Option C above, the rest of this tutorial will walk through how to implement this.  You can also follow the tutorial linked in the Option C section above, but these steps should simplify the official tutorial some more.

Step 1: Develop a PowerBI Report

While it may seem obvious, this first step is important to leveraging some of the tools to their greatest extent.  You can change your specific report later, however for the purpose of following the PowerBI Embedding wizard, it's easiest to have a .pbix file on hand as you embed your first report.
The easiest way to develop your first report is to download the PowerBI client and create a report to embed.  If you haven't done so already, you may download the PowerBI client from powerbi.com.

Step 2: Obtain a Service Account

This approach assumes that a service account user will be logging into PowerBI on behalf of your application, therefore, you will need to have a fully licensed PowerBI user [with password] created. Speak with your organization's Azure AD administrator and have them authorize the new user for PowerBI in the Office Portal (portal.office.com). 

Step 2a -Test Logging In with Service Account

Just to be sure your user was provisioned correctly (and has access to PowerBI), PLEASE login to Powerbi.com with your new user and ensure they can use or see a report (ideally the one you created above in Step 1).

Step 3: Use the Wizard!

The PowerBI product group recently developed an amazing wizard to walk users through the process of creating and embedding reports in your website.  Navigate to the wizard at https://app.powerbi.com/embedsetup and choose the option labeled "Embed for Customers".  If you are using PowerBI Government, the same wizard is available to you at https://app.powerbigov.us/embedsetup.

The following are some important notes for as you walk through the wizard:

Step	Note
Step 1 - Sign In	Sign in with your new service account. If you do not login with your service account, your "user" will never have the chance to accept terms and conditions (Step 5), and you will get some strange unauthorized error in your code.
Step 2 - Register Your Application	The PowerBI report you are creating needs to be registered in Azure Active Directory so that OAuth can be used to verify your user has rights to the report being published. The official Microsoft tutorial goes into great detail on what this means and why, but for now, just give your application a name so that it gets permission to use the embedded objects.
Step 3 - Create a Workspace	Even though you probably already have a PowerBI workspace, just let the application create one for you. Your code can be updated later.
Step 4 - Import Content	Same as above. Even though you've probably already created a report, just for now, provide it a .PBIX file so that it creates another one for the sample source code that comes out of the wizard.
Step 5 - Grant Permissions	Since this service account is acting like a user, and every user needs to accept terms and conditions when using Azure AD for Oauth. . . .you'll need to allow your application and user to be related with one another in this step.

Upon completion, you should see an option to download sample code.  Download this .zip file and unzip it somewhere you can open it in Visual Studio 2015 or higher.

Step 4: Modify the Sample Solution Code

Open the .sln file you just downloaded in Visual Studio and navigate to the web.config.

Step 4a - Add Password to Web Config

The solution should have everyhing you need. . . EXCEPT a password.  While we should NOT publish this code (nor check it into source control) with a password in our code, for now we just want to be sure everything is working.  Add your password to the AppSettings section where you see the blank.

Step 4b -  Restore NuGet Packages

From the Tools Menu, navigate to the NuGet Package Manager and choose the option to restore packages not currently in the solution.

Step 4c - Update NuGet Packages (Optional)

If you will be publishing your work to a modern web server, you will likely want to update your packages to ensure any vulnerability and server-side incompatibilities are addressed before being published.  

Step 4d - Build and Run

If it worked, you should see a set of 3 buttons. . . if you pick Embed Report, the following should show without an error:

Step 5: Secure Your Identity

Now that we know it works, you will now want to go through and hide your service account's login in something other than plain text in the web.config file.

In the next article we will go through the options for securing your identity if you are using an Azure Web Service.  Stay tuned!

C#: Azure Government Development in Visual Studio 2017

A lot of government developers I've worked with over the past several weeks were all curious how to  implement and deploy Cloud-based solutions to Azure Government from their Visual Studio environments.  This brief tutorial goes through the steps currently required to configure Visual Studio 2017 (any version) to publish cloud services.

Step 0 - Verify Visual Studio has the Azure SDK

Before working with any Azure cloud service (Government or Commercial), Visual Studio must first have the Azure SDK installed on it.  This provides a great many pre-defined templates and class libraries that developers can use in building their solutions.  

To ensure your version has the Azure SDK installed, simply try to create a new project and look for the Cloud option under your preferred language and see that templates are displayed as shown in the following:

If you do NOT have these, click on "Open Visual Studio Installer" at the bottom of the left panel to fire it up and download the Azure SDK.

Step 1 - Install the Azure Environment Selector

Out-of-the-box today, Visual Studio expects developers to be accessing and publishing to the standard Azure Commercial or Enterprise Cloud.  Since we are going to be working in the Government cloud, we have to switch the configurations inside of Visual Studio.  Rather than do this manually every time from the command prompt or a text editor, we'll be installing the Environment Selector "extension" instead.  

From the Tools menu, select Extensions and Updates

From the Extensions window, find and download the "Azure Environment Selector" extension.

Once downloaded you will see an alert at the bottom of the window next to the Close button that alerts you this will be installed once you exit Visual Studio.  

Exit Visual Studio and you will be prompted with the Visual Studio Extension installer to modify Visual Studio.

Step 2 - Switch Environments

Upon returning to Visual Studio, you should now see a new item on the Tools menu for the Environment Selector.

Clicking on this new menu item will bring up a dialog box allowing you to change from the Commercial Cloud to the Government Cloud.  Once selected this will require a restart of Visual Studio in order to take effect.

Step 3 - Publish Cloud Projects to Azure Government

Now that Visual Studio is targeting Azure Government, open (or create a new) Cloud-Based project and from the project name in the Solution Explorer, right click and "Publish" your service.

Visual Studio will take you to a Publishing wizard that allows you to publish a new service or replace an existing one.  

Before you can complete the publishing process, you will need to login to Azure Government with your credentials (shown in the top right of the screen as shown here:

C#: Sharing a Visual Studio Pro 2017 Project on GitHub

This article will go through and provide a step-by-step guide on how to post a Visual Studio 2017 Project and Solution to a newly established GitHub Repository (repo).  As with many tools, there are a multitude of paths to take and different ways to accomplish a task like this.  This just provides one possible path to accomplish this task.

Step 1 - Add GitHub Tools to Visual Studio

Before we can use GitHub from within Visual Studio 2017, we need to install the plug-in to make it easier to manage.  You can of course just use Git from the command line as well. . . .this article instead looks at the GUI though.
From the Tools menu, navigate to Extensions and Updates.

Once the Extensions and Updates window opens up, navigate to the "Online" item and search for "GitHub".  The "GitHub Extension for Visual Studio" (the one with the official GitHub icon) is the extension you're looking for.  Find it and Install it.  

Step 2 - Configure the Team Explorer

For this next step, I'll assume you have the Professional or Enterprise edition installed with Team Explorer functionality.  Navigate to the Team Explorer if you don't already see it on your screen by going to View >> Team Explorer.

In the Team Explorer window, click on the plug-shaped connections icon to add a new connection to GitHub.

From here, we need to login to GitHub with your GitHub account (just go sign-up for a new account if you don't have one yet). 

Step 3 - Create a New GitHub Repo

Now that you've connected GitHub to your Visual Studio environment, you should see your existing GitHub repos listed in the Team Explorer Connect screen.  For this tutorial, we'll create a new repo for a new project by clicking on the "Create" link and entering some details about the repo in the accompanying pop-up window.

WARNING: you will not be able to mark the repo as "Private Repository" unless you have a paid GitHub Account.  Free accounts are only available publicly for all to see.  Again, just to reiterate. . . .the new repo you create will, by default, be PUBLIC and available for ANYONE to see.

Assuming your create request was successful, you will see a resulting success alert in the Team Services window.

Step 4 - Create a New Solution & Project In the Repo

Now that we have a repo, we can navigate back to the Team Explorer Tab and select our newly created repo to make it active in our work-space.

Once selected, the "Home" subtab inside of the Team Explorer should open and present you with a list of actions you can take with the repo.  Initially, we see that no project has been created or associated with this repo, so we will choose the "New.." link under Solutions.

This will bring up the familiar New Project wizard to allow you to pick your project type and name your project.  For this demo, we will just create a sample web project.

Once created, we can navigate back to the Solution Explorer and see our project exists and source code control icons exist next to each file to denote the status of each file under source control.  By default, Visual Studio includes all relevate source code files but one can add items to be excluded (e.g. add them to the .gitignore) pretty easily later on the commit page.

You should also note, that the toolbar at the bottom of the Visual Studio window now shows a number of Git-related icons that can be interacted with to view edits, make a pull request and select the active branch you are working in at the moment.

Step 5 - Commit Your Work Locally

Git, as an open standard, allows users to work locally on their machines with a copy of the source code in a local repo, and then when satisfied the code is correct, it allows you to commit your changes locally first, then eventually (and separately) commit your code externally to your server or cloud provider.
The first part is committing our work to our local repo hosted on our machine.
In order to do this, we simply click on the pencil icon in the toolbar, or choose "Changes" from the Team Explorer.

Step 6 - Commit Your Code to Cloud

Now that the code has been committed locally, it's time to commit our changes to the GitHub servers.  In order to active this process, we simply choose "Sync" from the Project Explorer to allow Git to see if anyone has already made changes on the server that need to be resolved on our client before posting our changes.  

Once Git has done its job and you have addressed any conflicts, the changes can be "Pushed" to the cloud from the Sync page.

If the push was completed successfully, a warning appears on the Team Explorer like so:

And you can navigate to https://www.github.com/ to see that your project is now accessible in the new Git Repo you created.