thumbnail

PnP Powershell: How to get your job done faster in one line

There are various ways that lets you perform CRUD (Create, Read, Update, Delete) operations and queries against SharePoint such as:

  • using the REST API;
  • Microsoft Graph API;
  • SharePoint CSOM: retrieve, update, and manage data in SharePoint;
  • PowerShell cmdlets: lets you manage most aspects of SharePoint Server.

I’m going to show you a ‘good to know’ solution I use to perform actions when it comes to implement a new functionality in my SP Web Application and how to approach possible problems that you can encounter.

When it comes to make changes into a site collection or a list, you can easily do it manually in the UI provided by SP platform.

For example, you have a custom document library that contains important documents related to employees and you need a column called Hobbies that gives you extra information about the employee.  This can be done by accessing Add from existing site columns under Library Settings menu. That’s totally fine and correct but, imagine having to implement that change for each similar document library from each site collection in each web application of the farm.

Or imagine having to create 10 lists on all your sites from all your web applications. This is not an easy job to do manually and can lead to lots of problems because it is in human nature to do mistakes, to forgot and omit details. Not to mention about the time spent doing this.

How does it sound to you a way in which a few lines of code can solve this in just a couple of minutes?

This can be accomplished by using the PnP library, that I consider easy to use for SharePoint beginners and administrators without programming knowledge. PnP stands for Patterns and Practices and it is a library made of PowerShell commands. Those commands can be used to perform complex actions towards SharePoint. There are commands for both SharePoint Online and SharePoint On-Premises environments.

This article is based on commands for SharePoint on-premises, but the differences are not that big. With PnP you can access sites, subsites, web applications, app catalogs, site instances: lists, document libraries, site columns, content types, site theme and font etc.

In order to get this library and make operations on your SharePoint application, first you need to install the library, and this can be easily done by running the following command:

  • Install-Module SharePointPnPPowerShell2019

    You can also update the library, as we already know that Microsoft team and the community continues developing and offering support: 

  • Update-Module SharePointPnPPowerShell*

    After the PnP library is installed, you can jump into work and get connected to your SharePoint site:

  • Connect-PnPOnline “http://computer-name:port/siteCollectionName” -CurrentCredentials

You may ask: “Where should I run all these commands?”. For writing scripts and running commands, I suggest Windows PowerShell Integrated Scripting Environment (ISE). With Windows PowerShell ISE you can run and write commands, test and debug scripts, but this is not the only software you can use in order to write scripts. You can also use Visual Studio Code with the PowerShell Extension. Microsoft designed Windows PowerShell ISE as a tool that helps you automate and quickly solve lots of tedious administrative tasks. The ISE provides among others, multiline editing, tab completion, syntax coloring, selective execution, the possibility to debug a script and set breakpoints.

The major benefit of using PnP PowerShell is that it is easy to use even for those with very little programming experience. For example, if you want to create a SharePoint site without having to do it all manually in the UI, you can use the following command:

poster

Or if you want to set a default value for a field in your list/document library:

poster

But the most amazing and useful thing you can do with PnP and PowerShell commands is iterating through site objects as lists, like in the example below. Here, the script iterates through all the lists of the current site collection having template 101 (document library) and stores them into $documentLibraries variable.

Using PowerShell commands, an iteration over them and their content types is performed in order to do some logic. In this case, a column with a specified name is marked as hidden. This example shows how easily a repetitive change can be performed using a script written in PnP combined with PowerShell cmdlets rather than doing it manually.

poster

Perhaps you have noticed the dispose method  I have invoked here. This is a case where you can encounter some problems when using PnP. In the following I’ll explain why this can happen and how to prevent errors when running a script.

When you develop a SharePoint application it is a must to understand the need for memory disposal practice. SharePoint objects, such as Get-PnPSite/SPSiteGet-PnPWeb/SPWeb, etc., consume resources, and it is the developer’s responsibility to release these resources by calling the dispose method on these types of objects when done using them.

Disposing objects it’s a very important process especially when it comes to run a large script or a script that goes through site collections:

poster

The preceding command iterates over every site collection for every web application in the farm. For each site collection, the script performs some logic. The issue with this command is that the call to Get-PnPSite for each web application uses space in memory for the new site object.

In a standard Windows PowerShell, not disposing of the site object after each iteration would cause a memory leak. When you close the PowerShell.exe process, the memory is freed. If you need to dispose objects to keep memory pressure down (important in production environments or if you're looping over all sites/webs), make sure to dispose.

            As you have discovered, memory management of SharePoint objects in PowerShell is important. If you are writing small scripts that have a short execution time, then memory-management is not one of your major concerns. However, if you have a script that iterates a large site collection and performs significant processing, then you can easily find yourself eating memory until your PowerShell instance crashes.

There is one more important point to be aware of: PowerShell does not clean up leaked objects at the end of scripts. In other words, if you have a leaky script, which you execute several times (perhaps because you are debugging), PowerShell is unable to claim the leaked memory until you terminate the PowerShell process. Again, this is not a big consideration if you are executing your scripts in a short window of time, but if you have a PowerShell script running for a lengthy duration, pay close attention to the amount of memory the PowerShell process consumes.

To sum up everything, here are some advantages and disadvantages when using PnP library:

Advantages of PnP:

  • works on both Online and On-Premises SharePoint environments;
  • one line of code it’s enough to do common tasks;
  • simple to install and update;
  • has a very powerful set of commands that enables coding in a single line;
  • maintained by Microsoft community and developers;
  • easy to use and learn;
  • efficient when it comes to perform repetitive actions that can be transformed into iteration statements.

Disadvantages of PnP:

  • the availability of the commands can be sometimes dictated by the SharePoint Server version;
  • forgetting to dispose objects may cause problems;
  • there are situations when using PowerShell commands makes the script easier to write.

As you could see in the code samples from this article, PnP is a nice solution when it comes to write one-line commands, but in most cases PowerShell commands offers a welcomed help. It’s recommended do be aware of what objects you are using in building your scripts. Consider that the dispose method eliminates all the managed resources and frees the memory.