Essential PowerShell: Know your system variables

By default PowerShell v1.0 comes with 44 variables preinstalled.  Some of these variables are used to configure the maximum number of objects that PowerShell supports, others are used to configure output preferences for scripts, and there are more with many other purposes.  As a script author, it is very useful to understand what the variables are used for so that you can take advantage of them in your scripts.

Fortunately, the wonderful folks at Microsoft who created PowerShell embedded tons of help documentation about PowerShell directly within the shell.  So learning what variables are used for is simple as long as you know how to get the information (which isn’t always that simple for newcomers).

Here’s a useful one-liner that can be used to produce a detailed list of all PowerShell variables.  The output includes the variable name, type, description, value, and options set on the variable.  It also includes a custom member called DisplayValue which is a more detailed view of the data that the variable contains.  Here’s the one-liner, split across multiple lines to improve readability:

Get-ChildItem -Path Variable: `
       | Add-Member `
              -Name Type `
              -MemberType ScriptProperty `
              -Value { $this.GetType().FullName } `
              -PassThru `
       | Add-Member `
              -Name DisplayValue `
              -MemberType ScriptProperty `
              -Value { (Get-Variable -Name $this.Name -Scope 1 -ValueOnly | Format-List -Property * | Out-String).Trim("`r`n") } `
              -PassThru `
       | Sort-Object -Property Name `
       | Format-List -Property Name,Type,Description,Value,DisplayValue,Options `
       | Out-Host -Paging

For the most part, the output of this one-liner provides enough of a description for each variable to explain what it is used for.  Some variables that don’t have descriptions are easily understood by looking at their DisplayValue.  A few might be confusing though.  The $ variable (which you would use in your script as $$) contains the last token in the last command that was run.  The ^ variable ($^ in your script) contains the first token in the last command that was run.  The error variable ($error) contains the history of errors encountered during the current PowerShell session.  You can clear this history at any time by running the $error.Clear() command.

If you are authoring a PowerShell extension (an extension may be a PowerShell snapin, a set of functions, PowerShell scripts, etc) and if your extension adds additional global variables that will be useful to consumers of your extension, I strongly encourage you to provide enough details in the variable description that PowerShell continues to be a self-documenting scripting environment.  The self-documenting nature of PowerShell is unique and incredibly beneficial to PowerShell users.  Please continue to promote this through your own PowerShell work.

If there are any system variables that you are having a hard time with, or that you feel I should have described in more detail in this post because they just aren’t intuitive, feel free to let me know in the comments and I’ll help you out as best as I can.

Kirk out.

Technorati Tags: , , ,

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s