Getting started with the Office 365 Developer Patterns and Practices PowerShell Cmdlets
Update 2020-08-17: Updated post to reflect latest state
Update 2018-03-14: Updated post to reflect latest state
Update 2015-08-25: Updated links
Update 2015-08-06: If you want to see the cmdlets in action, please check out this video on Channel 9.
The Microsoft 365 PnP Powershell Cmdlets are a set of cmdlets specifically designed to provision and modify artifacts in Microsoft 365. In this way they differ a bit from the Microsoft SharePoint Online Management Shell provided by Microsoft which are mainly focused on administrative task towards SharePoint Online.
In this post I will introduce you to the basics of the cmdlets.
The cmdlets utilize CSOM behind the scenes, which means that you can run them on any computer that has access to your server over HTTP / HTTPS.
Installation from the PowerShell Gallery
The cmdlets are available in the PowerShell Gallery at https://www.powershellgallery.com. If you are on a recent version of Windows, installing the cmdlets is very straight forward:
Install-Module -Name SharePointPnPPowerShellOnline
The packages for SharePoint on-premises are called SharePointPnPPowerShell2013, SharePointPnPPowerShell2016 and SharePointPnPPowerShell2019 respectively.
Using the cmdlets
The cmdlets use CSOM behind the scenes. CSOM stands for Client Side Object Model and is the default SDK that .NET developers use to build addins for SharePoint. A requirement to use this SDK is that the developer creates a so-called ‘context’ object. Think of a context object as a connection point to the server. In PowerShell we have to do something similar. We ‘connect’ the PowerShell session to your remote server with the Connect-PnPOnline cmdlet:
Connect-PnPOnline -Url https://yourtenant.sharepoint.com
When you enter the command, obviously with a functional url to your server and or Office 365, you will be prompted to enter your user credentials.
After you entered the Connect-PnPOnline cmdlet you can execute all the other cmdlets available in the PnP Cmdlets module to perform various tasks.
For instance, to retrieve all the lists in the site:
Get-PnPList
To retrieve a specific list:
Get-PnPList -Identity "Site Assets"
or
Get-PnPList -Identity c7617def-5f20-4c0a-a938-7b045ef6a6fb
To view a property of the list:
$list = Get-PnPList -Identity "Site Assets"
$list.Title
Or to get an overview of all the properties available in the list:
$list = Get-PnPList -Identity "Site Assets"
$list | get-member
Notice that not all properties might be ’loaded’ yet. CSOM tries to be efficient when it comes to retrieving data from a SharePoint Server, and this means it will only retrieve those properties that have been explicitely requested. It will for instance never automatically retrieve values of a collection. Let me explain this with an example:
$list = Get-PnPList -Identity "Site Assets"
$list.Views
This will return an error as shown in the following screenshot:
This means that while the $list object has a property called Views, you need to explicitly request it from the server (notice, there is also a Get-PnPView cmdlet, which returns all the views for a list, but in this case we’re going to retrieve the views the ‘hard way’).
In order to explicitly show the views we need to tell the server to retrieve the collection, and for that we need a ClientContext object. Look at the following PowerShell snippet:
$list - Get-PnPList -Identity "Site Assets" -Includes Views
$list.Views
Whats commands are available?
Currently there are close to 500 cmdlets available, each focused on a specific tasks. It goes to far to describe them all, especially because we have built-in help in PowerShell for the cmdlets after all. To get an overview of all available cmdlets after you installed them, open PowerShell and enter:
Get-Command -Module SharePointPnPPowerShellOnline
This will list all available cmdlets.
If you want more details about a specific cmdlet, for instance about the Get-SPOList cmdlet, enter:
Get-Help Get-PnPList -Detailed
This will return an overview of the supported parameters, a short description per parameter and one or more examples (notice, not all PnP Cmdlets show examples, but most of them do).
If you want you to have a look at all the available cmdlets with your browser, head over here: https://docs.microsoft.com/en-us/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets?view=sharepoint-ps
Missing functionality or want to contribute?
The cmdlet source code is available in the following github repository: https://github.com/pnp/pnp-powershell.