Fun with PowerShell Enums

Introduction

This post begins a series on using Classes in PowerShell. As a first step, we will cover the use of an Enum, as enums are frequently used in combination with classes.

An Enum is a way to provide a set of predetermined values to the end user. This allows the user to pick from a finite list, and assure a value being passed into a function or class will be valid.

We’ll take a deeper look in a moment, but first let me mention that for all of the examples we’ll display the code, then under it the result of our code. In this article I’ll be using PowerShell Core, 7.2, and VSCode. The examples should work in PowerShell 5.1 in the PowerShell IDE, although they’ve not been tested there.

To run a snippet of code highlight the lines you want to execute, then in VSCode press F8 or in the IDE F5. You can display the contents of any variable by highlighting it and using F8/F5.

Basic Enum Declaration

Enum is short for enumerated value. As mentioned in the intro, it is a set of predetermined values that will ensure users of your script select a valid value required by your PowerShell code. Let’s start by defining a basic Enum.

Enum MyTwitters
{
  ArcaneCode
  ArcaneTC
  N4IXT
}

As you can see, the basic declaration is very simple. You simply use the keyword Enum followed by what you wish to name it. In the squiggly braces you list the valid values.

Here I’ve listed three of my Twitter accounts. The first is the main one I use, ArcaneCode. The second is the one I use for my company ArcaneTC (short for Arcane Training and Consulting). I use it primarily to announce new Pluralsight courses, so it doesn’t see a huge amount of use.

One of my hobbies is amateur radio, also known as ham radio. N4IXT is my FCC assigned amateur radio call sign I use to identify myself on the air. I don’t post a lot, I use it mostly to read through the latest news in the ham radio world.

Note that Enums cannot have spaces in their names, although you could use separators such as an underscore. Arcane_Code would be a valid value for an enum.

What are my valid Enum values?

You’ve now created an Enum, perhaps you’ve included it within a module you are providing to other programmers in your company. How can they retrieve a list of valid values?

Hopefully you’ve provided documentation, but it’s also easy for a user to have PowerShell return a list of values. First, make sure you have executed the code above by highlighting it and using F8 (VSCode) or F5 (PowerShell IDE) to get the Enum into memory. Then you can run the line of code below.

[MyTwitters].GetEnumNames()

Result:

ArcaneCode
ArcaneTC
N4IXT

As you can see, it simply returns a list of the values that we declared in the Enum.

Assigning an Enum to a Variable

Now we have our enum, and know what the values are. We’re now ready to use our enum in our script. Here I’ll just assign it to a variable, but we could also pass an enumerated value into a function.

Begin typing out the following code sample, and note what happens when you hit the second colon.

$tweet = [MyTwitters]::

When you have entered the second colon, you should see a list of the enumerated values in VSCode.

I say should as sometimes I’ve had VSCode return enums that were declared in my script, and not for the specific enum I was working with.

In the PowerShell ISE though, I’ve had it work right every time.

When complete, your assignment should look like:

$tweet = [MyTwitters]::ArcaneCode

Is it Valid?

So you have a value from the enum copied into your variable, $tweet. How do we test it?

It’s important to understand enums are objects. In addition to the values you provide they have a set of properties and methods you can use. In the previous example, you saw the GetEnumNames method being used.

Another useful method is IsDefined.

[enum]::IsDefined(([MyTwitters]), $tweet)

Result:

True

Into the IsDefined method you pass in your enumeration, then the value you want to test. Here our value is in the variable $tweet. If the value is contained in the enum, the method returns True.

What if the user passes in a value that is not contained in our enum?

$tweet = 'Invalid'
[enum]::IsDefined(([MyTwitters]), $tweet)

Result:

False

Returning False makes it easy to use an if statement and raise an error if the user tries to use an invalid value. For more on the if statement, see my post Fun with PowerShell Logic Branching.

Conclusion

For these examples we used my Twitter accounts for our enum values, but there are many more uses some of them extremely common. You could load an enum with the days of the week, months of the year, colors, and other common values your scripts might use.

In the introduction I mentioned we are starting our series on classes with the enum as enums are frequently used with classes. However this is not a requirement. You can use enums with any PowerShell code you want to write.

In the my next post we’ll continue exploring the enum. We’ll look at a few more useful methods, as well as see how to assign values to our enum values.

The demos in this series of blog posts came from my Pluralsight course PowerShell 7 Quick Start for Developers on Linux, macOS and Windows, one of many PowerShell courses I have on Pluralsight. All of my courses are linked on my About Me page.

If you don’t have a Pluralsight subscription, just go to my list of courses on Pluralsight . At the top is a Try For Free button you can use to get a free 10 day subscription to Pluralsight, with which you can watch my courses, or any other course on the site.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s