{"id":235,"date":"2018-02-15T09:15:16","date_gmt":"2018-02-15T17:15:16","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/koryt\/?p=235"},"modified":"2020-04-29T10:04:36","modified_gmt":"2020-04-29T17:04:36","slug":"powershell-for-programmers-how-to-write-a-function-the-right-way","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/powershell-for-programmers-how-to-write-a-function-the-right-way\/","title":{"rendered":"PowerShell for Programmers: How to write a function the right way"},"content":{"rendered":"

Just like I mentioned in my first post<\/a>, PowerShell supports a lot of stuff that makes it pretty easy to dive in and get stuff running. The following two examples are supported in PowerShell, but not<\/em><\/strong> something you should really be doing for any reusable tool set.<\/span><\/p>\n

\n
Function MyFunction ($P1, $P2)\r\n{\r\nWrite-host $p1 -foregroundcolor cyan\r\nWrite-host $p2 -foregroundcolor Magenta\r\n}\r\n\r\nMyFunction -P1 \"hello\" -p2 \"world\"\r\n\r\nFunction MyFunction\r\n{\r\nWrite-host $args[0] -foregroundcolor cyan\r\nWrite-host $args[1] -foregroundcolor Magenta\r\n}\r\n\r\nMyFunction \"hello\" \"world\"<\/span><\/pre>\n
Putting your parameters (arguments) next to the function name in parenthesis is pretty standard in most languages, but in PowerShell it will limit your functionality. Similarly, $args will stop working for you if you add some of those more useful features, but I\u2019ll show you a way to mimic the functionality on your own later.<\/span><\/p>\n<\/div>\n
So, how should you be writing your functions? With the param() keyword:<\/span><\/p>\n
\n
Function MyFunction\r\n{\r\nparam($P1, $P2)\r\nWrite-host $p1 -foregroundcolor cyan\r\nWrite-host $p2 -foregroundcolor Magenta\r\n}<\/span><\/pre>\n
 <\/p>\n<\/div>\n
For super basic stuff, this won’t make a big difference, but for adding attributes (such as common parameters, mandatory parameters, etc) we need to use the later version. <\/span><\/p>\n
Get in the habit of using param() every time<\/strong>.<\/span><\/p>\n
\u201cWait, shouldn\u2019t they already be mandatory?\u201d<\/span><\/p><\/blockquote>\n
Not in PowerShell. Let\u2019s take a look at the syntax:<\/span><\/p>\n
\n
get-command myfunction -Syntax<\/span><\/pre>\n
 <\/p>\n<\/div>\n
\n
Myfunction [[-p1] <object>] [[-p2] <object>]<\/span><\/pre>\n<\/div>\n
Unlike most languages, by default everything is:<\/span><\/p>\n
    \n
  1. optional<\/span><\/li>\n
  2. positional<\/span><\/li>\n
  3. assigned the generic object type<\/span><\/li>\n<\/ol>\n
    I\u2019ll walk you through how we can change some of that stuff and get functions more like what we are used to, and I\u2019ll follow up in a later post with more details on what we can do with advanced functions<\/u>. <\/span><\/p>\n
    Strong Typing<\/span><\/h3>\n
    Strongly typing parameters will assign them a data type other than object in the syntax, and provide the same auto-conversion or erroring we saw in the variables section. <\/span><\/p>\n
    Function Myfunction2\r\n{\r\nparam([int]$p1, [int]$p2)\r\n\"p1 is $p1\"\r\n\"p2 is $p2\"\r\n}\r\n\r\nget-command myfunction -Syntax\r\n\r\nMyfunction2 5.5 2.5\r\n\r\nMyfunction2 \"fred\" 4<\/span><\/pre>\n
     <\/p>\n
    Default Values<\/span><\/h3>\n
    Assigning default values for parameter is easy in PowerShell. If you want something to essentially be mandatory, but have a default value if nothing else is specified we can assign it right in the param() statement.<\/span><\/div>\n
    \n
     <\/p>\n
    Function Myfunction3\r\n{\r\nparam([int]$p1=2, [int]$p2=5)\r\n\"p1 is $p1\"\r\n\"p2 is $p2\"\r\n}\r\n\r\nMyfunction3 1 2\r\nMyfunction3 -p2 2\r\nMyfunction3<\/span><\/pre>\n<\/div>\n
    <\/h3>\n
    Mandatory Parameters<\/span><\/h3>\n
    <\/div>\n
    If you want \u201cnormal\u201d mandatory parameters, we can accomplish this through .NET attributes. We\u2019ll learn about some more attributes later, but if things being optional is frustrating you right now, here is how to flag it as mandatory. Notice in PowerShell the mandatory flags will prompt the user when using it interactively instead of just failing. We\u2019ll just make $p1 mandatory here:<\/span><\/div>\n
    \n
     <\/p>\n
    Function Myfunction4\r\n{\r\nparam([parameter(Mandatory)][int]$p1,\r\n[int]$p2=5)\r\n\"p1 is $p1\"\r\n\"p2 is $p2\"\r\n}\r\n\r\nGet-command myfunction4 -syntax\r\n\r\nMyfunction4 1 2\r\nMyfunction4 -p2 2\r\nMyfunction4<\/span><\/pre>\n
     <\/p>\n<\/div>\n
    Well that\u2019s all for now, hopefully this helps you get going on your PowerShell journey and clear up why functions might look and behave a bit differently than you\u2019re used to. In my next post I\u2019ll show some more attributes we can use to build out these advanced functions and have them behave like cmdlets. <\/span><\/p>\n
    For the main series post, check back here.<\/a><\/span><\/p>\n
    If you find this helpful don’t forget to rate, comment and share \ud83d\ude42<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"
    Just like I mentioned in my first post, PowerShell supports a lot of stuff that makes it pretty easy to dive in and get stuff running. The following two examples are supported in PowerShell, but not something you should really be doing for any reusable tool set. Function MyFunction ($P1, $P2) { Write-host $p1 -foregroundcolor […]<\/p>\n","protected":false},"author":7300,"featured_media":87096,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1738,2126],"tags":[2221,2125],"class_list":["post-235","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","category-powershell_for_programmers","tag-kory-thacher","tag-koryt"],"acf":[],"blog_post_summary":"
    Just like I mentioned in my first post, PowerShell supports a lot of stuff that makes it pretty easy to dive in and get stuff running. The following two examples are supported in PowerShell, but not something you should really be doing for any reusable tool set. Function MyFunction ($P1, $P2) { Write-host $p1 -foregroundcolor […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/235","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\/7300"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=235"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/235\/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=235"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=235"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=235"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}