A paraméterek beállításaAbout parameter sets

RÖVID LEÍRÁSSHORT DESCRIPTION

Leírja, hogyan lehet definiálni és használni a paramétereket a speciális függvényekben.Describes how to define and use parameter sets in advanced functions.

HOSSZÚ LEÍRÁSLONG DESCRIPTION

A PowerShell paraméter-készleteket használ, így egyetlen függvényt írhat, amely különböző műveleteket hajthat végre különböző helyzetekben.PowerShell uses parameter sets to enable you to write a single function that can do different actions for different scenarios. A paraméterek lehetővé teszik, hogy különböző paramétereket tegyen elérhetővé a felhasználó számára.Parameter sets enable you to expose different parameters to the user. És ha a felhasználó által megadott paraméterek alapján különböző adatokat szeretne visszaadni.And, to return different information based on the parameters specified by the user.

Paraméterek beállítása – követelményekParameter set requirements

Az alábbi követelmények minden paraméter-készletre érvényesek.The following requirements apply to all parameter sets.

  • Minden paraméter-készletnek legalább egy egyedi paraméterrel kell rendelkeznie.Each parameter set must have at least one unique parameter. Ha lehetséges, ezt a paramétert kötelező paraméterként hajtsa végre.If possible, make this parameter a mandatory parameter.

  • A több pozíciós paramétert tartalmazó paraméterérték egyedi pozíciókat kell meghatároznia az egyes paraméterekhez.A parameter set that contains multiple positional parameters must define unique positions for each parameter. A két pozíciós paraméter nem adhat meg ugyanazt a pozíciót.No two positional parameters can specify the same position.

  • Egy készleten belül csak egy paraméter deklarálhatja a ValueFromPipeline kulcsszót a következő értékkel: true .Only one parameter in a set can declare the ValueFromPipeline keyword with a value of true. Több paraméter is meghatározhatja a ValueFromPipelineByPropertyName kulcsszó értékét true .Multiple parameters can define the ValueFromPipelineByPropertyName keyword with a value of true.

  • Ha nem ad meg paramétert egy paraméterhez, a paraméter az összes paraméter-készlethez tartozik.If no parameter set is specified for a parameter, the parameter belongs to all parameter sets.

Megjegyzés

A 32-es paraméterek száma korlátozott.There is a limit of 32 parameter sets.

Alapértelmezett paraméter-készletekDefault parameter sets

Ha több paraméter van definiálva, a DefaultParameterSetName CmdletBinding attribútum kulcsszava az alapértelmezett paramétert adja meg.When multiple parameter sets are defined, the DefaultParameterSetName keyword of the CmdletBinding attribute specifies the default parameter set. A PowerShell az alapértelmezett paramétert használja, ha nem tudja meghatározni a használni kívánt paramétert a parancshoz megadott információk alapján.PowerShell uses the default parameter set when it can't determine the parameter set to use based on the information provided to the command. További információ a CmdletBinding attribútumról: about_functions_cmdletbindingattribute.For more information about the CmdletBinding attribute, see about_functions_cmdletbindingattribute.

Paraméter-készletek deklarálásaDeclaring parameter sets

A beállításhalmaz létrehozásához meg kell adnia a paraméter ParameterSetName attribútumának kulcsszóját Parameter a set paraméter minden paramétere esetében.To create a parameter set, you must specify the ParameterSetName keyword of the Parameter attribute for every parameter in the parameter set. Több paraméterhez tartozó paramétereknél adjon hozzá egy Parameters attribútumot az egyes paraméterekhez.For parameters that belong to multiple parameter sets, add a Parameter attribute for each parameter set.

A paraméter attribútum lehetővé teszi, hogy a paramétert az egyes beállított paraméterektől eltérően határozza meg.The Parameter attribute enables you to define the parameter differently for each parameter set. Megadhat például egy paramétert kötelezőként egy készletben, és opcionálisan egy másikban.For example, you can define a parameter as mandatory in one set and optional in another. Azonban minden egyes paraméternek tartalmaznia kell legalább egy egyedi paramétert.However, each parameter set must contain at least one unique parameter.

Azok a paraméterek, amelyek nem rendelkeznek hozzárendelt paraméterekkel, az összes paraméter készletéhez tartoznak.Parameters that don't have an assigned parameter set name belong to all parameter sets.

PéldaExample

A következő példa függvény egy szövegfájlban lévő sorok, karakterek és szavak megszámlálására használható.The following example function counts the number lines, characters, and words in a text file. Paraméterek használatával megadhatja, hogy mely értékeket kívánja visszaadni, és hogy mely fájlokat szeretné mérni.Using parameters, you can specify which values you want returned and which files you want to measure. Négy paraméter-készlet van definiálva:There are four parameter sets defined:

  • Elérési útPath
  • PathAllPathAll
  • LiteralPathLiteralPath
  • LiteralPathAllLiteralPathAll
function Measure-Lines {
    [CmdletBinding(DefaultParameterSetName = 'Path')]
    param (
        [Parameter(Mandatory = $true,
            ParameterSetName = 'Path',
            HelpMessage = 'Enter one or more filenames',
            Position = 0)]
        [Parameter(Mandatory = $true,
            ParameterSetName = 'PathAll',
            Position = 0)]
        [string[]]$Path,

        [Parameter(Mandatory = $true, ParameterSetName = 'LiteralPathAll')]
        [Parameter(Mandatory = $true,
            ParameterSetName = 'LiteralPath',
            HelpMessage = 'Enter a single filename',
            ValueFromPipeline = $true)]
        [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 = $true, ParameterSetName = 'PathAll')]
        [Parameter(Mandatory = $true, 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
        }

        if ($Path) {
            $Files = Get-ChildItem -Path $Path -Recurse:$Recurse
        }
        else {
            $Files = Get-ChildItem -LiteralPath $LiteralPath
        }
    }
    process {
        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
        }
    }
}

Minden paraméter-készletnek egyedi paraméterrel vagy paraméterek egyedi kombinációjával kell rendelkeznie.Each parameter set must have a unique parameter or a unique combination of parameters. A Path és a PathAll paraméter-készletek nagyon hasonlóak, de az all paraméter egyedi a PathAll beállított paraméternél.The Path and PathAll parameter sets are very similar but the All parameter is unique to the PathAll parameter set. Ugyanez igaz a LiteralPath és a paraméter- LiteralPathAll készletekkel is.The same is true with the LiteralPath and LiteralPathAll parameter sets. Annak ellenére, hogy a PathAll és a LiteralPathAll paraméter is az all paraméterrel rendelkezik, az elérési út és a LiteralPath paraméterek megkülönböztetik őket.Even though the PathAll and LiteralPathAll parameter sets both have the All parameter, the Path and LiteralPath parameters differentiate them.

A use (használat Get-Command -Syntax ) érték az egyes paraméterek szintaxisát jeleníti meg.Use Get-Command -Syntax shows you the syntax of each parameter set. A paraméter neve azonban nem jelenik meg.However it does not show the name of the parameter set. Az alábbi példa azt mutatja, hogy mely paramétereket lehet használni az egyes paraméterekben.The following example shows which parameters can be used in each parameter set.

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

Paraméter-készletek a műveletbenParameter sets in action

Ebben a példában a PathAll beállított paramétert használjuk.In this example, we are using the PathAll parameter set.

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