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

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:

1. 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 Min tanımlanır. Tamser türü için en yüksek değere ayarlanan değeri tanımlar Max .

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

<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.Byte
• sbyte - System.SByte
• short - System.Int16
• ushort - System.UInt16
• int - System.Int32
• uint - System.UInt32
• long - System.Int64
• ulong - 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.

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 ScriptMethod için Update-TypeData cmdlet'ini kullanın.