Remoting
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 RemoteSignedin order for the SPE Remoting module will run. This typically requires elevated privileges.- 1.
- 2.Grant the remoting service user account through a configuration patch and granting acess to the appropriate role. See the Security page for more details.
SPE Remoting Module
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 security section here. The SOAP service may require additional Windows authentication using the
-Credential parameter which is common when logged into a Windows Active Directory domain.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:
1
New-WebServiceProxy : The request failed with HTTP status 401: Unauthorized.
Copied!
Example: The following connects Windows PowerShell ISE to a remote Sitecore instance using Windows credentials and executes the provided script.
1
Import-Module -Name SPE
2
$credential = Get-Credential
3
$session = New-ScriptSession -Username admin -Password b -ConnectionUri https://remotesitecore -Credential $credential
4
Invoke-RemoteScript -Session $session -ScriptBlock { Get-User -id admin }
5
Stop-ScriptSession -Session $session
6
​
7
# Name Domain IsAdministrator IsAuthenticated
8
# ---- ------ --------------- ---------------
9
# sitecore\admin sitecore True False
Copied!
Example: The following connects to several remote instances of Sitecore and returns the server name.
1
# If you need to connect to more than one instance of Sitecore add it to the list.
2
$instanceUrls = @("https://remotesitecore","https://remotesitecore2")
3
$session = New-ScriptSession -Username admin -Password b -ConnectionUri $instanceUrls
4
Invoke-RemoteScript -Session $session -ScriptBlock { $env:computername }
5
Stop-ScriptSession -Session $session
Copied!
File and Media Service
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 Security page for more details about the services available and how to configure.
Example: The following downloads a single file from the Package directory.
1
Import-Module -Name SPE
2
$session = New-ScriptSession -Username admin -Password b -ConnectionUri https://remotesitecore
3
Receive-RemoteItem -Session $session -Path "default.js" -RootPath App -Destination "C:\Files\"
4
Stop-ScriptSession -Session $session
Copied!
Example: The following downloads a single media item from the library.
1
Import-Module -Name SPE
2
$session = New-ScriptSession -Username admin -Password b -ConnectionUri https://remotesitecore
3
Receive-RemoteItem -Session $session -Path "/Default Website/cover" -Destination "C:\Images\" -Database master
4
Stop-ScriptSession -Session $session
Copied!
Script Sessions and Web API Tutorial
SPE Web API
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.1
Import-Module -Name SPE
2
$session = New-ScriptSession -Username admin -Password b -ConnectionUri https://remotesitecore
3
$jobId = Invoke-RemoteScript -Session $session -ScriptBlock {
4
"master", "web" | Get-Database |
5
ForEach-Object {
6
[Sitecore.Globals]::LinkDatabase.Rebuild($_)
7
}
8
} -AsJob
9
Wait-RemoteScriptSession -Session $session -Id $jobId -Delay 5 -Verbose
10
Stop-ScriptSession -Session $session
Copied!
Example: The following remotely runs a script and checks for any output errors. The LastErrors parameter is available for
ScriptSession objects.1
$jobId = Invoke-RemoteScript -Session $session -ScriptBlock {
2
Get-Session -ParameterDoesNotExist "SomeData"
3
} -AsJob
4
# This delay could actually be that you got up to get some coffee or tea.
5
Start-Sleep -Seconds 2
6
​
7
Invoke-RemoteScript -Session $session -ScriptBlock {
8
$ss = Get-ScriptSession -Id $using:JobId
9
$ss | Receive-ScriptSession
10
​
11
if($ss.LastErrors) {
12
$ss.LastErrors
13
}
14
}
Copied!
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 here.1
Invoke-RemoteScript -ScriptBlock {
2
Write-Verbose "Hello from the other side" -Verbose 4>&1
3
"data"
4
Write-Verbose "Goodbye from the other side" -Verbose 4>&1
5
} -Session $session
Copied!
Example: The following improves upon the previous example.
1
Invoke-RemoteScript -ScriptBlock {
2
function Write-Verbose {
3
param([string]$Message)
4
Microsoft.PowerShell.Utility\Write-Verbose -Message $Message -Verbose 4>&1
5
}
6
​
7
Write-Verbose "Hello from the other side"
8
"data"
9
Write-Verbose "Goodbye from the other side"
10
} -Session $session
Copied!
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):1
+ FullyQualifiedErrorId : NamedParameterNotFound,Microsoft.PowerShell.Commands.NewItemCommand
Copied!
then add the following line as the first line within the Invoke-RemoteScript block:
Set-Location -Path "master:"Example:
1
Invoke-RemoteScript -ScriptBlock {
2
Set-Location -Path "master:"
3
...
4
[The rest of your script]
5
...
6
}
Copied!
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
Last modified 2yr ago