{"id":242,"date":"2020-05-08T18:26:24","date_gmt":"2020-05-08T17:26:24","guid":{"rendered":"http:\/\/192.168.8.14\/?p=242"},"modified":"2020-05-08T18:26:24","modified_gmt":"2020-05-08T17:26:24","slug":"tutorial-functions","status":"publish","type":"post","link":"https:\/\/www.jasonstreet.com\/?p=242","title":{"rendered":"Tutorial Functions"},"content":{"rendered":"\n

Powershell, like just about every other programming\/scripting language has functions. These functions can be simple one liners or very complicated, depending on your needs.<\/p>\n\n\n\n

A very simple function is show below.<\/p>\n\n\n

\nfunction Do-PrintHelloWorld\n{\n    Write-Host "Hello world!" -ForegroundColor Green\n}\n<\/pre><\/div>\n\n\n
This function has a name and a code block. It has no input and will only output to the screen.<\/p>\n\n\n\n
Why should I use functions.<\/h3>\n\n\n\n
<\/p>\n\n\n\n
  • You can wrap up commonly used code to save space\/typing and improve the readability of your scripts.<\/li>
  • Functions have read only access to the scripts variables. Don’t rely on this as a method to pass data to a function.<\/li>
  • Data can be passed to functions as parameters. parameters can be:
    1. Made compulsory.<\/li>
    2. Have default values set.<\/li>
    3. Can be forced to a certain type (string, int, object etc)<\/li>
    4. Can validate the incoming data.<\/li><\/ol><\/li>
    5. Can return (pass back) specific data back to the calling script.<\/li>
    6. All variables in the function are deleted when the script exits. <\/li>
    7. Variables in a function are not accessible to the console or ISE, so can be hard to debug.<\/li><\/ul>\n\n\n\n
      Using functions.<\/h3>\n\n\n\n
      Below is a slightly more complex function.<\/p>\n\n\n
      \nfunction Do-PrintStuff ($line1, $Line2 ="line2")\n{\n    Write-Host $Line1 -ForegroundColor Green\n    Write-Host $Line2 -ForegroundColor Green\n}\n<\/pre><\/div>\n\n\n
      Passing data in to a function like this is perfectly valid but not recommended. It will very quickly become hard to read. Also notice the $Line2 variable being set to “line2”. If the user does not pass a value for $Line2 it will default to “line2”.<\/p>\n\n\n\n
      The “correct” way to write the function is this.<\/p>\n\n\n
      \nfunction Do-PrintStuff \n{\n   [CmdletBinding()]\n    param(\n        [Parameter(Mandatory = $true,ValueFromPipeline=$true)] [string]$line1, \n        $Line2 = "This is line 2",\n        [Parameter(Mandatory=$false)]$Line3,\n        $Line4,\n        [Parameter()][ValidateRange(1,10)][int]$Number,\n        [Parameter()][ValidateSet("jase","bob")][string]$Name,\n        [Parameter()][ValidateScript({test-path $_})][string]$Path\n    )\n    Process{\n        Write-Host $Line1 -ForegroundColor Green\n        Write-Host $Line2 -ForegroundColor Green\n        Write-Host $Line3 -ForegroundColor Green\n        Write-Host $Line4 -ForegroundColor Green\n        Write-Host $Number -ForegroundColor Green\n        Write-Host $Name -ForegroundColor Green\n        Write-Host $Path -ForegroundColor Green\n    }\n}\n<\/pre><\/div>\n\n\n
      I now have a Parameter block.  <\/p>\n\n\n\n
      Listed are common validations I do.<\/p>\n\n\n\n
      • $Line1 is mandatory (powershell will prompt if its not set) and set to a string type, can also be piped in.<\/li>
      • $Line2 will default to “This is line 2” if not specified.<\/li>
      • $Line3 is not mandatory and not checked.<\/li>
      • $Line4 is not mandatory and not checked.<\/li>
      • $Number must be an integer and be between 1 to 10 inclusive.<\/li>
      • $Name must be a string and can only be “jase” or “bob” (and will tab complete)<\/li>
      • $Path must be a string and be a valid path. The code {test-path $_} must evaluate to true.<\/li><\/ul>\n\n\n\n
        If any of the parameter check fails you will get a helpful error and the function will not run.<\/p>\n\n\n\n
        \"\"
        Function output with valid inputs.<\/figcaption><\/figure>\n\n\n\n
        Below shows the error when the name and path parameters are invalid.<\/p>\n\n\n\n
        \"\"
        The error tells us the -name parameter is wrong.<\/figcaption><\/figure>\n\n\n\n
        The error states the name parameter is invalid. the function has not checked the path parameter.<\/p>\n\n\n\n
        Fixing the name parameter and leaving path incorrect gives us:<\/p>\n\n\n\n
        \"\"
        Error for invalid path parameter.<\/figcaption><\/figure>\n\n\n\n
        Again, the error is quite clear as it tells us the parameter and value that failed the check.<\/p>\n\n\n\n
        Getting data out of a function.<\/h3>\n\n\n\n
        Sometimes (most of the time) you will want the function to return something back to the script that called it and not output to the screen. To do that I use the return command.<\/p>\n\n\n\n
        Below is a function I have used i servile scripts.<\/p>\n\n\n\n
        I will take a test string and a number. If the length of the test string is less then the number, the function will add the required number of spaces and return a new string that is (number) charictors long. Good for column formatting.<\/p>\n\n\n
        \n<#\n   The function will take a text string and pad the end with spaces to make it $MaxSpace in length.\n   if the test string is to long the function will truncate it down to $MaxSpace - 3 in length and add ".. "\n   $testStringofLength20 = Do-FuncPadSpace $testStringOfLength10 20\n#>\nfunction Do-FuncPadSpace\n{\n    Param(\n        [Parameter(Mandatory = $true)] [string]$DisplayText,\n        [Parameter(Mandatory = $true)] [int]$MaxSpace\n    )\n\n    if ($DisplayText.length -le $MaxSpace)\n    {\n        # add spaces to text to make it the correct length\n        # I should do it with a loop but its not very readable (and didn't work)\n        $spacesToAdd = $MaxSpace - $DisplayText.length\n        if ($spacesToAdd -eq 0){}\n        if ($spacesToAdd -eq 1){$Spaces = " "}\n        if ($spacesToAdd -eq 2){$Spaces = "  "}\n        if ($spacesToAdd -eq 3){$Spaces = "   "}\n        if ($spacesToAdd -eq 4){$Spaces = "    "}\n        if ($spacesToAdd -eq 5){$Spaces = "     "}\n        if ($spacesToAdd -eq 6){$Spaces = "      "}\n        if ($spacesToAdd -eq 7){$Spaces = "       "}\n        if ($spacesToAdd -eq 8){$Spaces = "        "}\n        if ($spacesToAdd -eq 9){$Spaces = "         "}\n        if ($spacesToAdd -eq 10){$Spaces = "          "}\n        if ($spacesToAdd -eq 11){$Spaces = "           "}\n        if ($spacesToAdd -eq 12){$Spaces = "            "}\n        if ($spacesToAdd -eq 13){$Spaces = "             "}\n        if ($spacesToAdd -eq 14){$Spaces = "              "}\n        if ($spacesToAdd -eq 15){$Spaces = "               "}\n        if ($spacesToAdd -eq 16){$Spaces = "                "}\n        if ($spacesToAdd -eq 17){$Spaces = "                 "}\n        if ($spacesToAdd -eq 18){$Spaces = "                  "}\n        if ($spacesToAdd -eq 19){$Spaces = "                   "}\n        if ($spacesToAdd -eq 20){$Spaces = "                    "}\n        if ($spacesToAdd -eq 21){$Spaces = "                     "}\n        $Result = $DisplayText + $Spaces\n        return $Result\n    }else{\n        # text to long, error!\n        $Result = $DisplayText.Substring(0,$MaxSpace - 3) + ".. "\n        return $Result\n    }\n}\n<\/pre><\/div>\n\n\n
        In the above function, both if “branches” result in a string variable called $Result being populated. Once populated both “branches” end with:<\/p>\n\n\n\n
        return $Result<\/p>\n\n\n\n
        return $Result will end processing of the function and return whats after. in this case the $result variable.<\/p>\n\n\n\n
        I did not technically need the return command. I could have just had $Result on the line on its own. there is no code to be run after these lines so the function would exit anyway. But I like easy to read code so I always use the return command.<\/p>\n\n\n\n
        Calling the function would work like this.<\/p>\n\n\n\n
        $PaddedOutString = Do-FuncPadSpace -DisplayText $TestString -MaxSpace 20<\/p>\n\n\n\n
        That’s a quick look at functions.<\/p>\n","protected":false},"excerpt":{"rendered":"
        Powershell, like just about every other programming\/scripting language has functions. These functions can be simple one liners or very complicated, depending on your needs. A very simple function is show below. This function has a name and a code block. It has no input and will only output to the screen. Why should I use…<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[27],"tags":[17,13,22],"class_list":["post-242","post","type-post","status-publish","format-standard","hentry","category-tutorial","tag-function","tag-powershell","tag-tutorial"],"_links":{"self":[{"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=\/wp\/v2\/posts\/242","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=242"}],"version-history":[{"count":2,"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=\/wp\/v2\/posts\/242\/revisions"}],"predecessor-version":[{"id":248,"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=\/wp\/v2\/posts\/242\/revisions\/248"}],"wp:attachment":[{"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=242"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=242"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.jasonstreet.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=242"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}