about_Enum

Rövid leírás

A enum utasítás enumerálást deklarál. Az enumerálás egy különálló típus, amely nevesített címkékből, úgynevezett enumerátorlistából áll.

Hosszú leírás

A enum utasítás lehetővé teszi, hogy erősen begépelt címkéket hozzon létre. Ezt a számbavételt anélkül használhatja a kódban, hogy elemeznie vagy ellenőriznie kellene a helyesírási hibákat.

Az enumerálások belsőleg integrál értéktípusokként jelennek meg, nulla kezdőértékkel. A PowerShell-számbavételek alapértelmezés szerint a System.Int32 ([int]) alapul szolgáló típust használják. A PowerShell alapértelmezés szerint a lista első címkéjét nulla értékhez rendeli. A PowerShell alapértelmezés szerint egymást követő egész számokkal rendeli hozzá a többi címkét.

SZINTAXIS

A definícióban bármilyen egész számértéket megadhat címkéknek. A hozzárendelt érték nélküli címkék a következő egész számot veszik fel.

Az enumerálási címkék csak betűket, aláhúzásjeleket és számjegyeket tartalmazhatnak, de nem kezdődhetnek számjegyekkel. A címke nem lehet idézőjeles sztring; a függvénynek csupaszszó sztringként kell elemeznie. A címkék sztringként vannak elemezve, nem kulcsszavakként. Ezért létrehozhat egy olyan címkét, amely megegyezik a nyelvi kulcsszó nevével (például return).

Az enumerálások a következő szintaxisokat használják:

• Egész számbavétel definíciójának szintaxisa

  [[<attribute>]...] enum <enum-name> {
      <label> [= <int-value>]
      ...
  }
  

• Konkrét mögöttes típus enumerálási definíciószintaxisa

  [[<attribute>]...] enum <enum-name> : <underlying-type-name> {
      <label> [= <int-value>]
      ...
  }
  

• A számbavételi definíció szintaxisának megjelölése

  [[<attribute>]...] [Flags()] enum <enum-name>[ : <underlying-type-name>] {
      <label 0> [= 1]
      <label 1> [= 2]
      <label 2> [= 4]
      <label 3> [= 8]
      ...
      ...
  }
  

• Hozzáférés-szintaxis számbavétele

  [<enum-name>]::<label>
  

Példák

1. példa – Minimális számbavétel

Az alábbi kódblokk a MarkdownUnorderedListCharacter enumerálást három címkével határozza meg. Nem rendel explicit értékeket egyetlen címkéhez sem.

enum MarkdownUnorderedListCharacter {
    Asterisk
    Dash
    Plus
}

A következő kódblokk bemutatja, hogyan viselkednek mind az egész számok, mind a sztringértékek az enumerálási típusba való beíráskor.

$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

Az enumerálás értékével egyenlő öntvény egész számokat ad vissza. Az enumerálás címkéjének megfelelő karakterláncok visszaadják az enumerálást.

2. példa – Explicit és szinonimák számbavételi értékei

Az alábbi példa a médiafájlokhoz kapcsolódó objektumok számbavételét mutatja be. A definíció explicit értékeket rendel a music, picture, videomögöttes értékeihez . Az explicit hozzárendelést közvetlenül követő címkék a következő egész számot kapják meg. Szinonimákat úgy hozhat létre, hogy ugyanazt az értéket egy másik címkéhez rendeli; a következő értékek: ogg, oga, mogg, jpg, jpegvagy mpg, mpeg.

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
}

A GetEnumNames() metódus az enumerálás címkéinek listáját adja vissza.

[MediaTypes].GetEnumNames()

unknown
music
mp3
aac
ogg
oga
mogg
picture
jpg
jpeg
png
video
mpg
mpeg
avi
m4v

A GetEnumValues() metódus az enumerálás értékeinek listáját adja vissza.

[MediaTypes].GetEnumValues()

unknown
music
mp3
aac
ogg
ogg
ogg
picture
jpg
jpg
png
video
mpg
mpg
avi
m4v

Jegyzet

GetEnumNames() és GetEnumValues() úgy tűnik, hogy ugyanazokat az eredményeket adja vissza; névvel ellátott értékek listája. Belsőleg azonban GetEnumValues() számba adja az értékeket, majd az értékeket nevekké alakítja. Gondosan olvassa el a listát, és láthatja, hogy ogg, ogaés mogg jelennek meg a GetEnumNames()kimenetében, de a GetEnumValues() kimenete csak oggjelenik meg . Ugyanez történik jpg, jpegés mpg, mpeg. A Szinonimák értékeinek PowerShell-neve nem determinisztikus.

A GetEnumName() metódussal lekérheti egy adott értékhez társított nevet. Ha egy értékhez több név is társítva van, a metódus az elsőként megadott nevet adja vissza.

[MediaTypes].GetEnumName(15)

ogg

Az alábbi példa bemutatja, hogyan képezheti le az egyes neveket az értékéhez.

[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

Egyetlen enumerálási értéket a címkéje alapján adhat meg a [<enum-name>]::<label>szintaxissal.

[MediaTypes]::png
[MediaTypes]::png -eq 22

png
True

3. példa – Enumerálás jelzőként

Az alábbi kódblokk bitjelölők halmazaként hozza létre a FileAttributes enumerálást. Az egyes címkék értéke duplája az előző címke értékének.

[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

Annak ellenőrzéséhez, hogy egy adott jelölő be van-e állítva, használhatja a bináris összehasonlító operátort -band. Ez a példa a Eszköz és a Archív attribútumokat teszteli az $file2értékében.

PS > ($file2 -band [FileAttributes]::Device) -eq [FileAttributes]::Device
True

PS > ($file2 -band [FileAttributes]::Archive) -eq [FileAttributes]::Archive
False

A HasFlag() metódussal azt is tesztelheti, hogy egy adott jelölő van-e beállítva. Ez a példa a Eszköz és Rejtett attribútumokat teszteli az $file1értékében.

PS > $file1.HasFlag([FileAttributes]::Device)
True

PS > $file1.HasFlag([FileAttributes]::Hidden)
False

4. példa – Enumerálás paraméterként

A következő példában a ConvertTo-LineEndingRegex függvény határozza meg az InputObject paramétert az EndOfLine típusával.

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

A példában az első, ConvertTo-LineEndingRegex meghívást hívó utasítás a CRenumerálási értékét adja át. A második utasítás átadja a 'CRLF'sztringet , amelyet egy LineEnding. A harmadik utasítás a paraméter 2 értékét adja meg, amely a LF címkére van leképezve.

Az argumentumkiegészítési beállításokat a következő szöveg beírásával tekintheti meg a PowerShell-parancssorba:

ConvertTo-LineEndingRegex -InputObject <Tab>

Ha érvénytelen címkenevet vagy numerikus értéket ad meg a paraméterhez, a függvény hibát jelez.

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".

5. példa – Adott mögöttes típusok számbavétele

A PowerShell 6.2-től kezdődően definiálhat enumerációkat egy adott mögöttes típussal. Ez a példa az enumerálás érvényes mögöttes típusait mutatja be.

Az első kódblokk két változót inicializál tömbként. $EnumTypes egy üres tömb, amely a dinamikusan létrehozott típusok tárolására használható. $IntegralTypes egy tömb, amely az enumerálás érvényes mögöttes típusait tartalmazza.

$EnumTypes     = @()
$IntegralTypes = @(
    'byte', 'sbyte', 'short', 'ushort', 'int', 'uint', 'long', 'ulong'
)

A következő kódblokk meghatározza az enumerálási definíciók dinamikus létrehozásához használható sablont. Amikor a {0} formátumhelyőrzőt egy integrált típusnévre cseréli, a sablon létrehoz egy szkriptblokkot, amely a következő:

1. Definiál egy <type>Enumnevű enumerálást, például byteEnum. A definiált enumerálás a megadott integráltípust használja alapul szolgáló értéktípusként.

   Az enumerálás a Min az integráltípus minimális értékére van beállítva. Meghatározza a Max értéket, amely az integráltípus maximális értékére van beállítva.

2. Az újonnan definiált típust adja vissza.

$DefinitionTemplate = @"
enum {0}Enum : {0} {{
    Min = [{0}]::MinValue
    Max = [{0}]::MaxValue
}}

[{0}Enum]
"@

A következő kódblokk a sablon használatával hoz létre és hív meg egy szkriptblokkot az aktuális hatókörben. Hozzáadja a visszaadott típusdefiníciókat a $EnumTypes tömbhöz.

foreach ($IntegralType in $IntegralTypes) {
    $Definition  = $DefinitionTemplate -f $IntegralType
    $ScriptBlock = [scriptblock]::Create($Definition)
    $EnumTypes  += . $ScriptBlock
}

Az utolsó kódblokk ciklusok az enumerálási típusok felett, a GetEnumValuesAsUnderlyingType() metódus használatával az értékeket alapul szolgáló típusként sorolja fel. A hurok minden értékhez létrehoz egy új objektumot, amely megjeleníti az enumerálás típusát, az értéktípust, a címkét és a tényleges értéket.

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

Enumerálási módszerek

Az alábbi lista hasznos módszereket tartalmaz a PowerShell enumerációihoz és azok használatához.

Formátum

A Format() statikus metódus egy adott enumerálási típus, enumerálási érték és formázási sztring formázott sztringkimenetét adja vissza. A kimenet megegyezik az ToString metódus meghívásával a megadott formátumsztringgel rendelkező értéken.

Használhatja a statikus metódust a System.Enum alaposztálytípuson vagy egy adott enumerálási típuson.

[System.Enum]::Format([<enum-name>], <value>, <format-string>)

[<enum-name>]::Format([<enum-name>], <value>, <format-string>)

Az érvényes formátumsztringek a következők: G vagy g, D vagy d, X vagy x, valamint F vagy f. További információ: Számbavételi formázási sztringek.

Az alábbi példa a támogatott számbavételi formátum sztringjeinek mindegyikével konvertálja a TaskState enumerálás minden értékét a sztringreprezentációkká.

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

A GetEnumName() tükröződési metódus egy adott számbavételi érték nevét adja vissza. A bemeneti értéknek érvényes alapul szolgáló típusnak kell lennie egy enumeráláshoz, például egész számhoz vagy enumerálási értékhez. Ha egy értékhez több név is társítva van, a metódus az elsőként megadott nevet adja vissza.

[<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

A GetEnumNames() tükröződési módszer minden enumerálási érték nevét sztringként adja vissza. A kimenet szinonimákat tartalmaz.

[<enum-name>].GetEnumNames()

enum Season {
    Unknown
    Spring
    Summer
    Autumn
    Winter
    Fall   = 3
}

[Season].GetEnumNames()

Unknown
Spring
Summer
Fall
Autumn
Winter

GetEnumUnderlyingType

A GetEnumUnderlyingType() tükröződési módszer az enumerálási értékek alapjául szolgáló típust adja vissza.

[<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

A GetEnumValues() tükröződési módszer az enumerálás minden definiált értékét visszaadja.

[<enum-name>].GetEnumValues()

enum Season {
    Unknown
    Spring
    Summer
    Autumn
    Winter
    Fall   = 3
}

[Season].GetEnumValues()

Unknown
Spring
Summer
Fall
Fall
Winter

GetEnumValuesAsUnderlyingType

A GetEnumValuesAsUnderlyingType() tükröződési módszer az enumerálás minden definiált értékét visszaadja alapul szolgáló típusként.

[<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

A HasFlag példánymetódus határozza meg, hogy egy bitjelző be van-e állítva egy jelölő enumerálási értékéhez. Ennek a módszernek a használata rövidebb és könnyebben olvasható, mint a bináris összehasonlítás és az egyenértékűség ellenőrzése.

<enum-value>.HasFlag(<enum-flag-value>)

Az alábbi példa az ModuleFeatures jelző számbavételét határozza meg, és megjeleníti, hogy mely jelölőkkel rendelkezik az 39 érték.

[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

A IsDefined() statikus metódus $true ad vissza, ha a bemeneti érték az enumeráláshoz van definiálva, máskülönben $false. Ezzel a módszerrel ellenőrizheti, hogy egy érték érvényes-e az enumerálásra anélkül, hogy érvénytelen argumentumhibákat kellene kezelnie.

Használhatja a statikus metódust a System.Enum alaposztálytípuson vagy egy adott enumerálási típuson.

[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

A ToString() példány metódus egy enumerálási érték címkéjét adja vissza. Ez a metódus az enumerálási érték kimenetként való megjelenítésének alapértelmezett nézete is. Megadhat egy formátumsztringet is, amely szabályozza az érték megjelenítését. További információ a formázásról: Formázási számbavételi értékek.

Jegyzet

Egy adott érték szinonimáit definiáló enumerálások esetén ne írjon olyan kódot, amely a ToString()kimenetétől függ. A metódus bármilyen érvényes nevet visszaadhat az értéknek.

<enum-value>.ToString([<format-string>])

Az alábbi példa a Árnyékolás enumerálást definiálja, Gray pedig a Greyszinonimájaként. Ezután olyan objektumokat ad ki, amelyek a tényleges számértéket, az enumot sztringként, az enumot pedig egész számként jelenítik meg.

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

Számbavételi érték szinonimái

Megadhat olyan enumerálásokat, amelyek különböző neveket adnak ugyanahhoz az egész számhoz. Ha így tesz, az azonos mögöttes értékre mutató neveket szinonimáknak nevezzük. A szinonimák számbavétele lehetővé teszi, hogy a felhasználók különböző neveket adjanak meg ugyanahhoz az értékhez.

Ha szinonimákat tartalmazó enumerálást határoz meg, ne írjon olyan kódot, amely egy szinonimaértéktől függ, és egy adott név lesz. Megbízhatóan írhat olyan kódot, amely szinonimasztringet konvertál az enumerálási értékre. Ha magát az enumerálási értéket használja, sztring helyett mindig számbavételi értékként vagy annak alapjául szolgáló típusként hasonlítsa össze.

Az alábbi kódblokk a Shade enumerálást Grey és Gray szinonimákként határozza meg.

enum Shade {
    White
    Grey
    Gray = 1
    Black
}

[Shade]'Grey' -eq [Shade]::Gray
[Shade]::Grey -eq 1
[Shade]'Gray' -eq 1

True
True
True

Enumerálások jelölőként

Az enumerálás egyik gyakori használata a kölcsönösen kizáró értékek halmazának ábrázolása. Egy ArrivalStatus-példány például Korai, OnTime vagy Késő értékű lehet. Nincs értelme egy ArrivalStatus példány értékének, hogy egynél több enumerálási állandót tükrözzön.

Más esetekben azonban az enumerálási objektumok értéke több enumerálási tagot is tartalmazhat, és minden tag egy bit mezőt jelöl az enumerálási értékben. A FlagsAttribute használatával jelezheti, hogy az enumerálás bitmezőkből áll a felhasználók által kombinálható jelzőkként.

Ahhoz, hogy az enumerálások jelölőként megfelelően működjenek, az egyes címkék egész számának értékét két hatványra kell állítania. Ha nem ad meg egy címkéhez tartozó értéket, a PowerShell az előző címkénél magasabb értékre állítja be az értéket.

Meghatározhat értékeket a gyakran használt jelölőkombinációkhoz, így a felhasználók könnyebben adhatnak meg egyszerre egy jelölőkészletet. Az érték nevének a jelölők kombinált neveinek kell lennie. Az egész szám értékének a jelzőértékek összegének kell lennie.

Annak megállapításához, hogy egy adott jelölő van-e beállítva egy értékhez, használja a HasFlag() metódust az értéken, vagy használja a bináris összehasonlító operátort -band.

A jelölő számbavételét és a jelölő beállításának ellenőrzését bemutató mintaért tekintse meg 3. példa.

Enumerálások paraméterekként

Definiálhat olyan parancsmagparamétereket, amelyek típusként számokat használnak. Ha egy paraméter típusaként enumerálást ad meg, a felhasználók automatikusan befejezik és érvényesítik a paraméter értékét. Az argumentumkiegészítés az enumerálás érvényes címkéinek listáját javasolja.

Ha egy paraméter típusa enumerálás, a következők bármelyikét megadhatja:

• Enumerálás, például [<EnumType>]::<Label>
• Az enumerálás címkéje sztringként
• Enumerálás numerikus értéke

Az enumerálási típusú paraméterek viselkedését bemutató minta a 4. példa.

Adott mögöttes típusok számbavétele

A PowerShell 6.2-től kezdődően definiálhat enumerációkat egy adott mögöttes típussal. Ha egy enumerálást meghatározott mögöttes típus nélkül határoz meg, a PowerShell a [int] (System.Int32) alapul szolgáló típusként hozza létre az enumerálást.

Az enumerálás alapjául szolgáló típusnak integrált numerikus típusnak kell lennie. Az alábbi lista tartalmazza az érvényes típusokat a rövid és a teljes típusnévvel:

• byte - System.Byte
• sbyte - System.SByte
• short - System.Int16
• ushort - System.UInt16
• int - System.Int32
• uint - System.UInt32
• long - System.Int64
• ulong - System.UInt64

Az enumeráláshoz definiálhat egy adott mögöttes típust rövid vagy teljes típusú névként. A következő definíciók funkcionálisan azonosak. Csak a mögöttes típushoz használt név különbözik.

enum LongValueEnum : long {
    Zero
    One
    Two
}

enum LongValueEnum : System.Int64 {
    Zero
    One
    Two
}

Számbavételi értékek formázása

Az enumerálási értékeket a statikus Formátum metódus meghívásával, valamint a példány ToString metódus túlterhelésének meghívásával alakíthatja át sztringre. A formázási sztringgel pontosan szabályozhatja, hogy az enumerálási érték pontosan hogyan jelenik meg sztringként. További információ: Számbavételi formázási sztringek.

Az alábbi példa a támogatott enumerálási formátum sztringjeinek (G vagy g, D vagy d, X vagy x, valamint F vagy f) használatával konvertálja a TaskState enumerálás minden tagját a sztringre.

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

Az alábbi példa a formátumsztringeket használja egy jelölő számbavételi értékeihez.

[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

Figyelje meg, hogy a jelölők számbavétele esetén a G és F formázási sztringek vesszővel tagolt érték jelölőinek listáját jelenítik meg. Az utolsó érték ( 8) nem sorol fel semmilyen jelölőt, mert valójában nem érvényes jelölőkészlet. Az enumerálási jelzők nem kombinálhatók a 8 összegének lekéréséhez legalább egy jelölő duplikálása nélkül.

Bővítménymetelyek definiálása Update-TypeData

Az enumerálás deklarációjában nem definiálhat metódusokat. Az enumerálás funkciójának kibővítéséhez az Update-TypeData parancsmaggal definiálhat ScriptMethod tagokat az enumeráláshoz.

Az alábbi példa a Update-TypeData parancsmaggal ad hozzá egy GetFlags() metódust a FileAttributes jelző számbavételéhez. Az értékhez beállított jelölők tömbjének visszaadása.

[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

Számbavételek exportálása típusgyorsítókkal

A PowerShell-modulok alapértelmezés szerint nem exportálják automatikusan a PowerShellben definiált osztályokat és számbavételeket. Az egyéni típusok nem érhetők el a modulon kívül using module utasítás meghívása nélkül.

Ha azonban egy modul típusgyorsítókat ad hozzá, ezek a típusgyorsítók azonnal elérhetők lesznek a munkamenetben, miután a felhasználók importálták a modult.

Jegyzet

A típusgyorsítók munkamenethez való hozzáadása belső (nem nyilvános) API-t használ. Az API használata ütközéseket okozhat. Az alábbi minta hibát jelez, ha a modul importálásakor már létezik egy azonos nevű típusgyorsító. Emellett eltávolítja a típusgyorsítókat, amikor eltávolítja a modult a munkamenetből.

Ez a minta biztosítja, hogy a típusok elérhetők legyenek egy munkamenetben. Ez nem befolyásolja az IntelliSense-t vagy a befejezést, amikor szkriptfájlt hoz létre a VS Code-ban. Az IntelliSense és a VS Code egyéni típusaira vonatkozó kiegészítési javaslatok beszerzéséhez hozzá kell adnia egy using module utasítást a szkript tetejére.

Az alábbi minta bemutatja, hogyan regisztrálhat PowerShell-osztályokat és számbavételeket típusgyorsítókként egy modulban. Adja hozzá a kódrészletet a gyökérszkriptmodulhoz a típusdefiníciók után. Győződjön meg arról, hogy a $ExportableTypes változó tartalmazza azokat a típusokat, amelyeket elérhetővé szeretne tenni a felhasználók számára a modul importálásakor. A másik kód nem igényel szerkesztést.

# 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()

Amikor a felhasználók importálják a modult, a munkamenet típusgyorsítóihoz hozzáadott típusok azonnal elérhetők lesznek az IntelliSense és a befejezés számára. A modul eltávolításakor a típusgyorsítók is.

Enumerációk manuális importálása PowerShell-modulból

Import-Module és a #Requires utasítás csak a modul által meghatározott modulfüggvényeket, aliasokat és változókat importálja. Az enumerálások nincsenek importálva.

Ha egy modul osztályokat és számbavételeket határoz meg, de nem ad hozzá típusgyorsítókat ezekhez a típusokhoz, egy using module utasítással importálhatja őket.

A using module utasítás osztályokat és számbavételeket importál egy szkriptmodul vagy bináris modul gyökérmoduljából (ModuleToProcess). Nem importálja következetesen a beágyazott modulokban vagy szkriptekben definiált osztályokban definiált osztályokat, amelyek pontforrásból vannak a gyökérmodulba. Definiálja azokat az osztályokat, amelyeket a modulon kívüli felhasználók számára közvetlenül a gyökérmodulban szeretne elérhetővé tenni.

A using utasítással kapcsolatos további információkért lásd: about_Using.

Újonnan módosított kód betöltése a fejlesztés során

A szkriptmodul fejlesztése során gyakori, hogy módosítja a kódot, majd betölti a modul új verzióját a Import-Module a Force paraméterrel. Ez csak a gyökérmodul függvényeinek módosítására használható. Import-Module nem tölt be beágyazott modulokat. Emellett nem lehet betölteni a frissített osztályokat.

Ahhoz, hogy a legújabb verziót futtassa, új munkamenetet kell indítania. A PowerShellben definiált és using utasítással importált osztályok és enumerációk nem távolíthatók el.

Egy másik gyakori fejlesztési gyakorlat a kód különböző fájlokra való elkülönítése. Ha egy másik modulban definiált enumerálásokat használó fájlban van függvény, a using module utasítással győződjön meg arról, hogy a függvények rendelkeznek a szükséges számbavételi definíciókkal.

Korlátozások

• A PowerShellben definiált enumerálási értékeket nem lehet attribútumokkal díszíteni. Csak magát az enumerálási deklarációt díszítheti, ahogy a FlagsAttribute is, amely bitjelölők halmazaként definiálja az enumerálást.

  Megkerülő megoldás: Nincs

• Az enumerálási definíciókban nem definiálhat metódusokat, és a PowerShell nem támogatja a [bővítménymetelyek] (például C#) definiálását.

  Megkerülő megoldás: Az Update-TypeData parancsmaggal definiálhat ScriptMethod tagokat az enumeráláshoz.