about_Enum
Kısa açıklama
deyimi enum bir numaralandırma bildirir. Numaralandırma, numaralandırıcı listesi olarak adlandırılan adlandırılmış etiketler kümesinden oluşan ayrı bir türdür.
Uzun açıklama
deyimi, enum kesin olarak belirlenmiş bir etiket kümesi oluşturmanıza olanak tanır. Bu numaralandırmayı kodda, yazım hatalarını ayrıştırmak veya denetlemek zorunda kalmadan kullanabilirsiniz.
Numaralandırmalar dahili olarak sıfır başlangıç değerine sahip integral değer türleri olarak temsil edilir. Varsayılan olarak, PowerShell sabit listeleri temel tür olarak System.Int32 ([int]) kullanır. Varsayılan olarak, PowerShell listedeki ilk etiketi sıfır olarak atar. Varsayılan olarak, PowerShell kalan etiketleri ardışık tamsayılarla atar.
Tanımda, etiketlere herhangi bir tamsayı değeri verebilirsiniz. Değer atanmamış etiketler sonraki tamsayı değerini alır.
Sözdizimi
Numaralandırmalar aşağıdaki söz dizimlerini kullanır:
Tamsayı numaralandırma tanımı söz dizimi
[[<attribute>]...] enum <enum-name> {
<label> [= <int-value>]
...
}
Belirli temel tür sabit listesi tanımı söz dizimi
[[<attribute>]...] enum <enum-name> : <underlying-type-name> {
<label> [= <int-value>]
...
}
Bayrak numaralandırma tanımı söz dizimi
[[<attribute>]...] [Flag()] enum <enum-name>[ : <underlying-type-name>] {
<label 0> [= 1]
<label 1> [= 2]
<label 2> [= 4]
<label 3> [= 8]
...
...
}
Numaralandırma erişimi söz dizimi
[<enum-name>]::<label>
Örnekler
Örnek 1 - En az numaralandırma
Aşağıdaki kod bloğu, üç etiketli MarkdownUnorderedListCharacter numaralandırmasını tanımlar. Herhangi bir etikete açık değerler atamaz.
enum MarkdownUnorderedListCharacter {
Asterisk
Dash
Plus
}
Sonraki kod bloğu, numaralandırma türüne yayınlandığında hem tamsayı hem de dize değerlerinin nasıl davrandığını gösterir.
$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
Bir sabit listesi değerine eşit tamsayıları atama, bu numaralandırmayı döndürür. Bir sabit listesi etiketiyle aynı dizeleri atama, bu numaralandırmayı döndürür.
Örnek 2 - Açık ve eş anlamlı numaralandırma değerleri
Aşağıdaki örnek, medya dosyalarıyla bağıntılı nesnelerin bir numaralandırmasını gösterir. Tanım, temel alınan , , picturevideodeğerlerine açık değerler musicatar. Açık atamanın hemen ardından gelen etiketler sonraki tamsayı değerini alır. Aynı değeri başka bir etikete atayarak eş anlamlılar oluşturabilirsiniz; için oluşturulan değerlere bakın: ogg, oga, mogg, veya jpg, jpegveya 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
}
yöntemi, GetEnumNames() numaralandırma için etiketlerin listesini döndürür.
[MediaTypes].GetEnumNames()
unknown
music
mp3
aac
ogg
oga
mogg
picture
jpg
jpeg
png
video
mpg
mpeg
avi
m4v
yöntemi, GetEnumValues() numaralandırma için değerlerin listesini döndürür.
[MediaTypes].GetEnumValues()
unknown
music
mp3
aac
ogg
ogg
ogg
picture
jpg
jpg
png
video
mpg
mpg
avi
m4v
Not
GetEnumNames() ve GetEnumValues() aynı sonuçları döndürecek gibi görünüyor; adlandırılmış değerlerin listesi. Ancak, GetEnumValues() dahili olarak değerleri numaralandırır, ardından değerleri adlarla eşler. Listeyi dikkatlice okuduğunuzda , ogave öğesinin oggçıktısında GetEnumNames()göründüğünü ancak yalnızca çıktısının gösterildiğini GetEnumValues() oggfark mogg edersiniz. Aynı şey , ve mpg, jpegiçin jpgde mpegolur. PowerShell'in eş anlamlı değerler için döndürdüğü ad belirleyici değildir.
Yöntemini kullanarak GetEnumName() belirli bir değerle ilişkilendirilmiş bir ad alabilirsiniz. Bir değerle ilişkilendirilmiş birden çok ad varsa, yöntemi ilk tanımlı adı döndürür.
[MediaTypes].GetEnumName(15)
ogg
Aşağıdaki örnekte, her adın kendi değerine nasıl eş adım adım gösterildiği gösterilmiştir.
[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
söz dizimi [<enum-name>]::<label>ile etiketine göre tek bir sabit listesi değeri belirtebilirsiniz.
[MediaTypes]::png
[MediaTypes]::png -eq 22
png
True
Örnek 3 - Bayrak olarak numaralandırma
Aşağıdaki kod bloğu FileAttributes numaralandırmasını bit bayrakları kümesi olarak oluşturur. Her etiketin değeri, önceki etiketin değerinin iki katıdır.
[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
Belirli bir bayrağın ayarlanıp ayarlanmadığını test etmek için ikili karşılaştırma işlecini -bandkullanabilirsiniz. Bu örnek, değerindeKimlik $file2ve Arşiv özniteliklerini test eder.
PS > ($file2 -band [FileAttributes]::Device) -eq [FileAttributes]::Device
True
PS > ($file2 -band [FileAttributes]::Archive) -eq [FileAttributes]::Archive
False
Belirli bir bayrağın ayarlanıp ayarlanmadığını HasFlag() test etmek için yöntemini de kullanabilirsiniz.
Bu örnek, değerindeki $file1Device ve Hidden özniteliklerini test eder.
PS > $file1.HasFlag([FileAttributes]::Device)
True
PS > $file1.HasFlag([FileAttributes]::Hidden)
False
Örnek 4 - Parametre olarak numaralandırma
Aşağıdaki örnekte işlevConvertTo-LineEndingRegex, InputObject parametresini EndOfLine türüyle tanımlar.
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
Örnekte, ilk deyim çağrısı ConvertTo-LineEndingRegex için CRnumaralandırma değerini geçirir. İkinci deyim, bir LineEnding'e yayınlanan dizesini 'CRLF'geçirir. Üçüncü deyim, etiketle eşlenen parametresinin LF değerini 2 belirtir.
PowerShell isteminize aşağıdaki metni yazarak bağımsız değişken tamamlama seçeneklerini görebilirsiniz:
ConvertTo-LineEndingRegex -InputObject <Tab>
Parametresi için geçersiz bir etiket adı veya sayısal değer belirttiğinizde işlev bir hata oluşturur.
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".
Örnek 5 - Belirli temel türler içeren numaralandırmalar
PowerShell 6.2'den başlayarak, belirli bir temel türe sahip numaralandırmalar tanımlayabilirsiniz. Bu örnekte bir sabit listesi için geçerli temel türler gösterilmektedir.
İlk kod bloğu iki değişkeni dizi olarak başlatır. $EnumTypes , dinamik olarak oluşturulan türleri tutmak için boş bir dizidir. $IntegralTypes , bir sabit listesi için geçerli temel türleri içeren bir dizidir.
$EnumTypes = @()
$IntegralTypes = @(
'byte', 'sbyte', 'short', 'ushort', 'int', 'uint', 'long', 'ulong'
)
Sonraki kod bloğu, numaralandırma tanımlarını dinamik olarak oluşturmak için kullanılacak bir şablon tanımlar. {0} Biçim yer tutucusu tam sayı türü adıyla değiştirildiğinde, şablon şu şekilde bir betik bloğu oluşturur:
gibi
byteEnumadlı<type>Enumbir numaralandırma tanımlar. Tanımlı numaralandırma, temel değer türü olarak belirtilen tamsayı türünü kullanır.Numaralandırma, tamsayı türü için en düşük değere ayarlanmış değerle
Mintanımlanır. Tamser türü için en yüksek değere ayarlanan değeri tanımlarMax.Yeni tanımlanan türü döndürür.
$DefinitionTemplate = @"
enum {0}Enum : {0} {{
Min = [{0}]::MinValue
Max = [{0}]::MaxValue
}}
[{0}Enum]
"@
Sonraki kod bloğu, geçerli kapsamda bir betik bloğu oluşturmak ve çağırmak için şablonu kullanır. Döndürülen tür tanımlarını diziye $EnumTypes ekler.
foreach ($IntegralType in $IntegralTypes) {
$Definition = $DefinitionTemplate -f $IntegralType
$ScriptBlock = [scriptblock]::Create($Definition)
$EnumTypes += . $ScriptBlock
}
Son kod bloğu, temel alınan tür olarak değerleri listelemek için yöntemini kullanarak GetEnumValuesAsUnderlyingType() sabit listesi türleri üzerinde döngü oluşturur. Döngü, numaralandırma türünü, değer türünü, etiketi ve gerçek değeri gösteren her değer için yeni bir nesne oluşturur.
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
Numaralandırma yöntemleri
Aşağıdaki liste, PowerShell'de numaralandırmalar için kullanılabilen kullanışlı yöntemleri ve bunların nasıl kullanılacağını içerir.
Biçimlendir
Statik Format() yöntem, belirli bir numaralandırma türü, numaralandırma değeri ve biçim dizesi için biçimlendirilmiş dize çıkışını döndürür. Çıkış, belirtilen biçim dizesine sahip değerde ToString yöntemini çağırmayla aynıdır.
System.Enum temel sınıf türünde veya belirli bir numaralandırma türünde statik yöntemi kullanabilirsiniz.
[System.Enum]::format([<enum-name>], <value>, <format-string>)
[<enum-name>]::format([<enum-name>], <value>, <format-string>)
Geçerli biçim dizeleri şunlardırG: veya g, D veya dveya xX , ve F ya da f. Daha fazla bilgi için bkz . Numaralandırma Biçim Dizeleri.
Aşağıdaki örnek, TaskState sabit listesinin her değerini dize gösterimlerine dönüştürmek için desteklenen numaralandırma biçimi dizelerinin her birini kullanır.
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
Yansıma GetEnumName() yöntemi, belirli bir sabit listesi değerinin adını döndürür. Giriş değeri, bir sabit listesi için tamsayı veya sabit listesi değeri gibi geçerli bir temel tür olmalıdır. Bir değerle ilişkilendirilmiş birden çok ad varsa, yöntemi ilk tanımlı adı döndürür.
[<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
Yansıma GetEnumNames() yöntemi, her sabit listesi değerinin adlarını dize olarak döndürür. Çıkış eş anlamlılar içerir.
[<enum-name>].GetEnumNames()
enum Season {
Unknown
Spring
Summer
Autumn
Winter
Fall = 3
}
[Season].GetEnumNames()
Unknown
Spring
Summer
Fall
Autumn
Winter
GetEnumUnderlyingType
Yansıma GetEnumUnderlyingType() yöntemi, numaralandırma değerleri için temel alınan türü döndürür.
[<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
Yansıma GetEnumValues() yöntemi, sabit listesi için tanımlanan her değeri döndürür.
[<enum-name>].GetEnumValues()
enum Season {
Unknown
Spring
Summer
Autumn
Winter
Fall = 3
}
[Season].GetEnumValues()
Unknown
Spring
Summer
Fall
Fall
Winter
GetEnumValuesAsUnderlyingType
GetEnumValuesAsUnderlyingType() Yansıma yöntemi, sabit listesi için tanımlanan her değeri temel alınan tür olarak döndürür.
[<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
HasFlag Örnek yöntemi, bayrak numaralandırma değeri için bit bayrağı ayarlanıp ayarlanmadığını belirler. Bu yöntemin kullanılması, ikili karşılaştırma ve denklik denetimi yapmaktan daha kısa ve okunmasını kolaylaştırır.
<enum-value>.HasFlag(<enum-flag-value>)
Aşağıdaki örnek ModuleFeatures bayrak numaralandırmasını tanımlar ve değerin 39 hangi bayraklara sahip olduğunu gösterir.
[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
Statik IsDefined() yöntem, giriş değeri sabit listesi için tanımlanmışsa ve aksi takdirde $falsedöndürür$true. Geçersiz bağımsız değişken hatalarını işlemeye gerek kalmadan bir değerin sabit listesi için geçerli olup olmadığını denetlemek için bu yöntemi kullanın.
System.Enum temel sınıf türünde veya belirli bir numaralandırma türünde statik yöntemi kullanabilirsiniz.
[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
ToString() Örnek yöntemi bir numaralandırma değeri etiketini döndürür.
Bu yöntem, bir numaralandırma değerinin çıkış olarak nasıl görüntülendiğinde de varsayılan görünümdür. İsteğe bağlı olarak, değerin nasıl görüntüleneceğini denetlemek için bir biçim dizesi belirtebilirsiniz. Biçimlendirme hakkında daha fazla bilgi için bkz . Numaralandırma değerlerini biçimlendirme.
Not
Belirli bir değer için eş anlamlıları tanımlayan numaralandırmalar için çıkışına bağlı kod yazmayın ToString(). yöntemi, değer için geçerli bir ad döndürebilir.
<enum-value>.ToString([<format-string>])
Aşağıdaki örnek, ile Gray Gölge numaralandırmasını için Greybir eş anlamlı olarak tanımlar. Daha sonra gerçek sabit listesi değerini, sabit toplamını dize olarak ve numaralandırmayı tamsayı olarak gösteren nesneler verir.
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
Numaralandırma değeri eş anlamlıları
Aynı tamsayı değerine farklı adlar veren numaralandırmalar tanımlayabilirsiniz. Bunu yaptığınızda, aynı temel değere işaret eden adlar eş anlamlı olarak adlandırılır. Eş anlamlılar içeren numaralandırmalar, kullanıcıların aynı değer için farklı adlar belirtmesine olanak tanır.
Eş anlamlılarla bir numaralandırma tanımlarken, belirli bir ada dönüştürülen eş anlamlı değere bağlı kod yazmayın. Bir eş anlamlı dizesini numaralandırma değerine dönüştüren kodu güvenilir bir şekilde yazabilirsiniz. Numaralandırma değeriyle çalışırken, bunu her zaman dize yerine bir numaralandırma değeri veya temel türü olarak karşılaştırın.
Aşağıdaki kod bloğu, ve Gray ile Grey Gölge numaralandırmasını eş anlamlılar olarak tanımlar.
enum Shade {
White
Grey
Gray = 1
Black
}
[Shade]'Grey' -eq [Shade]::Gray
[Shade]::Grey -eq 1
[Shade]'Gray' -eq 1
True
True
True
Bayrak olarak numaralandırmalar
Numaralandırmanın yaygın kullanımlarından biri, birbirini dışlayan değerler kümesini temsil etmektir. Örneğin, bir ArrivalStatus örneğinin Değeri Early, OnTime veya Late olabilir. Bir ArrivalStatus örneğinin değerinin birden fazla sabit listesi sabitini yansıtması mantıklı değildir.
Ancak diğer durumlarda, bir numaralandırma nesnesinin değeri birden çok numaralandırma üyesi içerebilir ve her üye numaralandırma değerinde bir bit alanını temsil eder. Numaralandırmanın , kullanıcıların birleştirebileceği bayraklar olarak bit alanlarından oluştuğunu belirtmek için FlagsAttribute kullanabilirsiniz.
Numaralandırmaların bayrak olarak düzgün çalışması için her etiketin tamsayı değerini iki güçte ayarlamanız gerekir. Bir etiket için değer belirtmezseniz, PowerShell değeri önceki etiketten bir üst değere ayarlar.
Kullanıcıların aynı anda bir bayrak kümesi belirtmesini kolaylaştırmak için yaygın olarak kullanılan bayrak birleşimleri için değerler tanımlayabilirsiniz. Değerin adı, bayrakların birleşik adları olmalıdır. Tamsayı değeri, bayrak değerlerinin toplamı olmalıdır.
Belirli bir bayrağın bir değer için ayarlanıp ayarlanmadığını belirlemek için, HasFlag() değerin üzerindeki yöntemini kullanın veya ikili karşılaştırma işlecini -bandkullanın.
Bayrak numaralandırmalarını kullanmayı ve bayrağın ayarlanıp ayarlanmadığını denetlemeyi gösteren bir örnek için bkz . Örnek 3.
Parametre olarak numaralandırmalar
Türü olarak bir sabit listesi kullanan cmdlet parametreleri tanımlayabilirsiniz. Bir parametrenin türü olarak bir sabit listesi belirttiğinizde, kullanıcılar parametrenin değerinin otomatik olarak tamamlanmasını ve doğrulanmasını sağlar. Bağımsız değişken tamamlama işlemi, sabit listesi için geçerli etiketlerin listesini önerir.
Bir parametrenin türü olarak bir sabit listesi olduğunda, şunlardan birini belirtebilirsiniz:
- Sabit listesi, örneğin
[<EnumType>]::<Label> - Sabit listesi için dize olarak etiket
- Numaralandırmanın sayısal değeri
Numaralandırma türündeki bir parametrenin davranışını gösteren bir örnek için bkz . Örnek 4.
Belirli temel türler içeren numaralandırmalar
PowerShell 6.2'den başlayarak, belirli bir temel türe sahip numaralandırmalar tanımlayabilirsiniz. Belirli bir temel türü olmayan bir numaralandırma tanımladığınızda PowerShell, temel alınan tür olarak (System.Int32) ile [int] numaralandırmayı oluşturur.
Sabit listesi için temel alınan tür tam sayı türünde olmalıdır. Aşağıdaki liste, kısa adı ve tam tür adıyla geçerli türleri içerir:
byte- System.Bytesbyte- System.SByteshort- System.Int16ushort- System.UInt16int- System.Int32uint- System.UInt32long- System.Int64ulong- System.UInt64
Sabit listesi için belirli bir temel türü kısa ad veya tam tür adı olarak tanımlayabilirsiniz. Aşağıdaki tanımlar işlevsel olarak aynıdır. Yalnızca temel alınan tür için kullanılan ad farklıdır.
enum LongValueEnum : long {
Zero
One
Two
}
enum LongValueEnum : System.Int64 {
Zero
One
Two
}
Numaralandırma değerlerini biçimlendirme
Sabit listesi değerlerini, statik Format yöntemini çağırarak ve toString yönteminin aşırı yüklemelerini çağırarak dize gösterimlerine dönüştürebilirsiniz. Bir numaralandırma değerinin dize olarak nasıl temsil edilir tam yolunu denetlemek için bir biçim dizesi kullanabilirsiniz. Daha fazla bilgi için bkz . Numaralandırma Biçim Dizeleri.
Aşağıdaki örnek, TaskState numaralandırmasının her bir üyesini dize gösterimlerine dönüştürmek için desteklenen numaralandırma biçimi dizelerinin her birini (G veya gdD , veya , X veya x, ve F veya f ) kullanır.
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
Aşağıdaki örnekte, bir bayrak sabit listesi değerleri için biçim dizeleri kullanılır.
[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
Bayrak numaralandırmaları G için ve F biçim dizelerinin virgülle ayrılmış değer için ayarlanan bayrakların listesini görüntülediğini fark edin. Son değer olan 8, aslında geçerli bir bayrak kümesi olmadığından hiçbir bayrağı listelemez. En az bir 8 bayrak yinelemeden toplamını almak için numaralandırma bayraklarını birleştiremezsiniz.
Update-TypeData ile uzantı yöntemlerini tanımlama
Bir numaralandırma için bildirimde yöntemler tanımlayamazsınız. Numaralandırmanın işlevselliğini genişletmek için Update-TypeData cmdlet'ini kullanarak numaralandırmanın üyelerini tanımlayabilirsinizScriptMethod.
Aşağıdaki örnek, FileAttributes bayrağı numaralandırmasına bir GetFlags() yöntem eklemek için cmdlet'ini kullanırUpdate-TypeData. Değer için ayarlanan bayrakların bir dizisini döndürür.
[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
Tür hızlandırıcılarıyla numaralandırmaları dışarı aktarma
Varsayılan olarak, PowerShell modülleri PowerShell'de tanımlanan sınıfları ve numaralandırmaları otomatik olarak dışarı aktarmaz. Özel türler, deyimi using module çağrılmadan modülün dışında kullanılamaz.
Ancak, bir modül tür hızlandırıcıları eklerse, kullanıcılar modülü içeri aktardıktan sonra bu tür hızlandırıcıları oturumda hemen kullanılabilir.
Not
Oturuma tür hızlandırıcıları eklemek için iç (genel değil) API kullanılır. Bu API'nin kullanılması çakışmalara neden olabilir. Aşağıda açıklanan desen, modülü içeri aktardığınızda aynı ada sahip bir tür hızlandırıcısı zaten varsa hata oluşturur. Ayrıca modülü oturumdan kaldırdığınızda tür hızlandırıcılarını da kaldırır.
Bu düzen, türlerin bir oturumda kullanılabilir olmasını sağlar. VS Code'da bir betik dosyası yazılırken IntelliSense'i veya tamamlanmayı etkilemez.
VS Code'daki özel türler için IntelliSense ve tamamlama önerileri almak için betiğin en üstüne bir using module deyim eklemeniz gerekir.
Aşağıdaki desen, PowerShell sınıflarını ve numaralandırmalarını bir modülde tür hızlandırıcıları olarak nasıl kaydedebileceğinizi gösterir. Kod parçacığını herhangi bir tür tanımından sonra kök betik modülüne ekleyin. Değişkenin $ExportableTypes , modülü içeri aktardığında kullanıcıların kullanımına açmak istediğiniz türlerin her birini içerdiğinden emin olun. Diğer kod herhangi bir düzenleme gerektirmez.
# 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()
Kullanıcılar modülü içeri aktardığında, oturum için tür hızlandırıcılarına eklenen tüm türler IntelliSense ve tamamlama için hemen kullanılabilir. Modül kaldırıldığında tür hızlandırıcıları da kaldırılır.
Sabit listeleri PowerShell modülünden el ile içeri aktarma
Import-Module#requires ve deyimi yalnızca modül tarafından tanımlandığı gibi modül işlevlerini, diğer adlarını ve değişkenlerini içeri aktarır. Numaralandırmalar içeri aktarılamaz.
Bir modül sınıfları ve numaralandırmaları tanımlıyor ancak bu türler için tür hızlandırıcıları eklemiyorsa, bunları içeri aktarmak için deyimini using module kullanın.
deyimi, using module bir betik modülünün veya ikili modülün kök modülünden (ModuleToProcess) sınıfları ve numaralandırmaları içeri aktarır. İç içe modüllerde tanımlanan sınıfları veya kök modüle nokta kaynaklı betiklerde tanımlanan sınıfları tutarlı bir şekilde içeri aktarmaz. Doğrudan kök modülde modülün dışındaki kullanıcıların kullanımına sunulmasını istediğiniz sınıfları tanımlayın.
Deyimi hakkında using daha fazla bilgi için bkz . about_Using.
Geliştirme sırasında yeni değiştirilen kodu yükleme
Bir betik modülünün geliştirilmesi sırasında kodda değişiklik yapmak ve ardından Force parametresini kullanarak Import-Module modülün yeni sürümünü yüklemek yaygın bir işlemdir. Bu, yalnızca kök modüldeki işlevlerde yapılan değişiklikler için çalışır. Import-Module iç içe modülleri yeniden yüklemez. Ayrıca, güncelleştirilmiş sınıfları yüklemenin hiçbir yolu yoktur.
En son sürümü çalıştırdığınızdan emin olmak için yeni bir oturum başlatmanız gerekir.
PowerShell'de tanımlanan ve bir using deyimle içeri aktarılan sınıflar ve numaralandırmalar kaldırılamaz.
Bir diğer yaygın geliştirme uygulaması da kodunuzu farklı dosyalara ayırmaktır. Başka bir modülde tanımlanan numaralandırmaları kullanan bir dosyada işleviniz varsa, işlevlerin using module gerekli numaralandırma tanımlarına sahip olduğundan emin olmak için deyimini kullanmanız gerekir.
Sınırlamalar
PowerShell'de tanımlanan numaralandırma değerlerini özniteliklerle süsleyemezsiniz. Numaralandırmayı bit bayrakları kümesi olarak tanımlamak için FlagsAttribute ile olduğu gibi yalnızca numaralandırma bildirimini süsleyebilirsiniz.
Geçici çözüm: Yok
Numaralandırma tanımları içinde yöntemler tanımlayamazsınız ve PowerShell C# gibi [uzantı yöntemleri] tanımlamayı desteklemez.
Geçici çözüm: Sabit listesi üyelerini tanımlamak
ScriptMethodiçin Update-TypeData cmdlet'ini kullanın.
PowerShell