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.
İşlevinize eklediğiniz parametreler, PowerShell'in tüm cmdlet'lere ve gelişmiş işlevlere otomatik olarak eklediği ortak parametrelere ek olarak kullanıcılar tarafından kullanılabilir. PowerShell ortak parametreleri hakkında 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 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."
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 .
Örneğin, işlevinizin verileri bayt dizisi olarak çıktı olarak verme seçeneği olabilir:
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.
Örneğin, switch parametresini kullanmak için kullanıcı parametresini komutuna yazın.
-IncludeAll
Boole parametresini kullanmak için kullanıcı parametresini ve boole değerini yazın.
-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
Anahtar parametrelerine varsayılan değerler verilmemelidir. Varsayılan olarak false olmalıdır.
Anahtar parametreleri varsayılan olarak konumsal parametrelerin dışında tutulur. Diğer parametreler örtük olarak konumsal olsa bile anahtar parametreleri değildir. Parametre özniteliğinde bunu geçersiz kılabilirsiniz, ancak kullanıcıların kafasını karıştırır.
Anahtar parametreleri, ayarlanacak şekilde tasarlanmalıdır, böylece bir komut varsayılan davranışından daha az yaygın veya daha karmaşık bir moda taşınır. Bir komutun en basit davranışı, anahtar parametrelerinin kullanılmasını gerektirmeyen varsayılan davranış olmalıdır.
Anahtar parametreleri zorunlu olmamalıdır. Anahtar parametresini zorunlu hale getirmenin gerekli olduğu tek durum, parametre kümesini ayırt etmek için gerekli olmasıdır.
Boole'dan açıkça bir anahtar ayarlama işlemi ile
-MySwitch:$boolValueve ile$params = @{ MySwitch = $boolValue }birlikte sıçranarak yapılabilir.Anahtar parametreleri, örtük olarak Boole değerine dönüştüren türündedir
SwitchParameter. Parametre değişkeni doğrudan bir koşullu ifadede kullanılabilir. Örneğin:if ($MySwitch) { ... }Yazmanız gerekmez
if ($MySwitch.IsPresent) { ... }
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 , Get-Contentve Set-Content cmdlet'lerinde kullanılabilirAdd-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-Helpkullanması gerekir.Get-Command
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 CmdletBinding özniteliğinin bağımsız değişkeninin değerini PositionalBinding 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 Computer bir ComputerName parametresi, parametre kümesinde User userName 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 Parametre özniteliğinde yalnızca bir ParameterSetName 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 User parametre kümelerine Summary parametresini Computer açıkça ekler. Ö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.
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-Helptarafı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. DynamicParameters 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:
- Pozitif - Sıfırdan büyük bir sayı.
- Negatif - 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 ValidateSet değerlerini dinamik olarak oluşturmak için bir Sınıf 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 SoundNames adlı bir Sınıf 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, ID parametresinin değeri olamaz$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
)
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.
Sürücüyü Yeterli Yönetici istrasyon (JEA) oturum yapılandırmalarında tanımlayabilirsinizUser. 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 6.1.1'e eklendi.
Şu anda özniteliği PowerShell tarafından dahili olarak kullanılır ve dış kullanıma yönelik değildir.
Ayrıca bkz.
PowerShell
Geri Bildirim
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz. https://aka.ms/ContentUserFeedback.
Gönderin ve geri bildirimi görüntüleyin