As the new year approaches I find myself making changes. Like everyone on the planet I plan to eat less and exercise more. I also plan on making another change, I’ll be moving away from my friend the venerable old SharePointPnPPowerShellOnline module to the new, sexier PnP.PowerShell. I thought I’d blog the experience so you all can follow along.
Why the Move?
The SharePointPnPPowerShellOnline module has been good to me over the last few years. It has helped me do amazing things both in PowerShell and in SharePoint. Why would I ever give that all up? Because the times, they are a-changing. The SharePointPnPPowerShellOnline module is being retired and all of that effort is being channeled to the PnP.PowerShell module. The SharePointPnPPowerShellOnline module will continue to be around for the on-prem versions of SharePoint Server (though not updated), but for SharePoint Online/Office 365/Microsoft 365 you’ll need to use the PnP.PowerShell module.
Why did the PnP team decide this? You can get the whole story at the official PnP PowerShell page, but there are two main reasons. The first is wider platform support. SharePointPnPPowerShellOnline had .NET dependencies that meant it would only run on Windows PowerShell. Emphasis on Windows. When that module was first created 6 years ago that made perfect sense, but since then PowerShell has gone open source and now runs on a variety of platforms like Mac, Linux, a variety toasters, etc. Since SharePointPnPPowerShellOnline required Windows it couldn’t follow PowerShell onto those other platforms. The PnP.PowerShell module was written without those Windows dependencies so it can run anywhere PowerShell can run. You may not use a Mac, but this also means that you can use PnP.PowerShell more easily in cloud environments like Azure Functions.
The second reason was to give wider application support. The SharePointPnPPowerShellOnline mostly supported SharePoint, as the name would suggest. These days you can’t manage SharePoint Online without also needing to touch Microsoft Groups, Teams, etc. The PnP added more and more cmdlets to handle that, but there were some big authentication changes that needed to be made to fully support all of the other applications. They started adding some of that to SharePointPnPPowerShellOnline, but it was cobbled together a bit. While they were refactoring the module for .NET Standard they went ahead and made some sweeping authentication changes that mean we’ll be able to use it more easily for SharePoint and all of the other applications we know and love.
First Step PowerShell 7
The first step to moving to the PnP.PowerShell module is to install PowerShell 7, also called PowerShell Core. I’m on Windows, so that’s the process I’m going to walk through. Windows comes with PowerShell, Windows PowerShell 5.1. To use PowerShell 7 we’ll have to install it. Windows PowerShell 5.1 and PowerShell Core 7 can happily coexist on your machine, so you don’t have to worry about breaking any of your other existing PowerShell scripts or tools.
You can see from this screenshot I have both versions of PowerShell installed and running on this machine. You can use the system variable $PSVersionTable to see which version of PowerShell your host is currently using. It’s also pretty easy to pick the version of PowerShell you want when firing it up.
While PowerShell 7.x can coexist with Windows PowerShell 5.x, it will replace PowerShell 6.x if you have that installed.
I installed PowerShell 7 by downloading the installation MSI from the GitHub page. For me that was the Windows x64 platform and I grabbed the stable build. That file was PowerShell-7.1.0-win-x64.msi, but obviously that filename will change as PowerShell 7 advances. Then I popped open a Windows PowerShell 5 (oh, the irony) prompt in Admin mode and ran the MSI.
The friendly wizard walked me through the process. There are few installation choices to make, but I’ve found the defaults are usually fine.
After the installation is finished you’ll have both Windows PowerShell 5.x and PowerShell Core 7.x. Time to install some modules.
Installing the PnP.PowerShell module is pretty easy, but if you have the older SharePointPnPPowerShellOnline module installed you’ll need to uninstall it first. The cmdlet names in both modules are the same, So PnP.PowerShell won’t install all of its cmdlets while there are collisions with the old version. To uninstall the SharePointPnPPowerShellOnline module open up a Windows PowerShell 5 host in Admin mode and enter this:
Uninstall-Module SharePointPnPPowerShellOnline –AllVersions
and wave a fond farewell to our old friend. After that’s finished, and you’re done sobbing, open up a shiny new PowerShell Core 7 host in Admin mode. While you’re in there opening up in Admin mode, go ahead and add PowerShell 7 to your Start Menu and your Taskbar. You’ll thank me later.
Then issue this command:
Install-Module PnP.PowerShell –AllowPrerelease
You’re all done. Since PnP.PowerShell is not an official release yet you’ll need the scary sounding –AllowPrerelease parameter. After January of 2021 you won’t need that anymore.
I mentioned earlier that one of the reasons for changing modules was a change in authentication. I don’t want to get too deep into it in this blog post but I do want to mention that you should run Register-PnPManagementShellAccess to set up a an Azure Application Registration. This is the magic that allows the new PnP PowerShell access to all of the applications in Office 365. You may have seen this referred to as Graph API. I’ll dig into it later, but for now all you need to know is that a tenant admin needs to run the PnP.PowerShell version of Register-PnPManagementShellAccess once in your tenant. After that is in place you should be able to use Connect-PnPOnline and get connected.