Office 365 – How do debug PnP PowerShell commands

Further to my one of my previous posts How to debug PnP Provisioning Engine in which I explained how to use the Set-SPOTraceLog Cmdlet to get more information from your PnP PowerShell commands. In this article I’m going to describe how to debug the PowerShell source code itself.

When the Set-SPOTraceLog got me to the point where a certain list was causing problems, I now want to know how to fix the actual issues. This quite often requires more detail than just knowing which list, content type of column is causing a command to fail.

The PnP PowerShell is a layer calling the PnP Site Core libraries. The core libraries are doing the actual work. So most likely when you feel the need to debug the PowerShell commands you will find that you actually want to debug the core library.

Setting up Visual Studio

First of all I’m assuming that you have installed the  PnP PowerShell by running the .msi files in the releases location of the PnP github. You will need to uninstall these as the Visual Studio version of the same files will located the command files in a different place.

Cloning PnP Repositories

We will now use the Clone option. You will now need to supply the url of the projects on Github.

You could use use https://github.com/OfficeDev/PnP-PowerShell however it would be better to use your own fork. Your fork is like a branch that is for your use only.

In my case I’ve set up my branch at: https://github.com/Pieter-Veenstra/PnP-PowerShell

Once the above form is complete click on Clone. This could take a while …

Once the PowerShell code is there you will see the repository there in Visual Studio.

Now it is time to repeat the same for two other repositories.

Again my forks are:

• https://github.com/Pieter-Veenstra/PnP-Sites-Core
• https://github.com/Pieter-Veenstra/PnP-Provisioning-Schema

You should of course create your own forks from the OfficeDev/PnP-Sites-Core and OfficeDev/PnP-Provisioning-Schema projects.

Once all repositories have been cloned you should have something like this (you don’t need the github repository):

Ok, so now I’ve got the latest code from my forks. But the code in the OfficeDev repositories has been updated. How do I sync this?

Synchronizing repositories

In Visual Studio you might see a warning:

If you get the warning then you haven’t installed Git yet. You can either click on the install link or download it from https://git-scm.com/download/win.

Once you have installed Git, you will be able to synchronize the repositories.

First I’m going to open the Provisioning Scheme project.

I can now see that my last updates were done at 08/01/2016 by Paolo Pialorsi

Now I want to synchronize with the latest code where more recent updates were done.

I will need to go to the git bash (this is installed as part of git). First I changed to the folder containing my repository.

Then the git-remote -v shows my my repositories.

I want to syn with the Office dev fork not my fork! Why does Git not know about the parent fork?

Now I run:

git remote add OfficeDev https://github.com/OfficeDev/PnP-Provisioning-Schema

then again I run the git-remote -v

OK, so now I’ve got git to know about OfficeDev, then I tried in Visual Studio to merge branches but Visual Stuido doesn’t seem to pick this up. It only knows about origin.

So back to Bash

I ran

git fetch OfficeDev

Alternatively within Visual Studio you can also fetch the code from officeDev:

and now Visual Studio knows about this branch. I select the Merge from option

Now I had to select which branch to merge from and I selected OfficeDev/master which is the master branch. So this code matches the latest release code. When needed you might want to select development branches here.  In the other two projects (PowerShell and Core) there is a clear branch called dev.

Then finally click on Merge and the master branch of my code should now be updated with the latest changes.

When I now check version history of my source code I can see the latest updates.

So now I go back to my fork on github and I’m still getting a 36 commits behind.

So I’ve got my latest code locally but I’ve not checked that into my fork in github.

In Visual Studio, you can see the outgoing commits in the Team Explorer -> Synchronization.

Click on Sync and your fork will be updated.

Now repeat this for the Site Core and PowerShell projects.

At last we’ve got the latest code both locally and in Github. Although technically we probably didn’t need to syn with Github to do the debugging it is a good idea to sync your personal fork every now and then.

Debug PnP PowerShell.

So now finally I get to the point of debugging PnP PowerShell

Open the project OfficeDevPnP.Core in Visual Studio and build the OfficeDevPnP.Core project.

Open the project OfficeDevPnP.PowerShell in Visual Studio.

Then Build the following projects:

• SharePointPnP.PowerShell.CmdletHelpAttributes.csproj
• SharePointPnP.PowerShell.CmdletHelpGenerator.csproj
• SharePointPnP.PowerShell.Commands.csproj

This last  build should copy the powershell commands to your profile:

C:\Users\username\Documents\WindowsPowerShell\Modules\SharePointPnPPowerShellOnline

Now we are ready to get started:

Open PowerShell ISE, or the non ISE version of PowerShell and check that the PowerShell commands are available.

Within your PowerShell window run the following commands:

Connect-SPOnline -Url https:/ /mytenant.sharepoint.com

Get-SPOProvisioningTemplate -Out c:\temp\templates.pnp

No open the pnp sites core project in Visual Studio and set a break point in the GetRemoteTemplate in the SiteToTemplateConversion.cs

This can be found in:  C:\Github\PnP-Sites-Core\Core\OfficeDevPnP.Core\Framework\Provisioning\ObjectHandlers\SiteToTemplateConversion.cs

No attach the debugger to your PowerShell ISE:

Select the powershell_ise process and click on Attach

Note that in Visual Studio your break point now shows the red dot.

rerun the Get-SPOProvisioningTemplate command in PowerShell and your breakpoints will be picked up and you can step through the code.

If you find that Visual Studio doesn’t pick up the thread then you might have to open up some ports on your firewall. For more information see: https://msdn.microsoft.com/en-us/library/mt592018.aspx

Alternatively you can also use the PowerShell Interactive Window available in Visual Studio. Just attach the process to the PowershellProcessHostConsole.exe instead of powershell_ise.exe