Aracılığıyla paylaş

about_Functions_Advanced_Parameters

  • Makale

Kısa açıklama

Gelişmiş işlevlere parametre eklemeyi açıklar.

Uzun açıklama

Yazdığınız gelişmiş işlevlere parametreler ekleyebilir ve işlev kullanıcılarının parametresiyle gönderdiği parametre değerlerini sınırlamak için parametre özniteliklerini ve bağımsız değişkenlerini kullanabilirsiniz.

özniteliğini CmdletBinding kullandığınızda PowerShell, Ortak Parametreleri otomatik olarak ekler. Common Parameters ile aynı adları kullanan hiçbir parametre oluşturamazsınız. Daha fazla bilgi için bkz . about_CommonParameters.

PowerShell 3.0'da başlayarak, komuttaki parametreleri temsil etmek için ile @args birlikteplatlama özelliğini kullanabilirsiniz. Splatting basit ve gelişmiş işlevlerde geçerlidir. Daha fazla bilgi için bkz . about_Functions ve about_Splatting.

Parametre bildirimi

Parametreler, bir işlevin veya betik bloğunun param() deyiminde bildirilen değişkenlerdir. İsteğe bağlı [Parameter()] özniteliğini tek başına veya [Alias()] özniteliği veya parametre doğrulama özniteliklerinden herhangi biriyle birlikte kullanabilirsiniz.

Parametre adları, değişken adları için kuralları izler. Parametre adları ondalık basamaklardan, alfabetik karakterlerden ve alt çizgilerden oluşur. Adlandırma kurallarının tam listesi için bkz. about_Variables.

Önemli

Ondalık basamakla başlayan bir parametre tanımlamak mümkündür. PowerShell bunları konumsal parametre olarak geçirilen dize değerleri olarak kabul ettiğinden parametre adlarını basamakla başlatma önerilmez.

Aşağıdaki örneği göz önünde bulundurun:

function TestFunction {
    param (
        [switch] $100,
        [string] $200
    )

    "100: $100"
    "200: $200"
}

Parametreleri kullanmaya çalışırsanız, PowerShell bunları konumsal parametre olarak geçirilen dizeler olarak yorumlar.

PS> TestFunction -100 -200 Hello
100: False
200: -100
$args: -200 Hello

Çıktı, PowerShell'in -100 değerini $200 parametre değişkenine bağladığını gösterir. Kalan konumsal değerler $argsbağlıdır. Sorunu aşmak için, parametre değerlerini aktarmak amacıyla "splatting" tekniğini kullanabilirsiniz.

PS> $ht = @{100 = $true; 200 = 'Hello'}
PS> TestFunction @ht
100: True
200: Hello
$args:

Daha fazla bilgi için bkz. about_Splatting.

Parametre değerlerinin tür dönüştürmesi

Dizeleri farklı bir tür bekleyen parametrelere bağımsız değişken olarak sağladığınızda, PowerShell dizeleri örtük olarak parametre hedef türüne dönüştürür. Gelişmiş işlevler, parametre değerlerinin kültür sabit ayrıştırma işlemini gerçekleştirir.

Buna karşılık, derlenmiş cmdlet'ler için parametre bağlaması sırasında kültüre duyarlı dönüştürme gerçekleştirilir.

Bu örnekte bir cmdlet ve parametre alan [datetime] bir betik işlevi oluşturacağız. Geçerli kültür, Almanca ayarlarını kullanacak şekilde değiştirilir. Parametreye Almanca biçimlendirilmiş bir tarih geçirilir.

# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
  using System;
  using System.Management.Automation;
  [Cmdlet("Get", "Date_Cmdlet")]
  public class GetFooCmdlet : Cmdlet {

    [Parameter(Position=0)]
    public DateTime Date { get; set; }

    protected override void ProcessRecord() {
      WriteObject(Date);
    }
  }
'@ -PassThru | % Assembly | Import-Module

[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'

Get-Date_Cmdlet $dateStr

Dienstag, 19. Juni 2018 00:00:00

Yukarıda gösterildiği gibi, cmdlet'ler dizeyi dönüştürmek için kültüre duyarlı ayrıştırma kullanır.

# Define an equivalent function.
function Get-Date_Func {
  param(
    [datetime] $Date
  )
  process {
    $Date
  }
}

[cultureinfo]::CurrentCulture = 'de-DE'

# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'

Get-Date_Func $dateStr

Gelişmiş işlevler kültür sabit ayrıştırma kullanır ve bu da aşağıdaki hataya neden olur.

Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."

Daha fazla bilgi için bkz. about_Type_Conversion.

Statik parametreler

Statik parametreler, işlevde her zaman kullanılabilen parametrelerdir. PowerShell cmdlet'leri ve betiklerindeki parametrelerin çoğu statik parametrelerdir.

Aşağıdaki örnek, aşağıdaki özelliklere sahip bir ComputerName parametresinin bildirimini gösterir:

  • Zorunlu (gerekli).
  • İşlem hattından giriş alır.
  • Giriş olarak bir dize dizisi alır.
param(
    [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
    [string[]]$ComputerName
)

Parametreleri değiştirme

Anahtar parametreleri, parametre değeri almayan parametrelerdir. Bunun yerine, iletişim durumu veya yokluğu aracılığıyla Boole değeri iletirler, böylece bir switch parametresi mevcut olduğunda doğru bir değere ve olmadığında yanlış değere sahiptir.

Örneğin, Yineleme parametresi Get-ChildItem bir anahtar parametresidir.

İşlevde anahtar parametresi oluşturmak için parametre tanımında türünü belirtin [switch] . Aşağıdaki örnek, verilerin bayt dizisi olarak çıkışını alma seçeneği sağlamak için kullanılabilecek bir switch parametresinin tanımını gösterir:

param([switch]$AsByteArray)

Anahtar parametreleri kullanımı kolaydır ve PowerShell için daha az doğal söz dizimine sahip Boole parametrelerine göre tercih edilir.

Switch parametresini kullanmak için parametresini komutuna ekleyin. Örneğin:

-IncludeAll

Boole parametresini kullanmak için parametresini ve Boole değerini sağlamanız gerekir.

-IncludeAll $true

Anahtar parametreleri oluştururken parametre adını dikkatle seçin. Parametre adının, parametrenin etkisini kullanıcıya ilettiklerinden emin olun. Bir değerin gerekli olduğu anlamına gelen Filtre veya Maksimum gibi belirsiz terimlerden kaçının.

Parametre tasarımında dikkat edilmesi gerekenler arasında geçiş yapma

  • Switch parametresi için varsayılan değer ayarlamayın. Parametreyi her zaman varsayılan olarak false olarak değiştirin.

  • Anahtar parametrelerini konumlu yapmayın. Varsayılan olarak, anahtar parametreleri konumsal parametrelerin dışında tutulur. Parameter özniteliğinde bunu geçersiz , ancak kullanıcıların kafasını karıştırabilir.

  • Parametrenin kullanılması komutun varsayılan davranışını daha az yaygın veya daha karmaşık bir moda değiştirecek şekilde parametreleri tasarlar. Bir komutun en basit davranışı, anahtar parametrelerinin kullanılmasını gerektirmeyen varsayılan davranış olmalıdır.

  • Anahtar parametrelerini zorunlu yapmayın. Anahtar parametresini zorunlu hale getirmenin yararlı olduğu tek durum, parametre kümesini ayırt etmek için gerekli olmasıdır.

  • Switch parametre değişkenini doğrudan bir koşullu ifadede kullanın. SwitchParameter türü örtük olarak Boole değerine dönüştürülür. Örneğin:

    if ($MySwitch) { ... }

  • Anahtar tarafından denetlenen davranışı her zaman parametrenin varlığını değil anahtarın değerini temel alır. Anahtar parametrelerinin olup olmadığını test etmenin çeşitli yolları vardır:

    • $PSBoundParameters anahtar parametresi adını anahtar olarak içerir
    • $MyInvocation.BoundParameters anahtar parametresi adını anahtar olarak içerir
    • Anahtar benzersiz bir parametre kümesi tanımladığında $PSCmdlet.ParameterSetName

    Örneğin, -MySwitch:$false veya sıçrama kullanarak anahtar için açık bir değer sağlamak mümkündür. Yalnızca parametresinin varlığını test ederseniz, komut anahtar değeri $trueyerine $false gibi davranır.

Dinamik parametreler

Dinamik parametreler, yalnızca belirli koşullar altında kullanılabilen bir cmdlet, işlev veya betiğin parametreleridir.

Örneğin, birkaç sağlayıcı cmdlet'inin parametreleri yalnızca cmdlet sağlayıcı sürücüsünde veya sağlayıcı sürücüsünün belirli bir yolunda kullanıldığında kullanılabilir. Örneğin, Kodlama parametresi yalnızca bir dosya sistemi sürücüsünde kullanıldığında , Add-Contentve Get-Content cmdlet'lerinde kullanılabilirSet-Content.

Ayrıca, yalnızca işlev komutunda başka bir parametre kullanıldığında veya başka bir parametrenin belirli bir değeri olduğunda görüntülenen bir parametre oluşturabilirsiniz.

Dinamik parametreler yararlı olabilir, ancak bunları yalnızca gerektiğinde kullanın çünkü kullanıcıların bulması zor olabilir. Dinamik parametreyi bulmak için kullanıcının sağlayıcı yolunda olması, cmdlet'in ArgumentList parametresini veya path parametresini Get-Commandkullanması gerekir.Get-Help

bir işlev veya betik için dinamik parametre oluşturmak için anahtar sözcüğünü dynamicparam kullanın.

Söz dizimi şu şekildedir:

dynamicparam {<statement-list>}

deyimi listesinde, işlevinde parametrenin hangi koşullar altında kullanılabilir olduğunu belirtmek için bir if deyimi kullanın.

Aşağıdaki örnekte Ad ve Yol adlı standart parametrelere ve KeyCount adlı isteğe bağlı dinamik parametreye sahip bir işlev gösterilmektedir. KeyCount parametresi parametre kümesindedir ByRegistryPath ve türündedirInt32. KeyCount parametresi işlevinde Get-Sample yalnızca Path parametresinin değeri ile HKLM:başladığında kullanılabilir ve kayıt defteri sürücüsünde HKEY_LOCAL_MACHINE kullanıldığını belirtir.

function Get-Sample {
  [CmdletBinding()]
  param([string]$Name, [string]$Path)

  dynamicparam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
          ParameterSetName = "ByRegistryPath"
          Mandatory = $false
      }

      $attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
      $attributeCollection.Add($parameterAttribute)

      $dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
        'KeyCount', [int32], $attributeCollection
      )

      $paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
      $paramDictionary.Add('KeyCount', $dynParam1)
      return $paramDictionary
    }
  }
}

Daha fazla bilgi için RuntimeDefinedParameter türü belgelerine bakın.

Parametrelerin öznitelikleri

Bu bölümde, işlev parametrelerine ekleyebileceğiniz öznitelikler açıklanmaktadır.

Tüm öznitelikler isteğe bağlıdır. Ancak, CmdletBinding özniteliğini atlarsanız, gelişmiş işlev olarak tanınmak için işlevin Parameter özniteliğini içermesi gerekir.

Her parametre bildirimine bir veya birden çok öznitelik ekleyebilirsiniz. Parametre bildirimine ekleyebileceğiniz öznitelik sayısı sınırı yoktur.

Parametre özniteliği

Parametre özniteliği, işlev parametrelerinin özniteliklerini bildirmek için kullanılır.

Parameter özniteliği isteğe bağlıdır ve işlevlerinizin parametrelerinden hiçbirinin özniteliklere ihtiyacı yoksa bunu atlayabilirsiniz. Ancak, basit bir işlev yerine gelişmiş bir işlev olarak tanınmak için, bir işlevin CmdletBinding özniteliğine veya Parameter özniteliğine ya da her ikisine de sahip olması gerekir.

Parameter özniteliği, parametrenin zorunlu mu yoksa isteğe bağlı mı olduğu gibi parametrenin özelliklerini tanımlayan bağımsız değişkenlere sahiptir.

Parameter özniteliğini, bağımsız değişkenini ve bağımsız değişken değerini bildirmek için aşağıdaki söz dizimini kullanın. Bağımsız değişkeni ve değerini kapsayan ayraçlar, araya hiç boşluk eklemeden Parametre'yi izlemelidir.

param(
    [Parameter(Argument=value)]
    $ParameterName
)

Ayraç içindeki bağımsız değişkenleri ayırmak için virgül kullanın. Parameter özniteliğinin iki bağımsız değişkenini bildirmek için aşağıdaki söz dizimini kullanın.

param(
    [Parameter(Argument1=value1, Argument2=value2)]
    $ParameterName
)

Parametre özniteliğinin boole bağımsız değişken türleri, Parameter özniteliğindenatlandığında varsayılan olarak False olarak ayarlanır. Bağımsız değişken değerini olarak $true ayarlayın veya yalnızca bağımsız değişkeni ada göre listeleyin. Örneğin, aşağıdaki Parametre öznitelikleri eşdeğerdir.

param(
    [Parameter(Mandatory=$true)]
)

# Boolean arguments can be defined using this shorthand syntax

param(
    [Parameter(Mandatory)]
)

Parametre özniteliğini bağımsız değişkenler olmadan kullanırsanız, CmdletBinding özniteliğini kullanmaya alternatif olarak öznitelik adını izleyen parantezler yine de gereklidir.

param(
    [Parameter()]
    $ParameterName
)

Zorunlu bağımsız değişken

Mandatory bağımsız değişkeni parametresinin gerekli olduğunu gösterir. Bu bağımsız değişken belirtilmezse, parametresi isteğe bağlıdır.

Aşağıdaki örnek ComputerName parametresini bildirir. Parametresini Mandatory zorunlu hale getirmek için bağımsız değişkenini kullanır.

param(
    [Parameter(Mandatory)]
    [string[]]$ComputerName
)

Konum bağımsız değişkeni

bağımsız değişkeni, Position parametre bir komutta kullanıldığında parametre adının gerekli olup olmadığını belirler. Parametre bildirimi bağımsız değişkenini içerdiğinde Position , parametre adı atlanabilir ve PowerShell adsız parametre değerini komutundaki adsız parametre değerleri listesinde konumuna veya sırasına göre tanımlar.

Position Bağımsız değişken belirtilmezse, parametre adı veya parametre adı diğer adı veya kısaltması, parametre bir komutta her kullanıldığında parametre değerinden önce olmalıdır.

Varsayılan olarak, tüm işlev parametreleri konumsaldır. PowerShell, parametrelere, parametrelerin işlevde bildirilmesi sırasına göre konum numaraları atar. Bu özelliği devre dışı bırakmak için CmdletBindingPositionalBindingdeğerini olarak $falseayarlayın. bağımsız değişkeni, Position CmdletBinding özniteliğinin bağımsız değişkeninin değerinden PositionalBindingönceliklidir. Daha fazla bilgi için bkz PositionalBinding. about_Functions_CmdletBindingAttribute.

Bağımsız değişkenin Position değeri tamsayı olarak belirtilir. 0 konum değeri komuttaki ilk konumu, 1 konum değeri ise komuttaki ikinci konumu temsil eder ve bu şekilde devam eder.

Bir işlevin konumsal parametresi yoksa PowerShell, parametrelerin bildirilmesine göre her parametreye konum atar. Ancak en iyi uygulama olarak bu atamaya güvenmeyin. Parametrelerin konumsal olmasını istediğinizde bağımsız değişkenini Position kullanın.

Aşağıdaki örnek ComputerName parametresini bildirir. Bağımsız değişkenini Position 0 değeriyle kullanır. Sonuç olarak, komuttan atlandığında -ComputerName değerinin komuttaki ilk veya tek adsız parametre değeri olması gerekir.

param(
    [Parameter(Position=0)]
    [string[]]$ComputerName
)

ParameterSetName bağımsız değişkeni

ParameterSetName bağımsız değişkeni, bir parametrenin ait olduğu parametre kümesini belirtir. Parametre kümesi belirtilmezse, parametre işlevi tarafından tanımlanan tüm parametre kümelerine aittir. Benzersiz olması için her parametre kümesinin, diğer parametre kümelerinin üyesi olmayan en az bir parametresi olmalıdır.

Not

Bir cmdlet veya işlev için 32 parametre kümesi sınırı vardır.

Aşağıdaki örnekte parametre kümesinde bir Computer parametresi, parametre kümesinde userName User parametresi ve her iki parametre kümesinde de Summary parametresi bildirilir.

param(
    [Parameter(Mandatory, ParameterSetName="Computer")]
    [string[]]$ComputerName,

    [Parameter(Mandatory, ParameterSetName="User")]
    [string[]]$UserName,

    [Parameter()]
    [switch]$Summary
)

Her bağımsız değişkende yalnızca bir ParameterSetName değer ve her ParameterSetName özniteliğinde yalnızca bir bağımsız değişken belirtebilirsiniz. Birden fazla parametre kümesine parametre eklemek için ek Parametre öznitelikleri ekleyin.

Aşağıdaki örnek, ve parametre kümelerine SummaryComputer. Özet parametresi parametre kümesinde Computer isteğe bağlıdır ve parametre kümesinde User zorunludur.

param(
    [Parameter(Mandatory, ParameterSetName="Computer")]
    [string[]]$ComputerName,

    [Parameter(Mandatory, ParameterSetName="User")]
    [string[]]$UserName,

    [Parameter(ParameterSetName="Computer")]
    [Parameter(Mandatory, ParameterSetName="User")]
    [switch]$Summary
)

Parametre kümeleri hakkında daha fazla bilgi için bkz . Parametre Kümeleri Hakkında.

ValueFromPipeline bağımsız değişkeni

ValueFromPipeline bağımsız değişkeni, parametrenin bir işlem hattı nesnesinden girişi kabul ettiğini gösterir. İşlev nesnenin yalnızca bir özelliğini değil, tüm nesneyi kabul ederse bu bağımsız değişkeni belirtin.

Aşağıdaki örnek, zorunlu olan bir ComputerName parametresini bildirir ve işlem hattından işleve geçirilen bir nesneyi kabul eder.

param(
    [Parameter(Mandatory, ValueFromPipeline)]
    [string[]]$ComputerName
)

ValueFromPipelineByPropertyName bağımsız değişkeni

ValueFromPipelineByPropertyName bağımsız değişkeni, parametrenin bir işlem hattı nesnesinin özelliğinden girişi kabul ettiğini gösterir. nesne özelliği, parametresiyle aynı ada veya diğer ada sahip olmalıdır.

Örneğin, işlevin bir ComputerName parametresi varsa ve kanallı nesne bir ComputerName özelliğine sahipse, ComputerName özelliğinin değeri işlevin ComputerName parametresine atanır.

Aşağıdaki örnekte zorunlu olan bir ComputerName parametresi bildirilir ve nesnenin işlem hattı aracılığıyla işleve geçirilen ComputerName özelliğinden gelen girişleri kabul eder.

param(
    [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
    [string[]]$ComputerName
)

Bu bağımsız değişkeni kullanarak bir işlevin uygulanmasını göz önünde bulundurun:

function Test-ValueFromPipelineByPropertyName{
  param(
      [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
      [string[]]$ComputerName
  )
  Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}

Ardından ComputerName özelliğine sahip bir nesnenin piping gösterimi şöyle olacaktır:

[pscustomobject]@{ ComputerName = "HelloWorld" } |
    Test-ValueFromPipelineByPropertyName

Saw that ComputerName was 'HelloWorld'

Not

İşlem hattı girişini () veya (by Valueby PropertyName) kabul eden türlenmiş bir parametre, parametrede delay-bind betik bloklarının kullanılmasını sağlar.

Delay-bind betik bloğu ParameterBinding sırasında otomatik olarak çalıştırılır. Sonuç parametresine bağlıdır. ScriptBlock veya System.Object türü olarak tanımlanan parametreler için gecikme bağlaması çalışmaz. Betik bloğu çağrılmadan geçirilir. Gecikmeli bağlama betik blokları hakkında daha fazla bilgi için bkz. about_Script_Blocks.

ValueFromRemainingArguments bağımsız değişkeni

ValueFromRemainingArguments bağımsız değişkeni, parametrenin işlevin diğer parametrelerine atanmamış olan komuttaki tüm parametre değerlerini kabul ettiğini gösterir.

Aşağıdaki örnekte zorunlu olan bir Value parametresi ve işleve gönderilen kalan tüm parametre değerlerini kabul eden Bir Kalan parametresi bildirilir.

function Test-Remainder {
    param(
        [Parameter(Mandatory, Position=0)]
        [string]$Value,

        [Parameter(Position=1, ValueFromRemainingArguments)]
        [string[]]$Remaining
    )

    "Found $($Remaining.Count) elements"

    for ($i = 0; $i -lt $Remaining.Count; $i++) {
        "${i}: $($Remaining[$i])"
    }
}
Test-Remainder first one, two

Found 2 elements
0: one
1: two

HelpMessage bağımsız değişkeni

bağımsız değişkeni, HelpMessage parametrenin veya değerinin kısa bir açıklamasını içeren bir dize belirtir. Komutu zorunlu parametre olmadan çalıştırırsanız PowerShell sizden giriş ister. Yardım iletisini görmek için istemde yazın !? ve Enter tuşuna basın.

Aşağıdaki örnek, zorunlu bir ComputerName parametresi ve beklenen parametre değerini açıklayan bir yardım iletisi bildirir.

param(
    [Parameter(Mandatory,
    HelpMessage="Enter one or more computer names separated by commas.")]
    [string[]]$ComputerName
)

Örnek çıkış:

cmdlet  at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:

İşlev için açıklama tabanlı yardım yoksa bu ileti çıktıda Get-Help -Full görüntülenir.

Bu bağımsız değişkenin isteğe bağlı parametreler üzerinde hiçbir etkisi yoktur.

DontShow argümanı

DontShow değeri genellikle eski bir parametrenin kaldırılamadığı bir komutun geriye dönük uyumluluğuna yardımcı olmak için kullanılır. DontShow True olarak ayarlanması, parametreyi sekme genişletme ve IntelliSense için kullanıcıdan gizler.

PowerShell v7 (ve üzeri), aşağıdaki eski parametreleri gizlemek için DontShow kullanır:

  • ve ConvertTo-Csv'ün Export-Csv parametresi
  • 'nin Format-Hex parametresi
  • ve Invoke-RestMethod'ün Invoke-WebRequest parametresi

DontShow bağımsız değişkeni aşağıdaki yan etkilere sahiptir:

  • DontShow kullanılmadığı bir parametre kümesi olsa bile ilişkili parametre için tüm parametre kümelerini etkiler.
  • Sekme tamamlama ve IntelliSense'ten ortak parametreleri gizler. DontShow isteğe bağlı ortak parametreleri gizlemez: WhatIf, Confirmveya UseTransaction.

Diğer ad özniteliği

Alias özniteliği, parametresi için alternatif bir ad oluşturur. Bir parametreye atayabileceğiniz diğer ad sayısıyla ilgili bir sınır yoktur.

Aşağıdaki örnekte CN ve MachineName diğer adlarını zorunlu ComputerName parametresine ekleyen bir parametre bildirimi gösterilmektedir.

param(
    [Parameter(Mandatory)]
    [Alias("CN","MachineName")]
    [string[]]$ComputerName
)

Kimlik bilgisi özniteliği

Credential özniteliği, parametresinin kimlik bilgilerini kabul ettiğini belirtmek için kullanılır. Aşağıdaki örnekte Credential özniteliğini kullanan bir parametre bildirimi gösterilmektedir.

param(
    [Parameter()]
    [System.Management.Automation.Credential()]
    [PSCredential]$Credential
)

Deneysel öznitelik

Deneysel özniteliğini kullanarak bazı kodları deneysel olarak bildirin. Özniteliğin tam açıklaması için bkz . about_Experimental_Features.

PSDefaultValue özniteliği

PSDefaultValue, komut dosyasındaki bir komut parametresinin varsayılan değerini belirtir. Bu bilgiler cmdlet'i Get-Help tarafından görüntülenir. Varsayılan değer bilgilerini görmek için işlevin açıklama tabanlı yardım içermesi gerekir. Örneğin:

<#
    .SYNOPSIS
     This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
    param(
        [PSDefaultValue(Help='Current directory')]
        [string]$Name = $PWD.Path
    )

    $Name
}

Varsayılan değer bilgilerini görmek için kullanın Get-Help .

Get-Help TestDefaultValue -Parameter Name

-Name <String>

    Required?                    false
    Position?                    1
    Default value                Current directory
    Accept pipeline input?       false
    Accept wildcard characters?  false

PSDefaultValue öznitelik bağımsız değişkenleri

PSDefaultValue özniteliğinin iki bağımsız değişkeni vardır:

  • Yardım - Varsayılan değeri açıklayan bir dize. Bu bilgiler cmdlet'i Get-Help tarafından görüntülenir.
  • Değer - Parametresinin varsayılan değeri.

Her iki bağımsız değişken de isteğe bağlıdır. Herhangi bir bağımsız değişken belirtmezseniz parametreye Get-Help atanan değeri gösterir.

PSTypeName özniteliği

Genişletilmiş tür adlarını tür bildiriminde kullanamazsınız. PSTypeName* özniteliği, parametre türünü genişletilmiş türle kısıtlamanıza olanak tanır.

Bu örnekte, Test-Connection cmdlet genişletilmiş bir tür döndürür. Parametrenin türünü genişletilmiş türle kısıtlamak için PSTypeName özniteliğini kullanabilirsiniz.

function TestType {
    param(
        [PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
        [psobject]$MtuStatus
    )

    $MtuStatus
}

$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu

System.Obsolete özniteliği

Artık desteklenmeyen parametreleri işaretlemek için System.Obsolete özniteliğini kullanın. Bu, bir işlevden parametreyi kaldırmak istediğinizde ancak işlevi kullanan mevcut betikleri kesmek istemediğinizde yararlı olabilir.

Örneğin, tür bilgilerinin çıkışa eklenip eklenmeyeceğini denetleen NoTypeInformation anahtar parametresine sahip bir işlev düşünün. Bu davranışı varsayılan yapmak ve parametresini işlevden kaldırmak istiyorsunuz. Ancak, işlevini kullanan mevcut betikleri bölmek istemezsiniz. Parametresini eski olarak işaretleyebilir ve değişikliği açıklayan bir ileti ekleyebilirsiniz.

param(
    [System.Obsolete("The NoTypeInformation parameter is obsolete.")]
    [SwitchParameter]$NoTypeInformation
)

Wildcards özniteliğini destekler

SupportsWildcards özniteliği, parametresinin joker karakter değerlerini kabul ettiğini belirtmek için kullanılır. Aşağıdaki örnekte joker karakter değerlerini destekleyen zorunlu path parametresi için parametre bildirimi gösterilmektedir.

param(
    [Parameter(Mandatory)]
    [SupportsWildcards()]
    [string[]]$Path
)

Bu özniteliğin kullanılması joker karakter desteğini otomatik olarak etkinleştirmez. Cmdlet geliştiricisinin joker karakter girişini işlemek için kodu uygulaması gerekir. Desteklenen joker karakterler, temel alınan API'ye veya PowerShell sağlayıcısına göre farklılık gösterebilir. Daha fazla bilgi için bkz . about_Wildcards.

Bağımsız değişken tamamlama öznitelikleri

ArgumentCompletions özniteliği

ArgumentCompletions özniteliği, belirli bir parametreye sekme tamamlama değerleri eklemenize olanak tanır. Sekme tamamlaması gereken her parametre için bir ArgumentCompletions özniteliği tanımlanmalıdır. ArgumentCompletions özniteliği ValidateSet'e benzer. Her iki öznitelik de kullanıcı parametre adından sonra Sekme tuşuna bastığında sunulacak değerlerin listesini alır. Ancak ValidateSet'in aksine değerler doğrulanmaz.

Bu öznitelik PowerShell 6.0'da kullanıma sunulmuştur.

Daha fazla bilgi için bkz . about_Functions_Argument_Completion.

ArgumentCompleter özniteliği

ArgumentCompleter özniteliği, belirli bir parametreye sekme tamamlama değerleri eklemenize olanak tanır. Sekme tamamlaması gereken her parametre için bir ArgumentCompleter özniteliği tanımlanmalıdır. Dinamik parametreler gibi, kullanıcı parametre adından sonra Sekme tuşuna bastığında kullanılabilir değerler çalışma zamanında hesaplanır.

Daha fazla bilgi için bkz . about_Functions_Argument_Completion.

Parametre ve değişken doğrulama öznitelikleri

Doğrulama öznitelikleri, kullanıcıların gelişmiş işlevi çağırdığında gönderdiği parametre değerlerini test etmek için PowerShell'i yönlendirir. Parametre değerleri testte başarısız olursa bir hata oluşturulur ve işlev çağrılmaz. Parametre doğrulaması yalnızca sağlanan girişe uygulanır ve varsayılan değerler gibi diğer değerler doğrulanmaz.

Kullanıcıların değişkenler için belirtebileceği değerleri kısıtlamak için doğrulama özniteliklerini de kullanabilirsiniz.

[AllowNull()] [int]$number = 7

Doğrulama öznitelikleri yalnızca parametrelere değil, herhangi bir değişkene uygulanabilir. Betik içindeki herhangi bir değişken için doğrulama tanımlayabilirsiniz.

Not

Türü belirlenmiş bir değişkene sahip öznitelikleri kullanırken, özniteliği türünden önce bildirmek en iyi yöntemdir.

Öznitelik ve değişken adından önce satır sonu içeren bir tür bildirirseniz, tür kendi deyimi olarak değerlendirilir.

[string]
[ValidateLength(1,5)] $Text = 'Okay'

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Bir türden sonra doğrulama özniteliği bildirirseniz, atanan değer tür dönüştürme işleminden önce doğrulanır ve bu da beklenmeyen doğrulama hatalarına yol açabilir.

[string] [ValidateLength(1,5)]$TicketIDFromInt        = 43
[string] [ValidateLength(1,5)]$TicketIDFromString     = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43

MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.

AllowNull doğrulama özniteliği

AllowNull özniteliği, zorunlu parametrenin değerinin olmasına $nullizin verir. Aşağıdaki örnekte null değere sahip olabilecek bir hashtable ComputerInfo parametresi bildirmektedir.

param(
    [Parameter(Mandatory)]
    [AllowNull()]
    [hashtable]$ComputerInfo
)

Not

Dize türü null değer kabul etmediğinden tür dönüştürücü dize olarak ayarlanırsa AllowNull özniteliği çalışmaz. Bu senaryo için AllowEmptyString özniteliğini kullanabilirsiniz.

AllowEmptyString doğrulama özniteliği

AllowEmptyString özniteliği, zorunlu parametrenin değerinin boş dize ("" olmasına) izin verir. Aşağıdaki örnek, boş dize değerine sahip olabilecek bir ComputerName parametresini bildirir.

param(
    [Parameter(Mandatory)]
    [AllowEmptyString()]
    [string]$ComputerName
)

AllowEmptyCollection doğrulama özniteliği

AllowEmptyCollection özniteliği, zorunlu parametrenin değerinin boş bir koleksiyon @()olmasına izin verir. Aşağıdaki örnek, boş bir koleksiyon değerine sahip olabilecek bir ComputerName parametresini bildirir.

param(
    [Parameter(Mandatory)]
    [AllowEmptyCollection()]
    [string[]]$ComputerName
)

ValidateCount doğrulama özniteliği

ValidateCount özniteliği, parametrenin kabul edildiği parametre değerlerinin en az ve en fazla sayısını belirtir. İşlevi çağıran komuttaki parametre değerlerinin sayısı bu aralığın dışındaysa PowerShell hata oluşturur.

Aşağıdaki parametre bildirimi, bir ila beş parametre değeri alan bir ComputerName parametresi oluşturur.

param(
    [Parameter(Mandatory)]
    [ValidateCount(1,5)]
    [string[]]$ComputerName
)

ValidateLength doğrulama özniteliği

ValidateLength özniteliği, parametre veya değişken değerindeki en az ve en fazla karakter sayısını belirtir. Bir parametre veya değişken için belirtilen değerin uzunluğu aralığın dışındaysa PowerShell hata oluşturur.

Aşağıdaki örnekte, her bilgisayar adının bir ile on karakter arasında olması gerekir.

param(
    [Parameter(Mandatory)]
    [ValidateLength(1,10)]
    [string[]]$ComputerName
)

Aşağıdaki örnekte değişkenin $text değeri en az bir karakter uzunluğunda ve en fazla on karakter olmalıdır.

[ValidateLength(1,10)] [string] $text = 'valid'

ValidatePattern doğrulama özniteliği

ValidatePattern özniteliği, parametre veya değişken değeriyle karşılaştırıldığında normal bir ifade belirtir. Değer normal ifade deseni ile eşleşmiyorsa PowerShell bir hata oluşturur.

Aşağıdaki örnekte parametre değeri dört basamaklı bir sayı içermeli ve her basamak sıfır ile dokuz arasında bir sayı olmalıdır.

param(
    [Parameter(Mandatory)]
    [ValidatePattern("[0-9]{4}")]
    [string[]]$ComputerName
)

Aşağıdaki örnekte değişkenin $ticketID değeri tam olarak dört basamaklı bir sayı olmalı ve her basamak sıfırdan dokuza kadar olmalıdır.

[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111

ValidateRange doğrulama özniteliği

ValidateRange özniteliği, her parametre veya değişken değeri için sayısal bir aralık veya ValidateRangeKind sabit listesi değeri belirtir. PowerShell, bu aralığın dışında bir değer varsa bir hata oluşturur.

ValidateRangeKind sabit listesi aşağıdaki değerlere izin verir:

  • Positive - Sıfırdan büyük bir sayı.
  • Negative - Sıfırdan küçük bir sayı.
  • NonPositive - Sıfırdan küçük veya sıfıra eşit bir sayı.
  • NonNegative - Sıfırdan büyük veya sıfıra eşit bir sayı.

Aşağıdaki örnekte, Attempts parametresinin değeri sıfır ile on arasında olmalıdır.

param(
    [Parameter(Mandatory)]
    [ValidateRange(0,10)]
    [int]$Attempts
)

Aşağıdaki örnekte değişkeninin $number değeri sıfır ile on arasında olmalıdır.

[ValidateRange(0,10)] [int]$number = 5

Aşağıdaki örnekte değişkeninin $number değeri sıfırdan büyük olmalıdır.

[ValidateRange("Positive")] [int]$number = 1

ValidateScript doğrulama özniteliği

ValidateScript özniteliği, parametre veya değişken değerini doğrulamak için kullanılan bir betiği belirtir. PowerShell, değeri betike döndürür ve betik döndürürse $false veya bir özel durum oluşturursa bir hata oluşturur.

ValidateScript özniteliğini kullandığınızda, doğrulanan değer değişkenine $_ eşlenir. Betikteki $_ değere başvurmak için değişkenini kullanabilirsiniz.

Aşağıdaki örnekte EventDate parametresinin değeri geçerli tarihten büyük veya buna eşit olmalıdır.

param(
    [Parameter(Mandatory)]
    [ValidateScript({$_ -ge (Get-Date)})]
    [datetime]$EventDate
)

Aşağıdaki örnekte değişkenin $date değeri geçerli tarih ve saat değerinden küçük veya buna eşit olmalıdır.

[ValidateScript({$_ -le (Get-Date)})] [datetime]$date = (Get-Date)

Not

ValidateScript kullanıyorsanız parametresine bir $null değer geçiremezsiniz. Null değer geçirdiğinizde ValidateScript bağımsız değişkeni doğrulayamaz.

Varsayılan hata iletisini geçersiz kılma

PowerShell 6'dan başlayarak, belirtilen bir değer bağımsız değişkenle ErrorMessage geçersiz olduğunda oluşturulan varsayılan hata iletisini geçersiz kılabilirsiniz. Bileşik biçim dizesi belirtin. Dizin 0 bileşeni giriş değerini kullanır. Dizin 1 bileşeni, giriş değerini doğrulamak için kullanılan ScriptBlock'ı kullanır.

Aşağıdaki örnekte EventDate parametresinin değeri geçerli tarih ve saat değerinden büyük veya buna eşit olmalıdır. Değer geçersizse, hata iletisi belirtilen tarih ve saatin çok eski olduğunu bildirir.

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date)},
        ErrorMessage = "{0} isn't a future date. Specify a later date."
    )]
    [datetime]$EventDate
)

Belirtilen değer geçmiş bir tarih olduğunda, özel hata iletisi döndürülür.

Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.

İsteğe bağlı biçim dizesi bileşenleriyle dizeye daha fazla biçimlendirme uygulayabilirsiniz.

Aşağıdaki örnekte EventDate parametresinin değeri geçerli tarih ve saat değerinden büyük veya buna eşit olmalıdır. Değer geçersizse, hata iletisi belirtilen tarihin çok eski olduğunu bildirir.

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date).Date},
        ErrorMessage = "{0:d} isn't a future date. Specify a later date."
    )]
    [datetime]$EventDate
)

Belirtilen değer geçmiş bir tarih olduğunda, özel hata iletisi döndürülür.

Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.

ValidateSet özniteliği

ValidateSet özniteliği, bir parametre veya değişken için bir dizi geçerli değer belirtir ve sekmenin tamamlanmasını sağlar. Bir parametre veya değişken değeri kümedeki bir değerle eşleşmiyorsa PowerShell hata oluşturur. Aşağıdaki örnekte Detail parametresinin değeri yalnızca Düşük, Ortalama veya Yüksek olabilir.

param(
    [Parameter(Mandatory)]
    [ValidateSet("Low", "Average", "High")]
    [string[]]$Detail
)

Aşağıdaki örnekte değişkenin $flavor değeri Chocolate, Strawberry veya Vanilla olmalıdır.

[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"

Bu değişken betik içinde bile atandığında doğrulama gerçekleşir. Örneğin, aşağıdakiler çalışma zamanında bir hatayla sonuçlanır:

param(
    [ValidateSet("hello", "world")]
    [string]$Message
)

$Message = "bye"

Bu örnek çalışma zamanında aşağıdaki hatayı döndürür:

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

ayrıca kullanarak ValidateSet bu parametre için değerlerin sekme genişletmesini etkinleştirin. Daha fazla bilgi için bkz . about_Tab_Expansion.

Sınıfları kullanan Dinamik ValidateSet değerleri

Çalışma zamanında class değerlerini dinamik olarak oluşturmak için bir kullanabilirsiniz. Aşağıdaki örnekte, değişken $Sound için geçerli değerler, kullanılabilir ses dosyaları için üç dosya sistemi yolunu denetleen class adlı bir aracılığıyla oluşturulur:

class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [string[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
            '/Library/Sounds','~/Library/Sounds'
        $SoundNames = foreach ($SoundPath in $SoundPaths) {
            if (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [string[]] $SoundNames
    }
}

Sınıf [SoundNames] daha sonra aşağıdaki gibi dinamik bir ValidateSet değeri olarak uygulanır:

param(
    [ValidateSet([SoundNames])]
    [string]$Sound
)

Not

IValidateSetValuesGenerator sınıfı PowerShell 6.0'da tanıtıldı

ValidateNotNull doğrulama özniteliği

ValidateNotNull özniteliği parametre değerinin olamaz$null. değeri olduğunda $nullPowerShell bir özel durum oluşturur.

ValidateNotNull özniteliği, parametre isteğe bağlı olduğunda ve tür tanımlanmamışsa veya nesne gibi bir null değeri örtük olarak dönüştüremeyen bir tür dönüştürücüye sahip olduğunda kullanılacak şekilde tasarlanmıştır. Dize gibi bir null değeri örtük olarak dönüştüren bir tür belirtirseniz, ValidateNotNull özniteliği kullanılırken bile null değer boş bir dizeye dönüştürülür. Bu senaryo için ValidateNotNullOrEmpty özniteliğini kullanın.

Aşağıdaki örnekte, Kimliği parametresinin değeri $null.

param(
    [Parameter()]
    [ValidateNotNull()]
    $Id
)

ValidateNotNullOrEmpty doğrulama özniteliği

ValidateNotNullOrEmpty özniteliği, atanan değerin aşağıdaki değerlerden hiçbiri olamaz:

  • $null
  • boş dize ("")
  • boş bir dizi (@())

Değer geçersiz olduğunda PowerShell bir özel durum oluşturur.

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string[]]$UserName
)

ValidateNotNullOrWhiteSpace doğrulama özniteliği

ValidateNotNullOrWhiteSpace özniteliği, atanan değerin aşağıdaki değerlerden biri olmadığını belirtir:

  • $null
  • boş dize ("")
  • boş bir dizi @()
  • yalnızca sekmeler, boşluklar, satır başı ve yeni satırlar gibi boşluk karakterleri içeren bir dize
  • boş olan veya yalnızca boşluk karakterleri içeren dizeleri içeren bir dizi

Değer geçersiz olduğunda PowerShell bir özel durum oluşturur.

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrWhiteSpace()]
    [string[]]$UserName
)

ValidateDrive doğrulama özniteliği

ValidateDrive özniteliği, parametre değerinin yolu temsil etmesi gerektiğini belirtir; bu yalnızca izin verilen sürücülere başvurur. Parametre değeri izin verilen dışındaki sürücülere başvuruyorsa PowerShell bir hata oluşturur. Sürücünün kendisi dışında yolun varlığı doğrulanmamıştır.

Göreli yol kullanıyorsanız, geçerli sürücü izin verilen sürücü listesinde olmalıdır.

param(
    [ValidateDrive("C", "D", "Variable", "Function")]
    [string]$Path
)

ValidateUserDrive doğrulama özniteliği

ValidateUserDrive özniteliği, parametre değerinin sürücüde User temsil etmesi gerektiğini belirtir. Yol farklı bir sürücüye başvuruyorsa PowerShell bir hata oluşturur. Doğrulama özniteliği yalnızca yolun sürücü ön ekinin varlığını test eder.

Göreli yol kullanıyorsanız geçerli sürücü olmalıdır User.

function Test-UserDrivePath{
    [OutputType([bool])]
    param(
        [Parameter(Mandatory, Position=0)]
        [ValidateUserDrive()]
        [string]$Path
    )
    $true
}

Test-UserDrivePath -Path C:\

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.

Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.

Yeterli Yönetim (JEA) oturum yapılandırmalarında sürücü tanımlayabilirsiniz User . Bu örnekte User: sürücüsünü oluşturacağız.

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $Env:HOMEPATH

Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
User               75.76         24.24 FileSystem    C:\Users\ExampleUser

Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

True

ValidateTrustedData doğrulama özniteliği

Bu öznitelik, PowerShell tarafından dahili olarak kullanılır ve dış kullanıma yönelik değildir.

Bu öznitelik PowerShell 6.1.1'e eklendi.

Ayrıca bkz.