Office 365 Developer PnP PowerShell Cmdlets

The OfficeDev PnP Cmdlets are a set of cmdlets specifically designed to provision and modify artifacts in SharePoint Online. In this way they differ a bit from the PowerShell cmdlets provided by Microsoft which are mainly focused on administrative tasks. 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.

If you want to see the cmdlets in action, please check out this video on Channel 9.


Installation

First you need to determine if you want to use the Cmdlets towards SharePoint Online / Office 365, or if you want to use them on-premises. There are two different builds of the cmdlets:

PnPPowerShellCommands15.msi for SharePoint 2013 On-Premises

PnPPowerShellCommands16.msi for SharePoint Online / Office 365.

You can download the releases here: https://github.com/OfficeDev/PnP-PowerShell/releases

Download the appropriate package and run the install.

intro01

Accept the license agrement and click ‘Install’. The Advanced option allows you to pick if the cmdlets should be installed only for you or if you want to install them for all users on your computer (the latter requires that you have administrative rights with the account you are logged in with).

The install shouldn’t take more than a few seconds.

Using the cmdlets

The cmdlets are using CSOM behind the scenes. CSOM stands for Client Side Object Model and is the default SDK that 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-SPOnline cmdlet:

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-SPOnline 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:

To retrieve a specific list:

or

To view a property of the list:

Or to get an overview of all the properties available in the list:

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:

This will return an error as shown in the following screenshot:

intro02

This means that while the $list  object has a property called Views, you need to explicitely request it from the server (notice, there is also a Get-SPOView  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 explicitely 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:

intro03

Whats commands are available?

Currently there are over 135 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:

This will list all available cmdlets.

If you want more details about a specific cmdlet, for instance about the Get-SPOList cmdlet, enter:

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://github.com/OfficeDev/PnP-PowerShell/tree/master/Documentation

 

Missing functionality or want to contribute?

The cmdlet sourcd code is available in the following github repository: https://github.com/officedev/pnp-powershell. This is a sub repository for the PnP Repository available at https://github.com/officedev/pnp. In the latter repository you will find a wiki page athttps://github.com/OfficeDev/PnP/wiki/contributing-to-Office-365-developer-patterns-and-practices that should get you up and running with a pull request, which is the github way of proposing an addition and/or change.


Further Information

Introduction to Office 365 PnP

Getting Started with Office 365 PnP

What is Office 365 PnP (Practice and Pattern)? It is about providing a site provisioning engine to create sites and site collections within a SharePoint Online tenant or a on premise SharePoint farm base on a given definition. The definition of a site provisioning engine is an object describing the provisioned components like list, libraries and features. But also SharePoint security groups, users, site property bags entries and Composed Looks. O365 PnP is also about rising initiatives awareness to the public community about training, best practices and guidance.

With the template provider, the definition object can be transformed to JSON or XML. This works in both ways, so you can transform a XML definition into an object. Therefore you are able to define the structure of a site or site collection in a XML template. The definition object will be referred to as PnP template. Few classic site provisioning techniques is best explain with the blog author Vesa Juvonen who explains these techniques in more detail.

The modern way of site provisioning is remote provisioning. Remote provisioning uses the Client Side Object Model (CSOM) or the REST API to create a site and fill this site incrementally with CSOM/REST requests. This model is suitable for both on-premises and Office 365 online in the cloud, since we control the customizations outside of the SharePoint farm in an independent solution.

To improve the experience using remote provisioning, the Office Dev PnP team created PnP Provisioning. As mentioned earlier, a really great part of PnP Provisioning is defining a site template in a XML using the PnP Provisioning Schema.

 

Component of PnP

All components of office dev pnp are placed on github. It started in a single repository, but soon the volume of the program became so large, the office dev pnp team decided to split the individual components in separate repositories.

Pnp partner pack
contains the pnp partner pack, a starter kit for customers and partners and combines numerous patterns and practices demonstrated in the pnp samples to one reusable solution, which can be deployed and used in any office 365 tenant.

Pnp sites core
contains the core library and the pnp provisioning engine. The pnp provisioning engine helps to deploy customizations to remote sharepoint environments.

Pnp powershell
contains powershell wrappers to the functionalities of pnp core.

Pnp guidance
contains the documentation and guidance of the program. The contents of the master branch are published to dev.Office.Com and msdn.

Pnp office add-ins
contains samples of how to work with the html and javascript based office add-in model.

Pnp tools
contains more tools, code packages and scripts for the on-premises and hybrid setup, than purely for the office 365 operations. Using classic terminology, this could be considered more targeted for it pro’s, architects and administrators in on-premises deployments.

Pnp transformation
contains the farm solution to add-in model transformation tooling and guidance.

Pnp provisioning schema
contains the provisioning schema for pnp provisioning in XML format, a community driven effort for designing one schema which can be used to define elements in the office 365.


To get started with Office 365, below are some top useful links to begin with:

1. Watch this video title “How to get started with Office 365 PnP” webcast from Channel 9 video blog. You can download the presentation slide for this video here

 

2. Visit the O365 PnP home page at:  http://dev.office.com/patterns-and-practices 
From this homepage go to the trainining section and watch the videos:

NOTE:
* To find and download the Power Point presentation slides for each video, go to https://docs.com and search for the video title.
* Each training video also contains its sample source codes which can be found at this GitHub site: https://github.com/OfficeDev/TrainingContent/tree/master/O3658

 

3. Visit the O365 PnP GitHub open repository site to explore sample codes and other useful links.

 

4. To find and search for relevant sample codes and documentation guide on using O365 PnP, go to http://dev.office.com/patterns-and-practices-resources

 

5. Install the following tools:

 

6. Create a Console application project in VS to provision a document library into O365 SharePoint site. For sample code watch the video title “How to get started with Office 365 PnP
Other useful links of sample codes for  specific project needs are:

Introducing PnP Core Component

Site collection and sub site provisioning:

PnP Partner Pack:


Further information