about_Parameter_Sets

Deskripsi singkat

Menjelaskan cara menentukan dan menggunakan set parameter dalam fungsi tingkat lanjut.

Deskripsi panjang

PowerShell menggunakan set parameter untuk memungkinkan Anda menulis satu fungsi yang dapat melakukan tindakan yang berbeda untuk skenario yang berbeda. Set parameter memungkinkan Anda mengekspos parameter yang berbeda kepada pengguna. Dan, untuk mengembalikan informasi yang berbeda berdasarkan parameter yang ditentukan oleh pengguna. Anda hanya dapat menggunakan satu parameter yang ditetapkan pada satu waktu.

Persyaratan set parameter

Persyaratan berikut berlaku untuk semua set parameter.

Jika tidak ada set parameter yang ditentukan untuk parameter, parameter milik semua set parameter.
Setiap set parameter harus memiliki kombinasi parameter yang unik. Jika memungkinkan, setidaknya salah satu parameter unik harus menjadi parameter wajib.
Set parameter yang berisi beberapa parameter posisi harus menentukan posisi unik untuk setiap parameter. Tidak ada dua parameter posisi yang dapat menentukan posisi yang sama.

Nota

Ada batas 32 set parameter.

Set parameter default

Saat beberapa set parameter ditentukan, kata kunci DefaultParameterSetName atribut CmdletBinding menentukan kumpulan parameter default. PowerShell menggunakan parameter default yang ditetapkan saat tidak dapat menentukan parameter yang diatur untuk digunakan berdasarkan informasi yang diberikan ke perintah . Untuk informasi selengkapnya tentang atribut CmdletBinding, lihat about_Functions_CmdletBindingAttribute.

Mendeklarasikan set parameter

Untuk membuat set parameter, Anda harus menentukan kata kunci ParameterSetName atribut Parameter untuk setiap parameter dalam set parameter. Untuk parameter yang termasuk dalam beberapa set parameter, tambahkan atribut Parameter untuk setiap set parameter.

Atribut Parameter memungkinkan Anda menentukan parameter secara berbeda untuk setiap set parameter. Misalnya, Anda dapat menentukan parameter sebagai wajib dalam satu set dan opsional di set lain. Namun, setiap set parameter harus berisi setidaknya satu parameter unik.

Parameter yang tidak memiliki nama set parameter yang ditetapkan milik semua set parameter.

Nama set parameter yang dicadangkan

PowerShell mencadangkan nama __AllParameterSets set parameter untuk penanganan khusus.

__AllParameterSets adalah nama parameter default yang ditetapkan ketika nama default eksplisit tidak digunakan.

ParameterSetName Mengatur atribut Parameter ke __AllParameterSets setara dengan tidak menetapkan ParameterSetName. Dalam kedua kasus, parameter milik semua set parameter.

Nota

Atribut CmdletBinding tidak mencegah Anda mengatur DefaultParameterSetName menjadi menjadi __AllParameterSets. Jika Anda melakukan ini, PowerShell membuat set parameter eksplisit yang tidak dapat dirujuk dengan benar oleh atribut Parameter .

Examples

Contoh fungsi berikut menghitung baris angka, karakter, dan kata dalam file teks. Dengan menggunakan parameter, Anda dapat menentukan nilai yang ingin Anda kembalikan dan file yang ingin Anda ukur. Ada empat set parameter yang ditentukan:

Jalan
PathAll
LiteralPath
LiteralPathAll

function Measure-Lines {
    [CmdletBinding(DefaultParameterSetName = 'Path')]
    param (
        [Parameter(Mandatory, ParameterSetName = 'Path', Position = 0)]
        [Parameter(Mandatory, ParameterSetName = 'PathAll', Position = 0)]
        [string[]]$Path,

        [Parameter(Mandatory, ParameterSetName = 'LiteralPathAll', ValueFromPipeline)]
        [Parameter(Mandatory, ParameterSetName = 'LiteralPath', ValueFromPipeline)]
        [string[]]$LiteralPath,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'LiteralPath')]
        [switch]$Lines,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'LiteralPath')]
        [switch]$Words,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'LiteralPath')]
        [switch]$Characters,

        [Parameter(Mandatory, ParameterSetName = 'PathAll')]
        [Parameter(Mandatory, ParameterSetName = 'LiteralPathAll')]
        [switch]$All,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'PathAll')]
        [switch]$Recurse
    )

    begin {
        if ($All) {
            $Lines = $Words = $Characters = $true
        }
        elseif (($Words -eq $false) -and ($Characters -eq $false)) {
            $Lines  = $true
        }
    }
    process {
        if ($Path) {
            $Files = Get-ChildItem -Path $Path -Recurse:$Recurse -File
        }
        else {
            $Files = Get-ChildItem -LiteralPath $LiteralPath -File
        }
        foreach ($file in $Files) {
            $result = [ordered]@{ }
            $result.Add('File', $file.FullName)

            $content = Get-Content -LiteralPath $file.FullName

            if ($Lines) { $result.Add('Lines', $content.Length) }

            if ($Words) {
                $wc = 0
                foreach ($line in $content) { $wc += $line.Split(' ').Length }
                $result.Add('Words', $wc)
            }

            if ($Characters) {
                $cc = 0
                foreach ($line in $content) { $cc += $line.Length }
                $result.Add('Characters', $cc)
            }

            New-Object -TypeName psobject -Property $result
        }
    }
}

Setiap set parameter harus memiliki parameter unik atau kombinasi parameter yang unik. Set parameter Path dan PathAll sangat mirip tetapi parameter Semua unik untuk kumpulan parameter PathAll. Hal yang sama berlaku dengan set parameter LiteralPath dan LiteralPathAll. Meskipun parameter PathAll dan LiteralPathAll keduanya memiliki parameter Semua, parameter Path dan LiteralPath membedakannya.

Gunakan Get-Command -Syntax menunjukkan sintaks setiap set parameter. Namun tidak menampilkan nama kumpulan parameter. Contoh berikut menunjukkan parameter mana yang dapat digunakan di setiap set parameter.

(Get-Command Measure-Lines).ParameterSets |
  Select-Object -Property @{n='ParameterSetName';e={$_.Name}},
    @{n='Parameters';e={$_.ToString()}}

ParameterSetName Parameters
---------------- ----------
Path             [-Path] <string[]> [-Lines] [-Words] [-Characters] [-Recurse] [<CommonParameters>]
PathAll          [-Path] <string[]> -All [-Recurse] [<CommonParameters>]
LiteralPath      -LiteralPath <string[]> [-Lines] [-Words] [-Characters] [<CommonParameters>]
LiteralPathAll   -LiteralPath <string[]> -All [<CommonParameters>]

Set parameter dalam tindakan

Contohnya menggunakan set parameter PathAll.

Measure-Lines test* -All

File                       Lines Words Characters
----                       ----- ----- ----------
C:\temp\test\test.help.txt    31   562       2059
C:\temp\test\test.md          30  1527       3224
C:\temp\test\test.ps1          3     3         79
C:\temp\test\test[1].txt      31   562       2059

Kesalahan menggunakan parameter dari beberapa set

Dalam contoh ini, parameter unik dari set parameter yang berbeda digunakan.

Get-ChildItem -Path $PSHOME -LiteralPath $PSHOME

Get-ChildItem: Parameter set cannot be resolved using the specified named
parameters. One or more parameters issued cannot be used together or an
insufficient number of parameters were provided.

Parameter Jalur dan LiteralPath unik untuk set parameter yang berbeda dari cmdlet Get-ChildItem. Ketika parameter dijalankan bersama-sama dalam cmdlet yang sama, kesalahan akan muncul. Hanya satu set parameter yang dapat digunakan per panggilan cmdlet pada satu waktu.

Cara mengetahui set parameter mana yang digunakan

Variabel otomatis $PSCmdlet menyediakan properti ParameterSetName. Properti ini berisi nama set parameter yang digunakan. Anda dapat menggunakan properti ini dalam fungsi Anda untuk menentukan set parameter mana yang digunakan untuk memilih perilaku set-spesifik parameter.

function Get-ParameterSetName {

    [CmdletBinding(DefaultParameterSetName = 'Set1')]
    param (
        [Parameter(ParameterSetName = 'Set1', Position = 0)]
        $Var1,

        [Parameter(ParameterSetName = 'Set2', Position = 0)]
        $Var2,

        [Parameter(ParameterSetName = 'Set1', Position = 1)]
        [Parameter(ParameterSetName = 'Set2', Position = 1)]
        $Var3,

        [Parameter(Position = 2)]
        $Var4
    )

    "Using Parameter set named '$($PSCmdlet.ParameterSetName)'"

    switch ($PSCmdlet.ParameterSetName) {
        'Set1' {
            "`$Var1 = $Var1"
            "`$Var3 = $Var3"
            "`$Var4 = $Var4"
            break
        }
        'Set2' {
            "`$Var2 = $Var2"
            "`$Var3 = $Var3"
            "`$Var4 = $Var4"
            break
        }
    }
}

PS> Get-ParameterSetName 1 2 3

Using Parameter set named 'Set1'
$Var1 = 1
$Var3 = 2
$Var4 = 3

PS> Get-ParameterSetName -Var2 1 2 3

Using Parameter set named 'Set2'
$Var2 = 1
$Var3 = 2
$Var4 = 3

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-09-29