Displaying Errors from Sitecore PowerShell Using Remoting

Question

Using the remoting capabilities in Sitecore PowerShell Extensions, I'm trying to execute some PowerShell remotely and ensure that any errors that occur display in the local console. How can I do that?

Here's what I have:

Import-Module -Name SPE

$session = New-ScriptSession -Username "admin" -Password "b" -ConnectionUri "http://sitecore.local"
$jobId = Invoke-RemoteScript -Session $session -AsJob -ScriptBlock { 
    $templatesPath = "master:/sitecore/content/data/tempdata"

    if (Test-Path $templatesPath) {
        if ((Get-Item $templatesPath).HasChildren -eq "True") {
            $children = Get-ChildItem $templatesPath
            foreach ($childItem in $children) {
                "Deleting temp content at $($childItem.FullPath)"

                # I recognize this next line does not work
                # It's wrong on purpose to test what happens when an error occurs
                Remove-Item "$($childItem.FullPath)" -Force -Recurse
            }
        }
    }
}

Wait-RemoteScriptSession -Session $session -Id $jobId -Delay 1 -Verbose
Stop-ScriptSession -Session $session

If I check the logs after execution I see that an error occurred, but I don't see the error in the console where I executed the script.

Answer 1

Dan, a very good question. Bringing back error messages through the SPE Remoting is quite tricky because of the way PowerShell handles streams of data. Script output is handled one way, and errors (or informational messages) are handled in a different way.

Here are some possible ways for you to troubleshoot.

Example: Run script without the use of asynchronous jobs. If the script turns fairly quickly then it won't be an issue in your testing. Running as a scheduled task, however, may be more suitable for async jobs. The ErrorRecord object is returned in the output.

Import-Module -Name SPE

$session = New-ScriptSession -Username michael -Password b -ConnectionUri http://spe
Invoke-RemoteScript -Session $session -ScriptBlock { 
    $templatesPath = "master:/sitecore/content/pathdoesnotactuallyexist"
    Remove-Item "$($templatesPath)"-Force -ParameterDoesNotActuallyExist
}

Stop-ScriptSession -Session $session

Using the above example you will see this in the Windows PowerShell ISE (remotely).

Now you may be thinking, "Well what if the job does take a while to run?"

Example: Run script asynchronously. A string version of the error is returned.

Import-Module -Name SPE

$session = New-ScriptSession -Username michael -Password b -ConnectionUri http://spe
$jobId = Invoke-RemoteScript -Session $session -ScriptBlock {
    try {
        $templatesPath = "master:/sitecore/content/pathdoesnotactuallyexist"
        Remove-Item "$($templatesPath)"-Force -ParameterDoesNotActuallyExist
    } catch {
        $_
    }
} -AsJob

Wait-RemoteScriptSession -Session $session -Id $jobId -Delay 1

Stop-ScriptSession -Session $session

Using the above example you will see this int he Windows PowerShell ISE (remotely).

This currently looks a little less polished but still gets the job done.

Update

If you desire for your script to return an error message for commands that normally continue, add $ErrorActionPreference = "Stop" in your ScriptBlock.

Example: Run script asynchronously and stop on any error.

Import-Module -Name SPE

$session = New-ScriptSession -Username michael -Password b -ConnectionUri http://spe
$jobId = Invoke-RemoteScript -Session $session -ScriptBlock {
    $ErrorActionPreference = "Stop"
    try {
        $templatesPath = "master:/sitecore/content/pathdoesnotactuallyexist"
        Get-Item "$($templatesPath)"-Force
    } catch {
        $_
    }
} -AsJob

Wait-RemoteScriptSession -Session $session -Id $jobId -Delay 1

Stop-ScriptSession -Session $session

Update 2

Version 4.4.1+ should include support for Write-Verbose and other Write- commands.

You can read more about it here.