about_Functions_Advanced_Parameters

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.

CmdletBinding özniteliğini 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 göstermek için @args ile birlikte sıçramayı 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 param() veya betik bloğunun 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 geçici olarak çözmek için, parametre değerlerini geçirmek için splatting 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, [datetime] parametresini alan bir cmdlet ve 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 true değeri olur ve olmadığında yanlış değeri olur.

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

İşlevde anahtar parametresi oluşturmak için parametre tanımında [switch] türünü belirtin. 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. Mesela:

-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. Filtre veya En Fazla gibi bir değerin gerekli olduğu anlamına gelen 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. Mesela:

  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-Content, Get-Contentve Set-Content cmdlet'lerinde kullanılabilir.

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 Get-Command parametresini veya Get-Help parametresini kullanması gerekir.

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

Söz dizimi aşağıdaki gibidir:

dynamicparam {<statement-list>}

deyimi listesinde, parametresinin işlevde hangi koşullarda kullanılabilir olduğunu belirtmek için bir if deyimi kullanın.

Aşağıdaki örnekte, Name ve Pathadlı standart parametrelere ve KeyCountadlı isteğe bağlı dinamik parametreye sahip bir işlev gösterilmektedir. KeyCount parametresi ByRegistryPath parametre kümesindedir ve Int32türündedir. KeyCount parametresi, Get-Sample işlevinde yalnızca Yolu parametresinin değeri, HKLM: kayıt defteri sürücüsünde kullanıldığını belirten HKEY_LOCAL_MACHINEile başladığında kullanılabilir.

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üne ilişkin belgelere 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

Parameter ö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ş işlev olarak tanınmak için, bir işlevin CmdletBinding özniteliğine veya Parameter özniteliğine veya 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.

Parametre özniteliğini, bağımsız değişkeni 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 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
)

Parameter özniteliğinin boole bağımsız değişkeni türleri, Parameter özniteliğinden atlandığında varsayılan olarak False olarak ayarlanır. Bağımsız değişken değerini $true olarak 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)]
)

Parameter ö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, parametrenin 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 zorunlu hale getirmek için Mandatory bağımsız değişkenini kullanır.

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

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

Position bağımsız değişkeni, parametre bir komutta kullanıldığında parametre adının gerekli olup olmadığını belirler. Parametre bildirimi Position bağımsız değişkenini içerdiğinde, 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şkeni 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 PositionalBinding özniteliğinin bağımsız değişkeninin değerini $falseolarak ayarlayın. Position bağımsız değişkeni, PositionalBinding özniteliğinin bağımsız değişkeninin değerinden önceliklidir. Daha fazla bilgi için bkz. PositionalBinding.

Position bağımsız değişkeninin değeri tamsayı olarak belirtilir. 0 konum değeri, komuttaki ilk konumu, 1 konum değeri 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 Position bağımsız değişkenini kullanın.

Aşağıdaki örnek, ComputerName parametresini bildirir. Positiondeğeriyle bağımsız değişkenini kullanır. Sonuç olarak, -ComputerName komutundan atlandığında değerinin komuttaki ilk veya yalnızca 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 örnek, parametre kümesinde bir Computer parametresi, parametre kümesinde User parametresi ve her iki parametre kümesinde de bir Özeti parametresi bildirir.

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, Summary parametresini Computer ve User parametre kümelerine açıkça ekler. Özeti parametresi, Computer parametre kümesinde isteğe bağlıdır ve User parametre kümesinde 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 parametresi 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 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 girişi 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 olur:

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

Saw that ComputerName was 'HelloWorld'

Not

İşlem hattı girişini () veya (by Valueby PropertyName) kabul eden türetilen parametre, parametrede gecikme bağlama 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 komutunda işlevin diğer parametrelerine atanmamış 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 Kalan parametresi bildirilir.

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

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

    "Value = $Value"
    "Found $($Remaining.Count) remaining values"

    for ($i = 0; $i -lt $Remaining.Count; $i++) {
        "${i}: $($Remaining[$i])"
    }
}

PS> Test-Remainder first one two three

Value = first
Found 3 remaining values
0: one
1: two
2: three

PowerShell 6.2'den başlayarak, ValueFromRemainingArguments'a geçirildiğinde koleksiyonlar farklı şekilde işlenir. Yalnızca bir koleksiyon geçirirseniz, koleksiyondaki her değer ayrı bir öğe olarak değerlendirilir.

PS> Test-Remainder first one, two, three

Value = first
Found 3 remaining values
0: one
1: two
2: three

En az birinin koleksiyon olmadığı birden çok değer geçirdiğinizde, koleksiyon tek bir öğe olarak değerlendirilir.

PS> Test-Remainder first one, two three four

Value = first
Found 3 remaining values
0: one two
1: three
2: four

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

HelpMessage bağımsız değişkeni, 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 istemine !? yazın ve enter tuşuna basın.

Aşağıdaki örnek, ComputerName parametresini zorunlu 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 Get-Help -Full çıktısında görüntülenir.

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

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

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-CsvExport-Csv parametresi
• Format-Hex parametresi
• ve Invoke-RestMethodInvoke-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 Onayla veya UseTransaction .

Diğer ad özniteliği

Diğer Ad özniteliği, parametre 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, zorunlu ComputerName parametresine CN ve MachineName diğer adlarını ekleyen bir parametre bildirimi gösterilmektedir.

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

Kimlik bilgisi özniteliği

Credential özniteliği, parametrenin 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

Bazı kodları deneysel olarak bildirmek için Experimental özniteliğini kullanın. Özniteliğin tam açıklaması için bkz. about_Experimental_Features.

PSDefaultValue özniteliği

PSDefaultValue betikteki bir komut parametresinin varsayılan değerini belirtir. Bu bilgiler Get-Help cmdlet'i 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. Mesela:

<#
    .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 Get-Help kullanın.

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 Get-Help cmdlet'i tarafından görüntülenir.
• Değer - Parametrenin 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, Get-Help parametreye atanan değeri gösterir.

PSTypeName özniteliği

Genişletilmiş tür adlarını tür bildiriminde kullanamazsınız. PSTypeName* özniteliği, parametrenin türünü genişletilmiş türle kısıtlamanızı sağlar.

Bu örnekte, Test-Connection cmdlet'i 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 çıktıya 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 bir 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 ValidateSetile benzerdir. Her iki öznitelik de kullanıcı parametre adından sonra sekme bastığında sunulacak değerlerin listesini alır. Ancak, ValidateSetaksine, 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 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 $nullolmasını sağlar. Aşağıdaki örnek, null değerine sahip olabilecek bir computerinfo parametresi bir hashtable bildirir.

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 ayarlandıysa 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ş bir dize ("") olmasını sağlar. Aşağıdaki örnek, boş bir dize değerine sahip olabilecek bir ComputerName parametresi 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 parametresi 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, $text değişkeninin 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, $ticketID değişkeninin değeri tam olarak dört basamaklı bir sayı olmalı ve her basamak sıfır ile dokuz arasında bir sayı 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 bir sayısal aralık veya ValidateRangeKind numaralandırma 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, Denemeleri 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, $number değişkeninin değeri sıfır ile on arasında olmalıdır.

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

Aşağıdaki örnekte, $number değişkeninin 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 kanallar ve betik $false döndürürse veya betik 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, $date değişkeninin 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

ValidateScriptkullanıyorsanız parametresine $null değeri 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 ErrorMessage bağımsız değişkeniyle geçersiz olduğunda oluşturulan varsayılan hata iletisini geçersiz kılabilirsiniz. bileşik biçim dizesi belirtin. 0 dizin bileşeni giriş değerini kullanır. 1 dizin 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.

isteğe bağlıbiçim dizesi bileşenleriyle dizede 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 geçerli değerler kümesini 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, Ayrıntı 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, $flavor değişkeninin 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.

ValidateSet kullanarak, bu parametre için değerlerin sekme genişletmesini de 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
    }
}

[SoundNames] sınıfı daha sonra aşağıdaki gibi dinamik 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 $nullolmadığını belirtir. Değer $nullolduğunda PowerShell bir özel durum oluşturur.

ValidateNotNull özniteliği, parametre isteğe bağlı olduğunda ve türü tanımsız olduğunda veya nesnesigibi bir null değeri örtük olarak dönüştüremeyen bir tür dönüştürücüsü olduğunda kullanılacak şekilde tasarlanmıştır. dizegibi 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 biri olmadığını belirtir:

• $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 User sürücüde gösterilmesi 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ü Userolmalıdır.

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 User sürücü tanımlayabilirsiniz. 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 bakınız

• about_Automatic_Variables
• about_Functions
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute