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.

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

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:\>

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

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

   Copy

   cd "C:\Source\Console"  // Your local source folder, with a new folder for the solution
   git init
   git remote add origin https://github.com/SitecorePowerShell/Console.git
   git fetch origin
   git checkout -b master --track origin/master

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:

{ 
    "sites": [
        {
            "path": "C:\\inetput\\wwwroot\\SitecoreSPE_8\\Website",
            "version": 8,
            "junction": 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

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

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

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.

We've provided a few commands to interact with the user through dialogs.

Simple Dialogs

Simple in the sense that the dialogs present the user with a short message and one or two buttons.

Alert

The Alert dialog is a way to notify the user of important information with an "OK" button.

Example: The following display a modal dialog.

No return value.

Confirmation

The Confirmation dialog is a way to verify with the user before proceeding.

Example: The following displays a modal dialog with an OK or Cancel confirmation.

User Input

Example: The following displays an input dialog for text.

Example: The following displays an input dialog with a error validation message.

Advanced Dialogs

Variable Settings

The Read-Variable command provides a way to prompt the user for information and then generate variables with those values.

Example: The following displays a dialog with a dropdown.

Note: The name selectedOption will result in a variable that contains the selected option.

Supported Parameter Values

Editor Types

• bool

• check

• date

• date time

• droplist

• droptree

• email

• groupeddroplink

• groupeddroplist

• info

• item

• link

• marquee

• multilist

• multilist search

• multiple user

• multiple user role

• multiple role

• multitext

• number

• pass

• radio

• rule

• rule action

• tree

• treelist

• tristate

• time

Confirmation Choice

The Confirmation Choice dialog allows for multiple combinations like that seen with a "Yes, Yes to all, No, No to all" scenario.

Example: The following displays a modal dialog with choices.

Note: The hashtable keys should be incremented like btn_0, btn_1, and so on. The return value is the key name.

Upload

The Upload dialog provides a way to upload files from a local filesystem to the media library or server filesystem.

Example: The following displays an advanced upload dialog.

No return value.

Download

The Download dialog provides a way to download files from the server to a local filesystem.

Example: The following displays a download dialog.

Field Editor

The Field Editor dialog offers a convenient way to present the user with fields to edit.

Example: The following displays a field editor dialog.

File Browser

The File Browser is an obvious choice when you need to upload, download, or delete files.

Example: The following displays a file browser dialog for installation packages.

Example: The following displays a simple file browser dialog.

Example: The following displays a Sheer UI control without any additional parameters.

Data List

The "Data List" is essentially a report viewer which supports custom actions, exporting, and filtering.

Example: The following displays a list view dialog with the child items under the Sitecore tree.

Results

The Results dialog resembles the Console but does not provide a prompt to the user. This is useful for when logging messages.

Example: The following displays a dialog with the all the information written to the ScriptSession output buffer.

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.

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

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.

Get-ChildItem "master:\content" -Recurse | 
    Add-ItemLanguage -Language "en-us" -TargetLanguage "en-ca" -IfExist OverwriteLatest

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.

$languageParameters = @{
    Path = "master:\content\home"
    Language = "en"
    TargetLanguage = @("pl-pl","en-us")
    IfExist = "Skip"
    IgnoredFields = @("Title")
}
Add-ItemLanguage @languageParameters

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.

Get-ChildItem "master:\content\home" -Language "en" -Recurse |
    Where-Object { $_.TemplateName -eq "Sample Item" } |
    Add-ItemLanguage -TargetLanguage "pl-pl" -IfExist Append |
    Format-Table Name, Language, Version -AutoSize

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.

Add-ItemLanguage -Path "master:\content\home" -TargetLanguage "pl-pl" -IfExist Skip -DoNotCopyFields -Recurse

Remove Language Version

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

Get-ChildItem "master:\content" -Recurse | 
    Remove-ItemLanguage -Language "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.

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

Name          Children Language Version Id                                     TemplateName
----          -------- -------- ------- --                                     ------------
Sample Item 3 False    en-CA    1       {C9517583-3AF9-4AFB-B247-BB0A09F55D94} Sample Item

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:

<configuration xmlns:patch="https://www.sitecore.net/xmlconfig/">
  <sitecore>
    <powershell>
      <translation>
        <ignoredFields>
          <field>__Archive date</field>
          <field>__Archive Version date</field>
          <field>__Lock</field>
          <field>__Owner</field>
          <field>__Page Level Test Set Definition</field>
          <field>__Reminder date</field>
          <field>__Reminder recipients</field>
          <field>__Reminder text</field>
          <!--field>__Security</field-->
        </ignoredFields>
      </translation>
  </sitecore>
</configuration>

References

There are several variables available out of the box for use in running commands and scripts. Many of the variables prefixed with Sitecore derive from the Sitecore.config settings. Run the command Get-Variable to see the complete list available in the currently running session.

Note: Any new variables created are stored within the current session; when the session ends the variables are removed. Be careful not to overwrite the built-in variables.

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

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:\>

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.

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.

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.

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

Context Menu

The Context Menu integration reveals a list of options to the user in the context menu under a special node called Scripts. The Sitecore rules engine may be used to control visibility and enabled state. The script is only executed when the option is clicked.

1. Begin by adding a new script to the Context Menu library. The name of the script will appear in the context menu.

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.

Note: Examples included in the following modules

• Authoring Instrumentation

• Copy Renderings

• Index On Demand

• Media Library Maintenance

• Package Generator
• Task Management

Gutter

The Gutter integration reveals a visual notification to the user in the far left gutter. The Sitecore rules engine may be used to control enabled state.

1. Begin by adding a new script to the Gutters library.

2. Edit the script to create a new instance of Sitecore.Shell.Applications.ContentEditor.Gutters.GutterIconDescriptor if the right conditions are met.

   • Set the Icon, Tooltip, and Click properties.

   • Return the gutter object

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

4. Rebuild the gutter integration from within the ISE.

   • Settings tab

   • Integration chunk

   • Sync Library with Content Editor Gutter command

Note: Examples included in the following modules

• Publishing Status Gutter

Insert Item

The Insert Item integration reveals a list of options to the user in the context menu under the node called Insert. The Sitecore rules engine may be used to control visibility and enabled state. The script is only executed when the option is clicked.

1. Begin by adding a new script to the Insert Item library. The name of the script will appear in the context menu.

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 Show rules as needed.

Note: Examples included in the following modules

• Task Management
• Platform

Ribbon

The Ribbon integration reveals commands to the user in the ribbon. The Sitecore rules engine may be used to control visibility and enabled state. The script is only executed when the option is clicked.

1. Begin by adding a new child script library to the Ribbon library; we'll refer to this library as the Tab library. Choose a name that matches an existing tab to be used, such as Home or Developer, or a new name to create a new tab.

2. Add a child script library to the Tab library; we'll call this the Chunk library. Choose a name such as Edit or Tools.

3. Add a new script to the Chunk script library; we'll refer to this library as the Command library. The name of the script will appear in the ribbon chunk as a command.

4. Optionally add a short description on the item, which is found as a standard field on the item. The description will appear as a tooltip on the ribbon button.

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

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

7. Configure any Enable or Show rules as needed.

Example: The following script gets the selected Context Menu item and displays an alert using the item name.

# Use the notation "." to get the current directory/item.
$item = Get-Item -Path .
Show-Alert -Title $item.Name

Button Size:

There is a way to generate small buttons and combo buttons. You simply need to prefix the script name and SPE will generate accordingly.

• Small$[SCRIPT_NAME]

• Combo$[SCRIPT_NAME]

• SmallCombo$[SCRIPT_NAME]

Contextual Ribbon

Similar to the Ribbon integration, this provides a way to show buttons when certain contextual conditions are met. Most common is with media items. The steps are the same as with the standard Ribbon, but the structure is slightly changed.

In the following example, we have a ribbon button that appears whenever the selected item in the Content Editor is a media item. Take note of the "Optimize" button.

The ribbon structure would look like the following:

Warning

The Warning integration reveals a notification to the user above content. The Sitecore rules engine can be used to control visibility and enabled state. The scripts are only executed when the rule is met and the command is clicked.

1. Begin by adding a new script library to the Warning library.

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

3. The warning notification title, text and icon should be configured in the script.

   • Include options to the warning by adding one or more secondary scripts to the script library.

4. Configure any Enable rules to ensure the script only runs when required.

Note: Examples included in the following modules

• License Expiration - disabled by default

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.

$title = "Thank you for using SPE!"
$text = "Today is $([datetime]::Now.ToLongDateString())"
$icon = @{$true="Office/32x32/information.png";$false="Applications/16x16/warning.png"}[$SitecoreVersion.Major -gt 7]

$notification = New-Object -TypeName Sitecore.Pipelines.GetPageEditorNotifications.PageEditorNotification -ArgumentList $text, "Info"

$notification.Icon = $icon
$pipelineArgs.Notifications.Add($notification)

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.

$item = Get-Item -Path .
$response = Show-Input -Prompt "What's the message for $($item.Name)?"
if($response) {
    $mailSettings = @{
        To = @("Michael West < mw@test.com >")
        From = "Console < noreply@test.com >"
        BodyAsHtml = $true
        SmtpServer = "localhost"
    }

    $subject = "Message sent regarding item $($item.Name) from $($SitecoreAuthority)"
    $response += "<br/>$($item.ItemPath)"
    Send-MailMessage @mailSettings -Subject $subject -Body $response
}

Close-Window