• $album is the name of the album
• $credential is a global variable that contains a PSCredential which is used by the cmdlet to authenticate with the Twitter service.  

• Audite Nova
• I Heard a Voice
• Deck the Halls

It's not uncommon that after I've created a fairly complicated script after a while of using it, something bad happens that I wasn't expecting. And I would really like to know how I got to this state, so a stacktrace of my script would be really, really nice. Sadly, this isn't something that is a default behavior or PowerShell, but fortunately, this sort of thing is actually possible to do with just a little bit of script!

Most of the real world examples are more complicated than we really need to use to illuminate the problem.  So, I've created a simple example that is useful for discussion.

Take the following script:
# test-stacktrace1.ps1
param ( $startVal )
function func1
{
    param ( $startVal )
    1/$startVal--
    func2 $startVal
}
function func2
{
    param ( $startVal )
    1/$startVal--
    func3 $startVal
}
function func3
{
    param ( $startVal )
    1/$startVal--
}
func1 $startVal

When I run this script, depending on the value of my argument, the script will run or fail:

PS# c:\temp\test-stacktrace 5
0.2
0.25
0.333333333333333
PS# c:\temp\test-stacktrace1 2
0.5
1
Attempted to divide by zero.
At c:\temp\test-stacktrace1.ps1:18 char:7
+     1/$ <<<< startVal--

The message is ok - it tells me that I had a problem on the appropriate line in the script, but I don't know how I got there by looking at the message.  What I would really like to see is both the error and the way I got there.  Here are some examples of what I want to see:

This example is the normal behavior
PS# c:\temp\test-stacktrace2 3
0.333333333333333
0.5
1

Notice that I see the functions that I called on the way to this error - This way I can see the path of woe that generated the error - which means I have a much better chance of actually fixing the problem. 

Here's another example of what happens when an error occurs sooner in the stack, notice that we only see func1 and func2 calls:
PS# c:\temp\test-stacktrace2 1
1
func2 : Attempted to divide by zero.
At c:\temp\test-stacktrace2.ps1:17 char:10
+     func2  <<<< $startVal
At c:\temp\test-stacktrace2.ps1:23 char:42+     trap { write-error $_; get-stacktrace  <<<< }
At c:\temp\test-stacktrace2.ps1:17 char:10+     func2  <<<< $startVal
At c:\temp\test-stacktrace2.ps1:36 char:6+ func1  <<<< $startVal
At line:1 char:25+ c:\temp\test-stacktrace2  <<<< 1

And finally what happens when an error occurs right away, notice that we only see func1 in the stack:
PS# c:\temp\test-stacktrace2 0
func1 : Attempted to divide by zero.
At c:\temp\test-stacktrace2.ps1:36 char:6
+ func1  <<<< $startVal
At c:\temp\test-stacktrace2.ps1:15 char:42+     trap { write-error $_; get-stacktrace  <<<< }
At c:\temp\test-stacktrace2.ps1:36 char:6+ func1  <<<< $startVal
At line:1 char:25+ c:\temp\test-stacktrace2  <<<< 0

So, here's the code - and a brief discussion follows:

param ( $startVal )
function get-stacktrace
{
    trap { continue }
    1..100 | %{
        $inv = &{ gv -sc $_ myinvocation } 2>$null
        if ($inv) { write-host -for blue $inv.value.positionmessage.replace("`n","") }
        }
    exit
}
function func1
{
    param ( $startVal )
    trap { write-error $_; get-stacktrace }
    1/$startVal--
    func2 $startVal
}
function func2
{
    param ( $startVal )
    trap { write-error $_; get-stacktrace }
    1/$startVal--
    func3 $startVal
}
function func3
{
    param ( $startVal )
    trap { write-error $_; get-stacktrace }
    1/$startVal
}
# Main
func1 $startVal

Notice the addition of the "get-stacktrace" function:

function get-stacktrace
{
    trap { continue }
    1..100 | %{
        $inv = &{ gv -sc $_ myinvocation } 2>$null
        if ($inv) { write-host -for blue $inv.value.positionmessage.replace("`n","") }
        }
    exit
} 

This function takes advantage of the fact that the PowerShell scoping rules allow you to inspect variables in different scopes from your current scope.  This isn't available via syntax, but it is available via the get-variable cmdlet (aliased to gv).  So our little get-stacktrace function just drills down our scopes looking for the myInvocation property which has the information about what line on the script we're on.  There are some other things that are going on.  The trap statement assures me that if I get any terminating errors that I ignore them and I've placed the call of gv in a script block - this allows me to really throw away any messages that get-variable may throw that aren't terminating errors.   Lastly, I want to be sure that my message is on a single line, so I replace the carriage returns with empty strings.

Notice also that each function now has a trap statement.  I think that this is generally good practice regardless, but these do two things.  First they write the error and then call the get-stacktrace function.  We need to write the error because the get-stacktrace function is going to exit, so if we didn't have this write-error we wouldn't actually see what the error was, just the stack trace which isn't enough info.

So, if you've got a complicated script and you would really like to discover how you got where you are, I hope this little bit of script will help!

Jim

As we were developing PowerShell, we knew that we wanted to provide a capability for searching through the help. Unfortunately, we don't always get to everything, and this is one of those things that we couldn't get to.  However, I still sometimes need to search through the help, so I created this little function to do the search.  It searches through the conceptual topics for the string for which I'm looking and with the switch parameter "-all", I search through the descriptions of the cmdlet help as well.

Like most things in PowerShell, it turns out to be pretty simple.  Here's how I would look for help that has the word "process" in it, I use -all to retrieve cmdlet help in addition to the conceptural (about*) topics. 

PS> search-help process -all
 
HelpTopic                  Reference
---------                  ---------
about_arithmetic_operators The command then processes the parameters as it w...
about_array                .NET Framework. For example, the objects that Get...
about_assignment_operators current process. For example, the following comma...
about_automatic_variables  Contains objects for which an error occurred whil...
about_commonparameters     the command during processing. This variable is
about_environment_variable system path, the number of processors used by the...
about_filter               processes that begin with the letters a through m...
about_foreach              displays any processes whose working-set (memory ...
about_function             filters. The primary difference between the two i...
about_location             As a result, all commands are processed from this...
about_logical_operator     When PowerShell processes this statement, it eval...
about_object               receives the objects from the first command, proc...
about_operator             fact that PowerShell processes operators in a ver...
about_parsing              When processing a command, the PowerShell parser ...
about_pipeline             down the pipeline to the second command. The seco...
about_provider             Alias                ShouldProcess               ...
about_quoting_rules        is passed to the command for processing. Consider...
about_shell_variable       example, the $PID variable stores the process ID ...
about_signing              export process.
about_switch               The keyword "break" indicates that no more proces...
about_wildcard             in order to return specific results. The process ...
default                    get-help get-process   : Displays help about the ...
ForEach-Object             Performs an operation against each of a set of in...
Where-Object               Creates a filter that controls which objects will...
Get-Process                Gets the processes that are running on the local ...
Stop-Process               Stops one or more running processes.
Set-Content                Writes or replaces the content in an item with ne...
Export-Csv                 Creates a comma-separated values (CSV) file that ...
Sort-Object                Sorts objects by property values.
Get-TraceSource            Gets the Windows PowerShell components that are i...

Here’s the search-help script - as you can see, it's just a few lines.   The interesting bit is the use of Select-Object.  With Select-Object, I create custom objects from both about* help and cmdlet help.  Select-Object allows me to specify which properties I want, but it also allows me to "rename" the property.  This way I can take two disparate bits of information (the bits I get back from Select-String and the bits I get out of the help object) and create objects that will act consistently regardless of their origin.

function Search-Help
{
   param ( $pattern, [switch]$all )
   $path = “${pshome}\about*.txt”
   Select-String -list –pattern ${pattern} –path ${path}|
    select-object @{ n="HelpTopic"; e = {$_.filename -replace ".help.txt"}},
        @{n="Reference";e={$_.line.trim()}}
   if ( $all )
   {
     Get-Help * | where-object { $_.description -match ${pattern}}|
        select-object @{n="HelpTopic";e={$_.Name}},
            @{n="Reference"; e={$_.synopsis}}
   }
}

I hope this is useful for you!

jim