Om parameteruppsättningar

Artikel
05/09/2024

KORT BESKRIVNING

Beskriver hur du definierar och använder parameteruppsättningar i avancerade funktioner.

LÅNG BESKRIVNING

PowerShell använder parameteruppsättningar så att du kan skriva en enda funktion som kan utföra olika åtgärder för olika scenarier. Med parameteruppsättningar kan du exponera olika parametrar för användaren. Och för att returnera annan information baserat på de parametrar som anges av användaren.

Krav för parameteruppsättningar

Följande krav gäller för alla parameteruppsättningar.

Varje parameteruppsättning måste ha minst en unik parameter. Om möjligt gör du den här parametern till en obligatorisk parameter.
En parameteruppsättning som innehåller flera positionsparametrar måste definiera unika positioner för varje parameter. Inga två positionsparametrar kan ange samma position.
Endast en parameter i en uppsättning kan deklarera nyckelordet ValueFromPipeline med värdet true. Flera parametrar kan definiera nyckelordet ValueFromPipelineByPropertyName med värdet true.
Om ingen parameteruppsättning har angetts för en parameter tillhör parametern alla parameteruppsättningar.

Anteckning

Det finns en gräns på 32 parameteruppsättningar.

Standardparameteruppsättningar

När flera parameteruppsättningar har definierats anger nyckelordet DefaultParameterSetNameför attributet CmdletBinding standardparameteruppsättningen. PowerShell använder standardparameteruppsättningen när den inte kan fastställa vilken parameteruppsättning som ska användas baserat på den information som tillhandahålls till kommandot. Mer information om attributet CmdletBinding finns i about_functions_cmdletbindingattribute.

Deklarera parameteruppsättningar

Om du vill skapa en parameteruppsättning måste du ange nyckelordet ParameterSetName för parameterattributet för varje parameter i parameteruppsättningen. För parametrar som tillhör flera parameteruppsättningar lägger du till ett parameterattribut för varje parameteruppsättning.

Med parameterattributet kan du definiera parametern på olika sätt för varje parameteruppsättning. Du kan till exempel definiera en parameter som obligatorisk i en uppsättning och valfri i en annan. Varje parameteruppsättning måste dock innehålla minst en unik parameter.

Parametrar som inte har ett tilldelat parameteruppsättningsnamn tillhör alla parameteruppsättningar.

Exempel

Följande exempelfunktion räknar antalet rader, tecken och ord i en textfil. Med hjälp av parametrar kan du ange vilka värden du vill returnera och vilka filer du vill mäta. Det finns fyra definierade parameteruppsättningar:

Sökväg
PathAll
LiteralPath
LiteralPathAll

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

Varje parameteruppsättning måste ha en unik parameter eller en unik kombination av parametrar. Parameteruppsättningarna Path och PathAll är mycket lika, men parametern Alla är unik för parameteruppsättningen PathAll . Samma sak gäller för parameteruppsättningarna LiteralPath och LiteralPathAll . Även om parameteruppsättningarna PathAll och LiteralPathAll båda har parametern Alla skiljer parametrarna Path och LiteralPath åt dem.

Använd Get-Command -Syntax visar syntaxen för varje parameteruppsättning. Den visar dock inte namnet på parameteruppsättningen. I följande exempel visas vilka parametrar som kan användas i varje parameteruppsättning.

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

Parameteruppsättningar i praktiken

I det här exemplet använder vi parameteruppsättningen 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

Dela via