about_Enum
Korte beschrijving
De enum instructie declareert een opsomming. Een opsomming is een uniek type dat bestaat uit een set benoemde labels, de enumeratorlijst genoemd.
Lange beschrijving
Met de enum instructie kunt u een sterk getypte set labels maken. U kunt die opsomming in de code gebruiken zonder dat u spelfouten hoeft te parseren of controleren.
Opsommingen worden intern weergegeven als integrale waardetypen met een beginwaarde van nul. PowerShell-opsommingen maken standaard gebruik van System.Int32 ([int]) als het onderliggende type. Standaard wijst PowerShell het eerste label toe aan de lijst met de waarde nul. Standaard wijst PowerShell de resterende labels toe met opeenvolgende gehele getallen.
In de definitie kunt u labels opgeven voor een geheel getal. Labels waaraan geen waarde is toegewezen, nemen de volgende gehele waarde.
Syntaxis
Opsommingen gebruiken de volgende syntaxis:
Definitiesyntaxis voor gehele getallen
[[<attribute>]...] enum <enum-name> {
<label> [= <int-value>]
...
}
Definitiesyntaxis van specifieke onderliggende typen
[[<attribute>]...] enum <enum-name> : <underlying-type-name> {
<label> [= <int-value>]
...
}
Syntaxis van opsommingsdefinitie markeren
[[<attribute>]...] [Flag()] enum <enum-name>[ : <underlying-type-name>] {
<label 0> [= 1]
<label 1> [= 2]
<label 2> [= 4]
<label 3> [= 8]
...
...
}
Opsommingssyntaxis voor toegang
[<enum-name>]::<label>
Voorbeelden
Voorbeeld 1- Minimale opsomming
Het volgende codeblok definieert de opsomming MarkdownUnorderedListCharacter met drie labels. Er worden geen expliciete waarden aan een label toegewezen.
enum MarkdownUnorderedListCharacter {
Asterisk
Dash
Plus
}
Het volgende codeblok laat zien hoe zowel gehele getallen als tekenreekswaarden zich gedragen wanneer ze naar het opsommingstype worden gecast.
$ValuesToConvert = @(0, 'Asterisk', 1, 'Dash', 2, 'Plus')
foreach ($Value in $ValuesToConvert) {
[MarkdownUnorderedListCharacter]$EnumValue = $Value
[pscustomobject]@{
AssignedValue = $Value
Enumeration = $EnumValue
AreEqual = $Value -eq $EnumValue
}
}
AssignedValue Enumeration AreEqual
------------- ----------- --------
0 Asterisk True
Asterisk Asterisk True
1 Dash True
Dash Dash True
2 Plus True
Plus Plus True
Het casten van gehele getallen die gelijk zijn aan de waarde van een opsomming, retourneert die opsomming. Het casten van tekenreeksen die hetzelfde zijn als het label van een opsomming, retourneert die opsomming.
Voorbeeld 2: Expliciete en synoniemenumwaarden
In het volgende voorbeeld ziet u een opsomming van objecten die correleren met mediabestanden. De definitie wijst expliciete waarden toe aan de onderliggende waarden van music, picture. video Labels direct na een expliciete toewijzing krijgen de volgende gehele waarde. U kunt synoniemen maken door dezelfde waarde toe te wijzen aan een ander label; zie de samengestelde waarden voor: ogg, oga, mogg, of jpg, jpeg.mpgmpeg
enum MediaTypes {
unknown
music = 10
mp3
aac
ogg = 15
oga = 15
mogg = 15
picture = 20
jpg
jpeg = 21
png
video = 40
mpg
mpeg = 41
avi
m4v
}
De GetEnumNames() methode retourneert de lijst met de labels voor de opsomming.
[MediaTypes].GetEnumNames()
unknown
music
mp3
aac
ogg
oga
mogg
picture
jpg
jpeg
png
video
mpg
mpeg
avi
m4v
De GetEnumValues() methode retourneert de lijst met de waarden voor de opsomming.
[MediaTypes].GetEnumValues()
unknown
music
mp3
aac
ogg
ogg
ogg
picture
jpg
jpg
png
video
mpg
mpg
avi
m4v
Notitie
GetEnumNames() en GetEnumValues() lijken dezelfde resultaten te retourneren; een lijst met benoemde waarden. Intern GetEnumValues() worden de waarden echter opgesomd en worden waarden vervolgens toegewezen aan namen. Lees de lijst zorgvuldig en u zult merken dat ogg, ogaen mogg worden weergegeven in de uitvoer van GetEnumNames(), maar de uitvoer van GetEnumValues() alleen wordt weergegeven ogg. Hetzelfde gebeurt voor jpg, jpegen mpg, mpeg. De naam PowerShell retourneert voor synoniemenwaarden is niet deterministisch.
U kunt de GetEnumName() methode gebruiken om een naam op te halen die is gekoppeld aan een specifieke waarde. Als er meerdere namen aan een waarde zijn gekoppeld, retourneert de methode de voornaam.
[MediaTypes].GetEnumName(15)
ogg
In het volgende voorbeeld ziet u hoe u elke naam aan de waarde ervan kunt toewijzen.
[MediaTypes].GetEnumNames() | ForEach-Object {
[pscustomobject]@{
Name = $_
Value = [int]([MediaTypes]::$_)
}
}
Name Value
---- -----
unknown 0
music 10
mp3 11
aac 12
ogg 15
oga 15
mogg 15
picture 20
jpg 21
jpeg 21
png 22
video 40
mpg 41
mpeg 41
avi 42
m4v 43
U kunt één opsommingswaarde opgeven op basis van het label met de syntaxis [<enum-name>]::<label>.
[MediaTypes]::png
[MediaTypes]::png -eq 22
png
True
Voorbeeld 3: Opsomming als vlaggen
Met het volgende codeblok wordt de opsomming FileAttributes gemaakt als een set bitvlagken. De waarde voor elk label is het dubbele van de waarde van het vorige label.
[Flags()] enum FileAttributes {
Archive = 1
Compressed = 2
Device = 4
Directory = 8
Encrypted = 16
Hidden = 32
}
[FileAttributes]$file1 = [FileAttributes]::Archive
[FileAttributes]$file1 += [FileAttributes]::Compressed
[FileAttributes]$file1 += [FileAttributes]::Device
"file1 attributes are: $file1"
[FileAttributes]$file2 = [FileAttributes]28 ## => 16 + 8 + 4
"file2 attributes are: $file2"
file1 attributes are: Archive, Compressed, Device
file2 attributes are: Device, Directory, Encrypted
Als u wilt testen of een specifieke vlag is ingesteld, kunt u de binaire vergelijkingsoperator -bandgebruiken. In dit voorbeeld worden de kenmerken Apparaat en Archief getest in de waarde van $file2.
PS > ($file2 -band [FileAttributes]::Device) -eq [FileAttributes]::Device
True
PS > ($file2 -band [FileAttributes]::Archive) -eq [FileAttributes]::Archive
False
U kunt ook de HasFlag() methode gebruiken om te testen of een specifieke vlag is ingesteld.
In dit voorbeeld worden de kenmerken Apparaat en Verborgen getest in de waarde van $file1.
PS > $file1.HasFlag([FileAttributes]::Device)
True
PS > $file1.HasFlag([FileAttributes]::Hidden)
False
Voorbeeld 4: Opsomming als parameter
In het volgende voorbeeld definieert de functie ConvertTo-LineEndingRegex de parameter InputObject met het type EndOfLine.
enum EndOfLine {
CR = 1
LF = 2
CRLF = 3
}
function ConvertTo-LineEndingRegex {
[CmdletBinding()]
param (
[Parameter(ValueFromPipeline)]
[EndOfLine[]]$InputObject
)
process {
switch ($InputObject) {
CR { '\r' }
LF { '\n' }
CRLF { '\r\n' }
}
}
}
[EndOfLine]::CR | ConvertTo-LineEndingRegex
'CRLF' | ConvertTo-LineEndingRegex
ConvertTo-LineEndingRegex 2
\r
\r\n
\n
In het voorbeeld geeft de eerste instructie die de ConvertTo-LineEndingRegex opsommingswaarde doorgeeft voor CR. De tweede instructie geeft de tekenreeks 'CRLF'door, die wordt omgezet in een LineEnding. Met de derde instructie wordt de waarde 2 voor de parameter opgegeven, die is toegewezen aan het LF label.
U kunt de opties voor het voltooien van argumenten zien door de volgende tekst in uw PowerShell-prompt te typen:
ConvertTo-LineEndingRegex -InputObject <Tab>
Wanneer u een ongeldige labelnaam of numerieke waarde voor de parameter opgeeft, wordt er een fout gegenereerd.
ConvertTo-LineEndingRegex -InputObject 0
ConvertTo-LineEndingRegex: Cannot process argument transformation on
parameter 'InputObject'. Cannot convert value "0" to type "EndOfLine" due
to enumeration values that are not valid. Specify one of the following
enumeration values and try again. The possible enumeration values are
"CR,LF,CRLF".
Voorbeeld 5: Opsommingen met specifieke onderliggende typen
Vanaf PowerShell 6.2 kunt u opsommingen definiëren met een specifiek onderliggend type. In dit voorbeeld ziet u de geldige onderliggende typen voor een opsomming.
Het eerste codeblok initialiseert twee variabelen als matrices.
$EnumTypes is een lege matrix die de dynamisch gemaakte typen bevat.
$IntegralTypes is een matrix die de geldige onderliggende typen voor een opsomming bevat.
$EnumTypes = @()
$IntegralTypes = @(
'byte', 'sbyte', 'short', 'ushort', 'int', 'uint', 'long', 'ulong'
)
In het volgende codeblok wordt een sjabloon gedefinieerd die moet worden gebruikt voor het dynamisch maken van de opsommingsdefinities. Wanneer de tijdelijke aanduiding voor opmaak {0} wordt vervangen door een integrale typenaam, maakt de sjabloon een scriptblok dat:
Definieert een opsomming met de naam
<type>Enum, zoalsbyteEnum. De gedefinieerde inventarisatie maakt gebruik van het opgegeven integrale type als het onderliggende waardetype.De opsomming wordt gedefinieerd met de
Minwaarde die is ingesteld op de minimumwaarde voor het integrale type. Hiermee definieert u deMaxwaarde die is ingesteld op de maximumwaarde voor het integrale type.Retourneert het zojuist gedefinieerde type.
$DefinitionTemplate = @"
enum {0}Enum : {0} {{
Min = [{0}]::MinValue
Max = [{0}]::MaxValue
}}
[{0}Enum]
"@
In het volgende codeblok wordt de sjabloon gebruikt om een scriptblock in het huidige bereik te maken en aan te roepen. Hiermee worden de geretourneerde typedefinities toegevoegd aan de $EnumTypes matrix.
foreach ($IntegralType in $IntegralTypes) {
$Definition = $DefinitionTemplate -f $IntegralType
$ScriptBlock = [scriptblock]::Create($Definition)
$EnumTypes += . $ScriptBlock
}
De laatste codebloklussen over de enum-typen, met behulp van de GetEnumValuesAsUnderlyingType() methode om de waarden weer te geven als het onderliggende type. De lus maakt een nieuw object voor elke waarde, met het opsommingstype, het waardetype, het label en de werkelijke waarde.
foreach ($EnumType in $EnumTypes) {
$EnumType.GetEnumValuesAsUnderlyingType() | ForEach-Object {
[pscustomobject]@{
EnumType = $EnumType.FullName
ValueType = $_.GetType().FullName
Label = $EnumType.GetEnumName($_)
Value = $_
}
}
}
EnumType ValueType Label Value
-------- --------- ----- -----
byteEnum System.Byte Min 0
byteEnum System.Byte Max 255
sbyteEnum System.SByte Max 127
sbyteEnum System.SByte Min -128
shortEnum System.Int16 Max 32767
shortEnum System.Int16 Min -32768
ushortEnum System.UInt16 Min 0
ushortEnum System.UInt16 Max 65535
intEnum System.Int32 Max 2147483647
intEnum System.Int32 Min -2147483648
uintEnum System.UInt32 Min 0
uintEnum System.UInt32 Max 4294967295
longEnum System.Int64 Max 9223372036854775807
longEnum System.Int64 Min -9223372036854775808
ulongEnum System.UInt64 Min 0
ulongEnum System.UInt64 Max 18446744073709551615
Opsommingsmethoden
De volgende lijst bevat nuttige methoden die beschikbaar zijn voor opsommingen in PowerShell en hoe u deze kunt gebruiken.
Notatie
De Format() statische methode retourneert de opgemaakte tekenreeksuitvoer voor een bepaald opsommingstype, opsommingswaarde en notatietekenreeks. De uitvoer is hetzelfde als het aanroepen van de ToString-methode voor de waarde met de opgegeven notatietekenreeks.
U kunt de statische methode gebruiken op het basisklassetype System.Enum of een specifiek opsommingstype.
[System.Enum]::format([<enum-name>], <value>, <format-string>)
[<enum-name>]::format([<enum-name>], <value>, <format-string>)
De geldige notatietekenreeksen zijnG, gD of d, X of x, en F of f. Zie Opsommingstekenreeksen voor meer informatie.
In het volgende voorbeeld worden alle ondersteunde opsommingsindelingstekenreeksen gebruikt om elke waarde van de TaskState-opsomming te converteren naar de tekenreeksweergaven.
enum TaskState {
ToDo
Doing
Done
}
# String format template for the statements
$Statement = "[System.Enum]::Format([TaskState], {0}, '{1}')"
foreach ($Format in @('G', 'D', 'X', 'F')) {
$StatementToDo = $Statement -f 0, $Format
$StatementDoing = $Statement -f "([TaskState]'Doing')", $Format
$StatementDone = $Statement -f '[TaskState]::Done', $Format
$FormattedToDo = [System.Enum]::Format(
[TaskState], 0, $Format
)
$FormattedDoing = [System.Enum]::Format(
[TaskState], ([TaskState]'Doing'), $Format
)
$FormattedDone = [System.Enum]::Format(
[TaskState], [TaskState]::Done, $Format
)
"{0,-62} => {1}" -f $StatementToDo, $FormattedToDo
"{0,-62} => {1}" -f $StatementDoing, $FormattedDoing
"{0,-62} => {1}" -f $StatementDone, $FormattedDone
}
[System.Enum]::Format([TaskState], 0, 'G') => ToDo
[System.Enum]::Format([TaskState], ([TaskState]'Doing'), 'G') => Doing
[System.Enum]::Format([TaskState], [TaskState]::Done, 'G') => Done
[System.Enum]::Format([TaskState], 0, 'D') => 0
[System.Enum]::Format([TaskState], ([TaskState]'Doing'), 'D') => 1
[System.Enum]::Format([TaskState], [TaskState]::Done, 'D') => 2
[System.Enum]::Format([TaskState], 0, 'X') => 00000000
[System.Enum]::Format([TaskState], ([TaskState]'Doing'), 'X') => 00000001
[System.Enum]::Format([TaskState], [TaskState]::Done, 'X') => 00000002
[System.Enum]::Format([TaskState], 0, 'F') => ToDo
[System.Enum]::Format([TaskState], ([TaskState]'Doing'), 'F') => Doing
[System.Enum]::Format([TaskState], [TaskState]::Done, 'F') => Done
GetEnumName
De GetEnumName() reflectiemethode retourneert de naam voor een specifieke opsommingswaarde. De invoerwaarde moet een geldig onderliggend type zijn voor een opsomming, zoals een geheel getal of een opsommingswaarde. Als er meerdere namen aan een waarde zijn gekoppeld, retourneert de methode de voornaam.
[<enum-name>].GetEnumName(<value>)
enum GateState {
Unknown
Open
Opening
Closing
Closed
}
foreach ($Value in 0..4) {
[pscustomobject]@{
IntegerValue = $Value
EnumName = [GateState].GetEnumName($Value)
}
}
IntegerValue EnumName
------------ --------
0 Unknown
1 Open
2 Opening
3 Closing
4 Closed
GetEnumNames
De GetEnumNames() reflectiemethode retourneert de namen voor elke opsommingswaarde als tekenreeksen. De uitvoer bevat synoniemen.
[<enum-name>].GetEnumNames()
enum Season {
Unknown
Spring
Summer
Autumn
Winter
Fall = 3
}
[Season].GetEnumNames()
Unknown
Spring
Summer
Fall
Autumn
Winter
GetEnumUnderlyingType
De GetEnumUnderlyingType() reflectiemethode retourneert het onderliggende type voor de opsommingswaarden.
[<enum-name>].GetEnumUnderlyingType()
enum IntBasedEnum {
Zero
One
Two
}
enum ShortBasedEnum : short {
Zero
One
Two
}
foreach ($EnumType in @([IntBasedEnum], [ShortBasedEnum])) {
[pscustomobject]@{
EnumType = $EnumType
ValueType = $EnumType.GetEnumUnderlyingType()
}
}
EnumType ValueType
-------- ---------
IntBasedEnum System.Int32
ShortBasedEnum System.Int16
GetEnumValues
De GetEnumValues() reflectiemethode retourneert elke gedefinieerde waarde voor de opsomming.
[<enum-name>].GetEnumValues()
enum Season {
Unknown
Spring
Summer
Autumn
Winter
Fall = 3
}
[Season].GetEnumValues()
Unknown
Spring
Summer
Fall
Fall
Winter
GetEnumValuesAsUnderlyingType
De GetEnumValuesAsUnderlyingType() reflectiemethode retourneert elke gedefinieerde waarde voor de opsomming als het onderliggende type.
[<enum-name>].GetEnumValuesAsUnderlyingType()
enum IntBasedEnum {
Zero
One
Two
}
enum ShortBasedEnum : short {
Zero
One
Two
}
foreach ($EnumType in @([IntBasedEnum], [ShortBasedEnum])) {
[pscustomobject]@{
EnumType = $EnumType
ValueType = $EnumType.GetEnumValuesAsUnderlyingType()[0].GetType()
}
}
EnumType ValueType
-------- ---------
IntBasedEnum System.Int32
ShortBasedEnum System.Int16
HasFlag
De HasFlag instantiemethode bepaalt of een bitvlag is ingesteld voor een markeringswaarde. Het gebruik van deze methode is korter en gemakkelijker te lezen dan het uitvoeren van een binaire vergelijkings- en equivalentiecontrole.
<enum-value>.HasFlag(<enum-flag-value>)
In het volgende voorbeeld wordt de opsomming van de moduleFeatures-vlag gedefinieerd en wordt weergegeven welke vlaggen de waarde 39 heeft.
[Flags()] enum ModuleFeatures {
Commands = 1
Classes = 2
Enums = 4
Types = 8
Formats = 16
Variables = 32
}
$Features = [ModuleFeatures]39
foreach ($Feature in [ModuleFeatures].GetEnumValues()) {
"Has flag {0,-12}: {1}" -f "'$Feature'", ($Features.HasFlag($Feature))
}
Has flag 'Commands' : True
Has flag 'Classes' : True
Has flag 'Enums' : True
Has flag 'Types' : False
Has flag 'Formats' : False
Has flag 'Variables' : True
IsDefined
De IsDefined() statische methode retourneert $true als de invoerwaarde is gedefinieerd voor de opsomming en anders $false. Gebruik deze methode om te controleren of een waarde geldig is voor een opsomming zonder dat u ongeldige argumentfouten hoeft te verwerken.
U kunt de statische methode gebruiken op het basisklassetype System.Enum of een specifiek opsommingstype.
[System.Enum]::IsDefined([<enum-name>], <value>)
[<enum-name>]::IsDefined([<enum-name>], <value>)
enum Season {
Unknown
Spring
Summer
Autumn
Winter
Fall = 3
}
foreach ($Value in 0..5) {
$IsValid = [Season]::IsDefined([Season], $Value)
$EnumValue = if ($IsValid) { [Season]$Value }
[pscustomobject] @{
InputValue = $Value
IsValid = $IsValid
EnumValue = $EnumValue
}
}
InputValue IsValid EnumValue
---------- ------- ---------
0 True Unknown
1 True Spring
2 True Summer
3 True Fall
4 True Winter
5 False
ToString
De ToString() instantiemethode retourneert het label voor een opsommingswaarde.
Deze methode is ook de standaardweergave voor de weergave van een opsommingswaarde als uitvoer. U kunt desgewenst een notatietekenreeks opgeven om te bepalen hoe de waarde wordt weergegeven. Zie Opsommingswaarden opmaken voor meer informatie over opmaak.
Notitie
Schrijf geen code die afhankelijk is van de uitvoer van ToString(). De methode kan elke geldige naam voor de waarde retourneren.
<enum-value>.ToString([<format-string>])
In het volgende voorbeeld wordt de opsomming Schaduw gedefinieerd met Gray als synoniem voor Grey. Vervolgens worden objecten uitgevoerd die de werkelijke enumwaarde, de enum als een tekenreeks en de opsomming als geheel getal weergeven.
enum Shade {
White
Grey
Gray = 1
Black
}
[Shade].GetEnumValues() | Foreach-Object -Process {
[pscustomobject]@{
EnumValue = $_
StringValue = $_.ToString()
IntegerValue = [int]$_
}
}
numValue StringValue IntegerValue
--------- ----------- ------------
White White 0
Grey Grey 1
Grey Grey 1
Black Black 2
Opsommingswaarde synoniemen
U kunt opsommingen definiëren die verschillende namen aan dezelfde gehele waarde geven. Wanneer u dit doet, worden de namen die naar dezelfde onderliggende waarde verwijzen, synoniemen genoemd. Met opsommingen met synoniemen kunnen gebruikers verschillende namen voor dezelfde waarde opgeven.
Wanneer u een opsomming met synoniemen definieert, hoeft u geen code te schrijven die afhankelijk is van een synoniemwaarde die wordt geconverteerd naar een specifieke naam. U kunt op betrouwbare wijze code schrijven waarmee een synoniemtekenreeks wordt geconverteerd naar de opsommingswaarde. Wanneer u met de opsommingswaarde zelf werkt, vergelijkt u deze altijd als een opsommingswaarde of het onderliggende type ervan in plaats van als een tekenreeks.
Het volgende codeblok definieert de arcering met Grey en Gray als synoniemen.
enum Shade {
White
Grey
Gray = 1
Black
}
[Shade]'Grey' -eq [Shade]::Gray
[Shade]::Grey -eq 1
[Shade]'Gray' -eq 1
True
True
True
Opsommingen als vlaggen
Een veelvoorkomend gebruik van een opsomming is het vertegenwoordigen van een set wederzijds exclusieve waarden. Een ArrivalStatus-exemplaar kan bijvoorbeeld de waarde Early, OnTime of Late hebben. Het is niet logisch dat de waarde van een ArrivalStatus-exemplaar meer dan één opsommingsconstante weergeeft.
In andere gevallen kan de waarde van een opsommingsobject echter meerdere opsommingsleden bevatten en elk lid vertegenwoordigt een bitveld in de opsommingswaarde. U kunt de FlagsAttribute gebruiken om aan te geven dat de opsomming uit bitvelden bestaat als vlaggen die gebruikers kunnen combineren.
Als opsommingen als vlaggen goed werken, moet u de geheel getalwaarde van elk label instellen op een macht van twee. Als u geen waarde voor een label opgeeft, stelt PowerShell de waarde in op een hoger dan het vorige label.
U kunt waarden definiëren voor veelgebruikte vlagcombinaties, zodat gebruikers gemakkelijker een set vlaggen tegelijk kunnen opgeven. De naam voor de waarde moet de gecombineerde namen van de vlaggen zijn. De waarde van het gehele getal moet de som van de vlagwaarden zijn.
Als u wilt bepalen of een specifieke vlag is ingesteld voor een waarde, gebruikt u de HasFlag() methode voor de waarde of gebruikt u de binaire vergelijkingsoperator -band.
Zie voorbeeld 3 voor een voorbeeld waarin wordt getoond hoe u markeringen gebruikt en controleert of een vlag is ingesteld.
Opsommingen als parameters
U kunt cmdlet-parameters definiëren die een opsomming gebruiken als hun type. Wanneer u een opsomming opgeeft als het type voor een parameter, krijgen gebruikers automatische voltooiing voor en validatie van de waarde van de parameter. Met de voltooiing van het argument wordt de lijst met geldige labels voor de enum voorgesteld.
Wanneer een parameter een opsomming heeft als het type, kunt u een van de volgende opgeven:
- Een opsomming, zoals
[<EnumType>]::<Label> - Het label voor een opsomming als een tekenreeks
- De numerieke waarde van een opsomming
Zie voorbeeld 4 voor een voorbeeld van het gedrag van een parameter met opsommingstypen.
Opsommingen met specifieke onderliggende typen
Vanaf PowerShell 6.2 kunt u opsommingen definiëren met een specifiek onderliggend type. Wanneer u een opsomming zonder een specifiek onderliggend type definieert, maakt PowerShell de opsomming met [int] (System.Int32) als het onderliggende type.
Het onderliggende type voor een opsomming moet een integraal numeriek type zijn. De volgende lijst bevat de geldige typen met hun korte naam en volledige typenaam:
-
byte- System.Byte -
sbyte- System.SByte -
short- System.Int16 -
ushort- System.UInt16 -
int- System.Int32 -
uint- System.UInt32 -
long- System.Int64 -
ulong- System.UInt64
U kunt een specifiek onderliggend type voor opsomming definiëren als de korte naam of de volledige typenaam. De volgende definities zijn functioneel identiek. Alleen de naam die wordt gebruikt voor het onderliggende type is anders.
enum LongValueEnum : long {
Zero
One
Two
}
enum LongValueEnum : System.Int64 {
Zero
One
Two
}
Opsommingswaarden opmaken
U kunt opsommingswaarden converteren naar de tekenreeksweergaven door de methode static Format aan te roepen, evenals de overbelastingen van de ToString-methode van het exemplaar. U kunt een notatietekenreeks gebruiken om de precieze manier te bepalen waarop een opsommingswaarde wordt weergegeven als een tekenreeks. Zie Opsommingstekenreeksen voor meer informatie.
In het volgende voorbeeld wordt elk van de ondersteunde opsommingsopmaaktekenreeksen (of, of, G ofgD, en d of X ) gebruikt om elk lid van de x te converteren naar de tekenreeksweergaven. Ff
enum TaskState {
ToDo
Doing
Done
}
[TaskState].GetEnumValues() | ForEach-Object {
[pscustomobject]@{
"ToString('G')" = $_.ToString('G')
"ToString('D')" = $_.ToString('D')
"ToString('X')" = $_.ToString('X')
"ToString('F')" = $_.ToString('F')
}
}
ToString('G') ToString('D') ToString('X') ToString('F')
------------- ------------- ------------- -------------
ToDo 0 00000000 ToDo
Doing 1 00000001 Doing
Done 2 00000002 Done
In het volgende voorbeeld worden de notatietekenreeksen gebruikt voor waarden van een opsomming van een vlag.
[Flags()] enum FlagEnum {
A = 1
B = 2
C = 4
}
$FlagValues = @(
[FlagEnum]::A # 1
[FlagEnum]::B # 2
[FlagEnum]::A + [FlagEnum]::B # 3
[FlagEnum]::C # 4
[FlagEnum]::C + [FlagEnum]::A # 5
[FlagEnum]::C + [FlagEnum]::B # 6
[FlagEnum]::C + [FlagEnum]::A + [FlagEnum]::B # 7
[FlagEnum]::C + [FlagEnum]::C # 8
)
foreach ($Value in $FlagValues) {
[pscustomobject]@{
"ToString('G')" = $Value.ToString('G')
"ToString('D')" = $Value.ToString('D')
"ToString('X')" = $Value.ToString('X')
"ToString('F')" = $Value.ToString('F')
}
}
ToString('G') ToString('D') ToString('X') ToString('F')
------------- ------------- ------------- -------------
A 1 00000001 A
B 2 00000002 B
A, B 3 00000003 A, B
C 4 00000004 C
A, C 5 00000005 A, C
B, C 6 00000006 B, C
A, B, C 7 00000007 A, B, C
8 8 00000008 8
U ziet dat voor opsommingen van vlaggen de G tekenreeksen en F opmaaktekenreeksen de lijst met setvlagmen weergeven voor de waarde die is gescheiden door komma's. Met de laatste waarde worden 8geen vlaggen weergegeven, omdat het geen geldige vlagset is. U kunt de opsommingsvlagmen niet combineren om een som van 8 te krijgen zonder ten minste één vlag te dupliceren.
Extensiemethoden definiëren met Update-TypeData
U kunt geen methoden definiëren in de declaratie voor een opsomming. Als u de functionaliteit van een opsomming wilt uitbreiden, kunt u de cmdlet Update-TypeData gebruiken om leden voor de opsomming te definiëren ScriptMethod .
In het volgende voorbeeld wordt de Update-TypeData cmdlet gebruikt om een GetFlags() methode toe te voegen aan de opsomming fileAttributes-vlaggen . Hiermee wordt een matrix geretourneerd van de vlaggen die zijn ingesteld voor de waarde.
[Flags()] enum FileAttributes {
Archive = 1
Compressed = 2
Device = 4
Directory = 8
Encrypted = 16
Hidden = 32
}
$MemberDefinition = @{
TypeName = 'FileAttributes'
MemberName = 'GetFlags'
MemberType = 'ScriptMethod'
Value = {
foreach ($Flag in $this.GetType().GetEnumValues()) {
if ($this.HasFlag($Flag)) { $Flag }
}
}
}
Update-TypeData @MemberDefinition
$File = [FileAttributes]28
$File.GetFlags()
Device
Directory
Encrypted
Opsommingen exporteren met typeversnellers
PowerShell-modules exporteren standaard niet automatisch klassen en opsommingen die zijn gedefinieerd in PowerShell. De aangepaste typen zijn niet beschikbaar buiten de module zonder een using module instructie aan te roepen.
Als een module echter typeversnellers toevoegt, zijn deze typeversnellers onmiddellijk beschikbaar in de sessie nadat gebruikers de module hebben geïmporteerd.
Notitie
Het toevoegen van typeversnellers aan de sessie maakt gebruik van een interne (niet openbare) API. Het gebruik van deze API kan conflicten veroorzaken. Het onderstaande patroon genereert een fout als er al een typeversneller met dezelfde naam bestaat wanneer u de module importeert. Ook worden de typeversnellers verwijderd wanneer u de module uit de sessie verwijdert.
Dit patroon zorgt ervoor dat de typen beschikbaar zijn in een sessie. Dit heeft geen invloed op IntelliSense of voltooiing bij het ontwerpen van een scriptbestand in VS Code.
Als u IntelliSense en voltooiingssuggesties voor aangepaste typen in VS Code wilt ophalen, moet u een using module instructie toevoegen aan het begin van het script.
In het volgende patroon ziet u hoe u PowerShell-klassen en -opsommingen kunt registreren als typeversnellers in een module. Voeg het fragment toe aan de hoofdscriptmodule na een typedefinitie. Zorg ervoor dat de $ExportableTypes variabele elk van de typen bevat die u beschikbaar wilt maken voor gebruikers wanneer ze de module importeren. Voor de andere code is geen bewerking vereist.
# Define the types to export with type accelerators.
$ExportableTypes =@(
[DefinedTypeName]
)
# Get the internal TypeAccelerators class to use its static methods.
$TypeAcceleratorsClass = [psobject].Assembly.GetType(
'System.Management.Automation.TypeAccelerators'
)
# Ensure none of the types would clobber an existing type accelerator.
# If a type accelerator with the same name exists, throw an exception.
$ExistingTypeAccelerators = $TypeAcceleratorsClass::Get
foreach ($Type in $ExportableTypes) {
if ($Type.FullName -in $ExistingTypeAccelerators.Keys) {
$Message = @(
"Unable to register type accelerator '$($Type.FullName)'"
'Accelerator already exists.'
) -join ' - '
throw [System.Management.Automation.ErrorRecord]::new(
[System.InvalidOperationException]::new($Message),
'TypeAcceleratorAlreadyExists',
[System.Management.Automation.ErrorCategory]::InvalidOperation,
$Type.FullName
)
}
}
# Add type accelerators for every exportable type.
foreach ($Type in $ExportableTypes) {
$TypeAcceleratorsClass::Add($Type.FullName, $Type)
}
# Remove type accelerators when the module is removed.
$MyInvocation.MyCommand.ScriptBlock.Module.OnRemove = {
foreach($Type in $ExportableTypes) {
$TypeAcceleratorsClass::Remove($Type.FullName)
}
}.GetNewClosure()
Wanneer gebruikers de module importeren, zijn alle typen die zijn toegevoegd aan de typeversnellers voor de sessie direct beschikbaar voor IntelliSense en voltooiing. Wanneer de module wordt verwijderd, zijn dit de typeversnellers.
Opsommingen handmatig importeren vanuit een PowerShell-module
Import-Module en de #requires instructie importeert alleen de modulefuncties, aliassen en variabelen, zoals gedefinieerd door de module. Opsommingen worden niet geïmporteerd.
Als een module klassen en opsommingen definieert, maar geen typeversnellers toevoegt voor deze typen, gebruikt u een using module instructie om ze te importeren.
Met using module de instructie worden klassen en opsommingen geïmporteerd uit de hoofdmodule (ModuleToProcess) van een scriptmodule of binaire module. Klassen die zijn gedefinieerd in geneste modules of klassen die zijn gedefinieerd in scripts die zijn gedefinieerd in de hoofdmodule, worden niet consistent geïmporteerd. Definieer klassen die u rechtstreeks in de hoofdmodule beschikbaar wilt maken voor gebruikers buiten de module.
Zie using voor meer informatie over de instructie.
Nieuw gewijzigde code laden tijdens de ontwikkeling
Tijdens het ontwikkelen van een scriptmodule is het gebruikelijk om wijzigingen aan te brengen in de code en vervolgens de nieuwe versie van de module te laden met behulp van Import-Module de parameter Force . Dit werkt alleen voor wijzigingen in functies in de hoofdmodule.
Import-Module laadt geen geneste modules opnieuw. Er is ook geen manier om bijgewerkte klassen te laden.
Om ervoor te zorgen dat u de nieuwste versie uitvoert, moet u een nieuwe sessie starten.
Klassen en opsommingen die zijn gedefinieerd in PowerShell en geïmporteerd met een using instructie, kunnen niet worden uitgepakt.
Een andere gangbare ontwikkelpraktijk is het scheiden van uw code in verschillende bestanden. Als u een functie hebt in het ene bestand dat gebruikmaakt van opsommingen die zijn gedefinieerd in een andere module, moet u de using module instructie gebruiken om ervoor te zorgen dat de functies over de inventarisatiedefinities beschikken die nodig zijn.
Beperkingen
U kunt opsommingswaarden die zijn gedefinieerd in PowerShell niet voorzien van kenmerken. U kunt de opsommingsdeclaratie zelf alleen versieren, net als met de FlagsAttribute voor het definiëren van een opsomming als een set bitvlagmen.
Oplossing: Geen
U kunt geen methoden definiëren in opsommingsdefinities en PowerShell biedt geen ondersteuning voor het definiëren van [extensiemethoden] zoals C#.
Tijdelijke oplossing: gebruik de cmdlet Update-TypeData om leden te definiëren
ScriptMethodvoor de opsomming.
