1 of 100

Sitecore PowerShell Extensions

Introduction

About the Module

The Sitecore PowerShell Extensions (SPE) module is a Sitecore development accelerator that can drastically increase your productivity and curtail the amount of time it takes to deliver a Sitecore solution.

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.

The book provides documentation about how to use the module based on the latest released version. While some of the screenshots and materials may be slightly out-of-date, you will inevitably find details referring to something that doesn't exist on your installed version. Feel free to submit a pull request for corrections .

Support for Sitecore 7 has discontinued with SPE 5.0. Check the for version compatibility.

Development Team

Bundled Tools

The following are some helpful modules distributed with SPE.

Core
- Platform
  - PowerShell Background Session Manager

Endorsements

There is nothing you can not do with PowerShell Console, because you're inside the Sitecore application. You can call the Sitecore API. - - Sitecore Symposium 2012

Recommended by to use as a tool for .

Get a job done with a one liner! Just provisioned a new language for the whole content tree with a one-liner. Whaaaat? Have to include it as a default install for all sandboxes now. - 's comment on Marketplace

Thank you for the GitBook. Invaluable Reference. - 's

The Sitecore powershell tools are absurdly good and helpful. I know they make a lot of people nervous, but they are incredibly well managed. Everybody should learn to sling some shell in Sitecore, you'll never look back. -

I literally couldn't work without SPE - I can't remember the last implementation I did that didn't have it installed lol @michaellwest & @adamnaj better not ever retire it 😄 -

Help and Support

See the section for some common fixes.

Questions, comments, and feature requests should be submitted on . You may also check out the for more interactive support. Not on Slack yet? Contact us on Twitter and we'll send you an invite.

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.

Disclaimer

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.

Interfaces

SPE includes several built-in interfaces for managing and executing scripts, as well as provides tools for modifying content.

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

Scripting

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!

The default security configuration for SPE requires the ISE to be in an before executing scripts. The following figure shows the ISE when the User Account Controls (UAC) are disabled. While this is a common configuration for developers, we highly encourage you to ensure UAC is enabled in higher environments.

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

Home Tab

Interface Configuration

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

Help

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:

For further information on comment-based help, refer to the .

Online appendix

Online help is additionaly available for all SPE commands in this documentation, with detailed explanations of commands and their parameters, along with useful examples. These can be found in the .

Providers

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.

Note: Include the backslash in the path (i.e. **C:**) to get the root of the drive when interacting with the FileSystem provider; the behavior seen is different than you might expeect because of w3wp.exe. See issue #.

Modules

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:

The contained within each module can be enabled or disabled globally. For this to take full affect the integration should be rebuilt in the ISE.
Organization of custom scripts is a cinch.

Control Panel

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

Data Sources

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:

Event Handlers

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

Steps required to activate this integration include the following:

Enable the Spe.Events.config or apply your own patch with the required events enabled.
Add a new integration point library to your new or existing module.

Functions

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

Begin by adding a script library called "Functions" to a module. This can be created by the new module wizard.
Add a script to the "Functions" script library with a name that represents the purpose.
Use the command

ISE Plugins

Custom ribbon commands for use in the ISE.

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:

The path structure needs to follow [MODULE]/Internal/ISE Plugins/[PLUGIN_NAME]. Here we have X-Demo/Internal/ISE Plugins/Analyze Script.

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.

Page Editor

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

Pipelines

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

 $pipelineArgs = Get-Variable -Name pipelineArgs -ValueOnly

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

Tasks

The task scheduler is a great way to run scripts in a periodic fashion. You may find the need to automatically archive log files into a compressed file. Perhaps send an email with a generated report based on stale site content.

Video Tutorial

Authoring Tasks

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

Web API

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.

The url will look something like the following:

Here's the url broken down:

API Version - Specifies which service is being requested.

Workflows

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.

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.
Edit the Type string field to your custom type or to the built in type Spe.Integrations.Workflows.ScriptAction, Spe.

Packaging

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.

Releases

Thank you for taking the time to check out the latest and greatest changes for SPE. Send a tweet sharing how much you love the module on .

The following links provide a way to report issues and get the latest release.

Troubleshooting

General

We generally see issues occurring due to an incompatible version of Windows PowerShell. Be sure to install Windows PowerShell version 3 or newer.

Installation

Item Links

Examples for managing item referrers maintained by the Link Database.

Relink Item

Example: The following changes the image linked on an item to a new image. Originally posted here.

$item = Get-Item -Path "master:\media library\images\koala"
$itemNew = Get-Item -Path "master:\media library\images\penguins"
$links = Get-ItemReferrer -Item $item -ItemLink
foreach($link in $links) {
    $linkedItem = Get-Item -Path master:\ -ID $link.SourceItemID 
    $itemField = $linkedItem.Fields[$link.SourceFieldID]
    $field = [Sitecore.Data.Fields.FieldTypeManager]::GetField($itemField)
    
    $linkedItem.Editing.BeginEdit()
    $field.Relink($link, $itemNew)
    $linkedItem.Editing.EndEdit() | Out-Null
}

Remove Item Link

Example: The following removes an item link followed by removing the item. Originally posted .

Manage Templates

Examples for managing item templates.

Manage Templates

Change Template

# Sample Item
$sourceTemplate = Get-Item -Path "master:\{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"
# Sample Content
$targetTemplate = Get-Item -Path "master:\{93A8866B-972F-4FBF-8FD9-D6004B18C0AF}"

# Use Get-ItemReferrer to find all items referencing the template, rather than scanning the content tree.
$sourceTemplate | Get-ItemReferrer | 
    Where-Object { $PSItem.TemplateId -eq $sourceTemplate.ID -and $PSItem.Paths.IsContentItem } |
    ForEach-Object {
        Set-ItemTemplate -Item $PSItem -TemplateItem $targetTemplate
    }

Sitecore Stack Exchange

The following examples are best kept on SSE since it provides more context about the problem being solved.

Find all items based on a template found anywhere in the inheritance chain.

Common

Close-Window

Closes the runner job window after the script completes.

Syntax

Close-Window

ConvertFrom-CliXml

Imports a CliXml string with data that represents Microsoft .NET objects and creates the objects within PowerShell.

Syntax

ConvertFrom-CliXml [-InputObject] <String>

ConvertTo-CliXml

Exports Microsoft .NET objects froms PowerShell to a CliXml string.

Syntax

ConvertTo-CliXml [-InputObject] <PSObject>

Get-Archive

Returns Sitecore database archives.

Syntax

Get-Archive [[-Database] <Database>] [[-Name] <String>]

Get-Cache

Retrieves a Sitecore cache.

Syntax

Get-Cache [[-Name] <String>]

Get-UserAgent

Returns the current user's browser user agent.

Syntax

Detailed Description

Returns current user's browser user agent. Works only if Console is running outside of job. (e.g. in ISE - script needs to be run from the dropdown under the "Execute" button)

Parameters

Outputs

The output type is the type of the objects that the cmdlet emits.

System.String

Notes

Help Author: Adam Najmanowicz, Michael West

Examples

EXAMPLE

Invoke-JavaScript

Syntax

Detailed Description

Restart-Application

Restarts the Sitecore Application pool.

Syntax

Detailed Description

Restarts the Sitecore Application pool.

Parameters

Notes

Help Author: Adam Najmanowicz, Michael West

Examples

EXAMPLE

Security Policies

Understanding the security policies that govern SPE is essential for properly securing your installation. SPE operates under two primary security contexts that work together to control what scripts can do.

Overview

SPE security operates on two levels:

Application Pool Service Account - Controls OS-level access (file system, registry, network)
Sitecore User Account - Controls Sitecore API access (content, security, configuration)

Both security contexts work together to determine what a PowerShell script can accomplish.

Application Pool Service Account

How It Works

The Windows PowerShell runspace executes under the identity of the IIS application pool service account. This account determines what OS-level resources the script can access through PowerShell providers.

Key Providers Affected:

FileSystem - Read/write files and directories
Registry - Read/write Windows registry keys
Environment - Access environment variables
Certificate - Access certificate stores

Security Implications

The application pool service account gives SPE access to OS-level features. If the service account can delete files from the root directory, SPE can do the same.

Example: If your application pool runs as NETWORK SERVICE or ApplicationPoolIdentity, the script may have:

Read/write access to C:\inetpub\wwwroot
Access to the application directories
Potentially access to other directories on the system

Common Service Account Types

Service Account

Typical Permissions

Security Considerations

Best Practices

✅ Do:

Use the principle of least privilege
Audit file system permissions for the service account
Restrict the account to only necessary directories
Use a named service account when you need specific permissions

❌ Don't:

Run as LocalSystem or Administrator
Grant the service account unnecessary file system permissions
Assume ApplicationPoolIdentity is fully restricted
Allow write access to system directories

Verifying Service Account Access

Example: Check which directories the service account can access:

Restricting File System Access

You can restrict which directories SPE can access by:

NTFS Permissions - Remove unnecessary file system permissions from the service account
AppLocker - Use Windows AppLocker to restrict PowerShell execution paths
File Upload Restrictions - Configure SPE to only allow uploads to specific locations (see )

Sitecore User Account

How It Works

Scripts execute within the security context of the logged-in Sitecore user. The user's Sitecore roles and permissions determine what content and functionality the script can access through the Sitecore API.

Key Areas Controlled:

Content item access (read/write/delete)
Security management (users/roles)
Configuration access
Workflow operations

Security Implications

The Sitecore security model applies to all script operations that use the Sitecore API:

However, scripts can bypass Sitecore security just like any other Sitecore API code:

Security Note: Scripts can disable Sitecore security checks using SecurityDisabler and other disablers. This is why limiting who can write and execute scripts is critical.

Application-Level Security

SPE features are protected by Sitecore security at the application level. Access to SPE interfaces is controlled through item-level security in the Core database.

Configuration Location: core:\content\Applications\PowerShell

Feature

Default Visibility

Security Path

Note: Security is validated in each SPE application within the OnLoad function.

Context menu items in the Content Editor are also protected by security.

Configuration Location: core:\content\Applications\Content Editor\Context Menues\Default\

Feature

Visibility

Command State

Note: PowerShell Script Library and PowerShell Script items have additional visibility and enabled rules. Adjust role permissions on these items to control menu visibility.

Best Practices

✅ Do:

Only grant SPE access to trusted administrators
Use Sitecore roles to control feature access
Require Session Elevation (UAC) for production environments
Audit which users have access to Developer and related roles

❌ Don't:

Grant sitecore\Developer role to content authors
Assume Sitecore security prevents all unauthorized actions
Allow untrusted users to write or execute scripts
Ignore the fact that scripts can disable security

Verifying User Access

Example: Check current user context and permissions:

Combined Security Model

Both security contexts work together. A script is limited by whichever context is more restrictive:

Example Scenarios:

Scenario

Service Account

User Account

Result

Least Privilege Strategy

Implement defense in depth by restricting both security contexts:

Service Account

Minimum file system access
No access to sensitive directories
Regular permission audits

Sitecore User Account

Role-based access control
Session elevation required
Regular role membership audits
Script library security reviews

Additional Layers

- Require reauthentication
- Disable unnecessary endpoints
- Block anonymous access
- Detect unauthorized access

Next Steps

Configure to add an additional authentication layer
Review if you need external access
Learn about
Complete the

References

Logging and Monitoring

Comprehensive logging and monitoring are essential for detecting security incidents, troubleshooting issues, and maintaining compliance. This guide covers how to configure and use SPE logging for security purposes.

Overview

SPE provides logging capabilities that record:

Script execution
User authentication and authorization
Session elevation events
Delegated access usage
Web service calls
Errors and exceptions

Security Best Practice: Enable comprehensive logging in all non-development environments to create an audit trail.

SPE Log Files

Default Log Location

SPE logs are written to:

Typically resolves to:

Log Levels

SPE supports standard log4net levels:

Level

Description

Use Case

Configuring Log Level

Edit your log4net configuration (typically in App_Config\Sitecore.config or a patch file):

Recommended Settings:

Environment

Log Level

Rationale

What Gets Logged

Script Execution

Format:

Session Elevation

Format:

Delegated Access

Format:

Includes:

Script ID
Context user (actual logged-in user)
Impersonated user (elevated account)

This is critical for audit trails showing privilege escalation.

Web Service Calls

Format:

Logged Events:

Remoting connections
File uploads/downloads
RESTful API calls
Authorization failures

Authentication Events

Format:

Logged Events:

Successful authentication
Failed authentication
Authorization denials

Errors and Exceptions

Format:

Includes:

Exception details
Stack traces
User context
Operation being performed

Monitoring Strategies

Real-Time Monitoring

Using PowerShell to Tail Logs

Monitor for Specific Events

Log Analysis

Find Failed Authentication Attempts

Track Delegated Access Usage

Find Unauthorized Access Attempts

Analyze Web Service Usage

Scheduled Log Review

Create a scheduled task to analyze logs daily:

IIS Log Integration

IIS Logs for Web Services

IIS logs provide additional context for web service access:

Location:

Useful IIS Log Fields

Field

Description

Security Value

Analyzing IIS Logs for SPE

Find SPE web service requests:

Find failed authentication (401) to SPE services:

Alerting

Simple Email Alerts

Create alerts for critical security events:

Run this script via Task Scheduler every 5 minutes.

Integration with SIEM

For enterprise environments, integrate SPE logs with your Security Information and Event Management (SIEM) system.

Common SIEM Solutions:

Splunk
ELK Stack (Elasticsearch, Logstash, Kibana)
Azure Sentinel
ArcSight

Log Retention

Regulatory Requirements

Different compliance frameworks have different retention requirements:

Framework

Typical Requirement

Note: The requirements may have changed since the publishing of this document. Please confirm with your organization and legal team as to the requirements you must meet.

Configuration

The configuration of log retention will be dependent on your solution.

Archival Strategy

The archival strategy implementation will be dependent on your solution.

Security Metrics

Key Performance Indicators (KPIs)

Track these metrics for security monitoring:

Metric

Description

Threshold

Best Practices

Security Recommendations

✅ Do:

Enable INFO level logging in production
Monitor logs daily for suspicious activity
Set up alerts for critical security events
Retain logs per compliance requirements

❌ Don't:

Disable logging in production
Ignore failed authentication attempts
Delete logs prematurely
Log sensitive data (passwords, tokens)

Monitoring Frequency

Activity

Frequency

Method

Troubleshooting

Logs not being written

Possible causes:

log4net configuration incorrect
File permissions prevent writing
Disk space full
SPE logger disabled

Solution: Check log4net config, verify permissions, ensure disk space.

Too much log data

Cause: DEBUG level in production or high activity.

Solution: Change to INFO or WARN level, implement log rotation.

Can't find specific events

Cause: Log rotation moved old logs or logs were deleted.

Solution: Check archived logs, adjust retention period.

- Includes logging validation
- Monitoring delegated access usage
- Monitoring web service security
- IIS log integration

References

- Your Sitecore implementation may require vendor-specific documentation as log4net is bundled/compiled in the Sitecore libraries.

Security

Sitecore PowerShell Extensions (SPE) is a powerful administrative tool that requires proper security configuration. This guide provides comprehensive security documentation to help you secure your SPE installation.

Critical Warning: SPE is a powerful tool that should NEVER be installed on Content Delivery (CD) instances or internet-facing servers. Always implement security best practices and follow the principle of least privilege.

Quick Start

New to SPE security? Start here:

- Essential security setup for new installations
- Understand the SPE security model
- Validate your deployment before going live

Security Documentation

Core Security Topics

Understand the two-layer security model that governs SPE:

Application Pool Service Account (OS-level access)
Sitecore User Account (API-level access)
- Application and menu item security
Best practices for both security contexts

Configure User Account Control to require reauthentication:

How Session Elevation works
Elevation actions (Allow, Block, Password, Confirm)
Token configuration and expiration
Environment-specific recommendations

Control external access to SPE through web services:

Service descriptions and security implications
Enable/disable individual services
HTTPS and requireSecureConnection
Role-based authorization

Hardening and Protection

Prevent malicious file uploads:

File type restrictions (extensions and MIME types)
Upload location restrictions
Dangerous file types to never allow
Configuration examples

Grant controlled privilege escalation:

How delegated access works
Configuration steps
Use cases (publishing, reports, bulk operations)
Script implementation patterns

Add defense in depth at the web server level:

Deny anonymous access
Windows Authentication
IP address restrictions
SSL/TLS requirements

User Management

Manage Sitecore users and roles:

Bulk user operations
Role queries and management
Item Access Control Lists (ACL)
Active Directory integration

Deployment and Operations

Deploy only what's needed for CI/CD:

Required files for web services only
Disable UI components
Configuration for automation scenarios
Security best practices

Track security events and detect incidents:

What gets logged
Log levels and configuration
Real-time monitoring strategies
Log analysis examples

Validation and Compliance

Comprehensive validation before deployment:

Pre-deployment validation
Configuration checklist
Testing procedures
Environment-specific checklists

Security by Environment

Development Environment

Priority: Productivity with basic security

Recommendations:

Session Elevation: Relaxed (Allow or long timeouts)
Web Services: Enable as needed for testing
Logging: DEBUG level for troubleshooting
IP Restrictions: Not required

Start here:

QA/Staging Environment

Priority: Match production security for testing

Recommendations:

Session Elevation: Password or Confirm (5-15 minute timeout)
Web Services: Match production configuration
Logging: INFO level
IP Restrictions: Optional

Start here:

Production Environment

Priority: Maximum security

Recommendations:

Session Elevation: Password or Confirm (3-5 minute timeout)
Web Services: Only handleDownload, client, execution (disable remoting)
Logging: INFO or WARN level
IP Restrictions: Recommended

Start here:

CI/CD Environment

Priority: Automation with strict access control

Recommendations:

Minimal Deployment: Use minimal package
Remoting: Enabled with IP restrictions
Web Services: Only required services
Logging: INFO level with monitoring

Start here:

Security Layers (Defense in Depth)

SPE security uses multiple layers for comprehensive protection:

Each layer provides additional protection. If one layer is compromised, others provide continued security.

Common Security Scenarios

Scenario 1: Locking Down Production CM

Goal: Secure SPE for production content management server

Steps:

Review to understand the model
Configure with 5-minute Password timeout
Disable unnecessary
Configure to deny anonymous access

Scenario 2: Setting Up CI/CD Automation

Goal: Enable remote automation from build servers

Steps:

Use package
Enable Remoting in with specific user
Configure with IP restrictions to build servers
Configure for packages only

Scenario 3: Delegating Access to Reports and Tools

Goal: Allow content authors to run administrative reports and tools

Steps:

Understand concepts
Create delegated access configuration for tooling or reporting role
Configure impersonated user with read-only administrative access
Test tool or report access as content author

Scenario 4: Identity Server Integration (Sitecore 9.1+)

Goal: Configure SPE with Sitecore Identity Server

Steps:

Enable Spe.IdentityServer.config
Configure with Confirm action (not Password)
Test Console and ISE with federated authentication
Configure if needed

Security Best Practices Summary

✅ Do

Always deny anonymous access at IIS level
Always use Session Elevation (UAC) in production
Always require HTTPS for any enabled web services
Always follow principle of least privilege

❌ Don't

Never install SPE on Content Delivery (CD) servers
Never expose SPE to internet-facing servers
Never use elevationAction="Allow" in production
Never

Quick Reference

Configuration Files

File

Purpose

Documentation

Security Policies Location

Policy

Location

Documentation

Default Roles

Role

Default Access

Recommendation

Getting Help

New to SPE Security? Start with
Deploying to production? Use the
Setting up automation? See
Need to debug? Check

Support Resources

GitHub Issues:
Slack: #module-spe on Sitecore Community Slack
Documentation:

Security Incident Response

If you suspect a security breach:

Immediately lock down SPE using
Review logs using guidance
Document the incident
Contact your security team

Additional Resources

- Initial SPE installation
- Console, ISE, and Interactive Dialogs
- Using SPE Remoting for automation
- Integration points and features

External References

Version-Specific Notes

Sitecore 9.1+ with Identity Server

Enable the Identity Server configuration:

File: App_Config\Include\Spe\Spe.IdentityServer.config
Purpose: Prevents infinite loop in SPE Console
Use elevationAction="Confirm" instead of "Password"

Sitecore XM Cloud

Consult the latest SPE documentation for XM Cloud-specific security configurations.

Remember: Security is not a one-time configuration. Regular reviews, monitoring, and updates are essential to maintaining a secure SPE installation.

Last Updated: 2025 Maintained By: SPE Community

Working with Items

Command Introduction

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

Use this to retrieve a single item. Throws an error if the item does not exist.
Use when Sitecore query: or fast: is required. May return more than 1 item.

Use to return an item's children and grandchildren.

Use to create an item based on a specified data template.

Use to delete or recycle an item.
Accepts items returned by Get-Item and Get-ChildItem.

Use to transfer an item from one location to another.

Use to duplicate an item from one location to another.

Command Parameters

The following commands provide you with the core methods needed to manage your content. Due to the nature of Windows PowerShell, commands such as these are extended with custom parameters and switches using . These parameters are then added to the command at the time of use and only appear when the conditions are right. We've provided this table to help you discover the hidden gems within each command.

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

If you have retrieved your items directly using the Sitecore API you can still add the nice wrapper. You can do that by piping them through the Initialize-Item command. We'll show an of this later.

Check out some performance details when using different methods of querying items on the .

Get-Item : by Path

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

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#.

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.

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.

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

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

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.

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.
Workaround found .

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

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

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

Get-Item : Sitecore Fast query

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

Get-Item : by XPath

The setup is not exactly like you would find in the XPath Builder but should get the job done. Read more about it .

Example: The following retrieves items matching an XPath query.

Get-Item : by Id

Example: The following retrieves an item by id.

Get-Item : by Uri

The Uri encodes the language and version within the path.

Example: The following retrieves an item by uri.

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.

Example: The following uses the PSTemplate PropertySet.

Example: The following uses the PSImage PropertySet.

Example: The following uses the PSSchedule PropertySet.

Get-Item : properties with field type

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

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.

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

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.

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

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.

If the property name on the data template contains a space, such as `Closing Date`, then you will need to wrap the field name in quotes (single or double).

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

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

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

If you need to dynamically reference a property via a property name that is stored in a variable, there are numerous ways to reference it.

Example:

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.

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

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.

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.

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.

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.

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.

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

Sitecore.SecurityModel.SecurityDisabler
Sitecore.Data.BulkUpdateContext
Sitecore.Globalization.LanguageSwitcher

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.

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.

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.

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

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.

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

Creating Items

New-Item

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

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

Example: The following creates a new item as a child of the specified 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.

Sitecore PowerShell Extensions

Introduction

About the Module

Development Team

Bundled Tools

Endorsements

Help and Support

Disclaimer

Interfaces

Scripting

Home Tab

Interface Configuration

Colors

Help

Viewing all available commands

Viewing command help

Console

ISE

Documenting functions

Online appendix

Providers

Modules

Control Panel

Administration

Analytics

Database

Globalization

Preferences

Reports

Security

Data Sources

Event Handlers

Functions

ISE Plugins

Add a custom plugin

Page Editor

Notification

Pipelines

Logging In

Logged In

Logout

Tasks

Video Tutorial

Authoring Tasks

References

Web API

Workflows

Packaging

Package Creation

Releases

Troubleshooting

General

Installation

Item Links

Relink Item

Remove Item Link

Manage Templates

Manage Templates

Change Template

Sitecore Stack Exchange

Common

Close-Window

Syntax

ConvertFrom-CliXml

Syntax

ConvertTo-CliXml

Syntax

Get-Archive

Syntax

Get-Cache

Syntax

Get-UserAgent

Syntax

Detailed Description

Parameters

Outputs

Notes

Examples

EXAMPLE

Related Topics