about_Functions_Advanced_Parameters

Deskripsi singkat

Menjelaskan cara menambahkan parameter ke fungsi tingkat lanjut.

Deskripsi panjang

Anda dapat menambahkan parameter ke fungsi tingkat lanjut yang Anda tulis, dan menggunakan atribut parameter dan argumen untuk membatasi nilai parameter yang dikirimkan pengguna fungsi dengan parameter .

Parameter yang Anda tambahkan ke fungsi Anda tersedia untuk pengguna selain parameter umum yang ditambahkan PowerShell secara otomatis ke semua cmdlet dan fungsi tingkat lanjut. Untuk informasi selengkapnya tentang parameter umum PowerShell, lihat about_CommonParameters.

Dimulai di PowerShell 3.0, Anda dapat menggunakan splatting dengan @Args untuk mewakili parameter dalam perintah. Splatting valid pada fungsi sederhana dan tingkat lanjut. Untuk informasi selengkapnya, lihat about_Functions dan about_Splatting.

Konversi jenis nilai parameter

Saat Anda menyediakan string sebagai argumen ke parameter yang mengharapkan jenis yang berbeda, PowerShell secara implisit mengonversi string ke jenis target parameter. Fungsi lanjutan melakukan penguraian nilai parameter yang invarian budaya.

Sebaliknya, konversi sensitif budaya dilakukan selama pengikatan parameter untuk cmdlet yang dikompilasi.

Dalam contoh ini, kami membuat cmdlet dan fungsi skrip yang mengambil [datetime] parameter. Budaya saat ini diubah untuk menggunakan pengaturan Jerman. Tanggal berformat Jerman diteruskan ke parameter .

# 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

Seperti yang ditunjukkan di atas, cmdlet menggunakan penguraian sensitif budaya untuk mengonversi string.

# 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

Fungsi tingkat lanjut menggunakan penguraian invarian budaya, yang mengakibatkan kesalahan berikut.

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."
At line:13 char:15
+ Get-Date_Func $dateStr
+               ~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Get-Date_Func], ParameterBindingArgumentTransformationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Get-Date_Func

Parameter statik

Parameter statis adalah parameter yang selalu tersedia dalam fungsi. Sebagian besar parameter dalam cmdlet dan skrip PowerShell adalah parameter statis.

Contoh berikut menunjukkan deklarasi parameter ComputerName yang memiliki karakteristik berikut:

  • Ini wajib (diperlukan).
  • Dibutuhkan input dari alur.
  • Dibutuhkan array string sebagai input.
param(
    [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
    [string[]]$ComputerName
)

Beralih parameter

Parameter pengalihan adalah parameter yang tidak mengambil nilai parameter. Sebaliknya, mereka menyampaikan nilai true-or-false Boolean melalui kehadiran atau ketidakhadirannya, sehingga ketika parameter switch hadir, parameter tersebut memiliki nilai yang sebenarnya dan ketika tidak ada, parameter tersebut memiliki nilai palsu .

Misalnya, parameter Rekursi adalah Get-ChildItem parameter pengalihan.

Untuk membuat parameter pengalihan dalam fungsi, tentukan switch jenis dalam definisi parameter.

Misalnya, fungsi Anda mungkin memiliki opsi untuk menghasilkan data sebagai array byte:

param([switch]$AsByteArray)

Parameter switch mudah digunakan dan lebih disukai daripada parameter Boolean, yang memiliki sintaks yang kurang alami untuk PowerShell.

Misalnya, untuk menggunakan parameter pengalihan, pengguna mengetikan parameter dalam perintah .

-IncludeAll

Untuk menggunakan parameter Boolean, pengguna mengetikan parameter dan nilai Boolean.

-IncludeAll $true

Saat membuat parameter pengalihan, pilih nama parameter dengan hati-hati. Pastikan bahwa nama parameter mengkomunikasikan efek parameter kepada pengguna. Hindari istilah ambigu, seperti Filter atau Maksimum yang mungkin menyiratkan nilai diperlukan.

Beralih pertimbangan desain parameter

  • Parameter pengalihan tidak boleh diberikan nilai default. Mereka harus selalu default ke false.

  • Parameter pengalihan dikecualikan dari parameter posisi secara default. Bahkan ketika parameter lain secara implisit posisional, parameter pengalihan tidak. Anda dapat mengambil alihnya di atribut Parameter, tetapi akan membingungkan pengguna.

  • Parameter pengalihan harus dirancang sehingga mengaturnya memindahkan perintah dari perilaku defaultnya ke mode yang kurang umum atau lebih rumit. Perilaku paling sederhana dari perintah harus merupakan perilaku default yang tidak memerlukan penggunaan parameter sakelar.

  • Parameter pengalihan tidak boleh wajib. Satu-satunya kasus di mana perlu untuk membuat parameter pengalihan wajib adalah ketika diperlukan untuk membedakan set parameter.

  • Secara eksplisit mengatur sakelar dari boolean dapat dilakukan dengan -MySwitch:$boolValue dan berceceran dengan $params = @{ MySwitch = $boolValue }.

  • Parameter pengalihan berjenis SwitchParameter, yang secara implisit dikonversi ke Boolean. Variabel parameter dapat digunakan langsung dalam ekspresi bersyarah. Contohnya:

    if ($MySwitch) { ... }

    Tidak perlu menulis if ($MySwitch.IsPresent) { ... }

Parameter dinamis

Parameter dinamis adalah parameter cmdlet, fungsi, atau skrip yang hanya tersedia dalam kondisi tertentu.

Misalnya, beberapa cmdlet penyedia memiliki parameter yang hanya tersedia ketika cmdlet digunakan dalam drive penyedia, atau di jalur tertentu dari drive penyedia. Misalnya, parameter Pengodean tersedia pada Add-Contentcmdlet , Get-Content, dan Set-Content hanya saat digunakan dalam drive sistem file.

Anda juga dapat membuat parameter yang hanya muncul ketika parameter lain digunakan dalam perintah fungsi atau ketika parameter lain memiliki nilai tertentu.

Parameter dinamis dapat berguna, tetapi gunakan hanya jika perlu, karena mereka bisa sulit ditemukan pengguna. Untuk menemukan parameter dinamis, pengguna harus berada di jalur penyedia, menggunakan parameter ArgumentList cmdletGet-Command, atau menggunakan parameter Jalur .Get-Help

Untuk membuat parameter dinamis untuk fungsi atau skrip, gunakan DynamicParam kata kunci.

Sintaksisnya adalah sebagai berikut:

dynamicparam {<statement-list>}

Dalam daftar pernyataan, gunakan if pernyataan untuk menentukan kondisi di mana parameter tersedia dalam fungsi.

Contoh berikut menunjukkan fungsi dengan parameter standar bernama Nama dan Jalur, dan parameter dinamis opsional bernama KeyCount. Parameter KeyCount berada dalam ByRegistryPath set parameter dan memiliki jenis Int32. Parameter KeyCount tersedia dalam Get-Sample fungsi hanya ketika nilai parameter Path dimulai dengan HKLM:, menunjukkan bahwa parameter tersebut digunakan dalam HKEY_LOCAL_MACHINE drive registri.

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
    }
  }
}

Untuk informasi selengkapnya, lihat dokumentasi untuk jenis RuntimeDefinedParameter .

Atribut parameter

Bagian ini menjelaskan atribut yang dapat Anda tambahkan ke parameter fungsi.

Semua atribut bersifat opsional. Namun, jika Anda menghilangkan atribut CmdletBinding , maka untuk dikenali sebagai fungsi tingkat lanjut, fungsi harus menyertakan atribut Parameter .

Anda dapat menambahkan satu atau beberapa atribut di setiap deklarasi parameter. Tidak ada batasan jumlah atribut yang dapat Anda tambahkan ke deklarasi parameter.

Atribut parameter

Atribut Parameter digunakan untuk mendeklarasikan atribut parameter fungsi.

Atribut Parameter bersifat opsional, dan Anda dapat menghilangkannya jika tidak ada parameter fungsi Anda yang memerlukan atribut. Tetapi, untuk diakui sebagai fungsi lanjutan, daripada fungsi sederhana, fungsi harus memiliki atribut CmdletBinding atau atribut Parameter , atau keduanya.

Atribut Parameter memiliki argumen yang menentukan karakteristik parameter, seperti apakah parameter wajib atau opsional.

Gunakan sintaks berikut untuk mendeklarasikan atribut Parameter , argumen, dan nilai argumen. Tanda kurung yang mengapit argumen dan nilainya harus mengikuti Parameter tanpa ruang intervensi.

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

Gunakan koma untuk memisahkan argumen dalam tanda kurung. Gunakan sintaks berikut untuk mendeklarasikan dua argumen atribut Parameter .

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

Jenis argumen boolean dari atribut Parameter default ke False saat dihilangkan dari atribut Parameter . Atur nilai argumen ke $true atau cukup cantumkan argumen menurut nama. Misalnya, atribut Parameter berikut setara.

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

# Boolean arguments can be defined using this shorthand syntax

param(
    [Parameter(Mandatory)]
)

Jika Anda menggunakan atribut Parameter tanpa argumen, sebagai alternatif untuk menggunakan atribut CmdletBinding , tanda kurung yang mengikuti nama atribut masih diperlukan.

param(
    [Parameter()]
    $ParameterName
)

Argumen wajib

Argumen Mandatory menunjukkan bahwa parameter diperlukan. Jika argumen ini tidak ditentukan, parameter bersifat opsional.

Contoh berikut mendeklarasikan parameter ComputerName . Ini menggunakan Mandatory argumen untuk membuat parameter wajib.

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

Argumen posisi

Argumen Position menentukan apakah nama parameter diperlukan saat parameter digunakan dalam perintah. Saat deklarasi parameter menyertakan Position argumen, nama parameter dapat dihilangkan dan PowerShell mengidentifikasi nilai parameter yang tidak disebutkan namanya berdasarkan posisinya, atau urutannya, dalam daftar nilai parameter yang tidak disebutkan namanya dalam perintah.

Position Jika argumen tidak ditentukan, nama parameter, atau alias atau singkatan nama parameter, harus mendahului nilai parameter setiap kali parameter digunakan dalam perintah.

Secara default, semua parameter fungsi bersifat posisi. PowerShell menetapkan angka posisi ke parameter dalam urutan parameter dideklarasikan dalam fungsi. Untuk menonaktifkan fitur ini, atur nilai PositionalBinding argumen atribut CmdletBinding ke $False. Argumen Position lebih diutamakan daripada nilai PositionalBinding argumen atribut CmdletBinding . Untuk informasi selengkapnya, lihat PositionalBinding di about_Functions_CmdletBindingAttribute.

Nilai Position argumen ditentukan sebagai bilangan bulat. Nilai posisi 0 mewakili posisi pertama dalam perintah, nilai posisi 1 mewakili posisi kedua dalam perintah, dan sebagainya.

Jika fungsi tidak memiliki parameter posisi, PowerShell menetapkan posisi ke setiap parameter berdasarkan urutan parameter yang dideklarasikan. Namun, sebagai praktik terbaik, jangan mengandalkan tugas ini. Saat Anda ingin parameter menjadi posisi, gunakan Position argumen .

Contoh berikut mendeklarasikan parameter ComputerName . Ini menggunakan Position argumen dengan nilai 0. Akibatnya, ketika -ComputerName dihilangkan dari perintah, nilainya harus menjadi nilai parameter pertama atau hanya tidak bernama dalam perintah.

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

Argumen ParameterSetName

Argumen ParameterSetName menentukan parameter yang menetapkan parameter milik. Jika tidak ada set parameter yang ditentukan, parameter milik semua set parameter yang ditentukan oleh fungsi. Agar unik, setiap set parameter harus memiliki setidaknya satu parameter yang bukan anggota set parameter lainnya.

Catatan

Untuk cmdlet atau fungsi, ada batas 32 set parameter.

Contoh berikut mendeklarasikan parameter ComputerName dalam Computer set parameter, parameter UserName dalam User set parameter, dan parameter Ringkasan di kedua set parameter.

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

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

    [Parameter()]
    [switch]$Summary
)

Anda hanya dapat menentukan satu ParameterSetName nilai dalam setiap argumen dan hanya satu ParameterSetName argumen di setiap atribut Parameter . Untuk menyertakan parameter dalam lebih dari satu set parameter, tambahkan atribut Parameter tambahan.

Contoh berikut secara eksplisit menambahkan parameter Ringkasan ke Computer kumpulan parameter dan User . Parameter Ringkasan bersifat opsional dalam Computer set parameter dan wajib dalam User kumpulan parameter.

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

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

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

Untuk informasi selengkapnya tentang set parameter, lihat Tentang Set Parameter.

Argumen ValueFromPipeline

Argumen ValueFromPipeline menunjukkan bahwa parameter menerima input dari objek alur. Tentukan argumen ini jika fungsi menerima seluruh objek, bukan hanya properti objek.

Contoh berikut mendeklarasikan parameter ComputerName yang wajib dan menerima objek yang diteruskan ke fungsi dari alur.

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

Argumen ValueFromPipelineByPropertyName

Argumen ValueFromPipelineByPropertyName menunjukkan bahwa parameter menerima input dari properti objek alur. Properti objek harus memiliki nama atau alias yang sama dengan parameter .

Misalnya, jika fungsi memiliki parameter ComputerName, dan objek piped memiliki properti ComputerName, nilai properti ComputerName ditetapkan ke parameter ComputerName fungsi.

Contoh berikut mendeklarasikan parameter ComputerName yang wajib dan menerima input dari properti ComputerName objek yang diteruskan ke fungsi melalui alur.

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

Pertimbangkan implementasi fungsi menggunakan argumen ini:

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

Kemudian demonstrasi pipa objek dengan properti ComputerName adalah:

[pscustomobject]@{ ComputerName = "HelloWorld" } |
    Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'

Catatan

Parameter jenis yang menerima input alur (by Value) atau (by PropertyName) memungkinkan penggunaan blok skrip yang tertunda-ikat pada parameter .

Blok skrip yang tertunda dijalankan secara otomatis selama ParameterBinding. Hasilnya terikat ke parameter . Pengikatan penundaan tidak berfungsi untuk parameter yang didefinisikan sebagai jenis ScriptBlock atau System.Object. Blok skrip diteruskan tanpa dipanggil. Untuk informasi selengkapnya tentang blok skrip yang tertunda , lihat about_Script_Blocks.

Argumen ValueFromRemainingArguments

Argumen ValueFromRemainingArguments menunjukkan bahwa parameter menerima semua nilai parameter dalam perintah yang tidak ditetapkan ke parameter fungsi lainnya.

Ada masalah yang diketahui untuk menggunakan koleksi dengan ValueFromRemainingArguments di mana koleksi yang diteruskan diperlakukan sebagai elemen tunggal.

Contoh berikut menunjukkan masalah yang diketahui ini. Parameter yang tersisa harus berisi satu pada indeks 0 dan dua pada indeks 1. Sebagai gantinya, kedua elemen digabungkan menjadi satu entitas.

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 1 elements
0: one two

Catatan

Masalah ini diatasi di PowerShell 6.2.

Argumen HelpMessage

Argumen HelpMessage menentukan string yang berisi deskripsi singkat parameter atau nilainya. Jika Anda menjalankan perintah tanpa parameter wajib, PowerShell akan meminta input. Untuk melihat pesan bantuan, ketik !? pada perintah dan tekan Enter.

Contoh berikut mendeklarasikan parameter ComputerName wajib dan pesan bantuan yang menjelaskan nilai parameter yang diharapkan.

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

Contoh output:

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]:

Jika tidak ada bantuan berbasis komentar untuk fungsi, maka pesan ini ditampilkan dalam Get-Help -Full output.

Argumen ini tidak berpengaruh pada parameter opsional.

Atribut alias

Atribut Alias menetapkan nama alternatif untuk parameter . Tidak ada batasan jumlah alias yang dapat Anda tetapkan ke parameter.

Contoh berikut menunjukkan deklarasi parameter yang menambahkan alias CN dan MachineName ke parameter ComputerName wajib.

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

Atribut kredensial

Atribut Kredensial digunakan untuk menunjukkan bahwa parameter menerima kredensial. Contoh berikut menunjukkan deklarasi parameter yang menggunakan atribut Kredensial .

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

Atribut PSDefaultValue

PSDefaultValue menentukan nilai default parameter perintah dalam skrip. Informasi ini ditampilkan oleh Get-Help cmdlet. Untuk melihat informasi nilai default, fungsi harus menyertakan bantuan berbasis komentar. Contohnya:

<#
    .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
}

Gunakan Get-Help untuk melihat informasi nilai default.

Get-Help TestDefaultValue -Parameter name
-Name <String>

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

Argumen atribut PSDefaultValue

Atribut PSDefaultValue memiliki dua argumen:

  • Bantuan - String yang menjelaskan nilai default. Informasi ini ditampilkan oleh Get-Help cmdlet.
  • Nilai - Nilai default parameter.

Kedua argumen bersifat opsional. Jika Anda tidak menentukan argumen apa pun, maka Get-Help tampilkan nilai yang ditetapkan ke parameter .

Atribut PSTypeName

Anda tidak dapat menggunakan nama jenis yang diperluas dalam deklarasi jenis. Atribut PSTypeName* memungkinkan Anda membatasi jenis parameter ke jenis yang diperluas.

Dalam contoh ini, Test-Connection cmdlet mengembalikan jenis yang diperluas. Anda dapat menggunakan atribut PSTypeName untuk membatasi jenis parameter ke jenis yang diperluas.

function TestType {
    param(
        [PSTypeName('System.Management.ManagementObject#root\cimv2\Win32_PingStatus')]
        [psobject]$PingStatus
    )

    $PingStatus
}

$ping = Test-Connection bing.com -Count 1
TestType $ping

Atribut System.Usang

Gunakan atribut System.Usang untuk menandai parameter yang tidak lagi didukung. Ini dapat berguna ketika Anda ingin menghapus parameter dari fungsi tetapi Anda tidak ingin memutus skrip yang ada yang menggunakan fungsi .

Misalnya, pertimbangkan fungsi yang memiliki parameter sakelar NoTypeInformation yang mengontrol apakah informasi jenis disertakan dalam output. Anda ingin menjadikan perilaku tersebut sebagai default dan menghapus parameter dari fungsi . Namun, Anda tidak ingin memutus skrip yang ada yang menggunakan fungsi . Anda dapat menandai parameter sebagai usang dan menambahkan pesan yang menjelaskan perubahan.

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

Atribut SupportsWildcards

Atribut SupportsWildcards digunakan untuk menunjukkan bahwa parameter menerima nilai kartubebas. Contoh berikut menunjukkan deklarasi parameter untuk parameter Jalur wajib yang mendukung nilai kartubebas.

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

Menggunakan atribut ini tidak secara otomatis mengaktifkan dukungan kartubebas. Pengembang cmdlet harus menerapkan kode untuk menangani input wildcard. Wildcard yang didukung dapat bervariasi sesuai dengan API atau penyedia PowerShell yang mendasar. Untuk informasi selengkapnya, lihat about_Wildcards.

Atribut ArgumentCompleter

Atribut ArgumentCompleter memungkinkan Anda menambahkan nilai penyelesaian tab ke parameter tertentu. Atribut ArgumentCompleter harus ditentukan untuk setiap parameter yang memerlukan penyelesaian tab. Seperti DynamicParameters, nilai yang tersedia dihitung pada runtime saat pengguna menekan Tab setelah nama parameter.

Untuk informasi selengkapnya, lihat about_Functions_Argument_Completion.

Atribut validasi parameter dan variabel

Atribut validasi mengarahkan PowerShell untuk menguji nilai parameter yang dikirimkan pengguna saat mereka memanggil fungsi tingkat lanjut. Jika nilai parameter gagal dalam pengujian, kesalahan dihasilkan dan fungsi tidak dipanggil. Validasi parameter hanya diterapkan ke input yang disediakan dan nilai lain seperti nilai default tidak divalidasi.

Anda juga dapat menggunakan atribut validasi untuk membatasi nilai yang dapat ditentukan pengguna untuk variabel.

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

Atribut validasi dapat diterapkan ke variabel apa pun, bukan hanya parameter. Anda dapat menentukan validasi untuk variabel apa pun dalam skrip.

Catatan

Saat menggunakan atribut apa pun dengan variabel yang diketik, praktik terbaik adalah mendeklarasikan atribut sebelum jenisnya.

Jika Anda mendeklarasikan jenis dengan pemisah baris sebelum atribut dan nama variabel, jenis diperlakukan sebagai pernyataannya sendiri.

[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Jika Anda mendeklarasikan atribut validasi setelah jenis, nilai yang ditetapkan divalidasi sebelum konversi jenis, yang dapat menyebabkan kegagalan validasi yang tidak terduga.

[string] [ValidateLength(1,5)]$TicketIDFromInt        = 43
[string] [ValidateLength(1,5)]$TicketIDFromString     = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43
The attribute cannot be added because variable TicketIDFromInt with
value 43 would no longer be valid.
At line:1 char:1
+ [string][ValidateLength(1,5)]$TicketIDFromInt        = 43
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : MetadataError: (:) [], ValidationMetadata
   Exception
    + FullyQualifiedErrorId : ValidateSetFailure

Atribut validasi AllowNull

Atribut AllowNull memungkinkan nilai parameter wajib menjadi $null. Contoh berikut mendeklarasikan parameter ComputerInfo hashtable yang dapat memiliki nilai null.

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

Catatan

Atribut AllowNull tidak berfungsi jika pengonversi jenis diatur ke string karena jenis string tidak akan menerima nilai null. Anda dapat menggunakan atribut AllowEmptyString untuk skenario ini.

Atribut validasi AllowEmptyString

Atribut AllowEmptyString memungkinkan nilai parameter wajib menjadi string kosong (""). Contoh berikut mendeklarasikan parameter ComputerName yang dapat memiliki nilai string kosong.

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

Atribut validasi AllowEmptyCollection

Atribut AllowEmptyCollection memungkinkan nilai parameter wajib menjadi koleksi @()kosong . Contoh berikut mendeklarasikan parameter ComputerName yang dapat memiliki nilai koleksi kosong.

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

Atribut validasi ValidateCount

Atribut ValidateCount menentukan jumlah minimum dan maksimum nilai parameter yang diterima parameter. PowerShell menghasilkan kesalahan jika jumlah nilai parameter dalam perintah yang memanggil fungsi berada di luar rentang tersebut.

Deklarasi parameter berikut membuat parameter ComputerName yang mengambil satu hingga lima nilai parameter.

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

Atribut validasi ValidateLength

Atribut ValidateLength menentukan jumlah karakter minimum dan maksimum dalam parameter atau nilai variabel. PowerShell menghasilkan kesalahan jika panjang nilai yang ditentukan untuk parameter atau variabel berada di luar rentang.

Dalam contoh berikut, setiap nama komputer harus memiliki satu hingga sepuluh karakter.

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

Dalam contoh berikut, nilai variabel $text harus minimal satu karakter panjangnya, dan maksimum sepuluh karakter.

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

Atribut validasi ValidatePattern

Atribut ValidatePattern menentukan ekspresi reguler yang dibandingkan dengan parameter atau nilai variabel. PowerShell menghasilkan kesalahan jika nilai tidak cocok dengan pola ekspresi reguler.

Dalam contoh berikut, nilai parameter harus berisi angka empat digit, dan setiap digit harus berupa angka nol hingga sembilan.

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

Dalam contoh berikut, nilai variabel $ticketID harus persis berupa angka empat digit, dan setiap digit harus berupa angka nol hingga sembilan.

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

Atribut validasi ValidateRange

Atribut ValidateRange menentukan rentang numerik untuk setiap parameter atau nilai variabel. PowerShell menghasilkan kesalahan jika ada nilai di luar rentang tersebut.

Dalam contoh berikut, nilai parameter Percobaan harus antara nol dan sepuluh.

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

Dalam contoh berikut, nilai variabel $number harus antara nol dan sepuluh.

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

Atribut validasi ValidateScript

Atribut ValidateScript menentukan skrip yang digunakan untuk memvalidasi parameter atau nilai variabel. PowerShell menyalurkan nilai ke skrip, dan menghasilkan kesalahan jika skrip kembali $false atau jika skrip melemparkan pengecualian.

Saat Anda menggunakan atribut ValidateScript , nilai yang sedang divalidasi dipetakan ke $_ variabel . Anda dapat menggunakan $_ variabel untuk merujuk ke nilai dalam skrip.

Dalam contoh berikut, nilai parameter EventDate harus lebih besar dari atau sama dengan tanggal saat ini.

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

Dalam contoh berikut, nilai variabel $date harus kurang dari atau sama dengan tanggal dan waktu saat ini.

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

Catatan

Jika Anda menggunakan ValidateScript, Anda tidak dapat meneruskan $null nilai ke parameter . Saat Anda meneruskan nilai null ValidateScript tidak dapat memvalidasi argumen.

Atribut ValidateSet

Atribut ValidateSet menentukan sekumpulan nilai yang valid untuk parameter atau variabel dan mengaktifkan penyelesaian tab. PowerShell menghasilkan kesalahan jika parameter atau nilai variabel tidak cocok dengan nilai dalam set. Dalam contoh berikut, nilai parameter Detail hanya boleh Rendah, Rata-Rata, atau Tinggi.

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

Dalam contoh berikut, nilai variabel $flavor harus Chocolate, Strawberry, atau Vanilla.

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

Validasi terjadi setiap kali variabel tersebut ditetapkan bahkan dalam skrip. Misalnya, berikut menghasilkan kesalahan saat runtime:

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

$Message = "bye"

Contoh ini mengembalikan kesalahan berikut saat runtime:

The attribute cannot be added because variable Message with value bye would no
longer be valid.
At line:1 char:1
+ [ValidateSet("hello", "world")][string]$Message = 'bye'
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : MetadataError: (:) [], ValidationMetadataException
    + FullyQualifiedErrorId : ValidateSetFailure

Menggunakan ValidateSet juga mengaktifkan perluasan tab nilai untuk parameter tersebut. Untuk informasi selengkapnya, lihat about_Tab_Expansion.

Nilai ValidateSet Dinamis menggunakan kelas

Anda dapat menggunakan Kelas untuk menghasilkan nilai secara dinamis untuk ValidateSet saat runtime. Dalam contoh berikut, nilai yang valid untuk variabel $Sound dihasilkan melalui Kelas bernama SoundNames yang memeriksa tiga jalur sistem file untuk file suara yang tersedia:

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
    }
}

Kelas [SoundNames] kemudian diimplementasikan sebagai nilai ValidateSet dinamis sebagai berikut:

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

Catatan

Kelas IValidateSetValuesGenerator diperkenalkan di PowerShell 6.0

Atribut validasi ValidateNotNull

Atribut ValidateNotNull menentukan bahwa nilai parameter tidak boleh $null. Saat nilainya adalah $null, PowerShell akan memunculkan pengecualian.

Atribut ValidateNotNull dirancang untuk digunakan ketika parameter bersifat opsional dan jenisnya tidak terdefinisi atau memiliki pengonversi jenis yang tidak dapat secara implisit mengonversi nilai null seperti objek. Jika Anda menentukan jenis yang secara implisit mengonversi nilai null, seperti string, nilai null dikonversi ke string kosong bahkan saat menggunakan atribut ValidateNotNull . Untuk skenario ini, gunakan atribut ValidateNotNullOrEmpty .

Dalam contoh berikut, nilai parameter ID tidak boleh $null.

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

Atribut validasi ValidateNotNullOrEmpty

Atribut ValidateNotNullOrEmpty menentukan bahwa nilai yang ditetapkan tidak boleh salah satu nilai berikut:

  • $null
  • string kosong ("")
  • array kosong (@())

Ketika nilai tidak valid, PowerShell akan memunculkan pengecualian.

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

Memvalidasi atribut validasiDrive

Atribut ValidateDrive menentukan bahwa nilai parameter harus mewakili jalur, yang hanya mengacu pada drive yang diizinkan. PowerShell menghasilkan kesalahan jika nilai parameter mengacu pada drive selain yang diizinkan. Keberadaan jalur, kecuali untuk drive itu sendiri, tidak diverifikasi.

Jika Anda menggunakan jalur relatif, drive saat ini harus berada dalam daftar drive yang diizinkan.

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

Atribut validasi ValidateUserDrive

Atribut ValidateUserDrive menentukan bahwa nilai parameter harus diwakili dalam User drive. PowerShell menghasilkan kesalahan jika jalur mengacu pada drive yang berbeda. Atribut validasi hanya menguji keberadaan awalan drive jalur.

Jika Anda menggunakan jalur relatif, drive saat ini harus 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.

Anda dapat menentukan User drive dalam konfigurasi sesi Just Enough Administration (JEA). Untuk contoh ini, kami membuat drive Pengguna: .

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

Lihat juga