{"id":12431,"date":"2011-10-11T00:01:00","date_gmt":"2011-10-11T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2011\/10\/11\/use-powershell-parameter-attributes-to-avoid-errors\/"},"modified":"2011-10-11T00:01:00","modified_gmt":"2011-10-11T00:01:00","slug":"use-powershell-parameter-attributes-to-avoid-errors","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/use-powershell-parameter-attributes-to-avoid-errors\/","title":{"rendered":"Use PowerShell Parameter Attributes to Avoid Errors"},"content":{"rendered":"

Summary:<\/strong> Use Windows PowerShell parameter attributes to avoid input errors in a function.<\/p>\n

 <\/p>\n

Microsoft Scripting Guy Ed Wilson here. This week is great. The Scripting Wife and I are enjoying meeting Windows PowerShell luminaries. I am working with a group of IT pros to help them to learn Windows PowerShell, and the weather has been wonderful. I hope to get some  ime to head out to a really neat hardware store and gaze longingly at the hand planes.<\/p>\n

Anyway, one of the students, who reads the Hey, Scripting Guy! Blog on a daily basis, commented that he thought that the script in yesterday’s Cool PowerShell Game Teaches Cmdlet Names<\/a> post could stand a bit of improvement. I definitely agree.<\/p>\n

In today’s article, I am going to modify the script from yesterday and turn it into a function. In addition, I am going to add parameter validation. For example, in yesterday’s script it would be possible to get a divide-by-zero error if you ran the script with the wrong number for the  ount. In addition, it is possible to receive an output of a continuous solid line if you were to change the input value to a one. To make it easy to use the code and to modify the difficulty of the puzzle, I will include a command-line parameter to allow for quickly changing the difficulty. The complete New-CmdletPuzzle <\/b>function is shown here.<\/p>\n

function New-CmdletPuzzle<\/p>\n

{<\/p>\n

 Param(<\/p>\n

  [Parameter(Position=0,<\/p>\n

             HelpMessage=”A number between 2 and 7″)]<\/p>\n

  [alias(“Level”)]<\/p>\n

  [ValidateRange(2,7)]<\/p>\n

  [int]$difficulty = 4<\/p>\n

 ) #end param<\/p>\n

 $array = @()<\/p>\n

 $array = Get-Command -CommandType cmdlet |<\/p>\n

 ForEach-Object { $_.name.tostring() }<\/p>\n

 <\/p>\n

 Foreach($cmdlet in $array)<\/p>\n

 {<\/p>\n

  $rndChar = get-random -InputObject ($cmdlet.tochararray()) `<\/p>\n

           -count ($cmdlet.length\/$difficulty)<\/p>\n

  foreach($l in $rndchar)<\/p>\n

  {<\/p>\n

   $cmdlet = $cmdlet.Replace($l,”_”)<\/p>\n

  }# end foreach l<\/p>\n

  $cmdlet<\/p>\n

 } #end foreach cmdlet<\/p>\n

}
#end function New-CmdletPuzzle<\/p>\n

 <\/p>\n

The two changes I made to yesterday’s script convert the inline script to a function and add a command-line parameter. To convert the script to a function, all I needed to do was use the function<\/b> <\/i>keyword, provide a function name, and place the code in a pair of braces (curly  rackets).<\/p>\n

The param<\/b> <\/i>keyword tells the function to expect a value from the command line. I use the parameter<\/b> <\/i>attribute to create a parameter in position 0 and assign a helpmessage<\/b> <\/i>value as well. Here is the first part of the param<\/b> <\/i>statement:<\/p>\n

Param(<\/p>\n

  [Parameter(Position=0,<\/p>\n

             HelpMessage=”A number between 2 and 7″)]<\/p>\n

In addition, I decided to create an alias for the input parameter. To do this I use the alias<\/b> <\/i>attribute:<\/p>\n

[alias(“Level”)]<\/p>\n

The most important attribute for my New-CmdletPuzzle <\/b>is the validaterange<\/b> <\/i>attribute. It limits the permissible values for the function. For this function, I do not want anyone to use a level less than 2 or greater than 7. To do this, I specify my minimum and maximum range as  rguments to the attribute. Here is validaterange<\/b> <\/i>attribute.<\/p>\n

[ValidateRange(2,7)]<\/p>\n

If I supply a value to the function that is outside the allowed range specified by the validaterange<\/b> <\/i>attribute, a nonterminating error occurs. A sample error is shown here:<\/p>\n

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

The last thing I do is specify a default value for the difficulty <\/i>parameter. In addition, I use a type constraint to ensure the value is an integer. This line of code is shown here:<\/p>\n

[int]$difficulty = 4<\/p>\n

The entire parameter section is shown here:<\/p>\n

Param(<\/p>\n

  [Parameter(Position=0,<\/p>\n

             HelpMessage=”A number between 2 and 7″)]<\/p>\n

  [alias(“Level”)]<\/p>\n

  [ValidateRange(2,7)]<\/p>\n

  [int]$difficulty = 4<\/p>\n

 ) #end param<\/p>\n

That is it. When I run the function with no input parameters, it runs with a default value of 4. If I made the parameter mandatory, the function would ignore the default value and prompt. But when I have a default value assigned, it is always used unless it is overridden, so the  arameter is essentially mandatory because a value is always used for the parameter. I can use the level<\/b> <\/i>alias, and pipe the output as I would a regular Windows PowerShell cmdlet. The command and associated output for this are shown in the following image.<\/p>\n

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

The file created by the previous command is shown in the following image.<\/p>\n

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

Well, that is enough playing around for one day. Join me tomorrow as I continue to explore string manipulation, and as I continue, my progression from script to function to…see you tomorrow. Until then, have a great day.<\/p>\n

 <\/p>\n

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

Ed Wilson, Microsoft Scripting Guy<\/b><\/p>\n

 <\/p>\n

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

Summary: Use Windows PowerShell parameter attributes to avoid input errors in a function.   Microsoft Scripting Guy Ed Wilson here. This week is great. The Scripting Wife and I are enjoying meeting Windows PowerShell luminaries. I am working with a group of IT pros to help them to learn Windows PowerShell, and the weather has […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[69,3,4,21,45],"class_list":["post-12431","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-functions","tag-scripting-guy","tag-scripting-techniques","tag-string-manipulation","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Use Windows PowerShell parameter attributes to avoid input errors in a function.   Microsoft Scripting Guy Ed Wilson here. This week is great. The Scripting Wife and I are enjoying meeting Windows PowerShell luminaries. I am working with a group of IT pros to help them to learn Windows PowerShell, and the weather has […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/12431","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\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=12431"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/12431\/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=12431"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=12431"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=12431"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}