Since the PnP team announced that the venerable SharePointPnPPowerShellOnline module was going to be replaced by the shiny, new PnP.PowerShell module there has been some confusion on which module to use and which PowerShell to use. I have good news, the answer is “D. All of the above.” In this blog post I’ll show you how you can have both modules installed and use them interchangeably as well as use either of them on whatever version of PowerShell tickles your fancy.
A Few Words about Modules
Before we can get into how to do this I want to spend some pixels on why we have to do it the way we do. I intended to publish this blog post a couple of weeks (okay, months) ago but as I was doing my research I kept learning more. Most of the learning was around the “Module” cmdlets and what each of them does. In order to get the two modules to cooperate we need to use the right Module cmdlets at the right time. Here are the Cliff’s Notes:
Several Module cmdlets deal with what PowerShell Modules are installed on your system with PowerShellGet. There are a lot of ways to install Modules into PowerShell and PowerShellGet is one of the most popular and it’s built into PowerShell. Here are the pertinent cmdlets and what they do:
- Install-Module – Downloads a module from a repository (the PowerShell Gallery by default) and installs it on the system.
- Get-InstalledModule – Lists the modules that were installed on the computer with PowerShellGet
- Uninstall-Module – Uninstalls a packages from that computer that was installed with PowerShellGet
The key here is that the scope of those commands, and the other PowerShellGet cmdlets, is the whole computer
“Host” is a fancy word for PowerShell window or console. There are a few common Module cmdlets that deal only with the host they’re run in. Here are some of my favorites:
- Import-Module – Imports a module that was already installed on the computer into the host
- Get-Module – Lists the modules currently imported into the host. The –ListAvailable parameter shows modules installed on the computer that can be imported into the host
- Remove-Module – Unloads (unimports? exports?) a module from the host
These cmdlets are all part of Microsoft.PowerShell.Core as opposed to PowerShellGet.
The Import Business
Now we know how to get a module installed onto our computer, and how to manually coax it into our host. But most of us have never done all this Import-Module business but everything seems to work. How’s that? PowerShell has the ability to automatically load modules when they’re needed. The entire, exciting, story of how PowerShell imports modules is chronicled here, but I’ll give you the highlights. If you try to use (or reference it with something like Get-Command) a cmdlet that isn’t in a module already loaded PowerShell will walk through the PSModulePath locations looking into each module for the cmdlet you’re trying to run. If it finds it, it implicitly imports that module and Bob’s your uncle. You can use $env:PSModulePath to see where PowerShell will look. It’s important to note that Windows PowerShell 5 and PowerShell 7 have similar, but different PSModulePaths. Here’s what it looks like in both. I added -split ";" to put each path on its own line, and I piped it through Sort-Object to make them easy to keep track of.
$env:PSModulePath -split ";" | Sort-Object
To make either Module, SharePointPnPPowerShellOnline or PnP.PowerShell, available to both Windows PowerShell 5 and PowerShell 7 it has to be installed in one of the paths that both versions of PowerShell will look in. For backwards compatibility PowerShell 7 looks in the PowerShell 5 paths, so I do the Install-Module bit in PowerShell 5 and PowerShell 7 gets it for free. You could install it in both, that works. But this way keeps you from having to update it both places every time a new version comes out. The PnP.PowerShell module is aimed for PowerShell 7, but also works fine in PowerShell 5. Erwin told me they may remove that support in future, but for now it’s safe.
You can see from the screenshots that I have my Known Folders redirected to OneDrive. When installing these modules PowerShell was installing them to my personal folders and it was causing problems. A couple of the Module cmdlets don’t handle that well. To get around some of that chicanery I had to install the modules in a different path. The easiest way I found to do that was the specify the scope Allusers, like this:
Install-Module PnP.PowerShell -Scope AllUsers
In PowerShell 5 that installed into C:\Program Files\WindowsPowerShell\Modules\PnP.PowerShell, which PowerShell 7 can see so it can be imported into a host of either version and it’s not in OneDrive.
Using Both Modules in Both PowerShells
We know both PowerShells can run both modules if we install it right. To get everything playing nicely I uninstalled both modules from both versions of PowerShell using Uninstall-Module -Force –AllVersions. In one case Uninstall couldn’t clean it all up so I had to go into the file system and delete the folder manually. I also had to close the host various times as it had imported the module I was trying to uninstall and I couldn’t get it unloaded in that host.
After all the uninstalling was done I closed all of the PowerShell windows I had open and I opened a PowerShell 5 window in Admin mode. I installed the old module with this:
Install-Module -Name SharePointPnPPowerShellOnline -Scope Allusers
That made it so it could be imported into both PowerShell 5 and PowerShell 7. Next I installed the PnP.PowerShell module. This one took a bit of extra coaxing. It’s currently in prerelease so Install-Module requires the –AllowPrerelease parameter. The version of PowerShellGet in PowerShell 5 does have that. I had to upgrade PowerShellGet first with this line:
Update-Module -Name PowerShellGet
I close the window and opened a new one for good measure. This put me at version 2.2.5 of PowerShellGet. One problem solved. The second problem is that PnP.PowerShell and SharePointPnPPowerShellOnline share most of their cmdlet names, so a regular Install-Module is going to fail. To fix that we need to use the –AllowClobber parameter. The whole thing looks like this:
Install-Module -Name PnP.PowerShell -AllowPrerelease –AllowClobber
At first this sounds scary, but remember, Install is just dropping the bits onto your computer. You can still control which module gets loaded in a script or host. To do that using Import-Module. The key is to use Import-Module before you do anything that will trigger PowerShell implicitly loading the module for you. If you want to force your script to use a specific module include one of these lines at the top:
You would do the same thing in a PowerShell window when you open it to run some cmdlets. I’ve been doing this for a few weeks and it works well.
Using Both Modules in the Same Host
Now I’m just going to show off a bit. We know we can load either module into a host, but what if we need both modules into the same host or script at the same time? It came be done! It sounds like magic, but it works. The key is using the –Prefix parameter of Import-Module. If you want both modules loaded and available in the same window you need to import one with a prefix. It looks like this:
Import-Module SharePointPnPPowerShellOnline -Prefix Old
You can see from the screenshot that both sets of cmdlets are available, with the SharePointPnPPowerShellOnline versions having the additional prefix of “Old.” I wouldn’t recommend doing this as a normal course of action, but it’s good to know it’s there. PowerShell 7 is a little fussy when doing this. I had issues importing the old version if I had already imported the PnP.PowerShell module explicitly or implicitly, which is why I didn’t in this screenshot. Get-Command implicitly loaded it for me, so that wasn’t an issue. PowerShell 5 handles it more gracefully.
There it is, the culmination of weeks (maybe months) of me fiddling around to understand the inner workings of PowerShell module installing and importing. Thanks to Jeff Hicks for holding my hand and answering all my dumb questions. Hopefully my pain will make your transitions from PowerShell 5 to PowerShell 7 and from SharePointPnPPowerShellOnline to PnP.PowerShell easier.