{"id":8509,"date":"2015-01-05T06:00:00","date_gmt":"2015-01-05T14:00:00","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=8509"},"modified":"2016-04-08T16:37:22","modified_gmt":"2016-04-08T23:37:22","slug":"enumerators-in-windows-powershell-5-0","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2015\/01\/05\/enumerators-in-windows-powershell-5-0\/","title":{"rendered":"Enumerated Types in Windows PowerShell 5.0"},"content":{"rendered":"

Follow @juneb_get_help<\/a><\/p>\n

[Update: The original post referred to “enums” as “enumerators” when, in fact, they are “enumerated types.” By contrast, enumerators allow you to process items one at a time. Many thanks to Windows PowerShell MVP Dave Wyatt (@msh_Dave<\/a>) for the correction.<\/em>]<\/p>\n

Enums\u00a0have always been a part of Windows PowerShell, because they’re an important part of the .NET Framework. But they’re about to become even more popular, because changes in Windows PowerShell 5.0 make them very easy to create.<\/p>\n

———–<\/p>\n

Enumerated types\u00a0(“enums”) define a set of values, knows as “members” of the enum. You use enums to create a set of valid values and prohibit all other values. In Windows PowerShell, you can use enumerated types just as you use .NET classes. For example, the value of the ExecutionPolicy<\/strong> parameter of the Set-ExecutionPolicy<\/a> cmdlet has a type of ExecutionPolicy <\/strong>and its Scope<\/strong> parameter has a type of ExecutionPolicyScope<\/strong>.<\/p>\n

Set-ExecutionPolicy [-ExecutionPolicy] <ExecutionPolicy> [[-Scope] <ExecutionPolicyScope>] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]<\/pre>\n
Both ExecutionPolicy<\/a><\/strong> and ExecutionPolicyScope<\/a><\/strong> are enums. The enum members are listed and defined on the MSDN page for each enum.<\/p>\n
\"image\"<\/a><\/p><\/blockquote>\n
If you try to use a value that is not a member of the enum, you get a very helpful error. The error explains that the value is limited to the enum and lists the valid values. So, a quick way to find the members of an enum is to try a value that is clearly not valid, like good old “foo”.<\/p>\n
[ADMIN]: PS C:\\ps-test> Set-ExecutionPolicy -ExecutionPolicy foo\r\nSet-ExecutionPolicy : Cannot bind parameter 'ExecutionPolicy'. Cannot convert value \"foo\" \r\nto type \"Microsoft.PowerShell.ExecutionPolicy\". Error: \"Unable to match the identifier \r\nname foo to a valid enumerator name. Specify one of the following enumerator names and try \r\nagain: Unrestricted, RemoteSigned, AllSigned, Restricted, Default, Bypass, Undefined\"\r\nAt line:1 char:38\r\n+ Set-ExecutionPolicy -ExecutionPolicy foo\r\n+\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ~~~\r\n+ CategoryInfo\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : InvalidArgument: (:) [Set-ExecutionPolicy], ParameterBindingException\r\n+ FullyQualifiedErrorId : CannotConvertArgumentNoMessage,Microsoft.PowerShell.Commands.SetExecutionPolicyCommand<\/pre>\n
 <\/p>\n
It’s easy to use enums. This excellent article<\/a> from the TechNet Library explains it well. And, Windows PowerShell has let you define your own enums since 1.0, but it was a bit tricky. Not any more!<\/p>\n
 <\/p>\n
Create an enum<\/h1>\n
In Windows PowerShell 5.0, the enum<\/strong> keyword makes it much easier. Here’s a WineSweetness enum that I created for my Wine class.<\/p>\n
enum WineSweetness\r\n{\r\n    VeryDry\r\n    Dry\r\n    Moderate\r\n    Sweet\r\n    VerySweet\r\n}<\/pre>\n
 <\/p>\n
I use it to limit parameter values, much like ValidateSet, but unlike ValidateSet, once it’s defined in my session, script, or module, I can use it repeatedly without redefining it. In this example, I use it to limit the values of the Sweetness property of instances of my Wine class.<\/p>\n
class Wine\r\n{\r\n    #Properties\r\n    [String]$Name\r\n    [WineSweetness]$Sweetness\r\n    ...\r\n}<\/pre>\n
I can also use it functions, such as my Get-Wine function, without redefining it.<\/p>\n
function Get-Wine\r\n{\r\n    Param\r\n    (\r\n    [parameter(Mandatory = $false)]\r\n    [WineSweetness]\r\n    $SweetnessValue,\r\n    ...\r\n}<\/pre>\n
 <\/p>\n
Enum syntax<\/h2>\n
The enum<\/strong> syntax is so easy. Just note that the list is NOT comma-separated. If you prefer to list the values on a single line, use semi-colons.<\/p>\n
enum \r\n{\r\n    Value1\r\n    [Value2...]\r\n}<\/pre>\n
-or-<\/p>\n
enum \r\n{\r\n    Value1; [Value2...;]\r\n}<\/pre>\n
 <\/p>\n
The value names cannot include spaces or special characters<\/strong>, although an underscore (_) is permitted. Enclosing a names with spaces in quotation marks or curly braces doesn’t help. If you include a space, Windows PowerShell thinks it’s an expression, which is permitted.<\/p>\n
enum WineSweetness\r\n{\r\n    VeryDry\r\n    Dry\r\n    Moderate\r\n    Sweet\r\n    Very Sweet\u00a0\u00a0 # <--- No spaces\r\n}\r\nVery : The term 'Very' is not recognized as the name of a cmdlet, function, script file, \r\nor operable program. Check the spelling of the name, or if a path was included, verify \r\nthat the path is correct and try again.\r\nAt line:1 char:5\r\n+\u00a0\u00a0\u00a0\u00a0 Very Sweet\r\n+\u00a0\u00a0\u00a0\u00a0 ~~~~\r\n+ CategoryInfo\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : ObjectNotFound: (Very:String) [], CommandNotFoundException\r\n+ FullyQualifiedErrorId : CommandNotFoundException<\/pre>\n
 <\/p>\n
The values cannot be numbers<\/strong> and the first character of a value name cannot be a number. The ‘ missing closing “}” ‘ error is not very helpful, so watch out for this one.<\/p>\n
PS C:\\> enum WineSweetness\r\n{\r\n    VeryDry\r\n    Dry\r\n    3\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 # <------ No numbers\r\n    Sweet\r\n    VerySweet\r\n}\r\nAt line:4 char:8\r\n+\u00a0\u00a0\u00a0\u00a0 Dry\r\n+\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ~\r\nMissing closing '}' in statement block or type definition.\r\nAt line:8 char:1\r\n+ }\r\n+ ~\r\nUnexpected token '}' in expression or statement.\r\n+ CategoryInfo\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : ParserError: (:) [], ParentContainsErrorRecordException\r\n+ FullyQualifiedErrorId : MissingEndCurlyBrace<\/pre>\n
 <\/p>\n
Enums have integer values<\/h1>\n
Every enum value has a corresponding integer value. When you create an enum in Windows PowerShell (by using the Add-Type<\/a> cmdlet or the enum<\/strong> keyword), the parser assigns a default integer value to each enum value. These default integer values begin with zero and increase by 1. The values are assigned in the order they are listed in the enum declaration.<\/p>\n
For example, when I created my WineSweetness<\/strong> enum, Windows PowerShell assigned the values 0 \u2013 4 to the enum values.<\/p>\n
enum WineSweetness\r\n{\r\n    VeryDry\r\n    Dry\r\n    Moderate\r\n    Sweet\r\n    VerySweet\r\n}<\/pre>\n
 <\/p>\n
To find the values in any enum, call the GetValues<\/strong> static method of the System.Enum type:<\/p>\n
PS C:\\> [System.Enum]::GetValues([WineSweetness])\r\n\r\nVeryDry\r\nDry\r\nModerate\r\nSweet\r\nVerySweet\r\n\r\n<\/pre>\n
 <\/p>\n
To find the underlying integer value of each enum value, cast the enum value to an integer (thanks to Keith Babinec<\/a> for this trick).<\/p>\n
PS C:\\> [System.Enum]::GetValues([WineSweetness]) | foreach { [int]$_ }\r\n\r\n0\r\n1\r\n2\r\n3\r\n4<\/pre>\n
 <\/p>\n
Let’s put them together. This command creates a custom object (I love PSCustomObject<\/a>!) with the names and integer value of each enum value.<\/p>\n
PS C:\\> [System.Enum]::GetValues([WineSweetness]) | \r\nforeach { [PSCustomObject]@{ValueName = $_; IntValue = [int]$_\u00a0 }\u00a0\u00a0 }\r\n\r\nValueName\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 IntValue\r\n---------\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 --------\r\nVeryDry\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0 0\r\nDry\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 1\r\nModerate\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 2\r\nSweet\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 3\r\nVerySweet\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 4\r\n<\/pre>\n
 <\/p>\n
You can also assign integer values, and expressions that return an integer value, to your enum values. The values that you assign override the default zero-based values. All enum values are constants, so you can’t change them after you assign them.<\/p>\n
PS C:\\> enum WineSweetness\r\n{\r\n    Sweet = 4\r\n    VeryDry = 2 * 4 + 2\r\n    Moderate = 6\r\n    VerySweet = 2\r\n    Dry = 8\r\n}\r\n\r\n[System.Enum]::GetValues([WineSweetness]) | \r\nforeach {[PSCustomObject]@{ValueName = $_; IntValue = [int]$_} }\r\n\r\nValueName\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 IntValue\r\n---------\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 --------\r\nVerySweet\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 2\r\nSweet\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 4\r\nModerate\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 6\r\nDry\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 8\r\nVeryDry\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 10<\/pre>\n
 <\/p>\n
Using an enum<\/h1>\n
When you use an enum, you can specify either a value name or its integer value.<\/p>\n
enum WineSweetness\r\n{\r\n    VeryDry = 1\r\n    Dry = 2\r\n    Moderate = 3\r\n    Sweet = 4\r\n    VerySweet = 5\r\n}<\/pre>\n
 <\/p>\n
I’ll create an instance of my Wine class and set its Sweetness<\/strong> property, which has a type of WineSweetness<\/strong>, to VeryDry (my personal favorite).<\/p>\n
PS C:\\>$PSWine = [Wine]::new(\"PSCabernet\")\r\nPS C:\\>$PSWine.Sweetness = VeryDry<\/pre>\n
I can use the dot method to get the string representation of the Sweetness<\/strong> property value:<\/p>\n
PS C:\\> $PSWine.Sweetness\r\nVeryDry<\/pre>\n
Or, use the Value__<\/strong> (that’s 2 underscores) property of all enum values to get its integer value.<\/p>\n
PS C:\\> $PSWine.Sweetness.value__\r\n1<\/pre>\n
If I try to change the value of the Sweetness<\/strong> property to a value that’s not in the enum, I get that awesome error that lists the valid values.<\/p>\n
PS C:\\ps-test> $PSWine.Sweetness = \"TooSweet\"\r\nException setting \"Sweetness\": \"Cannot convert value \"TooSweet\" to type \"WineSweetness\". \r\nError: \"Unable to match the identifier name TooSweet to a valid enumerator name. \r\nSpecify one of the following enumerator names and try again:\r\nVeryDry, Dry, Moderate, Sweet, VerySweet\"\"\r\nAt line:1 char:1\r\n+ $PSWine.Sweetness = \"TooSweet\"\r\n+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n+ CategoryInfo\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : NotSpecified: (:) [], SetValueInvocationException\r\n+ FullyQualifiedErrorId : ExceptionWhenSetting<\/pre>\n
Just so I use a valid value, I can assign either a string or a integer value.<\/p>\n
PS C:\\> $PSWine.Sweetness = Dry\r\nPS C:\\> $PSWine.Sweetness\r\nDry\r\n\r\nPS C:\\> $PSWine.Sweetness = 3\r\nPS C:\\> $PSWine.Sweetness\r\nModerate<\/pre>\n
When you sort objects by an enumerated property value, the Sort-Object<\/a> cmdlet sorts by integer value. For example, I have some wines in a $myWines variable.<\/p>\n
PS C:\\ps-test> $myWines\r\n\r\nName\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : Great Duck\r\nWinery\u00a0\u00a0\u00a0\u00a0\u00a0 : Escalante Winery\r\nYear\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : 2003\r\nisSparkling : True\r\nColor\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : White\r\nSweetness\u00a0\u00a0 : VerySweet\r\nDescription : Rich and magnificent\r\nRating\u00a0\u00a0\u00a0\u00a0\u00a0 : {98, 97}\r\n\r\n\u00a0\r\n\r\nName\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : PSCabernet\r\nWinery\u00a0\u00a0\u00a0\u00a0\u00a0 : Chateau Snover\r\nYear\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : 2006\r\nisSparkling : False\r\nColor\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : Red\r\nSweetness\u00a0\u00a0 : VeryDry\r\nDescription : Pithy\r\nRating\u00a0\u00a0\u00a0\u00a0\u00a0 : {96}\r\n\r\n\u00a0\r\n\r\nName\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : Shiraz\r\nWinery\u00a0\u00a0\u00a0\u00a0\u00a0 : SAPIEN Vineyards\r\nYear\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : 1990\r\nisSparkling : False\r\nColor\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 : Red\r\nSweetness\u00a0\u00a0 : Dry\r\nDescription : Bold and innovative\r\nRating\u00a0\u00a0\u00a0\u00a0\u00a0 : {100}<\/pre>\n
 <\/p>\n
When I sort them by the value of the Sweetness<\/strong> property, I get them in ascending integer value order. I used a calculated property<\/a> to add the integer value to the table.<\/p>\n
PS C:\\ps-test> $mywines |\r\nSort-Object -Property Sweetness |\r\nFormat-Table -Property Name, `\r\nSweetness, `\r\n@{Label=\"IntSweet\"; Expression={$_.Sweetness.Value__}} -AutoSize\r\n\r\nName\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Sweetness IntSweet\r\n----\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 --------- --------\r\nPSWine\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 VeryDry\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 1\r\nShiraz\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Dry\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 2\r\nGreat Duck VerySweet\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 5<\/pre>\n
 <\/p>\n
The introduction of the enum<\/strong> keyword has really made enumerated types available to everyone. Yet another tool for your Windows PowerShell toolbox.<\/p>\n
June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at <\/em>juneb@sapien.com<\/em><\/a> or follow her on Twitter at <\/em>@juneb_get_help<\/em><\/a>.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"
Follow @juneb_get_help [Update: The original post referred to “enums” as “enumerators” when, in fact, they are “enumerated types.” By contrast, enumerators allow you to process items one at a time. Many thanks to Windows PowerShell MVP Dave Wyatt (@msh_Dave) for the correction.] Enums\u00a0have always been a part of Windows PowerShell, because they’re an important part […]<\/p>\n","protected":false},"author":31,"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":[1033,941,25],"tags":[934,28],"class_list":["post-8509","post","type-post","status-publish","format-standard","hentry","category-classes-in-powershell-5-0","category-powershell-5-0","category-windows-powershell","tag-juneb","tag-powershell"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/8509","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/31"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=8509"}],"version-history":[{"count":32,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/8509\/revisions"}],"predecessor-version":[{"id":10604,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/8509\/revisions\/10604"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=8509"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=8509"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=8509"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}