Prof. Powershell

Can You Describe the Variable?

Variables already come with descriptions, but you can also provide more clarity to those descriptions as needed.

• By Jeffery Hicks
• 04/02/2012

In Windows PowerShell, we typically think of variables as simple place holders or containers for other objects, as in this example:

PS C:\> $dc="jdhit-dc01"
PS C:\> $dc
jdhit-dc01
PS C:\> $dc.getType().name
String

The variable, $dc is a string the variable itself is meaningless. Well, that's not quite true. If we use the Get-Variable cmdlet, we can see there is more than meets the eye:

PS C:\> Get-Variable dc | select *

Name        : dc
Description :
Value       : jdhit-dc01
Visibility  : Public
Module      :
ModuleName  :
Options     : None
Attributes  : {}

We can even verify that this is a special kind of object:

PS C:\> (Get-Variable dc).GetType().Name
PSVariable

One property that might come in handy is the variable description. When you run Get-Variable you see a big list, most of which you may have no clue about. However, many of the PowerShell variables have been described:

PS C:\> Get-Variable | where {$_.Description} | Select Name,Description

Name                  Description
----                  -----------
?                     Execution status of last command.
comp                  The default computername to connect to
ConfirmPreference     Dictates when confirmation should be...
ConsoleFileName       Name of the current console file.
DebugPreference       Dictates action taken when an Debug ...
...

Or you can look at them individually:

Description
-----------
The ShellID identifies the current shell. This is used by #Requires.

Finally, you can add descriptions to your own variables. This could be quite useful if you have a script that is defining some global variables or if you define something in your profile. Think of the description as mini-documentation. You can define the variable first:

PS C:\> $dc="CHI-DC01"

Then later, you can go back and add the description using Set-Variable:

PS C:\> Set-Variable dc -Description "The default domain controller"

Set-Variable doesn't get sent right to the pipeline unless you use -Passthru. Or you can create the variable and description at the same time with New-Variable:

PS C:\> New-Variable -Name doy -Value (Get-Date).DayOfYear -Description "The current day of the year"

Later, anyone can look at the variable and discover its purpose:

PS C:\> get-variable doy | format-list name,value,description

Name        : doy
Value       : 55
Description : The current day of the year

So the next time you are puzzled by a variable, see if it has been described and consider describing your own long-term variables.