about_Enum

Kısa açıklama

enum deyimi 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

enum deyimi, 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.

SÖZDİZİMİ

Tanımda, etiketlere herhangi bir tamsayı değeri verebilirsiniz. Değer atanmamış etiketler sonraki tamsayı değerini alır.

Sabit listesi etiketleri yalnızca harf, alt çizgi ve basamak içerebilir, ancak bir rakamla başlamamalıdır. Etiket tırnak içine alınmış bir dize olamaz; bir bareword dizesi olarak ayrıştırılmalıdır. Etiketler anahtar sözcük olarak değil dize olarak ayrıştırılır. Bu nedenle, bir dil anahtar sözcüğüyle (örneğin return) aynı ada sahip bir etiket oluşturmak mümkündür.

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>]...] [Flags()] 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, music, picturevideotemel değerlerine açık değerler atar. 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, moggveya 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
}

GetEnumNames() yöntemi, 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

GetEnumValues() yöntemi, numaralandırma değerlerinin 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, dahili olarak, GetEnumValues() değerleri numaralandırır, ardından değerleri adlarla eşler. Listeyi dikkatlice okursanız, oggçıktısında oga, moggve GetEnumNames() göründüğünü, ancak GetEnumValues() çıkışının yalnızca ogggösterdiğini fark edersiniz. jpg, jpegve mpgmpegiçin de aynı şey olur. PowerShell'in eş anlamlı değerler için döndürdüğü ad belirleyici değildir.

Belirli bir değerle ilişkili bir ad almak için GetEnumName() yöntemini kullanabilirsiniz. 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

tek bir sabit listesi değerini etiketine göre [<enum-name>]::<label>söz dizimi ile 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 -bandikili karşılaştırma işlecini kullanabilirsiniz. Bu örnek, değerinde Cihaz ve $file2 ö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ı test etmek için HasFlag() yöntemini de kullanabilirsiniz. Bu örnek, değerinde Cihaz ve Gizli $file1 için 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şlev ConvertTo-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, ConvertTo-LineEndingRegex çağıran ilk deyim CRiçin numaralandırma değerini geçirir. İkinci deyim, bir 'CRLF''e gönderilen dizesini geçirir. Üçüncü deyim, 2 etiketine eşlenen parametresi için LF değerini 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 tutan 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çimi yer tutucusu tam sayı türü adıyla değiştirildiğinde, şablon şu şekilde bir betik bloğu oluşturur:

1. <type>Enumgibi byteEnumadlı bir numaralandırma tanımlar. Tanımlı numaralandırma, temel değer türü olarak belirtilen tamsayı türünü kullanır.

   Numaralandırma, Min değeri tamsayı türü için en düşük değere ayarlanmış şekilde tanımlanır. İntegral türü için en yüksek değere ayarlanmış Max değerini tanımlar.

2. 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ı $EnumTypes dizisine ekler.

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

Son kod bloğu, değerleri temel alınan tür olarak listelemek için GetEnumValuesAsUnderlyingType() yöntemini kullanarak 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çim

Format() statik yöntemi, 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ğer üzerinde 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 G veya g, D veya d, X veya xve F veya f. Daha fazla bilgi için bkz. Numaralandırma Biçim Dizeleri.

Aşağıdaki örnek, TaskState numaralandırmasının 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

GetEnumName() yansıma 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

GetEnumNames() yansıma yöntemi, her numaralandırma 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

GetEnumUnderlyingType() yansıma 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

GetEnumValues() yansıma yöntemi, numaralandırma 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 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 örneği 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 39 değerinin 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

IsDefined() statik yöntemi, giriş değeri sabit listesi için tanımlanmışsa $true döndürür ve aksi takdirde $false. 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() örneği yöntemi, bir numaralandırma değerinin 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. Biçimlendirme numaralandırma değerlerini.

Not

Belirli bir değerin eş anlamlılarını tanımlayan numaralandırmalar için ToString()çıkışına bağlı kod yazmayın. yöntemi, değer için geçerli bir ad döndürebilir.

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

Aşağıdaki örnek, için eş anlamlı olarak Gray ile Grey numaralandırmasını 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ılar 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 adı dönüştüren bir 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, Shade numaralandırmasını Grey ve Gray eş anlamlı 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ği Early, OnTime veya Late değerine sahip olabilir. bir ArrivalStatus örneğinin değerinin birden fazla numaralandırma 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, değerdeki HasFlag() yöntemini kullanın veya -bandikili karşılaştırma işlecini kullanı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:

• [<EnumType>]::<Label> gibi bir numaralandırma
• 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 [int] (System.Int32) ile 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:

• System.Bytebyte -
• System.SBytesbyte -
• short - System.Int16
• System.UInt16ushort -
• int - System.Int32
• System.UInt32uint -
• long - System.Int64
• System.UInt64ulong -

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öntemi örneğin 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, G numaralandırmasının her bir üyesini dize gösterimlerine dönüştürmek için desteklenen numaralandırma biçimi dizelerinin (g veya D, d veya X, x veya Fve f veya ) 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ı için, G 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 bayrak yinelemeden 8 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. Bir numaralandırmanın işlevselliğini genişletmek için Update-TypeData cmdlet'ini kullanarak sabit listesi için ScriptMethod üyeleri tanımlayabilirsiniz.

Aşağıdaki örnek, Update-TypeData bayrak numaralandırmasına bir GetFlags() yöntemi eklemek için cmdlet'ini kullanır. 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, using module deyimi ç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 deyimi 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. $ExportableTypes değişkeninin, 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 ve #Requires deyimi yalnızca modül tarafından tanımlanan modül işlevlerini, diğer adlarını ve değişkenleri içeri aktarır. Numaralandırmalar içeri aktarılamaz.

Bir modül sınıfları ve numaralandırmaları tanımlar ancak bu türler için tür hızlandırıcıları eklemezse, bunları içeri aktarmak için using module deyimini kullanın.

using module deyimi, 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.

using deyimi hakkında 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 Import-Module parametresiyle kullanarak 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 using deyimiyle 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 gerekli numaralandırma tanımlarına sahip olduğundan emin olmak için using module 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 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 için üyeleri tanımlamak için ScriptMethod cmdlet'ini kullanın.