{"id":51743,"date":"2009-12-22T00:01:00","date_gmt":"2009-12-22T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2009\/12\/22\/hey-scripting-guy-how-can-i-use-real-names-for-windows-powershell-functions\/"},"modified":"2009-12-22T00:01:00","modified_gmt":"2009-12-22T00:01:00","slug":"hey-scripting-guy-how-can-i-use-real-names-for-windows-powershell-functions","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/hey-scripting-guy-how-can-i-use-real-names-for-windows-powershell-functions\/","title":{"rendered":"Hey, Scripting Guy! How Can I Use “Real Names” for Windows PowerShell Functions?"},"content":{"rendered":"

 \"Bookmark<\/a><\/p>\n

 <\/p>\n

\"Hey,<\/p>\n

Hey, Scripting Guy! I enjoyed reading yesterday’s blog post<\/a> about working with functions. I was really interested when you were talking about using “real names” for my functions. You did not say too much about why I should do that, but I guess it makes sense. I am thinking about writing a function that reads a text file, and I am considering using the Read<\/b> verb for that. Therefore, the function would be named Read-TextFile<\/b>. What do you think?<\/p>\n

— DS<\/span><\/p>\n

\n

 <\/p>\n<\/p>\n

\"Hey,Hello DS, <\/p>\n

Microsoft Scripting Guy Ed Wilson here, I am listening to The Go-Go’s<\/a> on my Zune HD<\/font><\/a> and sipping a cup of English Breakfast tea from my new tea pot. I had not heard The Go-Go’s for a while, and the shuffle feature just brought up the song. Nice compliment to my tea. <\/span><\/p>\n

 <\/p>\n<\/p>\n

\"Image<\/p>\n

Note: Portions of today’s Hey, Scripting Guy! article are excerpted from the Microsoft Press book, Windows PowerShell 2.0 Best Practices<\/em> by Ed Wilson. This book is now available<\/font><\/a>.<\/p>\n

DS, in addition to using “approved verbs,” it is a good idea to use the verb in the same manner in which the Windows PowerShell team used it. The easy way to verify this is to use the Get-Command<\/b> cmdlet with the verb parameter. To see cmdlets that use the Read<\/b> verb, you would use the command shown here:<\/p>\n

PS C:> Get-Command -Verb read<\/p>\n

<\/font><\/font><\/span><\/p>\n

<\/p>\n

 <\/font><\/p>\n

<\/span><\/p>\n

CommandType     <\/span>Name                             <\/span>Definition<\/p>\n

<\/font><\/font><\/span><\/p>\n

———–     <\/span>—-      <\/span>                       <\/span>———-<\/p>\n

<\/font><\/font><\/span><\/p>\n

Cmdlet          <\/span>Read-Host                        <\/span>Read-Host [[-Prompt] <Object>] [-AsSecureString]…<\/p>\n

<\/font><\/font><\/span><\/p>\n

<\/p>\n

 <\/font><\/p>\n

<\/span><\/p>\n

<\/p>\n

 <\/font><\/p>\n

<\/span><\/p>\n

PS C:><\/p>\n

<\/font><\/font><\/span><\/p>\n

In reviewing the list of cmdlets that use the verb Read<\/b>, you can see there is only one cmdlet that uses the verb Read<\/b>. It is the Read-Host<\/b> cmdlet, which is used to obtain information from the command line. This would indicate that the verb Read<\/b> is not used to describe reading a file. There is no verb called Display, and the Write<\/b> verb is used in cmdlet names such as Write-Error<\/b> and Write-Debug<\/b>, both of which do not really seem to have the concept of displaying information. If you were writing a function that would read the content of a text file and display statistics about that file, you might call the function Get-TextStatistics<\/b>. <\/p>\n

By using a name such as Get-TextStatistics<\/b>, we are following the Windows PowerShell team’s examples of cmdlet names such as Get-Process<\/b> and Get-Service<\/b>. The Get<\/b> <\/i>verb includes the concept of emitting retrieved content as essential functionality. The Get-TextStatistics<\/b> function accepts a single parameter called path<\/b>. The interesting thing about parameters for functions is that when you pass a value to the parameter, you use a dash. When you refer to the value inside the function, it is a variable such as $path<\/b>. To call the Get-TextStatistics<\/b> function, you have a couple of options. The first is to use the name of the function and put the value in parenthesis. This is seen here:<\/p>\n

Get-TextStatistics(“C:fsomytext.txt”)<\/p>\n

<\/font><\/span><\/p>\n

This is a natural way to call the function, and it works when there is a single parameter. It does not work when there are two or more parameters. Another way to pass a value to the function is to use the dash and the parameter name. This is seen here:<\/p>\n

Get-TextStatistics –path “C:fsomytext.txt”<\/p>\n

<\/font><\/span><\/p>\n

You will note from the previous example that no parentheses are required. You can also use positional arguments when passing a value. In this usage, you omit the name of the parameter entirely, and simply place the value for the parameter following the call to the function. This is illustrated here:<\/p>\n

Get-TextStatistics “C:fsomytext.txt”<\/p>\n

<\/font><\/span><\/p>\n

The use of positional arguments works well when one is working from the command line and wishes to speed things along by reducing the typing load. It can be a bit confusing, and in general I tend to avoid it, even when working at the command line. This is because I often copy my working code from the console directly into a script; as a result, I would need to retype the command a second time to get rid of aliases and unnamed arguments. With the improvements in tab expansion, I feel that the time saved by using positional arguments or partial arguments does not sufficiently warrant the time involved in retyping commands when they need to be transferred to scripts. The other reason for always using named arguments is that it helps me to be aware of the exact command syntax. <\/p>\n

One additional way to pass a value to a function is to use partial parameter names. All that is required is enough of the parameter name to disambiguate it from other parameters. This means if you have two parameters that both begin with the letter “p,” you would need to supply enough letters of the parameter name that will separate it from the other parameter. This is illustrated here:<\/p>\n

Get-TextStatistics –p “C:fsomytext.txt”<\/p>\n

<\/font><\/span><\/p>\n

The complete text of the Get-TextStatistics<\/b> function is seen here:<\/p>\n

Function Get-TextStatistics($path)
{
 <\/span>Get-Content -path $path |
 <\/span>Measure-Object -line -character -word
}<\/p>\n

<\/font><\/span><\/p>\n

Between Windows PowerShell 1.0 and Windows PowerShell 2.0, the number of verbs grew from 40 to 60. It is anticipated that the list of standard verbs should cover 80-85 percent of administrative tasks. The new verbs are listed here:<\/p>\n

Checkpoint
Complete
Connect
Debug
Disable
Disconnect
Enable
Enter
Exit
Limit
Receive
Register
Reset
Restore
Send
Show
Undo
Unregister
Use
Wait<\/p>\n

<\/font><\/span><\/p>\n

After the function has been named, you will create any parameters the function may require. The parameters are contained within parentheses. In the Get-TextStatistics<\/b> function, the function accepts a single parameter, path<\/b>. When you have a function that accepts a single parameter, you can pass the value to the function by placing the value for the parameter inside parentheses. This command is seen here:<\/p>\n

Get-TextLength(“C:fsotest.txt”)<\/p>\n

<\/font><\/span><\/p>\n

The path “C:fsotest.txt” is passed to the Get-TextStatistics<\/b> function via the path<\/b> parameter. Inside the function, the string “C:fsotext.txt” is contained in the $path<\/b> variable. The $path<\/b> variable only lives within the confines of the Get-TextStatistics<\/b> function. It is not available outside the scope of the function. It is available from within child scopes of the Get-TextStatistics<\/b> function. A child scope of the Get-TextStatistics<\/b> is one that is created from within the Get-TextStatistics<\/b> function. <\/p>\n

In the Get-TextStatisticsCallChildFunction.ps1 script, the Write-Path<\/b> function is called from within the Get-TextStatistics<\/b> function. This means the Write-Path<\/b> function will have access to variables that are created within the Get-TextStatistics<\/b> function. This is the concept of variable scope and is an extremely important concept when working with functions. As you use functions to separate the creation of objects, you must always be aware of where the object gets created and where you intend to use that object. In the Get-TextStatisticsCallChildFunction<\/b> the $path<\/b> variable does not obtain its value until it is passed to the function. Therefore, it lives within the Get-TextStatistics<\/b> function. But because the Write-Path<\/b> function is called from within the Get-TextStatistics<\/b> function, it inherits the variables from that scope. When you call a function from within another function, variables created within the parent function are available to the child function. This is seen in the Get-TextStatisticsCallChildFunction.ps1 script. <\/p>\n

Get-TextStatisticsCallChildFunction.ps1<\/p>\n

<\/b><\/p>\n

Function Get-TextStatistics($path)
{
 <\/span>Get-Content -path $path |
 <\/span>Measure-Object -line -character -word
 <\/span>Write-Path
}<\/p>\n

Function Write-Path()
{
 <\/span>“Inside Write-Path the `$path variable is equal to $path”
}<\/p>\n

Get-TextStatistics(“C:fsotest.txt”)
“Outside the Get-TextStatistics function `$path is equal to $path”<\/p>\n

<\/font><\/span><\/p>\n

Inside the Get-TextStatistics<\/b> function, the $path<\/b> variable is used to provide the path to the Get-Content<\/b> cmdlet. When the Write-Path<\/b> function is called, nothing is passed to it. But inside the Write-Path<\/b> function, the value of $path<\/b> is maintained. Outside both of the functions, however, $path<\/b> does not have any value. The output from running the script is seen here:<\/p>\n

\"Image<\/p>\n

\n

 <\/p>\n<\/p>\n

You will then need to open and close a script block. The curly bracket is used to delimit the script block on a function. As a best practice, when writing a function I will always use the function<\/b> keyword, and type the name, the input parameters, and the curly brackets for the script block at the same time. This is seen here:<\/p>\n

Function My-Function()
{
 <\/span>#insert code here
} <\/p>\n

<\/font><\/span><\/p>\n

\n

 <\/p>\n<\/p>\n

DS, that is all there is to working with function names and function parameters. Function Week will continue tomorrow. <\/p>\n

If you want to know exactly what we will be looking at tomorrow, follow us on Twitter<\/a> or Facebook<\/a>. If you have any questions, send e-mail to us at scripter@microsoft.com<\/font><\/a> or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/p>\n

\n

 <\/p>\n<\/p>\n

Ed Wilson and Craig Liebendorfer, Scripting Guys<\/span><\/b><\/p>\n

 <\/p>\n","protected":false},"excerpt":{"rendered":"

    Hey, Scripting Guy! I enjoyed reading yesterday’s blog post about working with functions. I was really interested when you were talking about using “real names” for my functions. You did not say too much about why I should do that, but I guess it makes sense. I am thinking about writing a function […]<\/p>\n","protected":false},"author":595,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[51,3,45],"class_list":["post-51743","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-getting-started","tag-scripting-guy","tag-windows-powershell"],"acf":[],"blog_post_summary":"

    Hey, Scripting Guy! I enjoyed reading yesterday’s blog post about working with functions. I was really interested when you were talking about using “real names” for my functions. You did not say too much about why I should do that, but I guess it makes sense. I am thinking about writing a function […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/51743","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/595"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=51743"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/51743\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=51743"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=51743"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=51743"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}