The sources of this project have been moved to the official PnP Samples at the following url : https://github.com/SharePoint/PnP/tree/master/Samples/Provisioning.PnPDeployer.Console

PNP.Deployer

Summary

PNP.Deployer.exe is a console application that makes it easy to deploy artifacts to SharePoint OnPremise/Online. Based on the PnP Provisioning Engine, it wraps the engine's main functionnalities and provides a new layer responsible for handling tokens, authentication, sequences and logging. Provide the PnP templates, define sequences in which you want the templates to be executed, specify whether you want to deploy everything OnPrem or Online, and your good to go.

Applies to

Office 365 Multi Tenant (MT)
Office 365 Dedicated (D)
SharePoint 2013 on-premises

Prerequisites

The projects within the Visual Studio solution have a dependency on the PnP Core library. By default, they are all configured for using the SharePoint PnP Core library for SharePoint 2013 nugget package, but feel free to change the nugget package for the one that suits your needs :

Solution

Solution	Author(s)
PNP.Deployer	Simon-Pierre Plante

Version history

Version	Date	Comments
1.0	September 7th 2016	Initial release

Disclaimer

THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.

How it works

Place the PNP.Deployer package in a location of your choice and configure the PNP.Deployer.exe.config file located in the bin\release folder.

Provide a package with the following elements and call the deployer with the proper parameters:

The artifact(s) that needs to be deployed (page layouts, images, css, js, etc)
The template(s) referencing those previous artifacts (XML templates based on the PnP Schema)
A sequences file that tells the deployer the templates to apply in the desired order
Optionnaly, a tokens file used for "tokenizing" the whole working directory before deploying

# Features

Command line parser for a better user experience

The console application uses the Command Line Parser Library in order to provide named arguments, a custom '--help' interface, and userfriendly command line argument exceptions.

Tokens accross any files

The PnP Provisioning Engine already supports tokens within template files, but what if you need tokens accross static files such as CSS files or a simple Page Layout? The deployer uses a Tokenizer that copies the whole working directory and generates a tokenized version of it (MyDirectory_Tokenized), which becomes the final working directory used by the deployer. The fact that tokens can be used accross the whole working directory makes the Tokenizer really powerfull, allowing the user to use tokens in any static files that aren't necessarily loaded in memory by the deployer.

<tokensConfiguration>
  <tokens>
    <token key="PortalUrl" value="http://company.sharepoint.com" />
    <token key="HubUrl" value="http://company.sharepoint.com/Hub" />
  </tokens>
</tokensConfiguration>

.item {
   background-image: url('{{HubUrl}}/SiteAssets/Images/item-background.png');
}

Authentication made simple

No need to handle the different types of authentication methods for on-premise and online environments, the deployer will automatically use the current user's credentials or prompt for a specific user's credential based on the specified Environment and PromptCredentials parameters.

Sequences for a configurable deployment

Sequences makes it easy to orchestrate the different templates and their firing order. The xml syntax allows the user to easily ignore a specific sequence or a specific template within a sequence.

<sequencesConfiguration>
  <sequences>
    <sequence name="SiteFields" description="..." webUrl="http://yoursite.sharepoint.com" ignore="false">
      <templates>
        <template name="TextFields" path="Templates/TextFields.xml" ignore="false" />
        <template name="ChoiceFields" path="Templates/ChoiceFields.xml" ignore="false" />
      </templates>
    </sequence>
    <sequence name="SiteContentTypes" description="..." webUrl="http://yoursite.sharepoint.com" ignore="false">
      <templates>
        <template name="ContentTypes" path="Templates/ContentTypes.xml" ignore="false" />
      </templates>
    </sequence>
  </sequences>
</sequencesConfiguration>

Easy logging

The deployer uses NLog for logging, which provides an easy way to configure the different output sources and their properties to the user's liking.

Customize the different output sources and the overall behavior of the logging engine simply by altering the provided NLog.config file, following the NLog configuration file documentation.

Supports ".pnp" packages

While supporting regular .xml templates, the deployer also supports the new .pnp open xml format. Specify a .pnp package just like a standard template within the sequences.xml file and everything within the .pnp package will be deployed.

...
<templates>
  <template name="My XML Template" path="Templates/MyXmlTemplate.xml" ignore="false" />
  <template name="My PnP Package" path="Templates/MyPnPPackage.pnp" ignore="false" />
</templates>
...

# Project Structure

# Getting Started

1 - Configuring the deployer

The configuration of the deployer is stored within the PNP.Deployer.exe.config file located in the bin\release folder. The <appSettings> section of the configuration file stores 4 kinds of information :

clientSequencesFile :
- The name of the sequences file that the deployer needs to look for (relative to the WorkingDirectory specified by the caller)
clientTokensFile
- The name of the tokens file that the deployer needs to look for (relative to the WorkingDirectory specified by the caller)
clientIgnoredFolders
- The path of the folders that can be ignored by the deployer in order to speed up the tokenizing process. The different paths must be delimited by a pipe ("|") and must be relative to the WorkingDirectory specified by the caller. This feature can be usefull for instance when deploying a package with large non-production-sub-folders on a development environment, for example a NPM package with a large node_modules sub folder
token-*
- The default tokens will be available for any package deployed by the deployer, and can be added to the <appSettings> section by adding entries with keys that are prefixed with token- followed by the name of the token that will become available within the client packages

<appSettings>
  <!-- =================================================================================== -->
  <!-- The path of the sequences file, relative to the client's working directory          -->
  <!-- =================================================================================== -->
  <add key="clientSequencesFile" value="Sequences.xml" />

  <!-- =================================================================================== -->
  <!-- The path of the tokens file, relative to the client's working directory             -->
  <!-- =================================================================================== -->
  <add key="clientTokensFile" value="Tokens.xml" />

  <!-- =================================================================================== -->
  <!-- Folders ignored by the deployer, relative to the client's working directory (x|y|z) -->
  <!-- =================================================================================== -->
  <add key="clientIgnoredFolders" value="node_modules" />
    
  <!-- =================================================================================== -->
  <!-- Default tokens used by the tokenizer (Must be prefixed by 'token-')                 -->
  <!-- =================================================================================== -->
  <add key="token-Token1" value="Value of 'Token1'" />
  <add key="token-Token2" value="Value of 'Token2'" />
  <add key="token-Token3" value="Value of 'Token3'" />
</appSettings>

### 2 - Configuring the client package

Files

The files can be organized as the user whishes, with as much folders as needed, as long as they are properly referenced by the templates. File references within templates are always relative to the WorkingDirectory specified while calling the deployer.

Templates

The templates can be organized as the user whishes, with as much folders as needed, as long as they are properly referenced by the sequences file. Template references within sequences are always relative to the WorkingDirectory specified while calling the deployer.

Sequences file

The sequences file must reflect the deployer's configuration by having the same name and being at the same location, which is once again relative to the WorkingDirectory specified while calling the deployer.

<sequencesConfiguration>
  <sequences>
    <sequence name="SiteFields" description="Deploys the site fields" webUrl="http://spptechnologies.sharepoint.com" ignore="false">
      <templates>
        <template name="TextFields" path="Templates/TextFields.xml" ignore="false" />
        <template name="ChoiceFields" path="Templates/ChoiceFields.xml" ignore="false" />
      </templates>
    </sequence>
    <sequence name="SiteContentTypes" description="Deploys the site content types" webUrl="http://spptechnologies.sharepoint.com" ignore="false">
      <templates>
        <template name="ContentTypes" path="Templates/ContentTypes.xml" ignore="false" />
      </templates>
    </sequence>
  </sequences>
</sequencesConfiguration>

Tokens file

While being optional, in order for the tokens file to be recognised, it also needs to reflect the deployer's configuration by having the same name and being at the same location, which is once again relative to the WorkingDirectory specified while calling the deployer.

<tokensConfiguration>
  <tokens>
    <token key="MyToken1" value="Value1" />
    <token key="MyToken2" value="Value2" />
    <token key="MyToken3" value="Value3" />
  </tokens>
</tokensConfiguration>

### 3 - Calling the deployer Once the deployer is in place and the client package is ready, simply call the deployer using the following syntax :

.\[...]\bin\release\PNP.Deployer.exe --WorkingDirectory "[...]\MyPackage" --Environment "OnPrem|Online" [--PromptCredentials]

--WorkingDirectory
- (Required) The full path of the package that needs to be deployed
--Environment
- (Required) Whether the deployment occurs on a "OnPrem" or "Online" environment
--PromptCredentials
- (Optionnal) Prompt for credentials to deploy under a specific account (Always prompts when "Online")

Another option is to use the benefits of an environment variable in order to avoid having to specify the absolute path to the deployer's exe, allowing the user to use this shorter alternative :

PNP.Deployer.exe --WorkingDirectory "[...]\MyPackage" --Environment "OnPrem|Online" [--PromptCredentials]

spplante / Provisioning.PnPDeployer.Console