about_Parameter_Sets

Artikel
04/01/2024

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.
Hanya satu parameter dalam satu set yang dapat mendeklarasikan ValueFromPipeline kata kunci dengan nilai true. Beberapa parameter dapat menentukan ValueFromPipelineByPropertyName kata kunci dengan nilai true.

Catatan

Ada batas 32 set parameter.

Set parameter default

Saat beberapa set parameter ditentukan, DefaultParameterSetName kata kunci 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 ParameterSetName kata kunci 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.

Contoh

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

Jalur
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. Path Set parameter dan PathAll sangat mirip tetapi parameter Semua unik untuk PathAll set parameter. Hal yang sama berlaku dengan LiteralPath set parameter dan LiteralPathAll . Meskipun PathAll set parameter 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 PathAll set parameter.

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 can't be resolved using the specified named parameters.
At line:1 char:1
+ Get-ChildItem -Path $PSHOME -LiteralPath $PSHOME
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Get-ChildItem], ParameterBindingException
    + FullyQualifiedErrorId : AmbiguousParameterSet,Microsoft.PowerShell.Commands.GetChildItemCommand

Parameter Path dan LiteralPath unik untuk set parameter cmdlet yang Get-ChildItem berbeda. 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 $PSCmdlet otomatis 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