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
, mogg
vagy jpg
, jpeg
vagy 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 CR
adja á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ő:
Definiál egy ,
<type>Enum
példáulbyteEnum
. 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 azMax
integráltípus maximális értékére beállított értéket.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 Grey
Gray
é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.Bytesbyte
- System.SByteshort
- System.Int16ushort
- System.UInt16int
- System.Int32uint
- System.UInt32long
- System.Int64ulong
- 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 F
f
) 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 G
F
formázási sztringek a 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 ú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.
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: