Get started with PnP-Powershell!
June 13, 2017 by Corrie Haffly

Welcome back to our guest blogger series. This is your chance to learn a little something about the men and women behind the screen and discover what drives them.

Our second entry comes from our Senior Web Developer, Corrie Haffly. With years of experience in front end design, web development, and SharePoint branding, Corrie is a vital member of our team. Join Corrie as she walks us through some of the pretty incredible things you can do in SharePoint using Powershell and PnP.

Using Powershell and PnP, we can do lots of cool things with SharePoint!

Upload files to different locations

Create lists and populate them

Create content types, columns/fields, terms

Create pages and add web parts to them

Apply page layouts

Inject Javascript

Apply alternate CSS

And more!

These are all things we’re used to doing in SharePoint Designer or with WSPs, but with PnP, we can essentially build a package that acts as a site template and push it out to update existing sites or create new sites. The possibilities are exciting.

The basic provisioning package folder structure looks like this, and can reside anywhere on your computer:

Inside the simple deployment package is a Powershell script file (simple.ps1), which holds the commands that will be run in Powershell.

Inside the templates folder is an XML file (simple.xml), which holds the provisioning template structure.

Finally, there is a pageimages/sample-photo.jpg file.

By the end of this article, you’ll be able to run the Powershell script which will upload the sample-photo.jpg file to the PublishingImages folder in a SharePoint site. You won’t be making any code changes; this is just an overview to walk through the files and the process!

The <pnp:ProvisioningTemplate> element is what will hold most of the things we are concerned with. It can contain other elements that you’ll find useful, such as <pnp:SiteFields>, <pnp:ContentTypes>, or <pnp:Lists>.

In this example, though, it only contains one element: <pnp:Files/>

<pnp:Files/> can also contain multiple elements for each file. In this example, we only have one file—the element for sample-photo.jpg.

Take a look at the <pnp:Files/> line of code (read the comments which are the lines preceded by a #!):

<pnp:FileFolder="PublishingImages" # this is the SharePoint path - so we will be putting this file into # the PublishingImages folder in the site collection rootOverwrite="true" # files can be overwritten - so if you already have this file # in your site, it will just be overwritten.Src="pageimages\sample-photo.jpg">
# this is the file path - so it needs to use back slashes to
# point to the file location relative to your XML file.
# You could change the "pageimages" folder name to
# whatever you want, as long as you change the location
# here as well.</pnp:File>

What if you wanted to upload two images to your SharePoint site? Simple – just copy the line of code and change the Src. Or, if you want to upload CSS files and other branding assets into the _catalogs/masterpage/ location in SharePoint, you could do that as well. Here are some examples of that kind of code below:

There are two parameters, separated by the comma. The first parameter is for the URL of the site to be provisioned. The second parameter is for optional credentials.

The parameters also have to have the type of input specified (String or PSCredential), and finally the variable name ($targetWebUrl, $Credentials) which stores the input and can be used in the rest of your script.

Where does the HelpMessage turn up? When you run the script without adding parameters, Powershell will prompt you for the mandatory parameters. In this example below, I ran the “simple.ps1” script in the Powershell console. (Don’t try this at home yet—at the end of this article, I’ll take you through all the step-by-steps!)

In try, Powershell connects to the web site using the credentials that were entered earlier. Then, it applies the provisioning template using the provided path.

Pro tip: If you are writing your own scripts, you can comment out some of the actions (such as Apply-SPOProvisioningTemplate in the try block and add Write-Host lines to print out variables to the console. This is an easy way to error-check without having to sit through waiting for the provisioning process to run.

Try it!

Prerequisites

You will need a SharePoint environment to play with. (SharePoint Online is best; SharePoint 2013 and 2016 should work as well with the latest server patches.)

You’ll need to make sure you have PnP-Powershell installed. Take a look at PnP-Powershell’s Github and scroll down to the Prerequisites section, then the Installation and Updating sections, to do everything you need to do.

If you want to check to make sure that your installation worked, open Windows Powershell and type:

Get-Command -Module *PnP*

If your installation is good, you’ll see a whole list of PnP-Powershell commands get listed out in the console:

Provision the template

Run Powershell to provision the template: First, open Windows Powershell as an admin (right-click on Powershell and choose Run as administrator.

CD to the folder that contains simple.ps1:cd "C:\yourdirectory"

Run the file. To do it with prompts as described above, type .\simple.ps1

To save yourself some time, enter your credentials first and then run the file with the parameters as well: