Thank you North American Collaboration Summit 2018!

Over the weekend I was able to attend and speak at the North American Collaboration Summit (Sharepointalooza) in Branson, Missouri. It was an extremely well run and attended event. It’s unbelievable to me that attendees were only paying $65 for content and experience that would cost $1500-2000+ elsewhere!

I spoke on Understanding SharePoint Patterns and Practices (PnP). I love this topic because it allows me to show off amazing stuff that always has immediate “Monday” value. People always leave this session with at least one or two things they’ll start using as soon as they get back to work. SharePoint PnP is awesome but it can be difficult to know about everything that is available.

I was able to demo:

  • SharePoint PnP PowerShell
  • Remote Provisioning
  • Site Designs with Remote Provisioning
  • PnPJS
  • Column Formatter

I even demonstrated how to do the simplest (but still very much appreciated) contribution by live fixing documentation!

Thanks to everyone who attended. I got a lot of great questions and once again people were really impressed with what PnP has to offer! Awesome event, awesome sponsors, awesome speakers, and awesome attendees!

Resources

 

Using SharePoint PnP PowerShell Modules Side-by-Side (2013, 2016, & Online)

Applies to SharePoint 2013, 2016, O365

Are you using SharePoint PnP PowerShell yet? Why not!?! Developers, IT Pros, and Power Users can all benefit from the SharePoint PnP PowerShell modules. The cmdlets wrap up a bunch of complex CSOM and REST calls into 280+ awesome commands. If you’re not using SharePoint PnP PowerShell you’re doing things on hard mode.

Installing SharePoint PnP PowerShell is super easy. You just choose your target version (2013, 2016, or Online) and install. If you’re on Windows 10 you can literally type Install-Module SharePointPnPPowerShellOnline into an administrator shell and you’re done.

But what if you’re like me and have multiple versions you need to target? I find myself needing to switch between SharePoint on premises and online all the time. Unfortunately the modules are often not cross-version compatible due to the different CSOM versions supported between the products. Something as simple as Get-PnPFolder against a 2013 site using the Online module won’t work and the errors aren’t always super obvious:

Error

For a while I’ve just used the Uninstall-Module command and just switched between them that way. This has struck me as dumb for a while now so I finally reached out to The Father himself, Erwin van Hunen, and he responded right away:

Tweet

Awesome! Here’s how to do that (with screenshots!):

Install All the Modules

Although you can install all the modules, you can only have 1 active within any given session. So if you want to switch modules (once you’ve already loaded one) you’ll need to close and reopen PowerShell.

Option 1 – SharePoint On-Premises as Default

If you install the modules using the PowerShell Gallery they will be installed into the default modules path. As a result, when you use a PnP PowerShell Command the first module will be auto loaded (but the other 2 won’t because of conflicts). This appears to be alphabetical. So if you installed all 3 then the default module will be 2013. If you want to use the Online module instead, you would simply run Import-Module SharePointPnPPowerShellOnline before running any PnP PowerShell Commands.

You can’t just run the simple install command for each module. You’ll end up with some version of this error on your second module:

ClobberError

You’ll need to use the -AllowClobber parameter:

Install

You can then check what versions you have installed using this command:

Get-Module SharePointPnPPowerShell* -ListAvailable | Select-Object Name,Version | Sort-Object Version -Descending

Now you can use any of the modules without having to uninstall/install first! By default you’ll be using 2013 (or 2016 if you skipped 2013) which may match your use case perfectly! You can always use the Import-Module command to target one of the other versions.

Option 2 – SharePoint Online as Default

To have the Online module be the one that is auto loaded when you use a PnP PowerShell Command but still have the option to load one of the on premises modules, you should only install the Online module through the PowerShell Gallery:

Install-OnlineOnly

You can then check what versions you have installed using this command to ensure you only have the Online module installed here:

Get-Module SharePointPnPPowerShell* -ListAvailable | Select-Object Name,Version | Sort-Object Version -Descending

To install the other module(s) you’ll use the Releases page to download the corresponding msi installers:

Releases

Just run these as normal to get these installed. Once the module(s) are installed, open System Properties from your control panel. Under the Advanced tab, click the Environment Variables… button. Under User variables, find the PSMODULEPATH variable. If the path(s) to the PnP PowerShell modules are the only values you can just delete it. Otherwise, you can edit it to remove those paths:

EnvironmentVariables

Now when you run a PnP PowerShell Command the Online module will be auto loaded (default). If you want to use one of the on premises modules instead, you have to run Import-Module PATHTOMODULE before running any PnP PowerShell Commands.

Unfortunately, the module path can be pretty long. For instance, here’s mine:

Import-Module C:\Users\ckent\AppData\Local\Apps\SharePointPnPPowerShell2013\Modules\SharePointPnPPowerShell2013

That’s not very convenient! Fortunately, the Windows PowerShell ISE provides snippets that can make it much simpler. You can create snippets using the New-IseSnippet command:

New-IseSnippet -Title " PnP2013" -Description "Imports the SharePointPnPPowerShell2013 Module" -Text "Import-Module $env:LOCALAPPDATA\Apps\SharePointPnPPowerShell2013\Modules\SharePointPnPPowerShell2013"

I put a space before the name so it would be at the top of the snippets. You can then access the snippet from either the script editor or the ISE prompt by pressing Ctrl-J:

Snippets

 

Now you can use the Online module by default but quickly load the on premises module as needed without having to uninstall/install all the time!

Join me at SharePoint Saturday St. Louis on January 20th!

I will be presenting Understanding SharePoint Framework Extensions AND Getting the Most out of SharePoint Patterns and Practices (PnP) on Saturday, January 20th, 2018 in St. Louis as part of SharePoint Saturday St. Louis!

city-of-st-louis-skyline-1.jpg

Mark Rackley and Stephanie Donahue will be presenting the keynote, Transforming Your Organization into a Digital Workspace and there are tons of other really great speakers!

At 9:10 i’ll be talking about SharePoint Patterns and Practices (PnP):

The SharePoint Patterns and Practices (PnP) is an open source initiative coordinated by SharePoint engineering – but what does that mean and why should you care? PnP has tons of tutorials, videos, samples, documentation, and tools (as in amazing, ground-breaking tools). If you haven’t heard of it or if you thought it was just one or two things, you’re doing SharePoint development on hard mode!

In this session we’ll dive into what’s available, how to get started, how to stay up to date, and even how to contribute. You’ll leave this session knowing not only what PnP is, but you’ll be ready to start taking advantage immediately! It doesn’t matter if your using On-Premises or Online, you’re sure to learn something new and likely amazing.

Then at 2:45, we’ll dive into the exciting world of SharePoint Framework Extensions:

SharePoint Framework Extensions are being touted as the replacement for Custom Actions, JS Link, and more – but what are they really? Whether you’ve started experimenting with the SharePoint Framework or not, come find out exactly what the Extensions are, when to use them, limitations, and advantages. SharePoint Framework Extensions are not only powerful and flexible tools to customize SharePoint, when it comes to modern pages, they’re the only way.

SPS St. Louis is sure to be a great event. If you’re even remotely in the area don’t miss out on this opportunity for free training and a chance to meet people who are also passionate about SharePoint and doing awesome stuff.

Join us at SharePoint Saturday New England on October 28th!

Matt Jimison and I will be presenting Getting the Most out of SharePoint Patterns and Practices (PnP) on Saturday, October 28th, 201 in Boston as part of SharePoint Saturday New England!

Our session is right after lunch at 12:45 pm and we’ll be talking about SharePoint Patterns and Practices (PnP):

The SharePoint Patterns and Practices (PnP) is an open source initiative coordinated by SharePoint engineering – but what does that mean and why should you care? PnP has tons of tutorials, videos, samples, documentation, and tools (as in amazing, ground-breaking tools). If you haven’t heard of it or if you thought it was just one or two things, you’re doing SharePoint development on hard mode! In this session we’ll dive into what’s available, how to get started, how to stay up to date, and even how to contribute. You’ll leave this session knowing not only what PnP is, but you’ll be ready to start taking advantage immediately! It doesn’t matter if your using On-Premises or Online, you’re sure to learn something new and likely amazing.

SPSNE_ST_Kids

SPS New England is a collaborative effort from the Boston Area, Connecticut, Granite State, and Rhode Island SharePoint Groups. There are a ton of awesome speakers, Chris McNulty will be doing a Microsoft Q&A, and the whole thing is FREE!

SPFx Extensions List Item Clone Demo

I was fortunate enough to present in the PnP Monthly Community Call yesterday. I demoed a sample I contributed to the SharePoint Framework Extensions sample repository called JS-Command-Clone. The sample is a ListView Command Set SPFx Extension that enables the creation of duplicate list items and utilizes PnP JS Core.

Ryan Schouten has provided a great summary and write-up of the full call. You can also watch the recording directly on YouTube. Of course, you can even watch it here where I’ve directly queued up my demo:

Please feel free to reach out to me with any questions or other feedback. Thanks!

Here are some related links:

SPFx Extension Toastr Notifications Demo

Applies To: SharePoint Framework

I had the honor of taking part in the PnP JS SIG call (Patterns and Practices JavaScript Special Interest Group) earlier today. On the call I was able to demo a sample I contributed for the SharePoint Framework Extensions called jQuery-Application-Toastr.

You can find a great write-up of the call on the Tech Community. You can also just watch the video directly on YouTube. You can even watch it right here, conveniently queued up to my demo, wowee!

Here are some related links:

Creating a PnP TemplateProviderExtension

Applies To: OfficeDev PnP, SharePoint, PowerShell

The SharePoint PnP Remote Provisioning engine is awesome. With just a couple of lines of code or some quick PowerShell you can have a deployable “template” for your SharePoint site (on-premises or O365). OfficeDev PnP offers much more, but it’s the provisioning aspect of things we’re going to talk about today.

Specifically, we’re going to talk about extending the process through the new ITemplateProviderExtension interface. In the August 2016 release the PnP team released the ability to create your own provider extensions and incorporate them directly in the retrieval and application of your PnP templates (Read the announcement here, see an example here).

These new extensions allow you to stick your custom logic directly into the generation of templates and the application of templates. This allows you to apply special tweaks, adjust output, generate additional objects/calls, etc. There are 4 entry points (see the interface below) that give you a lot of flexibility.

The Project

An extension is just a class that implements the ITemplateProviderExtension (more about this in a bit). If you are interfacing with the provisioning engine using .NET directly then you can just add the class to your project. More likely, however, you’ll want to add it as a Class Library (this is true for calling it through PowerShell as well).

In Visual Studio, add a new project of type Class Library (File > New > Project and select Class Library from the list of templates, give it a name, and click OK).

You’ll need to add the SharePoint PnP Core library NuGet package to your project. Right-Click on your project in Solution Explorer and choose Manage NuGet Packages… In the NuGet Package Manager click on Online in the left pane and type PnP into the Search Online box in the upper-right. From the results pick the SharePoint PnP Core library that matches your targeted version and click Install (I’m using SharePoint PnP Core library for SharePoint 2013 since I am targeting On-Premises SharePoint 2013):

PnP Package

This will take just a minute or so to copy everything into your project. You’ll probably be promoted to accept some licenses (just click accept). Once this is done, you can click Close.

The Interface

In your project you have a few files like Class1.cs, SharePointContext.cs and TokenHelper.cs. You can leave all of these (they won’t hurt anything). Right-click on Class1.cs and choose Rename. Enter the name of your extension. Visual Studio will also prompt you to rename the references for Class1 – Click Yes.

To implement the interface, you’ll want to slap a using statement up on top of your extension class for OfficeDevPnP.Core.Framework.Provisioning.Providers then implement the ITemplateProviderExtension like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using OfficeDevPnP.Core.Framework.Provisioning.Providers;

namespace MyExtension
{
    public class CommentIt : ITemplateProviderExtension
    {
    }
}

Right-Click on ITemplateProviderExtension and select Implement Interface > Implement Interface to have the class stubbed out for you:

ImplementInterface

So what the heck is all this? Let’s go through the methods and talk about what you’re going to want to use.

Entry Points

Your template provider extension can intercept the template at 4 different entry points and then do whatever it is you want to do. I find the name of the entry points a little difficult to follow, but here’s where they’re called within the life cycle of the template:

  • From SharePoint to Template (Get-SPOProvisioningTemplate)
    • Template object generated from SharePoint
      • PreProcessSaveTemplate
    • Template serialized into XML
      • PostProcessSaveTemplate
    • Template saved to file system

 

  • From Template to SharePoint (Apply-SPOProvisioningTemplate)
    • Template loaded from file system as XML
      • PreProcessGetTemplate
    • Template deserialized from XML to Template object
      • PostProcessGetTemplate
    • Template object applied to SharePoint

And here’s a reference chart:

Template Is
Action Template Object XML Stream
From SP to Template (Save) PreProcessSaveTemplate PostProcessSaveTemplate
Applying Template (Apply) PostProcessGetTemplate PreProcessGetTemplate

Supports Properties

The Supports properties indicate to the provisioning engine which entry points your extension supports (where you want to inject your logic). You’ll need to edit each of these to remove the NotImplementedException and to return true when you want to inject during that point and false when you don’t.

For my extension, I just want to tweak the XML when someone is saving the template from SharePoint so here’s what mine look like:

public bool SupportsGetTemplatePostProcessing
{
    get { return (false); }
}

public bool SupportsGetTemplatePreProcessing
{
    get { return (false); }
}

public bool SupportsSaveTemplatePostProcessing
{
    get { return (true); }
}

public bool SupportsSaveTemplatePreProcessing
{
    get { return (false); }
}

Initialize

The Initialize method is where you can pass any settings and do any setup. For my extension, I am just passing a string that I will inserting into the template XML:

private string _comment;
public void Initialize(object settings)
{
    _comment = settings as string;
}

Processing Methods

You only need to implement the methods where you indicated you were supporting them in the Supports properties. You can leave the rest with the default NotImplementedException in place.

For this example, I just want to tweak the XML when someone is saving the template from SharePoint so I returned true for the SupportsSaveTemplatePostProcessing property which means I need to implement the PostProcessSaveTemplate method. For what I’m doing, you’ll need a few more using statements:

using System.IO;
using System.Xml;
using OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml;

Here’s are my methods:

public OfficeDevPnP.Core.Framework.Provisioning.Model.ProvisioningTemplate PostProcessGetTemplate(OfficeDevPnP.Core.Framework.Provisioning.Model.ProvisioningTemplate template)
{
    throw new NotImplementedException();
}

public System.IO.Stream PostProcessSaveTemplate(System.IO.Stream stream)
{
    MemoryStream result = new MemoryStream();

    //Load up the Template Stream to an XmlDocument so that we can manipulate it directly
    XmlDocument doc = new XmlDocument();
    doc.Load(stream);
    XmlNamespaceManager nspMgr = new XmlNamespaceManager(doc.NameTable);
    nspMgr.AddNamespace("pnp", XMLConstants.PROVISIONING_SCHEMA_NAMESPACE_2016_05);

    XmlNode root = doc.SelectSingleNode("//pnp:Provisioning", nspMgr);
    XmlNode commentNode = doc.CreateComment(_comment);
    root.PrependChild(commentNode);

    //Put it back into stream form for other provider extensions to have a go and to finish processing
    doc.Save(result);
    result.Position = 0;

    return (result);
}

public System.IO.Stream PreProcessGetTemplate(System.IO.Stream stream)
{
    throw new NotImplementedException();
}

public OfficeDevPnP.Core.Framework.Provisioning.Model.ProvisioningTemplate PreProcessSaveTemplate(OfficeDevPnP.Core.Framework.Provisioning.Model.ProvisioningTemplate template)
{
    throw new NotImplementedException();
}

This is a pretty silly example, but here’s what the code above is doing in the PostProcessSaveTemplate method:

  • Line 28, The method expects us to return the transformed XML steam when we’re done making our tweaks, so just getting it ready
  • Lines 31-34, We can use the native XmlDocument objects to interact with the XML Stream. We just load it into a document and account for the pnp namespace.
  • Line 36, We find the root node of the XML Template using xpath and the namespace
  • Line 37, We generate a new XML Comment using the string passed into our Initialize method
  • Line 38, We jam the comment into the root node so it shows up right at the top
  • Lines 41-44, We save the modified XmlDocument to our result stream, reset it, then pass it along its way

Using Your Extension

Great, so now we’ve got an extension! How do we use this thing? In .NET it’s as simple as initializing our extension class and passing it into the XMLTemplateProvider’s SaveAs method (see the announcement for an example).

In PowerShell, we can write a script to load the extension from our dll and provide it in the TemplateProviderExtensions argument to the Get-SPOProvisioningTemplate or Apply-SPOProvisioningTemplate cmdlets.

Here’s an example of a PowerShell script that uses my custom CommentIt extension (Be sure to heck your dll location):

[CmdletBinding()]
param
(
    [Parameter(Mandatory = $true, HelpMessage="Enter the URL of the target site, e.g. 'https://intranet.mydomain.com/sites/targetSite'")]
    [String]
    $TargetSiteUrl,

    [Parameter(Mandatory = $false, HelpMessage="Enter the filepath for the template, e.q. Folder\File.xml or Folder\File.pnp")]
    [String]
    $FilePath,

    [Parameter(Mandatory = $true, HelpMessage="Enter the comment to add!")]
    [String]
    $TemplateComment,

    [Parameter(Mandatory = $false, HelpMessage="Optional administration credentials")]
    [PSCredential]
    $Credentials
)

if(!$FilePath)
{
    $FilePath = "Extractions\site.xml"
}

if($Credentials -eq $null)
{
	$Credentials = Get-Credential -Message "Enter Admin Credentials"
}

Write-Host -ForegroundColor Yellow "Target Site URL: $targetSiteUrl"

try
{
    Connect-SPOnline $TargetSiteUrl -Credentials $Credentials -ErrorAction Stop

    [System.Reflection.Assembly]::LoadFrom("MyExtension\bin\Debug\MyExtension.dll") | Out-Null
    $commentIt = New-Object MyExtension.CommentIt
    $commentIt.Initialize($TemplateComment)

    Get-SPOProvisioningTemplate -Out $FilePath -Handlers Lists,Fields,ContentTypes,CustomActions -TemplateProviderExtensions $commentIt

    Disconnect-SPOnline

}
catch
{
    Write-Host -ForegroundColor Red "Exception occurred!"
    Write-Host -ForegroundColor Red "Exception Type: $($_.Exception.GetType().FullName)"
    Write-Host -ForegroundColor Red "Exception Message: $($_.Exception.Message)"
}

Please note, that you’ll need the PnP PowerShell Cmdlets installed for this to work. Instructions can be found here. I am using the 2013 On-Premise version but this script will work with whatever version you’re using.

Here’s what’s happening in this script:

  • Lines 1-29, Just setting up the parameters for the script. Nothing too special here
  • Line 31, Always nice to remind the user of important details
  • Line 35, Connect to SharePoint with a single line – wowee!
  • Line 37, Load up your dll from the file system (You can provide a full or relative path here). The pipe to Out-Null just keeps us from printing dll information to the console which would be strange to an end user
  • Line 38, Get your extension class as an object using the namespace from your dll
  • Line 39, Call the Initialize method of the extension. In this case we are passing in the comment received as a parameter to the script
  • Line 41, This is a standard call to Get-SPOProvisioningTemplate with the exception that we are specifying our custom extension in the TemplateProviderExtensions parameter
  • Line 43, Close up that connection

If we take a look at the XML file generated by our template (With a TemplateComment parameter of Look at this sweet comment!), we can see:

Comment.PNG

Aw yeah, boyo!

Debugging Your Extension

Generally, you’re going to be doing something more complicated than that and you’ll probably want to debug the thing. If you are calling your extension in .NET within Visual Studio then things are pretty much as you’d expect – Set your breakpoints and run the thing. PowerShell is a little less obvious.

To debug your extension in the script above, you just need to see your breakpoints within the extension (say on the Initialize method). Then use the Debug > Attach to Process command within Visual Studio. Scroll through the processes until you find where your PowerShell script is running. I generally use the Windows PowerShell ISE to edit my scripts and that shows up as powershell_ise.exe. Choose it then click Attach:

AttachToProcess.PNG

Now when you run your script, your breakpoints should be hit. Fun Note, you’ll need to close and open the powershell window in order to release the dll when you want to make adjustments and build it.

Now you’re ready to take advantage of this incredibly powerful extension point! You can find the full code for this sample extension here. Have fun!