I like how my assumption that Part IV of Write Functions, Not Scripts wouldn’t be a worthy contender to the previous three parts (P1, P2, P3). Seriously, I didn’t think it compared, and if I’m not mistaken, it’s been the most popular post in this series thus far.

It’s a simple concept though: short, simple, single-purposed is sufficient for writing functions. Think small, easier to troubleshoot code. Say you have five functions that run in succession — one right after the other. The point at which things break will likely remove 4 of the 5 functions as areas you even need to review. That means you’re troubleshooting a fifth of the code the scriptwriter would have to review. Functions are a no-brainer. Well, they ought to be, anyway.

Time for some more thoughts on why functions over scripts. Hey, ever see one of these in a script?

$UserCount = 10
# When using in production, please comment out the above line.
# Then, uncomment the below line.
# $UserCount = 20

This is why we have a Read-Host. This, would be better.

$UserCount = Read-Host -Prompt 'Enter the preferred User Count'

Before blogging was my main gig, you might find me scouring various forums more often and helping others (and secretly learning more, too). A good number of people were getting their input via the Read-Host cmdlet. It’s nice and all, but by itself, there’s a bit of mystery as to what a user might enter. While I’m expecting 10, or 20, I could end up with all kinds of obnoxious values.

$UserCount = Read-Host -Prompt 'Enter the preferred User Count'
Enter the preferred User Count: DogCatMom5
# Huh!?

Inside a Do loop construct, we can better control the acceptable input.

Do {
    $UserCount = Read-Host -Prompt 'Enter the preferred User Count'
} Until ($UserCount -eq 10 -or $UserCount -eq 20)
Enter the preferred User Count: 1
Enter the preferred User Count: 2
Enter the preferred User Count: 3
Enter the preferred User Count: 4
Enter the preferred User Count: 5
Enter the preferred User Count: 6
Enter the preferred User Count: DogCatMom5
Enter the preferred User Count: 10

But there’s still a better way. Function’s allow for parameters and so, as absolutely as best as we can, we need to separate our lives — and our function writing — from Read-Host. If it’s ever in a function, and I’ll agree that it can happen, there ought to be really great reason as to why. We’ll close out today’s post with a simple function example that uses parameters. This is such a huge benefit.

Function Test-ParamsInAFunction {
    Param (
        $Number,
        $Letter
    )
 
    If ($Number -and $Letter) {
        Write-Output -InputObject "You have entered the number $Number, and the letter $Letter."
    } ElseIf ($Number) {
        Write-Output -InputObject "You have entered the number $Number."
    } ElseIf ($Letter) {
        Write-Output -InputObject "You have entered the letter $Letter."
    } Else {
        Write-Output -InputObject "You have not entered a number or letter."
    }
}

Test-ParamsInAFunction
Test-ParamsInAFunction -Number 5
Test-ParamsInAFunction -Letter X
Test-ParamsInAFunction -Number 10 -Letter D

You have not entered a number or letter.
You have entered the number 5.
You have entered the letter X.
You have entered the number 10, and the letter D.

Functions can handle run time delivered values. There’s no more opening up scripts and adding and removing static comments and variable assignments. There’s no using Read-Host inside our scripts and functions (unless, again, you’ve got a really great reason), even if, you’re using a language construct to protect the acceptable values. Before we full on wrap up, let me show you how to make a parameter only accept the 10 and 20 values.

Function Test-ParamsInAFunction {
    Param (
        [ValidateSet(10,20)]
        $Number
    )
    ...
}

See you again next time.

If you haven’t been with us in the previous three posts (this one, this one, and this one), we’ve been discussing why functions, over scripts. If you haven’t already, it’s time to change your mindset.

The idea is to write small, concise, single-purposed, chunks of code. We call these functions. What we don’t need… is long, overly complex, multi-purposed scripts. We’ve got to stop the scripting mentality. You know the one… you’re writing a script and your next thought is, now I need to do this…and then you write lines and lines beneath that which has already written. Now you have a multipurpose script and no clear end in sight.

It’s pretty simple: the longer the script, the more pieces to troubleshoot and when adding new features, the more potential areas to make errors. You’re creating more confusion. The whole process of script writing can easily and quickly get away from you. In one moment you add one solution, and then in another, you add more solutions to other problems you want to solve, and it’s all in a single file. Ugh.

That was it. Start writing in a single purposed methodology. Even if you’re not going not to write in functions beginning tomorrow morning, like you should, start scripting in single purposed scripts. If you need it, make that your first step. I’m not writing for my own benefit this evening; I’m writing for yours. You’re going to love being a function writer. You just need to make this the week you start, if you haven’t already. Here, I’ll get you started:

Function Get-ItDone {
    # Add your code here.
}
Get-ItDone

Alright, see you next time.

First off, I have to say, the first two posts in this series have been very successful. Nearly 200 visitors on a Saturday and then a Sunday, too — that’s unheard of during the weekend. And to think, these two posts: Part I and Part II, have felt like some of the most distracted and unpredictable writing of mine to date, and I’ve been at this for almost four years straight, without a missed month.

Okay, to continue with a distraction, in Write Functions, Not Scripts — Part II, I showed a picture of the fog on my cul-de-sac in Tucson, AZ (the desert) last Friday. Here’s that picture now. That fog, is not typical for us. Maybe it happens once a year.

I mentioned that I’d include the typical view, and so here’s a picture from Saturday — just one day later. And that’s, what it normally looks like around here.

Moving along, as if there’s a PowerShell related topic at hand. So, here’s one reason for functions, over scripts: it’s variables. Let’s move out the fog, and explain.

When we’re developing scripts, we often create variables and assign them values at the top of our code. Normal stuff. The problem is that when we go to execute the script a second (or third, or fourth) time, the variables in our script have already been assigned a value, and that may make our results incorrect. This can lead to confusion and wasted time, incorrect results, and extra lines of unnecessary commands to initialize variables. Stop initializing, and then re-initializing, variables.

Let’s take a look at an example.

In each pass though the below ForEach-Object cmdlet, we set the $User variable to my name with the number of the current pass at the end. Then, we increase the $Count variable by 1. Take a look at the below results. Everything looks perfect. My name includes the current iteration through the loop, and the count matches, as it should.

1..5 | ForEach-Object {
    $User = "tommymaynard$_"
    $Count++

    "Count: $($Count)"
    "User: $User"
}

Count: 1
User: tommymaynard1
Count: 2
User: tommymaynard2
Count: 3
User: tommymaynard3
Count: 4
User: tommymaynard4
Count: 5
User: tommymaynard5

Now, let’s run it again.

1..5 | ForEach-Object {
    $User = "tommymaynard$_"
    $Count++

    "Count: $($Count)"
    "User: $User"
}

Count: 6
User: tommymaynard1
Count: 7
User: tommymaynard2
Count: 8
User: tommymaynard3
Count: 9
User: tommymaynard4
Count: 10
User: tommymaynard5

We didn’t want to continue to increase the $Count variable past five, but because we’re scripting, we did it anyway. Writing something like this would required a Remove-Variable, or Clear-Variable command, when the final loop was done. Annoying, and without it, when you’re scripting, you’re going to have inaccuracies.

With functions, we don’t ever need to reinitialize variables to their default values. And of course, we don’t need to remove them, or clear them, before our code is run a second, or third time. This isn’t to say you’ll never change the value of a variable inside a function, it’s to say that variables in a function don’t typically exist before, or after, a function is executed.

Function Show-CountAndUser {
    1..5 | ForEach-Object {
        $User = "tommymaynard$_"
        $Count++

        "Count: $($Count)"
        "User: $User"
    }
}

PS > Show-CountAndUser
Count: 1
User: tommymaynard1
Count: 2
User: tommymaynard2
Count: 3
User: tommymaynard3
Count: 4
User: tommymaynard4
Count: 5
User: tommymaynard5

Okay, that was the first execution. One through five: it looks good. And here’s, the second execution.

PS > Show-CountAndUser
Count: 1
User: tommymaynard1
Count: 2
User: tommymaynard2
Count: 3
User: tommymaynard3
Count: 4
User: tommymaynard4
Count: 5
User: tommymaynard5

Ah, perfect! Write functions, and stop worrying about having to set, and reset, variables. Use the variable scope provided by functions — it wants to help you. It’s one reason for functions over scripts. Back again later.

Part IV is now available.

In Part I of this series, I was supposed to begin offering reasons as to why someone would want to stop writing scripts, and start writing functions. I got a bit distracted. Instead, we discussed making an easy, and mostly meaningless, function. The reasoning for this, was because I get this feeling that moving from a script writer to a function writer can be a unsettling endeavor for some. I liken it to bicycle training wheels. They’re so easy, and reliable. It’s just not until you take them off, and get your balance, that you suddenly realize all the things they actually kept your from doing. Learn to balance this bike, and then you can start jumping off your makeshift ramp in the middle of the cul-de-sac, instead of just riding around it.

Speaking of cul-de-sacs, here’s another distraction. It’s our view from Friday morning. That’s not what it usually looks like in Tucson, AZ. Fog is really, really rare. In one of these follow ups, I’ll be sure to include our typical desert view, uninterrupted by “winter” type weather events.

Functions can get advanced, sure, but once you know a few things about them, you’ll never look back. You’ll continue to learn more and more about them. There’s a whole new level of being proud of your work, as you transition to function writing. You’re going to sleep better at night knowing you’ve written five singled-purposed functions vs. that one long script you secretly hate to open and troubleshoot. Maybe, it’s not even a secret.

Look, at the end of the day, a function is nothing more than a scriptblock you can invoke by entering its name. You run commands all the time, maybe even a few, one right after the other. Now you can do the same thing, but by only typing a function’s name and pressing enter.

Let’s assume there’s was a point in time I often wanted to know the date, the system drive letter, the current PowerShell host major version, and return a random number between 1 and 20. If I grew tired of doing this manually, I could create a function to do this for me. It’s not likely this would ever be useful outside this post, but it certainly helps highlight what using a function does. It’s essentially four commands in one. Easy.

Function Start-RandomStuff {
    "Date : $(Get-Date)"
    "System Drive : $env:SystemDrive"
    "Host Major Version : $((Get-Host).Version.Major)"
    "Random Number (1-20) : $(Get-Random -Minimum 1 -Maximum 20)"
}
PS > Start-RandomStuff
Date : 02/13/2018 22:58:00
System Drive : C:
Host Major Version : 5
Random Number (1-20) : 3

Think of a function as a wrapper. You can wrap the execution of various (related) commands by running one command. This isn’t to say our example ran related commands so much; it really didn’t. The point is to keep in mind that functions should be single purposed. They’re tight, short, and to the point. If you start wondering if you’re adding too much procedural code to your function, you probably already have. If you keep adding to the function you’re currently writing, then you better be able to explain why.

I’ve done it again! I haven’t really hit those reasons as to why functions, over scripts. Or perhaps I have a little. I do have some specifics topics, and for the second time, let’s hope the next part of this series, gets serious. There really are a few specific things I want to share — reasons why functions are all you want to be writing.

Back soon. And hopefully, with a non winter picture of the cul-de-sac.

Part III is now available.

Seriously. If you’re not writing PowerShell functions yet, it’s. time. to. begin. It’s been time.

I’ve decided I should begin to compile some potentially influencing reasons why you’d want make this move. Additionally, I also thought that maybe we need to first, give those out there, that haven’t been doing it, a little push by example. Before we get to some reasons why functions over scripts, do this. Next time you start to write a PowerShell solution, just type what’s been written in the below example.

Function <Verb>-<SingularNoun(s)InPascalCase> {

}

Now, in place of <Verb>, enter an approved verb from the results of the Get-Verb cmdlet. As of today, there’s 98 approved verbs in Windows PowerShell 5.1, and an even 100 in PowerShell 6.0.*

PS > Get-Verb

[/plain]
Verb Group
—- —–
Add Common
Clear Common
Close Common
Copy Common
Enter Common
Exit Common
Find Common
Format Common
Get Common
Hide Common
Join Common
Lock Common
…
[/plain]

Once you’re done replacing <Verb> with your approved verb, replace <SingularNoun(s)InPascalCase> with a singular noun, or set of singular nouns in pascal case. Here’s some examples: Set-ADDisabledUser, Test-KMSServer, Get-TimeZone, Read-Log, etc. We don’t need plural nouns even if your function is going to run against multiple users, servers, timezones, or logs.

Let’s say you chose Get-TimeZone. Before we actually begin to write timezone related code, let’s make sure our function actually works. Copy and paste the below function to the ISE, or Visual Studio Code, or even the ConsoleHost, and press F8 or Enter (depending on which host you chose). What happens?

Function Get-TimeZone {
    '---->Testing our Get-TimeZone function.<----'
}

Nothing, right? It didn’t even work!

That’s not exactly true. Something did happen. Running the code that makes up a function, doesn’t invoke, or execute, the function. It adds it to memory, or, it adds it to the current PowerShell session. It gets it ready to be run, but how do we know? Let’s check our Function PSDrive. In this example, we’ll see the full process of the function not yet existing, it being created, and then it being available to use.

Here, we’ll verify the function doesn’t yet exist.

Get-Item -Path Function:\Get-TimeZone
Get-Item : Cannot find path 'Function:\Get-TimeZone' because it ...

Here, we’ll add the function to our session/memory.

Function Get-TimeZone {
    '---->Testing our Get-TimeZone function.<----'
}

And here, we’ll verify that it does, now exist.

Get-Item -Path Function:\Get-TimeZone

CommandType     Name                     Version    Source
-----------     ----                     -------    ------
Function        Get-TimeZone

Since it’s now available, let’s try it out.

PS > Get-TimeZone
---->Testing our Get-TimeZone function.<----

A function has a name that we can use to run its included code. The thing is, the code (our function) has to have been defined, or created, before we try and use it. Simple. So, before a function can be used… it must be loaded, or added to memory. Keep all of this in mind.

I want to show one other little secret that’s going to be helpful as you transition to using and writing functions. I know, I know, we were supposed to discuss why you want to use functions, not how to use them. I think it’s important to know a couple things before we really get started, and thus the minor derailment on today’s post. When we get back next time, we’ll immediately jump into the reasons to use functions.

Let’s say we have a file on our Desktop called MyFunctions.ps1. And, let’s say it contains three functions, like this:

Function Test-One {
    'This is the Test One function.'
}
Function Test-Two {
    'This is the Test Two function.'
}
Function Test-Three{
    'This is the Test Three function.'
}

How do we get these functions into our session!? They’re in a file… In a PowerShell host program, perhaps the ConsoleHost, dot source the file as in the below example. You can use either the full path, or navigate to the Desktop first, and just dot source the file by itself (no path). But what’s dot source, right? It’s a dot. Seriously.

PS > Get-Item -Path Function:\Test-One
Get-Item : Cannot find path 'Function:\Test-One' because it ...
PS > . C:\Users\tommymaynard\Desktop\MyFunctions.ps1
PS > Get-Item -Path Function:\Test-One

CommandType     Name                     Version    Source
-----------     ----                     -------    ------
Function        Test-One

[/powershell]
PS > Test-One
This is the Test One function.
PS > Test-Two
This is the Test Two function.
PS > Test-Three
This is the Test Three function.
[/powershell]

Had we not used the full path, we would have had to navigate to the file, and then as mentioned, dot source the file. This below example would also add the three functions to our current PowerShell session.

PS > Set-Location -Path C:\Users\tommymaynard\Desktop
PS > . .\MyFunctions.ps1

Okay, we’re done for today, and again, I’m promise we’ll go into why you want to use functions over scripts… now that you know functions aren’t even scary.

* If you’re curious which two additional approved verbs PowerShell 6.0 has over PowerShell 5.1, then take a look below to find out.

PS > ($PSVersionTable).PSVersion.ToString()
6.0.0
PS > (Get-Verb).Verb | Out-File .\Desktop\6.0Verbs.txt

PS > ($PSVersionTable).PSVersion.ToString()
5.1.14409.1012
PS > (Get-Verb).Verb | Out-File .\Desktop\5.1Verbs.txt
PS > 
PS > $Ref = Get-Content -Path .\Desktop\6.0Verbs.txt
PS > $Dif = Get-Content -Path .\Desktop\5.1Verbs.txt
PS > Compare-Object -ReferenceObject $Ref -DifferenceObject $Dif

InputObject SideIndicator
----------- -------------
Build       <=
Deploy      <=

Part II is now available!