Sitecore PowerShell Extensions
  • Introduction
  • Disclaimer
  • Installation
    • Contributor Guide
  • Training
  • Community
  • Interfaces
    • Console
    • Scripting
    • Interface Configuration
    • Interactive Dialogs
    • Help
  • Working with Items
    • Item Languages
    • Item Renderings
    • Variables
    • Providers
  • Modules
    • Libraries and Scripts
    • Integration Points
      • Content Editor
      • Control Panel
      • Data Sources
      • Event Handlers
      • Functions
      • ISE Plugins
      • Page Editor
      • Pipelines
      • Reports
        • Authoring Reports
      • Tasks
        • Authoring Tasks
      • Toolbox
      • Web API
      • Workflows
    • Packaging
  • Remoting
  • Security
    • Users and Roles
  • Releases
  • Troubleshooting
  • Code Snippets
    • Item Links
    • Field Types
    • Manage Templates
  • Appendix
    • Common
      • Add-BaseTemplate
      • Add-ItemVersion
      • Close-Window
      • ConvertFrom-CliXml
      • ConvertFrom-ItemClone
      • ConvertTo-CliXml
      • Expand-Token
      • Get-Archive
      • Get-ArchiveItem
      • Get-Cache
      • Get-Database
      • Get-ItemClone
      • Get-ItemCloneNotification
      • Get-ItemField
      • Get-ItemReference
      • Get-ItemReferrer
      • Get-ItemTemplate
      • Get-ItemWorkflowEvent
      • Get-SitecoreJob
      • Get-SpeModule
      • Get-SpeModuleFeatureRoot
      • Get-TaskSchedule
      • Get-UserAgent
      • Import-Function
      • Invoke-JavaScript
      • Invoke-Script
      • Invoke-ShellCommand
      • Invoke-Workflow
      • New-ItemClone
      • New-ItemWorkflowEvent
      • New-UsingBlock
      • Out-Download
      • Publish-Item
      • Read-Variable
      • Receive-File
      • Receive-ItemCloneNotification
      • Remove-BaseTemplate
      • Remove-ArchiveItem
      • Remove-ItemVersion
      • Reset-ItemField
      • Restart-Application
      • Restore-ArchiveItem
      • Send-File
      • Send-SheerMessage
      • Set-HostProperty
      • Set-ItemTemplate
      • Show-Alert
      • Show-Application
      • Show-Confirm
      • Show-FieldEditor
      • Show-Input
      • Show-ListView
      • Show-ModalDialog
      • Show-Result
      • Show-YesNoCancel
      • Start-TaskSchedule
      • Test-BaseTemplate
      • Test-Rule
      • Update-ItemReferrer
      • Update-ListView
      • Write-Log
    • Indexing
      • Find-Item
      • Get-SearchIndex
      • Initialize-Item
      • Initialize-SearchIndex
      • Initialize-SearchIndexItem
      • Remove-SearchIndexItem
      • Resume-SearchIndex
      • Stop-SearchIndex
      • Suspend-SearchIndex
    • Packaging
      • Export-Item
      • Export-Package
      • Export-UpdatePackage
      • Get-Package
      • Get-Preset
      • Get-UpdatePackageDiff
      • Import-Item
      • Install-Package
      • Install-UpdatePackage
      • New-ExplicitFileSource
      • New-ExplicitItemSource
      • New-FileSource
      • New-ItemSource
      • New-SecuritySource
      • Import-Item
      • New-Package
    • Presentation
      • Add-PlaceholderSetting
      • Add-Rendering
      • Get-Layout
      • Get-LayoutDevice
      • Get-PlaceholderSetting
      • Get-Rendering
      • Get-RenderingParameter
      • Merge-Layout
      • New-PlaceholderSetting
      • New-Rendering
      • Remove-PlaceholderSetting
      • Remove-Rendering
      • Remove-RenderingParameter
      • Reset-Layout
      • Set-Layout
      • Set-Rendering
      • Set-RenderingParameter
      • Switch-Rendering
    • Provider
      • Get-Item
    • Security
      • Add-ItemAcl
      • Add-RoleMember
      • Clear-ItemAcl
      • Disable-User
      • Enable-User
      • Export-Role
      • Export-User
      • Get-Domain
      • Get-ItemAcl
      • Get-Role
      • Get-RoleMember
      • Get-User
      • Import-Role
      • Import-User
      • Lock-Item
      • Login-User
      • Logout-User
      • New-Domain
      • New-ItemAcl
      • New-Role
      • New-User
      • Protect-Item
      • Remove-Domain
      • Remove-Role
      • Remove-RoleMember
      • Remove-User
      • Set-ItemAcl
      • Set-User
      • Set-UserPassword
      • Test-Account
      • Test-ItemAcl
      • Unlock-Item
      • Unprotect-Item
      • Unlock-User
    • Session
      • Get-ScriptSession
      • Get-Session
      • Receive-ScriptSession
      • Remove-ScriptSession
      • Remove-Session
      • Start-ScriptSession
      • Stop-ScriptSession
      • Wait-ScriptSession
Powered by GitBook
On this page
  • Remoting Automation Service
  • Remoting Module Setup
  • Windows Authenticated Requests
  • File and Media Service
  • Script Sessions and Web API Tutorial
  • Advanced Script Sessions
  • Troubleshooting
  • References
Export as PDF

Remoting

PreviousPackagingNextSecurity

Last updated 2 years ago

There are a number of use cases where you need to remotely run scripts within SPE. Here we will try to cover a few of those use cases.

Remoting Automation Service

We have provided a handy way of executing scripts via web service using the Remoting Automation Service.

Remoting Module Setup

The setup of the module only requires a few steps: 1. In the Sitecore instance install the Sitecore module package. 2. On the local desktop or server install the SPE Remoting module.

  • After downloading you may need to unblock the file by right-clicking the zip and unblocking.

  • Ensure that you have run Set-ExecutionPolicy RemoteSigned in order for the SPE Remoting module will run. This typically requires elevated privileges.

    1. Enable the remoting service through a configuration patch. See the page for more details.

    2. Grant the remoting service user account through a configuration patch and granting acess to the appropriate role. See the page for more details.

SPE Remoting Module

Windows Authenticated Requests

If you have configured the web services to run under Windows Authentication mode in IIS then you'll need to use the Credential parameter for the commands.

You'll definitely know you need it when you receive an error like the following:

New-WebServiceProxy : The request failed with HTTP status 401: Unauthorized.

Example: The following connects Windows PowerShell ISE to a remote Sitecore instance using Windows credentials and executes the provided script.

Import-Module -Name SPE
$credential = Get-Credential
$session = New-ScriptSession -Username admin -Password b -ConnectionUri https://remotesitecore -Credential $credential
Invoke-RemoteScript -Session $session -ScriptBlock { Get-User -id admin }
Stop-ScriptSession -Session $session

# Name                     Domain       IsAdministrator IsAuthenticated
# ----                     ------       --------------- ---------------
# sitecore\admin           sitecore     True            False

Example: The following connects to several remote instances of Sitecore and returns the server name.

# If you need to connect to more than one instance of Sitecore add it to the list.
$instanceUrls = @("https://remotesitecore","https://remotesitecore2")
$session = New-ScriptSession -Username admin -Password b -ConnectionUri $instanceUrls
Invoke-RemoteScript -Session $session -ScriptBlock { $env:computername }
Stop-ScriptSession -Session $session

File and Media Service

Example: The following downloads a single file from the Package directory.

Import-Module -Name SPE
$session = New-ScriptSession -Username admin -Password b -ConnectionUri https://remotesitecore
Receive-RemoteItem -Session $session -Path "default.js" -RootPath App -Destination "C:\Files\"
Stop-ScriptSession -Session $session

Example: The following downloads a single media item from the library.

Import-Module -Name SPE
$session = New-ScriptSession -Username admin -Password b -ConnectionUri https://remotesitecore
Receive-RemoteItem -Session $session -Path "/Default Website/cover" -Destination "C:\Images\" -Database master
Stop-ScriptSession -Session $session

Script Sessions and Web API Tutorial

Advanced Script Sessions

Inevitably you will need to have long running processes triggered remotely. In order to support this functionality without encountering a timeout using Invoke-RemoteScript you can use the following list of commands.

  • Get-ScriptSession - Returns details about script sessions.

  • Receive-ScriptSession - Returns the results of a completed script session.

  • Remove-ScriptSession - Removes the script session from memory.

  • Start-ScriptSession - Executes a new script session.

  • Stop-ScriptSession - Terminates an existing script session.

  • Wait-ScriptSession - Waits for all the script sessions to complete before continuing.

These commands are not only used for remoting, we just thought it made sense to talk about them here.

Example: The following remotely runs the id of a ScriptSession and polls the server until completed.

Import-Module -Name SPE
$session = New-ScriptSession -Username admin -Password b -ConnectionUri https://remotesitecore
$jobId = Invoke-RemoteScript -Session $session -ScriptBlock {
        "master", "web" | Get-Database | 
            ForEach-Object { 
                [Sitecore.Globals]::LinkDatabase.Rebuild($_)
            }
} -AsJob
Wait-RemoteScriptSession -Session $session -Id $jobId -Delay 5 -Verbose
Stop-ScriptSession -Session $session

Example: The following remotely runs a script and checks for any output errors. The LastErrors parameter is available for ScriptSession objects.

$jobId = Invoke-RemoteScript -Session $session -ScriptBlock {
    Get-Session -ParameterDoesNotExist "SomeData"
} -AsJob
# This delay could actually be that you got up to get some coffee or tea.
Start-Sleep -Seconds 2

Invoke-RemoteScript -Session $session -ScriptBlock {
    $ss = Get-ScriptSession -Id $using:JobId
    $ss | Receive-ScriptSession

    if($ss.LastErrors) {
        $ss.LastErrors
    }
}
Invoke-RemoteScript -ScriptBlock {
    Write-Verbose "Hello from the other side" -Verbose 4>&1
    "data"    
    Write-Verbose "Goodbye from the other side" -Verbose 4>&1
} -Session $session

Example: The following improves upon the previous example.

Invoke-RemoteScript -ScriptBlock {
    function Write-Verbose {
        param([string]$Message)
        Microsoft.PowerShell.Utility\Write-Verbose -Message $Message -Verbose 4>&1
    }

    Write-Verbose "Hello from the other side"
    "data"    
    Write-Verbose "Goodbye from the other side"
} -Session $session

Troubleshooting

If you receive the following error when trying to run a script (note the namespace is Microsoft.PowerShell.Commands instead of Spe or similar):

    + FullyQualifiedErrorId : NamedParameterNotFound,Microsoft.PowerShell.Commands.NewItemCommand

then add the following line as the first line within the Invoke-RemoteScript block: Set-Location -Path "master:"

Example:

Invoke-RemoteScript -ScriptBlock {
    Set-Location -Path "master:"
    ...
    [The rest of your script]
    ...
}

This issue occurs due to the fact that the remoting session defaults to the FileSystem provider. Changing the location activates the custom provider included with SPE. As part of the custom provider there are additional parameters added to commands native to PowerShell.

References

The remoting services use a combination of a SOAP service (ASMX) and HttpHandler (ASHX). Remoting features are disabled by default and should be configured as needed as can be seen in the . The SOAP service may require additional Windows authentication using the -Credential parameter which is common when logged into a Windows Active Directory domain.

We have provided a service for downloading all files and media items from the server. This disabled by default and can be enabled using a patch file. See the page for more details about the services available and how to configure.

SPE Web API

Example: The following redirects messages from Write-Verbose to the remote session. The data returned will be both System.String and Deserialized.System.Management.Automation.VerboseRecord so be sure to filter it out when needed. More information about the redirection 4>&1 can be read .

Michael's follow up post on

Adam's initial post on

Click for a demo
security section here
Security
Click for a demo
here
Remoting
Remoting
Security
Security