Since every environment is different, all code should not be run in a production environment without your team or organization thoroughly testing first. We recommend the use of a test lab environment often referred to as a development/staging instance of Sitecore.

The disclaimer is provided because someone somewhere will inevitably not follow this recommendation and if they do hose their Sitecore environment, they have no one to blame but themselves.

All data and information provided in this book are for informational purposes only. Adam Najmanowicz, Michael West, and the SPE Team make no representations as to accuracy, completeness, currentness, suitability, or validity of any information in this book and will not be liable for any errors, omissions, or delays in this information or any losses, injuries, or damages arising from its display or use. All information found in this book is provided "as is" with no express or implied warranties.

Prerequisites

• Windows Management Framework 5.1 (PowerShell) is generally available for most Windows environments.

Docker

Working with Docker is going to be the preferred method of installation.

You can find two flavors of the images:

• • Ex: docker pull sitecorepowershell/sitecore-powershell-extensions:6.4-1809

• Sitecore Built

  • Ex: docker pull scr.sitecore.com/sxp/modules/sitecore-spe-assets:6.4-1809

With this approach, you essentially add a new layer during your image build to include the files from the asset image. Here are some samples of what you can add to your existing setup. Check out Sitecore's samples for additional guidance.

docker-compose.yml

services:
  mssql-init:
    image: ${REGISTRY}${COMPOSE_PROJECT_NAME}-xm1-mssql-init:${VERSION:-latest}
    build:
      context: ./docker/build/mssql-init
      args:
        BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xm1-mssql-init:${SITECORE_VERSION}
        SPE_IMAGE: ${SITECORE_MODULE_REGISTRY}sitecore-spe-assets:${SPE_VERSION}
  cm:
    image: ${REGISTRY}${COMPOSE_PROJECT_NAME}-xm1-cm:${VERSION:-latest}
    build:
      context: ./docker/build/cm
      args:
        BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xm1-cm:${SITECORE_VERSION}
        SPE_IMAGE: ${SITECORE_MODULE_REGISTRY}sitecore-spe-assets:${SPE_VERSION}

Dockerfile (mssql-init)

# escape=`

ARG BASE_IMAGE
ARG SPE_IMAGE

FROM ${SPE_IMAGE} as spe
FROM ${BASE_IMAGE}

COPY --from=spe C:\module\db C:\resources\spe

Dockerfile (cm)

# escape=`

ARG BASE_IMAGE
ARG SPE_IMAGE

FROM ${SPE_IMAGE} as spe
FROM ${BASE_IMAGE}

SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

WORKDIR /inetpub/wwwroot

COPY --from=spe \module\cm\content .\

Installation Wizard

The SPE module installs like any other for Sitecore. This approach is appropriate for installations not within a containerized environment.

• For Sitecore 10.1 and newer along with Identity Server you should enable the provided configuration Spe.IdentityServer.config.

• For Sitecore 10.1 and newer you can leverage the IAR packages. There is still the need for dacpac deployments because SPE includes a security user and role.

Upgrade

We've tried to make upgrading SPE as seamless as possible. The following should provide you with some basic information on what to expect when upgrading.

From 6.x

You should be able to install directly over the previous installation of 6.0+.

• For Sitecore 10.1 and newer along with Identity Server you should enable the provided configuration Spe.IdentityServer.config.

• For Sitecore 10.1 and newer you can leverage the IAR packages. There is still the need for dacpac deployments because SPE includes a security user and role.

From 5.x and older

These versions used a different name for the assemblies and configs. You may find it easier to delete all files originally distributed with SPE before installing a newer version. Here are a few steps to consider:

• Delete all files in the bin and App_Config/Include directories prefixed with Cognifide.

• Delete /sitecore modules/Shell/PowerShell

• Delete /sitecore modules/PowerShell

Reference the original SPE package (if available) to identify if any other files were included.

Sitecore items in the content tree will potentially shuffle around into their new location. Be sure to backup your custom scripts first.

Troubleshooting

About the Module

The module provides a command line (CLI) and a scripting environment (ISE) for automating tasks. SPE works with the Sitecore process, capable of making native calls to the Sitecore API and manipulating files. Running commands and writing scripts follow the standard and well-known Windows PowerShell syntax. Windows PowerShell is a common tool used in IT for desktop and server management, so we decided to stick with that as a framework to build upon.

Development Team

Bundled Tools

The following are some helpful modules distributed with SPE.

• Core

  • Platform

    • PowerShell Background Session Manager

    • Recreate site from sitemap
• Extensions
• Maintenance

  • Index On Demand

  • Media Library Maintenance

  • System Maintenance

  • Task Management
• Reporting
• Samples

  • Automatically show quick info section

  • Enforce user password expiration

  • Example Event Handlers

  • Getting Started - includes the Kitchen Sink Demo for Read-Variable.

  • License Expiration

  • Random desktop background

  • Training Modules

  • Unlock user items on logout

• Tools

  • Authoring Instrumentation

  • Copy Renderings

  • Data Management

    • Bulk Data Generator - useful for items and users

    • Bulk Item Restorer - restore items from recycle bin

    • Bulk Template Changer - can't think of a better description than this

    • Data Importer - create or update items from a Csv

    • Find and Replace - use Content Search to change text

  • Elevated Unlock - provides options to unlock items using delegated administration

  • Package Generator - a simple method to package up items

  • Publishing Status Gutter

  • Security Management

    • Logged in Session Manager

    • Transfer item security

• Training

Endorsements

Help and Support

Disclaimer: With great power comes great responsibility – this tool can do a lot of good but also bring harm to a lot of content in a very short time – backup your system before running a script that modifies your content and never run any untested scripts in a production environment! We will not be held responsible for any use of it. Test your scripts on your development server first! Test on an exact copy of production before running scripts on production content.

Colors

The Console, ISE, and Result dialog all provide a way a way to view output data. The $host variable provides access to configuring the colors for this output data.

Example: The following configures colors for the background and forground text in multiple streams.

$Host.UI.RawUI.BackgroundColor = ($bckgrnd = 'DarkRed')
$Host.UI.RawUI.ForegroundColor = 'Cyan'
$Host.PrivateData.WarningForegroundColor = 'Magenta'
$Host.PrivateData.WarningBackgroundColor = "Green"
$Host.PrivateData.VerboseForegroundColor = 'Green'
$Host.PrivateData.VerboseBackgroundColor = "Red"
Write-Host " Write-Host "
Write-Verbose " Write-Verbose " -Verbose
Write-Warning " Write-Warning "
Show-Result -Text -Width 500 -Height 300

The Integrated Scripting Environment (ISE) is a great way to group together commands and save for later use. This tool helps you write scripts in Powerful Ways!

Let's have a quick walk through of each ribbon tab available.

Home Tab

• Write:

  • New - Creates a new script or module.

  • Open - Opens an existing script for the library.

  • Save - Saves the current script to the library.

  • Save As - Saves a copy of the current script to the library.

  • Reload - Opens the original copy of the current script without saving any modifications.

• Script Execution:

  • Execute - Runs the current script as a background job or in the HttpContext.

  • Selection - Runs the selected text of the current script.

  • Debug - Runs the current script with the debugging mode enabled. A temporary file is generated on the file system to support the use of breakpoints.

  • Abort - Stops the execution of an executing script.

• Context:

  • Context - Specifies the current item in the script. Helpful if you write a script dependent on a specific path, or the current directory is denoted as a . (dot) or _$pwd (_present working directory). An MRU and tree view are provided for choosing a path.

  • Session - Specifies the session to use when executing the script. Reused sessions live in the HttpSession. Options include the session created for the ISE instance, One-Time session, or the Persistent Session ID configured on the script.

• UI Context:

  • Language - Specifies the context language to use when executing the script.

  • User - Specifies the context user to impersonate when executing the script. This can be used to emulate UserSwitcher code.

Settings Tab

• Preferences:

  • Settings - This is where you configure the Console and ISE font family, font size, and other useful things.

• Integration:

  • Rebuild All - This is where you rebuild the integration points for Control Panel, Gutters, and Ribbons. Without running this you will not see those integrations appear (or disappear).

Plugins Tab

The plugins feature is a great way to add custom behaviors while in the ISE. Any plugin added can make use of the Enable or Show rules to control how it appears in the ribbon.

• Platform: Custom scripts added to the ISE Plugins integration point script library will appear here.

The Open dialog provides both a search and tree view of the scripts stored in the script libraries.

Shortcuts

Below are the shortcuts available in the ISE.

Here we'll discuss the Console, ISE, and other dialogs made available through SPE.

The world renowned Sitecore PowerShell Extensions module has so much to offer, but sometimes those new to the module may find it difficult to know where to start. The following book should provide you with enough information to use and be productive with SPE.

Don't worry, you will be able to use it without having to write any code.

Videos and Blogs

Language Basics

PowerShell is built on the Microsoft .Net technology; you will find that most APIs in your libraries can be accessed from within the PowerShell runtime. In this section we will see similarities between the C# and PowerShell syntax.

C# to PowerShell

Use the table below to aid in translating from C# to PowerShell. Some of the examples below are not "exact" translations, but should give you a good idea on what it would look like. For example, creating a new dynamic list in C# is often written as a fixed dimensional array recreated with every new addition.

Note: Variables in PowerShell are denoted by the $ character followed by the name. You will see this through the examples below.

// Perform simple math in C#
var total = 1 + 1;
total += 2;

# Perform simple math in PowerShell
$total = 1 + 1
$total += 2

/*
  Create a new dynamic list of strings in C#
*/
var names = new List<string>();
names.Add("Michael");
names.Add("Adam");

<#
  Create a new fixed list of strings in PowerShell
#>
[string[]]$names = @()
$names += "Michael"
$names += "Adam"

// Create a hashtable of data in C#
var table = new Hashtable();
table["Name"] = "Michael";
table["Age"] = 33;

# Create a new hashtable of data in PowerShell
$table = @{}
$table["Name"] = "Michael"
$table["Age"] = 33

// Ordered Dictionary in C#
var od = new OrderedDictionary();
od.Add("z","Last Letter");
od.Add("a","First Letter");

# Ordered Dictionary in PowerShell
$od = [ordered]@{}
$od.Add("z","Last Letter")
$od.Add("a","First Letter")

// Check if the string is null or empty using a static method in C#
if(string.IsNullOrEmpty(name)) { 
  ...
}
else {
  ...
}

# Check if the string is null or empty using a static method in PowerShell
if([string]::IsNullOrEmpty($name)) {
  ...
} else {
  ...
}

// Compare values in C#
name == "Michael"
total <= 3 names.Count() > 2 && name[0] != "Adam"

# Compare values in PowerShell
$name -eq "Michael"

# case-insensitive
$total -le 3 $names.Count -gt 2 –and $name[0] -ne "Adam"

// Negate value in C#
var isTrue = !false;

# Negate value in PowerShell
$isTrue = !$false
$isTrue = -not $false

// String interpolation in C#
var message = $"Hello, {name}";

# String interpolation in PowerShell
$message = "Hello, $($name)"

// Escape characters in C#
string message = "They said to me, \"SPE is the greatest!\".";
message = 'I said, "Thanks!"';
message = "We celebrated together, 'Go SPE!'";

# Escape characters in PowerShell
$message = "They said to me, `"SPE is the greatest!`"."
$message = 'I said, "Thanks!".'
$message = "We celebrated together, 'Go SPE!'."

// Access static property in C#
var today = DateTime.Today;

# Access static property in PowerShell
$today = [datetime]::Today

As you can see in the table above, the language syntax is not all that different between C# and PowerShell. Within a few minutes you might even be able to translate code from your library classes into SPE scripts.

Performance Considerations

You may find yourself trying to optimize your scripts. A few things that might help include the following.

# Use ArrayList to append items rather than creating new fixed dimensional arrays
$names = [System.Collections.ArrayList]@()
$names.Add("Michael") > $null
$names.Add("Adam") > $null

# Optionally create static static typed arrays
$names = [System.Collections.Generic.List[string]]@()
$names.Add("Michael") > $null
$names.Add("Adam") > $null

# HashSet when only values are needed
$nameLookup = New-Object System.Collections.Generic.HashSet[string]
$nameLookup.Add("Michael") > $null

# Case insensitive lookup
$nameLookup = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
$nameLookup.Add("Michael") > $null

if($nameLookup.Contains("michael")) {
  Write-Host "Found it!" -ForegroundColor Green
} else {
  Write-Host "No esta aqui :-(" -ForegroundColor White -BackgroundColor Red
}

# Instead of using Compare-Object to compare two datasets, such as for strings or integeters, consider using HashSet instead.
# Populate collection
$referenceIds = [System.Collections.Generic.List[string]]@()
# Populate collection
$differenceIds = [System.Collections.Generic.List[string]]@()

<#
$leftOnlyObjects = Compare-Object -ReferenceObject $referenceIds -DifferenceObject $differenceIds | 
            Where-Object { $_.SideIndicator -eq "<=" } | Select-Object -ExpandProperty InputObject
#>
$referenceHash = New-Object 'System.Collections.Generic.HashSet[String]'
$referenceHash.UnionWith($referenceIds)
$differenceHash = New-Object 'System.Collections.Generic.HashSet[String]'
$differenceHash.UnionWith($differenceIds)
$leftOnlyHash = New-Object 'System.Collections.Generic.HashSet[String]'($referenceHash)
$leftOnlyHash.ExceptWith($differenceHash)
$leftOnlyObjects = $leftOnlyHash

# Queue when ... a queue is needed
$queue = New-Object System.Collections.Queue
$queue.Enqueue("{GUID}")
$queue.Dequeue()

Measure-Command -Expression {
    Get-Item -Path "master:" > $null
} | Select-Object -ExpandProperty TotalMilliseconds

$watch = [System.Diagnostics.Stopwatch]::StartNew()
Get-Item -Path "master:" > $null
$watch.Stop()
$watch.ElapsedMilliseconds

# Slow but functional
$builder = New-Object System.Text.StringBuilder
$builder.Append("Hello World!") | Out-Null
$builder.ToString()

# Much faster
$builder = New-Object System.Text.StringBuilder
$builder.Append("Hello World!") > $null
$builder.ToString()

Checklist of performance tuning ideas:

• Use dynamic arrays to avoid the use of +=

• Suppress output with > $null instead of Out-Null

• Use hashtables as lookup tables for data

PowerShell Commands

Learning PowerShell begins with running your first command. In this section we learn about the basic command syntax, and some common ones you should learn.

Syntax

Example: The following provides an example syntax for a fake command.

Get-Something [[-SomeParameter] <sometype[]>] [-AnotherParameter <anothertype>] [-SomeSwitch]

PowerShell commands follow a Verb-Noun syntax. Notice that all properly named commands start with a verb such as Get, Set, or Remove and end with a noun such as Item, User, or Role.

The parameters follow the command and usually require arguments. In our example above we have a parameter called SomeParameter followed by an argument of type SomeType. The final parameter SomeSwitch is called a switch. The switch is like a flag that enables or disables behavior for the command.

Example: The following provides possible permutations for the fake command.

<#
    All of the parameters in the command are surrounded by square brackets 
    indicating they are optional.
#>
Get-Something

<# 
    SomeParameter has double brackets around the parameter name and argument 
    indicating the name is optional and when an argument is passed the name 
    can be skipped.
#>
Get-Something "data"

<#
    AnotherParameter has single brackets indicating that the parameter is 
    optional. If the argument is used so must the name. The same reasoning 
    can be applied to the switch.
#>
Get-Something "data","data2" -AnotherParameter 100 –SomeSwitch

# Splat parameters to command
$props = @{
    "SomeParameter" = @("data","data2")
    "AnotherParameter" = 100
    "SomeSwitch" = $true
}
Get-Something @props

Allow scripts to be written with the full command and parameter names

• Avoid relying on positional or optional parameters.

• Avoid abbreviating parameter names.

• Avoid using command aliases (e.g. dir, cd).

Some of the most useful commands to learn can be seen in the table below. These come with vanilla PowerShell.

Pipelines

PowerShell supports chaining of commands through a feature called "Pipelines" using the pipe "|". Similar to Sitecore in that you can short circuit the processing of objects using Where-Object. Let’s have a look at a few examples.

Example: The following queries a Sitecore item and removes it.

# The remove command accepts pipeline input.
Get-Item -Path "master:\content\home\sample item" | Remove-Item

# If multiple items are passed through the pipeline each are removed individually.
$items | Remove-Item

PowerShell also comes with a set of useful commands for filtering and sorting. Let’s see those in action.

Example: The following queries a tree of Sitecore items and returns only those that meet the criteria. The item properties are reduced and then sorted.

# Use variables for parameters such as paths to make scripts easier to read.
$path = "master:\content\home\"

Get-ChildItem -Path $path -Recurse | 
    Where-Object { $_.Name -like "*Sitecore*" } | 
    Select-Object -Property ID,Name,ItemPath
    Sort-Object -Property Name

Example: The following demonstrates how commands can be written clearly with little confusion on the intent, then how aliases and abbreviations can get in the way. Always think about the developer that comes after you to maintain the code.

# Longhand - recommended
Get-Command -Name ForEach-Object –Type cmdlet | Select-Object -ExpandProperty ParameterSets

# Shorthand - not recommend
gcm -na foreach-object -ty cmdlet | select -exp parametersets

Windows PowerShell is bundled with a ton of documentation that could not possibly be included with this book; we can however show you how to access it.

Example: The following examples demonstrate ways to get help…with PowerShell.

# Displays all of the about help documents.
help about_*

# Displays help documentation on the topic of Splatting.
help about_Splatting

# Displays help documentation on the specified command.
help Get-Member

Providers

The provider architecture in PowerShell enables a developer to make a command like Get-Item interact with the filesystem files and folders, and then interact with the Sitecore CMS items.

The SPE module implements a new provider that bridges the Windows PowerShell platform with the Sitecore API. The following table demonstrates the use of Get-Item for a variety of providers.

The default provider used by the PowerShell Console and ISE is the CmsItemProvider with the drive set to the master database.

Example: The following demonstrates switching between providers using the function cd, an alias for Set-Location, while in the Console.

PS master:\> cd c:\
PS C:\> cd hklm:
PS HKLM:\> cd env:
PS Env:\>

The following guide should provide you with enough information to setup a development environment configured to contribute to SPE. We'll begin with a single installation of Sitecore 8+.

The solution requires Visual Studio 2015 or later.

This guide assumes a source root location of "C:\Source" and a site root location of "C:\inetput\wwwroot". These are not prerequisites of the project, and you can use whatever folder locations suit you.

Single Instance for Sitecore 8 & 9

2. Install Sitecore 8+ to a folder of your choice, for example C:\inetpub\wwwroot\SitecoreSPE_8

3. Clone the repo to your local development environment
4. Copy C:\Source\Console\deploy.user.json.sample to C:\Source\Console\deploy.user.json. This will be a file just for your local environment and will be ignored by git.

5. Edit the sites definition in deploy.user.json to target your Sitecore web root folder, making sure you use double-slashes for paths like in the existing file. For this site, make sure the version property is 8. Remove any other sites in the file that do not apply.

   The deploy.user.json file supports deploying SPE to multiple Sitecore installations. For now, we are just deploying to a single instance, but later on in the tutorial we will cover multiple instances.

6. Copy C:\Source\Console\UserConfiguration\App_Config\Include\z.Spe.Development.User.config.sample to a file of the same name, without the .sample suffix. This file can be edited to add any SPE-specific configuration that you want in your sites, but don't wish to commit back into the repo.

   You may notice there is a %%sourceFolder%% value in this configuration file. This is a special string that gets replaced as part of the SPE deployment with your source folder location. You don't need to update this manually.

7. Open the solution in Visual Studio.

8. Compile the solution. Whenever you compile the solution, SPE will be automatically deployed to the site web root paths you have set in deploy.user.json

9. Login to Sitecore

10. Navigate to /Unicorn.aspx. Use Unicorn to sync all projects into Sitecore.

11. SPE is now installed in Sitecore and you're ready for developing!

Any changes you make going foward just require a build of the solution. Remember that when pulling down updates to the source, you should execute a Unicorn sync to ensure your items are up to date.

Multiple Instances

The SPE deployment process supports multiple sites and multiple versions of Sitecore. The following steps carry on from above to add further support for another Sitecore site, such as 8.x or 9.x.

1. Complete the steps for a Single Instance.

2. Install Sitecore 8.x/9.x to a folder of your choice, for example C:\inetpub\wwwroot\SitecoreSPE_91

3. Edit the sites definition in deploy.user.json to add your new Sitecore web root folder. Set the version property to 9.0, 9.1 or 9.2 depending on the major/minor version.

4. Follow steps 7 onward from the Single Instance guide above to deploy to your Sitecore 8.x/9.x installation and sync the SPE items into Sitecore.

SPE can be deployed to as many Sitecore sites as you like. Each time you first deploy to a new installation, make sure you use Unicorn to sync the latest state of items into Sitecore.

Optional: PowerShell Remoting support

To add the SPE PowerShell Remoting Module scripts into your machine's PowerShell Module path, execute the .\Setup_Module.ps1 script from the source folder. This will add the \Modules folder from source into your PSModulePath environment variable. Once this is done, you can use Import-Module SPE on your development machine to run the remoting scripts.

Optional: Junction Support

As part of the SPE deployment process, all of the relevant binary, configuration and sitecore module files are copied over from the projects within the solution. This means that any changes to static files such as JS / CSS files require a full build for these to be deployed to the site. As the build triggers an application pool recycle of your site, this can be a little slow for quick changes.

To enable a junction deployment for a site, add junction property to the site definition and set it to true:

Note that with junction deployments, a solution build is still required if you want to deploy any code or .config changes.

It is not currently supported for a junction deployment site to be changed back into a non-junction deployment site. If you wish to do this, you should manually delete the following folders from your Sitecore installation before updating the junction property back to false: sitecore modules\PowerShell and sitecore modules\Shell\PowerShell

Add Language Version

Example: The following example queries all of the content items and adds a new language version of "en-ca", while overwriting any that exist.

Example: The following example adds a language version from English to US and Polish while leaving the Title field blank. If a version already exists nothing happens.

Example: The following example adds a language version from English to Polish of Template Name Sample Item. If the version exists a new version is created for that language. Finally the results are displayed as a table showing only the Name, Language, and Version.

Example: The following example adds a language version in Polish to the Home item and all its children. If the version exists nothing happens. No fields were harmed in the making of this version.

Remove Language Version

Example: The following example queries all of the content items and removes the language version of "fr-CA".

New Item with Forced Language Version

Example: The following example creates a new item with language versions only matching the specified languages; all other language version are removed.

Parameters and Configuration

Supported parameters:

• -Recurse Translates item and its children

• -IfExist Accepts one of 3 pretty self explanatory actions: Skip, Append or OverwriteLatest

• -TargetLanguage accepts a list of languages that should be created

• -DoNotCopyFields creates a new version but does not copy field values from original language

• -IgnoredFields list of fields that should not be copied over from original item this can contain e.g. __Security if you don't want the new version to have the same restrictions as the original version.

On top of the ignored fields in the -IgnoredFields the following fields are ignored as configured within the Spe.config file:

References

The Console is a command line interface (CLI) designed for efficiency, providing a streamlined tool for working with Windows PowerShell and Sitecore.

Shortcuts

Below are the shortcuts available in the console.

Note: The font family, font size, and other settings can be configured through the ISE.

In this section we'll show how to manage item renderings.

List renderings

Example: The following demonstrates the use of Get-LayoutDevice and Get-Rendering to find all renderings on a page associated with the FinalLayout.

Update rendering parameters

Example: The following demonstrates the use of Get-Rendering and Set-Rendering for updating values on templates.

Find pages using rendering

Example: The following demonstrates how to report on pages referencing the specified rendering.

Find renderings marked cacheable

Example: The following demonstrates how to report on which renderings are globally set to "Cacheable".

Find renderings with personalization

Example: The following demonstrates how to find renderings with a conditions node set on the item.

Disable cacheable setting on renderings

Example: The following demonstrates how to disable global caching on all renderings.

Move renderings between placeholders

Remove datasource from rendering

Example: The following removes a datasource from a rendering on the FinalLayout.

Replace compatible rendering

Further Reading

There are multiple methods of accessing help documentation in SPE to provide you with information on the commands available to you.

Viewing all available commands

A report is available which will show you all available SPE commands:

When executed, this report provides a paged view of the SPE commands.

Viewing command help

Console

To display the available help for a command in the Console, simply use the Get-Help command:

For full documentation, including examples, use the -Full parameter:

ISE

Through the Integrated Scripting Environment (ISE), SPE provides a method of acccessing help for available commands. To view the help for a command, simply highlight the command and press Ctrl + Enter.

After doing this, a dialog will appear with the relevant help information:

Documenting functions

When writing scripts, you are able to include formatted comments that will be used to provide help text for functions. If formatted correctly, this help text will be available through the methods described above.

Example: A simple function with documentation:

Once the script containing this function has been invoked, the help text will be available:

Online appendix

Administration

Note: Examples included in the following modules

• System Maintenance

Analytics

Database

Globalization

Preferences

Reports

Note: Examples included in the following modules

• System Maintenance

Security

Modules may contain PowerShell Script Library items and PowerShell Script items. The following section outlines some of the basic concepts you need to know for the following chapters.

PowerShell Script Library

The library items represent a collection of scripts, and may be structured with one or more levels of libraries.

Naming Convention

You'll find that with the Integration Points some libraries should be created with specific names (i.e. Content Editor, Control Panel).

As a best practice we recommend that the Functions library consist of reusable scripts containing PowerShell functions (i.e. Do-Something) while other libraries contain the solution specific scripts (i.e. MakeScriptingGreatAgain).

Example: The following demonstrates the use of the Functions script library containing Get-DateMessage.

# /sitecore/system/modules/powershell/script library/spe rocks/functions/get-datemessage
function Get-DateMessage {
  "The current date and time is: $(Get-Date)"
}

# /sitecore/system/modules/powershell/script library/spe rocks/alerts/show-datemessage
Import-Function -Name Get-DateMessage

Show-Alert (Get-DateMessage)

Some names we've used included:

• Beginner Tutorials

• Content Editor

• Content Maintenance

• Content Interrogation

• Development

• Event Handlers

• Functions

• Internal

• Page Editor

• Pipelines

• Profile and Security

• Reports

• Script Testing

• Tasks

• Toolbox

• User Interaction

• Web API

Fields

Interactive : The following fields support the two custom rules as well as a variety of out-of-the-box rules.

• ShowRule (Show if rules are met or not defined) - typically controls visibility of integration points.

  • PowerShell

    • where specific persistent PowerShell session was already initiated

    • where specific persistent PowerShell session was already initiated and has the specific variable defined and not null

    • where exposed in a specific view

  • PowerShell ISE

    • when length script length is compares to number characters long

    • when the edited script is in a state

• EnableRule (Enable if rules are met or not defined) - typically controls enabled state of integration points.

  • Same as above

Rules Usage

There are a number of use cases for the EnableRule and ShowRule.

• If there is a UI component the ShowRule can be used to ensure it appears while the EnableRule can toggle when it can be clicked.

• If there is no UI component, the EnableRule is used to determine when the script should be executed; useful to limit creation of PowerShell runspaces.

PowerShell Script

The script items represent the code that will be executed.

Naming Convention

There are three conventions that we recommend you follow which are shown with an example below.

• Title Casing - This should be used when the name will be exposed in places such as the Content Editor, script library names, and Reports root directory.

• Sentence casing - This should be used when the name is long and will not be visible to the user or is a report with a very long name.

• Noun-Verb - This should be used when the script is stored within the Functions script library and will be imported using the command Import-Function.

Fields

Scripting

• Script (Script body) : This is a multi-line text than should be edited using the PowerShell ISE application.

Session Persistency

• PersistentSessionId (Persistent Session ID) : Context scripts using this ID will execute in a single session and be reused; leaving empty will cause the session to be discarded after execution. This value should be used for rules requesting the session ID.

You can interact with the providers typically available in the standard Windows PowerShell Console. Below are some of the important providers. Run the command Get-PSProvider to see the complete list.

• FileSystem - Supports interacting with files and folders.

• CmsItemProvider - Supports interacting with the Sitecore content items.

The console prompt typically begins with PS master:\>. The present working directory is using the CmsItemProvider and set to the master database.

Example: Change directories between providers.

 PS master:\> cd core:
 PS core:\> cd C:
 PS C:\windows\system32\inetsrv> Set-Location -Path master:
 PS master:\>

The SPE Modules support a wide variety of predefined script libraries to help with exposing scripts to the Sitecore interface.

The following list outlines the available libraries for Integration Points that may be added to modules. These may also be generated automatically when creating or updating modules.

• • Context Menu - Visibility can be control using rules made available from within the Interactive field section.

  • Insert Item - Visibility can be control using rules made available from within the Interactive field section.

  • Warning - Appears as a warning message beneath the ribbon in the Content Editor.

• Internal

  • List View - Represents the ribbon buttons such as for Actions and Exports.

• • Notification - Appears as a notification message beneath the ribbon in the Experience Editor.

• • LoggedIn

  • LoggingIn

  • Logout

Other Integrations

Syncing Integrations

Command Introduction

The majority of scripts written with SPE contain one or more of the following commands:

Get-Item -Path "master:\content\home"

Get-ChildItem -Path "master:\content\home" -Recurse

New-Item -Path "master:\content\home" -Name "Demo" -ItemType "Sample/Sample Item"
# or
New-Item -Path "master:\content\home" -Name "Demo" -ItemType "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"

Get-Item -Path "master:\content\home\delete-me" | Remove-Item

Move-Item -Path "master:\content\home\Demo" -Destination "master:\content\home\Demo1"

# Add -PassThru to output the new item
Copy-Item -Path "master:\content\home\Demo1" -Destination "master:\content\home\Demo2"

Command Parameters

Legend: "–" - not applicable; "✓" - available.

Below we will show how to use each command with the Windows PowerShell syntax followed by some examples of the common C# equivalent.

Finding Items

Get-Item : by Path

Example: The following will retrieve the item based on the Sitecore path.

PS master:\> Get-Item -Path master:\content\home

Name Children Languages                Id                                     TemplateName
---- -------- ---------                --                                     ------------
Home True     {en, de-DE, es-ES, pt... {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} Sample Item

As you may have noticed, the /sitecore portion of the path is unnecessary. This is because the Sitecore item is represented by the root item of the drive master: and is therefore optional.

Let's have a look at the equivalent code in C#.

Sitecore.Data.Database master = Sitecore.Configuration.Factory.GetDatabase("master");
Sitecore.Data.Items.Item item = master.GetItem("/sitecore/content/home");

The above will return the latest version of the item in your current language. But what if you want the item in another language? No problem!

Example: The following will retrieve the Danish version of the Home item.

PS master:\> Get-Item -Path master:/content/home -Language da | Format-Table -Property DisplayName, Language, Id, Version, TemplateName

DisplayName Language ID                                     Version TemplateName
----------- -------- --                                     ------- ------------
Hjem        da       {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item

I've formatted the output above to show you that indeed the right language was returned. The command supports wildcards for both -Language and -Version parameters. You may have also noticed that the forward and backward slashes can be used interchangeably.

Example: The following retrieves the latest version for all languages of an item.

PS master:\> Get-Item -Path master:/content/home -Language * | Format-Table -Property DisplayName, Language, Id, Version, TemplateName

DisplayName Language ID                                     Version TemplateName
----------- -------- --                                     ------- ------------
Home        en       {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home        de-DE    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home        pl-PL    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home        en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 3       Sample Item
Home        en-GB    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Hjem        da       {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item

Notice that the item with language en-US at its third version.

Example: The following retrieves the item in all languages and versions.

PS master:\> Get-Item -Path master:/content/home -Language * -Version *| Format-Table -Property DisplayName, Language, Id, Version, TemplateName

DisplayName Language ID                                     Version TemplateName
----------- -------- --                                     ------- ------------
Home        en       {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home        de-DE    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home        pl-PL    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home        en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home        en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 2       Sample Item
Home        en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 3       Sample Item
Home        en-GB    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Hjem        da       {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item

You can see that specifying the language and version using the wildcard will retrieve all possible variants of an item. The wildcard can also include a partial match like en-*. The use of that filter would return all items in the English language, ignoring the region.

Get-ChildItem : by Path

Example: The following retrieves the child items in all languages and versions.

PS master:\> Get-ChildItem -Path master:/content -Language * -Version * | Format-Table -Property DisplayName, Language, Id, Version, TemplateName

DisplayName         Language ID                                     Version TemplateName
-----------         -------- --                                     ------- ------------
Home                en       {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home                de-DE    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home                pl-PL    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home                en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home                en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 2       Sample Item
Home                en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 3       Sample Item
Home                en-GB    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Hjem                da       {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item

Get-Item : Sitecore query

It's not always most efficient to operate on items by traversing the tree using Get-ChildItem. This is especially true if you need to work on large trees but need to select only a few items (e.g. a specific template). For this we’ve introduced support for the Sitecore query within our provider.

Important to note that the query format sometimes requires the use of a # before and after paths when they contain reserved keywords or spaces.

Example: The following retrieves all items beneath the path /sitecore/content/ with the template of Sample Item.

PS master:\> Get-Item -Path master: -Query "/sitecore/content//*[@@templatename='Sample Item']"

Name                             Children Languages                Id                                     TemplateName
----                             -------- ---------                --                                     ------------
Copy of Home                     True     {en, de-DE, es-ES, pt... {503713E5-F9EE-4847-AEAF-DD13FD853004} Sample Item
Home                             True     {en, de-DE, es-ES, pt... {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} Sample Item

Example: The following retrieves all items beneath the path /sitecore/content/ with the template of Sample Item in all versions and languages.

PS master:\> Get-Item -Path master: -Query "/sitecore/content//*[@@templatename='Sample Item']" -Language * -Version * | Format-Table -Property DisplayName, Language, Id, Version, TemplateName -AutoSize

DisplayName  Language ID                                     Version TemplateName
-----------  -------- --                                     ------- ------------
Home         de-DE    {503713E5-F9EE-4847-AEAF-DD13FD853004} 1       Sample Item
Hjem         da       {503713E5-F9EE-4847-AEAF-DD13FD853004} 1       Sample Item
Home         en       {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home         de-DE    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home         pl-PL    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home         en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Home         en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 2       Sample Item
Home         en-US    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 3       Sample Item
Home         en-GB    {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item
Hjem         da       {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} 1       Sample Item

Example: The following retrieves items matching the query with a specified ISO date and present in a report dialog.

$isoDate = [Sitecore.DateUtil]::ToIsoDate([datetime]::Today)
Get-Item -Path master: -Query "/sitecore/content/home//*[@__Publish > '$($isoDate)']" | 
    Show-ListView -Property ID,Name,ItemPath

Get-Item : Sitecore Fast query

Example: The following returns items with a specific template under a given root using Fast query.

$rootItemId = "{839085D0-C279-47C6-83C9-9CC28E7C111E}"
$rootItem = Get-Item -Path "master:" -ID $rootItemId
$templateId = "{759BA7B1-A216-467E-A37C-2B8D7F1A713C}"

$query = "fast:$($rootItem.ItemPath)//*[@@templateid='$($templateId)']"
Get-Item -Path "master:" -Query $query

Get-Item : by XPath

Example: The following retrieves items matching an XPath query.

$query = "ancestor-or-self::*[@@templatename='Sample Item']"

# Retrieve the items with Axes and a given context item.
$SitecoreContextItem.Axes.SelectItems($query)

# Retrieve the items using the Query class and context item.
# Retrieve the items by prepending the context path to the query.
Get-Item -Path "master:" -Query ("$($SitecoreContextItem.Paths.Path)/$query")

Get-Item : by Id

Example: The following retrieves an item by id.

PS master:\> Get-Item -Path master: -ID "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"

Name  Children Languages                Id                                     TemplateName
----  -------- ---------                --                                     ------------
Home  True     {en, de-DE, es-ES, pt... {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} Sample Item

Get-Item : by Uri

The Uri encodes the language and version within the path.

Example: The following retrieves an item by uri.

PS master:\> Get-Item -Path master: -Uri "sitecore://master/{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}?lang=en&ver=1"

Name Children Languages                Id                                     TemplateName
---- -------- ---------                --                                     ------------
Home True     {en, de-DE, es-ES, pt... {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} Sample Item

In all the examples you'll notice we specified the database. Windows PowerShell needs to know which provider to execute within. This also signals to SPE to show the dynamic parameters. Other examples of providers include the following:

• HKLM: - The registry provider for HKEY_LOCAL_MACHINE.

• C: - The filesystem provider for the C drive.

Get-Item : select properties

The following examples make use of custom PropertySet for the command Select-Object.

Example: The following uses the PSSecurity PropertySet.

PS master:\ >Get-Item -Path "master:\content\home" | Select-Object -Property PSSecurity

Name ID                                     __Owner        __Security
---- --                                     -------        ----------
Home {110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9} sitecore\admin au|sitecore\michael|pe|+item:read|

Example: The following uses the PSTemplate PropertySet.

PS master:\> Get-Item -Path "/sitecore/media library/Images/SPE/kitten1" | Select-Object -Property PSTemplate

Name    ID                                     BaseTemplate
----    --                                     ------------
kitten1 {E58FA823-3CAF-43A1-A5ED-FBE24D3C21B4} {Image, File, Standard template, Media classification...}

Example: The following uses the PSImage PropertySet.

PS master:\> Get-Item -Path "/sitecore/media library/Images/SPE/kitten1" | Select-Object -Property PSImage

Name      : kitten1
ID        : {E58FA823-3CAF-43A1-A5ED-FBE24D3C21B4}
Alt       : Yay
Width     : 225
Height    : 225
Extension : jpg
Size      : 6593

Example: The following uses the PSSchedule PropertySet.

PS master:\> Get-Item -Path "/sitecore/system/Tasks/Schedules/Content Testing/Calculate Statistical Relevancy" | Select-Object -Property PSSchedule 

Name     : Calculate Statistical Relevancy
ID       : {C7533E65-A1D6-4F99-9F12-0AB157299D80}
Schedule : 1900101|19000101|127|1.00:00
Last run : 1/1/0001 12:00:00 AM
Command  : {6A79C206-0CD2-4DDD-9DFF-5BF21E002931}
Items    :

Get-Item : properties with field type

Example: The following accesses the Image field casted to the type Sitecore.Data.Fields.ImageField.

$item = Get-Item -Path "master:\content\home"
$item._.Image.Alt

Note: You can use ._ and .PSFields to gain access to the typed field.

Example: The following accesses the Link field casted to the type Sitecore.Data.Fields.LinkField. From there you can see all of the available properties.

PS master:\> $currentItem = Get-Item -Path 'master:\content\home\sample-item'
PS master:\> $currentItem.PSFields."LinkFieldName"

Anchor       :
Class        :
InternalPath : /sitecore/content/home/sample-item/
IsInternal   : True
IsMediaLink  : False
LinkType     : internal
MediaPath    :
QueryString  :
Target       :
TargetID     : {263293D3-B1B3-4C2C-9A75-6BD418F376BC}
TargetItem   : Sitecore.Data.Items.Item
Text         : CLICK HERE
Title        :
Url          :
Root         : link
Xml          : #document
InnerField   : <link linktype="internal" text="CLICK HERE" querystring="" target="" id="{263293D3-B1B3-4C2C-9A75-6BD418F376BC}" />
Value        : <link linktype="internal" text="CLICK HERE" querystring="" target="" id="{263293D3-B1B3-4C2C-9A75-6BD418F376BC}" />

Example: The following finds all of the TextFields and outputs to the console.

$item = Get-Item -Path "master:\content\home"
foreach($field in $item.Fields) {
    $item.PSFields."$($field.Name)" | 
        Where-Object { $_ -is [Sitecore.Data.Fields.TextField] }
}

Editing Items

Get-Item : then change item properties

We often see the following two ways of accessing and changing fields used in scripts. One uses Set-ItemProperty and the other is more natural to a Sitecore developer.

Example: The following sets the title property using Set-ItemProperty.

PS master:\> Set-ItemProperty -Path master:/content/home -Name "Title" -Value "New Title"

Example: The following sets the title and clears the branch id using .Editing.BeginEdit and .Editing.EndEdit methods.

$item = Get-Item master:/content/home
$item.Editing.BeginEdit()
$item["Title"] = "New Title"
$item.BranchId = [Guid]::Empty # or a new value if changing it
$item.Editing.EndEdit()

Note: The above example may also be written in the ISE where no console prompt is visible.

The previous examples work but are not the most efficient ways to change item content. The items returned by the provider expose the Sitecore item fields as automatic PowerShell properties.

Example: The following sets the title property using the automated PowerShell property.

$item = Get-Item -Path master:/content/home
$item.Title = "New Title"
$item."Closing Date" = [datetime]::Today

Example: The following changes the display name of the item.

$item = Get-Item -Path "master:" -ID "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
$item."__Display name" = "I Like Turtles"

This technique may be used for a wide variety of property types.

Example:

$item = Get-Item -Path "master:" -ID "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
$fieldName = "__Display name"

# All variations will work
Write-Host ($item.$fieldName)
Write-Host ($item."$fieldName")
Write-Host ($item."$($fieldName)")

There are a other hidden gems in automated PowerShell properties. For example, if we detect that the field is a Date or Datetime field, we will return System.DateTime typed value from a field rather than the System.String Sitecore stores internally.

Example: The following gets the created date.

$item = Get-Item -Path "master:" -ID "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
$item.__Created 

# Monday, April 07, 2008 1:59:00 PM

Example: The following assigns a System.DateTime value to the PowerShell automated property.

$item = Get-Item -Path "master:" -ID "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
$item.__Created = [DateTime]::Now
$item.__Created

# Tuesday, March 17, 2020 12:00:00 PM

Great we've just changed it! Our property handlers take care of all the necessary usages of .Editing.BeginEdit and .Editing.EndEdit. This method can be applied for a variety of field types such as GeneralLink and Image.

To provide an example – I’ve extended my home with additional fields as follows:

Example: The following assigns an image to the Image field.

$homeItem = Get-Item -Path "master:/content/home"
$homeItem.Image = Get-Item -Path "master:\media library\logo"

Easy enough, isn't it? Let SPE detect the field type for you and worry about what to call! Now let's assign a content item to GeneralLink.

Example: The following assigns a content item to a GeneralLink field.

$homeItem = Get-Item -Path "master:/content/home"
$homeItem.GeneralLink = Get-Item -Path "master:\content\home-away-from-home"

What about fields that accept lists of items? We've got your back here as well.

Example: The following assigns all children of /sitecore/content/ item to the ItemList field.

$homeItem = Get-Item -Path "master:/content/home"
$homeItem.ItemList = Get-ChildItem -Path 'master:\content\'

Let's see how our item looks in the Content editor after all the assignments that we've just performed:

Great! Looks like it worked.

Those little improvements make your scripts much more succinct and understandable. Try it for yourself!

When not to use the automated properties?

As with every rule there is an exception to this one. Those automated properties perform the $item.Editing.BeginEdit() and $item.Editing.EndEdit() every time which results in saving the item after every assignment. Assigning multiple properties on an item this way might be detrimental to the performance of your script. In such cases you might want to call $item.Editing.BeginEdit() yourself before modifying the item. Subsequently call the $item["field name"] = "new value" for each property modify. Finally end with the $item.Editing.EndEdit().

Choosing this way is situational and will usually only be required if you're working with a large volume of data. In those cases you might also want to introduce the Sitecore.Data.BulkUpdateContext technique.

Example: The following sets multiple properties while using the Sitecore.Data.BulkUpdateContext.

New-UsingBlock (New-Object Sitecore.Data.BulkUpdateContext) {
    foreach($item in Get-ChildItem -Path "master:\content\home") {
        $item.Editing.BeginEdit()
        $item["Title"] = "Sample Item"
        $item["Text"] = "Sample Item"
        $item.Editing.EndEdit() > $null
    }
}

Example: The following generates a relative url to the specified site and assigns to a variable. Because the New-UsingBlock command creates a new closure, you need to return the data to use in a different scope.

$site = [Sitecore.Sites.SiteContextFactory]::GetSiteContext("usa")
$relativeUrl = New-UsingBlock (New-Object Sitecore.Sites.SiteContextSwitcher $site) {
    $pageItem = Get-Item -Path "master:" -Id "{50BE527C-7241-4613-A7A9-20D0217B264B}"
    [Sitecore.Links.LinkManager]::GetItemUrl($pageItem)
}

Some other classes you may want to use with the New-UsingBlock function:

• Sitecore.SecurityModel.SecurityDisabler

• Sitecore.Data.BulkUpdateContext

• Sitecore.Globalization.LanguageSwitcher

• Sitecore.Sites.SiteContextSwitcher

• Sitecore.Data.DatabaseSwitcher

• Sitecore.Security.Accounts.UserSwitcher

• Sitecore.Data.Items.EditContext

• Sitecore.Data.Proxies.ProxyDisabler

• Sitecore.Data.DatabaseCacheDisabler

• Sitecore.Data.Events.EventDisabler

Sitecore API

If you have reached this point, then you are clearly a nerd and want to access using the raw Sitecore API.

Example: The following queries all descendants of the media library, filters by size, and wraps with automatic properties.

# Get the root node using Get-Item, then a call to Axes.
$mediaItemContainer = Get-Item -Path "master:/media library"
$items = $mediaItemContainer.Axes.GetDescendants() | 
    Where-Object { [int]$_.Fields["Size"].Value -gt 100000 } | Initialize-Item

Copying Items

Copy-Item : to a new destination

You will find yourself one day in need of copying items on a small to large scale. The Copy-Item command will likely meet the need.

Example: The following copies the item to the specified path with a new ID.

Copy-Item -Path "master:\content\home\Sample Item\Sample Item 1" -Destination "master:\content\home\Sample Item\Sample Item 2"

Note: The item name will match just as you type it in the command. Lowercase name in the destination will result in an item with a lowercase name.

Example: The following transfers the item to the specified path with the same ID.

Copy-Item -Path master:\content\Home -Destination web:\content\home -TransferOptions 0

Example: The following copies an entire tree of items and maintains the tree structure.

$sourceId = "{AF27FAD3-2AF0-4682-9BF7-375197587579}"
$destinationId = "{53F94442-555B-4622-B813-A16ED2CAB01B}"
$children = Get-ChildItem -Path "master:" -ID $sourceId
foreach($child in $children) {
    $child | Copy-Item -Destination $destinationId -Recurse
}

Moving Items

Move-Item : to a new destination

There is a always a better way to do something. Moving items en masse is certainly one that you don't want to do by hand. If the destination item exists the moved item will be added as a child. If the destination item does not exist the source item will be renamed when moved.

Example: The following moves the item from one parent to another.

Move-Item -Path "master:\content\home\sample item\Sample Item 1" -Destination "master:\content\home\sample item 2\"

Example: The following gets an item and moves to a new parent node, along with all the children.

Get-Item -Path "master:" -ID "{65736CA0-7D69-452A-A16F-2F42264D21C5}" | 
    Move-Item -Destination "master:{DFDDF372-3AB7-45B1-9E7C-0D0B27350439}"

Creating Items

New-Item

Example: The following creates a new item with the specified template.

$itemPath = "master:\content\home\sample item\Sample Item 3"
New-Item -Path $itemPath -ItemType "Sample/Sample Item"

Name                             Children Languages                Id                                     TemplateName
----                             -------- ---------                --                                     ------------
Sample Item 3                    False    {en}                     {F6F4F7B7-5E72-4C16-9294-218D80ED89E8} Sample Item

Example: The following creates a new item with the specified template id and id.

$itemPath = "master:\content\home\sample item\Sample Item 4"
$templateId = "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"
$itemId = "{9459ADDD-4471-4ED3-A041-D33E559BD321}"
New-Item -Path $itemPath -ItemType $templateId  -ForceId $itemId

Name                             Children Languages                Id                                     TemplateName
----                             -------- ---------                --                                     ------------
Sample Item 4                    False    {en}                     {9459ADDD-4471-4ED3-A041-D33E559BD321} Sample Item

Example: The following creates a new item as a child of the specified item.

$templateId = "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"
$parentItem = Get-Item -Path "master:\" -ID "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
New-Item -Parent $parentItem -Name "Sample Item 3" -ItemType $templateId


Name          Children Language Version Id                                     TemplateName
----          -------- -------- ------- --                                     ------------
Sample Item 3 False    en       1       {2F71043A-C731-4EC2-BFE4-0604D4D71652} Sample Item

Note: The New-Item command was passed to Format-Table -Autosize to improve the formatting.

Removing Items

Remove-Item : permanently

Example: The following removes the item permanently. Proceed with caution.

Remove-Item -Path "master:\content\home\sample item\Sample Item 3" -Permanently

References

Sitecore PowerShell Extensions provides an organization structure composed of modules, libraries, and scripts. Modules make up the highest level and can be grouped together by module folders.

Some benefits to using modules:

• Organization of custom scripts is a cinch.

Create a custom module

Getting started with your own module is a short process and something you should do for all of your custom scripts.

1. Navigate to the Script Library item and Insert -> PowerShell Script Module.
2. Enter the name for the new module and click OK.

3. Right click the new module and Scripts -> Create libraries for integration points.
4. Select the appropriate integration points for your module.
5. Select the module and enable for use.
6. Open the ISE, switch to the Settings tab, and rebuild integrations.

The Functions integration allows for scripts to be discoverable through autocomplete while authoring scripts. Functions can be "disabled" by disabling the containing module.

1. Begin by adding a script library called "Functions" to a module. This can be created by the new module wizard.

2. Add a script to the "Functions" script library with a name that represents the purpose.

3. Use the command Import-Function to discover the available functions.

Note: It's best practice to create function scripts that follow the Verb-Noun pattern as outlined by Microsoft.

Here's a short video on authoring custom functions.

Notification

The Notification integration reveals to the user a notification above the content. The Sitecore rules engine may be used to control the enabled state; simply configure the Enable rule on the script. The script is executed every time the page loads.

Example: The following adds an information notification to the page for Sitecore 8 and a warning for Sitecore 7.

Note: Examples included in the following modules

• License Expiration

Experience Button

The Experience Button integration adds a button to the Page Editor. Rules can be used to control visiblity and enablement. The script is only executed when the button is clicked.

1. Begin by adding a new script to the Experience Button library. The name of the script will appear in the tooltip.

2. Edit the script to perform the appropriate actions. The script can run in the background and show dialogs.

3. Change the icon of the item to match the script purpose.

4. Configure any Enable or Show rules as needed.

Example: The following adds a command which will display a dialog asking a question, then send an email with the response.

The Event Handler integration provides a way to execute scripts when defined events are fired.

Steps required to activate this integration include the following:

1. Enable the Spe.Events.config or apply your own patch with the required events enabled.

2. Add a new integration point library to your new or existing module.

3. Add a new script to the appropriate event library.

4. Configure an Enable Rule if needed.

5. Profit!

Enable Configuration

While SPE comes with an example configuration, which is disabled by default, it contains several events that may not meet your requirements.

An event configuration patch may look like the following:

Add Event Script

To mimic the event item:added you should create nested script libraries such as Event Handlers -> Item -> Added followed by a script.

You can include custom ribbon commands in the ISE to aid in improving the script authoring experience.

Add a custom plugin

For this example, we wish to have a plugin that analyzes the script and reports on any errors.

Create a new script stored under the following structure:

Use the following sample to fill in the script body.

Now you can run the command from the ribbon and see the results in the ISE.

Scripted Data Sources provide a way to use a PowerShell script to perform complex queries.

Here are some good reasons to use this feature:

• Delivering complex functionality based on multiple criteria.

• Your field may need to provide different set of items to choose from based on:

  • user name or role (in simplest case this can be done using right management, but maybe not always possible in a more elaborate scenario)

  • current day or month?

  • In a multisite/multimarket scenario you may want to show different items for each site

    based on engagement analytics parameters of the page

    based on where in the tree an item exist (some of it can be done with use of a “query:”)

  • anything you might want to build the code data source for…

Something that would be beyond the reach of a regular Sitecore query and potentially something that you would really need to deliver code source for. But maybe you’re not in a position to deploy that on your environment?

Field Data Source

Field Data Source provides a great opportunity for a script.

Below are field types you may wish to use a script:

• Checklist

• Droplist

• Grouped Droplink

• Grouped Droplist

• Multilist

• Name Lookup Value List

• Droplink

• Begin by adding a new script library called Data Sources followed by adding a script. You can call it something like Get-GlobalOption.
• Add the path to your script in the Source field on the data template. The source should be prefixed with script: followed by the path.
• Enjoy the results.

Rendering Data Source Roots

//TODO

Rendering Data Source Items

//TODO

References

Use the following in your scripts to get access to the arguments passed to the processor.

Configure any Enable rules to ensure your script only runs when necessary.

Logging In

Note: Examples included in the following modules

• Enforce user password expiration

Logged In

Note: Examples included in the following modules

• Automatically show quick info section

Logout

Note: Examples included in the following modules

• Unlock user items on logout

Ever wanted to package up items and files without opening the Sitecore Package Designer each time? There are a number of commands available for generating packages.

Package Creation

Example: The following example demonstrates how to generate a package.

$package = New-Package "Package-of-Stuff"
$package.Sources.Clear()

$package.Metadata.Author = "Michael West"
$package.Metadata.Publisher = "Team Awesome"
$package.Metadata.Version = "1.0"
$package.Metadata.Readme = @"
Set of instructions for the user.
"@

# Items using New-ItemSource and New-ExplicitItemSource
$source = Get-Item -Path "master:\templates\Feature\Forms" | 
    New-ItemSource -Name 'Feature Forms Items' -InstallMode Overwrite
$package.Sources.Add($source)

# Files using New-FileSource and New-ExplicitFileSource
$source = Get-Item -Path "$AppPath\App_Config\Include\Feature\Forms\Company.Feature.Forms.config" | 
    New-ExplicitFileSource -Name "Feature Forms Files"
$package.Sources.Add($source)

Export-Package -Project $package -Path "$($package.Name)-$($package.Metadata.Version).xml"
Export-Package -Project $package -Path "$($package.Name)-$($package.Metadata.Version).zip" -Zip
Download-File "$SitecorePackageFolder\$($package.Name)-$($package.Metadata.Version).zip"

Post Step

Example: The following adds a Post Step and custom attributes.

$package = New-Package "Package-of-Stuff"
$package.Sources.Clear()

$package.Metadata.Author = "Michael West"
$package.Metadata.Publisher = "Team Awesome"
$package.Metadata.Version = "1.0"
$package.Metadata.Readme = @"
Set of instructions for the user.
"@
$package.Metadata.PostStep = "Some.Library.Class,Some.Library"
$package.Metadata.Attributes = "scriptId={9b9a3906-1979-11e7-8c9d-177c30471cec}|width=50|height=200"

Export-Package -Project $package -Path "$($package.Name)-$($package.Metadata.Version).xml"

Example: The following adds a Post Step included with SPE to delete a file. The SPE Post Step code reads xml data stored in the comment section of the package.

Import-Function -Name New-PackagePostStep

$package = New-Package "Package-of-Stuff"
$package.Sources.Clear()

$package.Metadata.Author = "Michael West"
$package.Metadata.Publisher = "Team Awesome"
$package.Metadata.Version = "1.0"
$package.Metadata.Readme = @"
Set of instructions for the user.
"@
$newPackageFiles = @([PSCustomObject]@{"FileName"="/bin/Company.Feature.Unused.dll"})
$package.Metadata.PostStep = "Spe.Package.Install.PackagePostStep, Spe.Package"
$package.Metadata.Comment = New-PackagePostStep -PackageFiles $newPackageFiles

Example: The following adds a Post Step Script included with SPE to change icons. The SPE Post Step code executes a script included with the package as stored in the attributes section.

$package = New-Package "Package-of-Stuff"
$package.Sources.Clear()

$package.Metadata.Author = "Michael West"
$package.Metadata.Publisher = "Team Awesome"
$package.Metadata.Version = "1.0"
$package.Metadata.Readme = @"
Set of instructions for the user.
"@
$package.Metadata.PostStep = "Spe.Integrations.Install.ScriptPostStep, Spe"
$package.Metadata.Attributes = "scriptId={737CD0CC-12F7-4528-8FBD-E0FDEFC41325}"

Write-Log "Processing changes to ensure backwards compatibility."
$oldVersion = New-Object System.Version(10,0)
if($PSVersionTable["SitecoreVersion"] -lt $oldVersion) {
    $iseButton = Get-Item -Path "core:{bfc79034-857c-4432-a5c2-2d93af784384}"
    $iseButton.Editing.BeginEdit()
    $iseButton.Fields["{D25B56D4-23B6-4462-BE25-B6A6D7F38E13}"].Value = "powershell/32x32/ise8.png"
    $iseButton.Editing.EndEdit() > $null

    $reportButton = Get-Item -Path "core:{74744022-353c-43f1-b8e4-5bc569ca9348}"
    $reportButton.Editing.BeginEdit()
    $reportButton.Fields["{D25B56D4-23B6-4462-BE25-B6A6D7F38E13}"].Value = "Office/32x32/chart_donut.png"
    $reportButton.Editing.EndEdit() > $null
    Write-Log "Changes complete."
} else {
    Write-Host "No changes required."
}
Close-Window

The reports which come out of the box provide a wide variety of information regarding your Sitecore installation.

Running a Report

The custom reports can be found by navigating to Sitecore -> Reporting Tools -> PowerShell Reports.

As an example, let's run the Unused media items report.

Once the report completes, the results appear in a report window.

Reports in SPE like ASR

While SPE contains many reports, they don't match identical to ASR reports. We've done our best to build those that seem most relevant or likely to be used. If you find a report in ASR that you would like to exist in SPE please submit a request.

Check the reports in SPE under these sections to see the full list.

• 1 Configuration Audit report

• 2 Content Audit report

• 3 Media Audit report

• 4 Solution Audit report

• 5 Toolbox

Note: Examples included are in the following modules

• Content Reports

Reports Security

You may wish to expose the reports to users such as Content Authors. Here are the steps required to grant access to users in the sitecore\Sitecore Client Authoring role.

Here is what users may see in the event they do not have the appropriate access.

1. Navigate to the item /sitecore/content/Documents and settings/All users/Start menu/Right/Reporting Tools/PowerShell Reports

2. Grant access to sitecore\Sitecore Client Authoring
3. Verify the reports are now visible to the Authoring users.

Note: In verson 6.4 the default access changed from sitecore\Sitecore Client Maintaining to a lower privileged account sitecore\Sitecore Client Authoring.

The PowerShell Toolbox is quick way to access frequently used scripts.

Navigate to Sitecore -> PowerShell Toolbox and after selecting you should see the configured scripts:

Note: Examples included in the following modules

• Authorable Reports

• Logged in Session Manager

• Package Generator

• Task Management

• Platform

Available Tools

Index Viewer

Logged in Session Manager

View the list of user sessions and "kick" them out as needed.

Rules based report

Generate a report using the Sitecore Rules Engine.

PowerShell Background Session Manager

View the list of SPE sessions and "kill" them as needed.

Create Anti-Package

Re-create Site from Sitemap

Simple tool for generating a site tree using an existing sitemap.

Task Manager

View and manage the configured scheduled tasks.

Create Tools for the Toolbox

To create your own Toolbox item take the following steps: 1. Create the Toolbox folder under an SPE module. Use the context menu to simplify the process.

• Right click the module name and choose Scripts -> Create libraries for integration points.
• Select the Toolbox item and click Proceed.

  1. Create a PowerShell Script under the Toolbox item.

• Right click the Toolbox library and choose PowerShell Script.

  1. Open and edit the PowerShell Script using the ISE.
  2. Run the Rebuild All command in the ISE by navigating to the Settings tab and selecting the icon to rebuild. Be certain to enable the module before running the rebuild command.
  3. Verify the new toolbox item appears in the Toolbox.

The Web API integration point exposes scripts through a url. This can be especially helpful when a script needs to be executed on the server but without knowledge of the script contents.

Here's the url broken down:

• API Version - Specifies which service is being requested.

  • v2 - This is the service that executes scripts stored in the integration point library.

• Database - Specifies which database contains the script.

  • master - This database requires the credentials to be provided.

• Script - Specifies the name of the script contained in the database. The SPE module containing the script needs to be enabled otherwise you'll receive a 404 error.

  • homeanddescendants - Replace this name with whatever your script is called in the Web API library.

• Query String Parameters (deprecated) - Specifies the additional bits of data for use by the web service.

  • user and password - Authenticates the request and in most cases will be needed. If the script is published to the web database the credentials are not required. You should use the Basic header instead of the query string.

  • All of the query string parameters added to the variable scriptArguments. Use this PowerShell hashtable inside of your scripts. Check out the function Invoke-ApiScript for an example of how these parameters can be put to good use.

Headers:

Use the Basic header to provide authentication information. Here is an example of how to build that for a script.

$username = "admin"
$password = "b"

$pair = "$($username):$($password)"

$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))

$basicAuthValue = "Basic $encodedCreds"

$headers = @{
    Authorization = $basicAuthValue
}

Invoke-RestMethod -Headers $headers -Uri "https://spe.dev.local/-/script/v2/master/TrainingWebApi?offset=3&limit=2&fields=(Name,ItemPath,Id)"

Note: Examples included in the following modules

• Getting Started

Security

References

The Sitecore task scheduler is capable of running PowerShell scripts when using the task command PowerShellScriptCommand. The Task Management module includes a few shortcuts to managing tasks.

The module provides the ability to create, edit, and run scheduled tasks.

References

The Workflows integration allows for scripts to run like workflow commands. Rules can be used to control visiblity and enablement. The script is only executed when the command is triggered.

1. Begin by adding a new item to a workflow command of template type /Modules/PowerShell Console/PowerShell Script Workflow Action. We've added an insert option to help with this.

2. Edit the Type string field to your custom type or to the built in type Spe.Integrations.Workflows.ScriptAction, Spe.

3. Edit the Script body with the appropriate script. I like to save my workflow scripts in a library called Workflows.

4. Configure the Enable rules on the workflow action item to specify when to execute. Leave the rule alone if you wish for it to execute any time the command is activated.

5. Edit the script in your Workflows library to perform the appropriate actions. The script can run in the background and show dialogs.

6. Change the icon of the workflow action item to match the script purpose.

7. Celebrate your success with the team!