Summary: Ed Wilson, Microsoft Scripting Guy, talks about adding a description to variables.

Microsoft Scripting Guy, Ed Wilson, is here. There is a “water feature” outside that keeps running and running and running. It is a bit strange, and to be honest, it makes me think that it is raining all the time. In central Florida in the summer, it is generally a safe bet that it will rain, but even when the sun is outside, without a cloud in the sky, the giant frog keeps spitting water into a pond. I don’t get it. It is not relaxing like a Zen pond, and it does not keep bugs at bay like a real frog would do. It just sits there.

Sometimes I run across things on my computer that are bit like that ceramic frog, and I just don’t get it. I see a user account and wonder, “Why was that created?” Or I see a group that causes the same question.

On the network, it is even worse, because there are multiple admins, and often a bit of turnover, so no one knows why something was created. Unfortunately, the old technique of “delete it and see who complains” does not work for today’s fast-paced environments. I mean, who in their right mind wants to create additional work for themselves.

And unfortunately, “see who complains” might not complain for several months—in which time you forget what you deleted in the first place. So it means hours of troubleshooting (because if I really knew the app in the first place, I would know what the "thing" I was getting ready to delete would do).

Luckily, with Windows PowerShell, I can fix some of that.

Add descriptions to global variables

In my profile last week, I added two variables that I want to always be available to me. These are global variables (meaning I can use them in functions, modules, and the like), and I really don’t want them changed. In fact, the reason I created them was so that I would have a consistent environment.

But unfortunately, when I created them, I did not ensure any of that. To make matters worse, I did not even document why I was creating the variables in the first place.

Luckily, I can easily fix that by adding various parameters of from the New-Variable cmdlet. I am often asked why we have a New-Variable cmdlet when I can create a variable by simply making an assignment to the variable, for example:

$a = 1

And why do we have the New-Variable cmdlet when I can create a new variable by adding it to the variable drive like this:

PS C:\> New-Item -Name b -Value 2 -Path variable:

Name                           Value

—-                           —–

b                              2

PS C:\> $b

2

Both of these techniques work fine if I am not concerned about adding things like a description, or scope, or whether it is Read-only. I can assign the additional properties to a variable by using the Set-Variable cmdlet. As shown here, if I do not set these additional properties, the only the name and value are assigned:

PS C:\> $a = 1

PS C:\> Get-Variable a

Name                           Value

—-                           —–

a                              1

PS C:\> Get-Variable a | fl *

Name        : a

Description :

Value       : 1

Visibility  : Public

Module      :

ModuleName  :

Options     : None

Attributes  : {}

When I use Set-Variable to add a description, I can pick it up with the Get-Variable cmdlet:

PS C:\> Set-Variable a -Description "my variable"

PS C:\> Get-Variable a | select name, description

Name                                                        Description

—-                                                        ———–

a                                                           my variable

Note  When using Get-Variable or Set-Variable, I do not use the dollar sign ( $ ) in my variable name.

Include the description and options

As a best practice, I should include the description and options for my variables when I create them in my profile. In this way, I can easily find them. In fact, if I use the same description or the same words in my description, I will be able to find my specific profile-created variables. Here are the changes I make to my two variables in my profile:

#Variables

New-Variable -Name doc -Value "$home\documents" `

   -Description "My documents library. Profile created" `

   -Option ReadOnly -Scope "Global"

if(!(Test-Path variable:backupHome))

{

 new-variable -name backupHome -value "$doc\WindowsPowerShell\profileBackup" `

    -Description "Folder for profile backups. Profile created" `

    -Option ReadOnly -Scope "Global"

}

When I close my Windows PowerShell console, and open it up again, the changes take effect. I can now find my profile-created variables easily. This is shown here:

PS C:\> (Get-Variable).where({$_.description -match 'profile created'})

Name                           Value

—-                           —–

backupHome                     C:\Users\ed\documents\WindowsPowerShell\profileBackup

doc                            C:\Users\ed\documents

I can now pipe the output to the Format-List cmdlet and see the additional information. This is shown in the following image:

That is all there is to using a variable description. Join me tomorrow when I will talk more about Windows PowerShell profiles.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy