about_Enum

Rövid leírás

Az 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

Az enum utasítás lehetővé teszi, hogy egy erősen gépelt címkekészletet 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]) függvényt használják alapul szolgáló típusként. 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.

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.

Syntax

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>]...] [Flag()] 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. video 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; lásd a következőhöz tartozó létrehozott értékeket: ogg, oga, moggvagy 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

Feljegyzés

GetEnumNames() és GetEnumValues() úgy tűnik, hogy ugyanazokat az eredményeket adja vissza; az elnevezett értékek listáját. Belsőleg azonban számba adja az értékeket, GetEnumValues() majd az értékeket nevekké alakítja. Olvassa el figyelmesen a listát, és láthatja, hogy ogg, ogaés mogg megjelenik a kimenetben GetEnumNames(), de csak a kimenete GetEnumValues() jelenik meg ogg. Ugyanez történik a jpg, jpegés mpg, mpeg. A Szinonimák értékeinek PowerShell-neve nem determinisztikus.

A metódussal GetEnumName() 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 szintaxissal [<enum-name>]::<label>rendelkező címke alapján adhat meg.

[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 az Eszköz és az Archív attribútumok értékét teszteli az értékben$file2.

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

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

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

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

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

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

Az alábbi példában a függvény ConvertTo-LineEndingRegex az InputObject paramétert EndOfLine típussal határozza meg.

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ő hívási ConvertTo-LineEndingRegex utasítás a számbavételi értéket CRadja át. A második utasítás átadja a sztringet 'CRLF', amely egy LineEndingre kerül. A harmadik utasítás a paraméter értékét 2 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>Enumpé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 az Min integráltípus minimális értékére van beállítva. Meghatározza az Max integráltípus maximális értékére beállított értéket.

  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 hurkok az enumerálási típusok felett, a GetEnumValuesAsUnderlyingType() metódus használatával az értékeket az 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 számbavételi típus, enumerálási érték és formázott sztring formázott sztringkimenetét adja vissza. A kimenet ugyanaz, mint a ToString metódus meghívása 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ázási sztringek a következőkG: vagyg, D vagy d, X vagy x, ésF.f További információ: Sztringek számbavétele.

Az alábbi példa a támogatott enumerálási formátum sztringjeinek mindegyikével konvertálja a TaskState enumerálás egyes értékeit a sztring-ábrázolásokká.

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 módszer 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ési módszer az enumerálás minden definiált értékét az alapul szolgáló típusként adja vissza.

[<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ő számbavételi é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 a ModuleFeatures jelző számbavételét határozza meg, és megmutatja, hogy az érték 39 mely jelölőkkel rendelkezik.

[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 akkor ad vissza $true értéket, ha a bemeneti érték definiálva van az enumeráláshoz és más esetben $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ánymetó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. A formázással kapcsolatos további információkért lásd a számbavételi értékek formázását ismertető témakört.

Feljegyzés

Egy adott érték szinonimáit definiáló enumerálások esetén ne írjon olyan kódot, amely a kimenettől ToString()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 Shade enumerációt Gray definiálja szinonimaként Grey. 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 adott névvé konvertáló szinonimaértéktől függ. 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 szinonimákként GreyGray és szinonimákként definiálja a Shade enumerálást.

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 Late é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 az HasFlag() érték metódusát, vagy használja a bináris összehasonlító operátort -band.

A jelölő-számbavételek használatát és a jelölő beállításának ellenőrzését bemutató mintát a 3. példában talál.

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ás típusú paraméterek viselkedését bemutató minta esetében lásd a 4. példát.

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 (System.Int32) enumerálást [int] hozza létre alapul szolgáló típusként.

Az enumerálás alapjául szolgáló típusnak integrál 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ó: Sztringek számbavétele.

Az alábbi példa a támogatott enumerálási formátumú sztringek (G vagy g, D vagy d, X vagy x, és Ff ) használatával konvertálja a TaskState enumerálás minden tagját a sztringreprezentációkká.

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 GF formázási sztringek a vesszővel tagolt érték jelölőinek listáját jelenítik meg. Az utolsó érték 8nem 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 úgy, hogy legalább egy jelölő duplikálása nélkül összegződjenek 8 .

Bővítménymetelyek definiálása az Update-TypeData használatával

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álhatja ScriptMethod az enumerálás tagjait.

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 utasítás meghívása using module 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.

Feljegyzés

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. Ahhoz, hogy intelliSense és kiegészítési javaslatokat kapjon a VS Code egyéni típusaihoz, hozzá kell adnia egy utasítást using module 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 az #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 utasítással using module importálhatja őket.

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

Az utasítással kapcsolatos további információkért lásd: using 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 Force paraméterrelImport-Module. 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 utasítással using importált osztályok és enumerálások 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, az utasítással using module 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, ahogyan 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.