about_Functions_Advanced_Parameters

Rövid leírás

Ez a cikk azt ismerteti, hogyan adhat hozzá paramétereket a speciális függvényekhez.

Hosszú leírás

Paramétereket adhat hozzá az Ön által írt speciális függvényekhez, és paraméterattribútumok és argumentumok használatával korlátozhatja a paraméterrel a függvény felhasználói által beküldött paraméterértékeket.

A CmdletBinding attribútum használatakor a PowerShell automatikusan hozzáadja a gyakori paramétereket. Nem hozhat létre olyan paramétereket, amelyek ugyanazokat a neveket használják, mint a Common Parameters. További információ: about_CommonParameters.

A PowerShell 3.0-tól kezdve használhatja a @args használatával a parancs paramétereit. A splatting egyszerű és speciális függvényekre érvényes. További információ: about_Functions és about_Splatting.

Paraméterdeklaráció

A paraméterek egy függvény vagy szkriptblokk utasításában param() deklarált változók. Az opcionális [Parameter()] attribútumot használhatja önállóan, vagy a [Alias()] attribútummal vagy a paraméterérvényesítési attribútumok bármelyikével együtt.

A paraméternevek a változónevekre vonatkozó szabályokat követik. A paraméternevek tizedesjegyekből, betűrendi karakterekből és aláhúzásokból állnak. Az elnevezési szabályok teljes listáját a about_Variablescímű témakörben találja.

Fontos

Megadható egy tizedesjegykel kezdődő paraméter. A paraméternevek számjegyekkel való indítása nem ajánlott, mert a PowerShell a helyparaméterként átadott sztringértékekként kezeli őket.

Vegye figyelembe a következő példát:

function TestFunction {
    param (
        [switch] $100,
        [string] $200
    )

    "100: $100"
    "200: $200"
}

Ha megpróbálja használni a paramétereket, a PowerShell pozícióparaméterként átadott sztringként értelmezi őket.

PS> TestFunction -100 -200 Hello
100: False
200: -100
$args: -200 Hello

A kimenet azt mutatja, hogy a PowerShell a -100 értéket a $200 paraméterváltozóhoz kötötte. A többi pozícióérték $argsvan kötve. A probléma megkerüléséhez splatting használatával adja át a paraméterértékeket.

PS> $ht = @{100 = $true; 200 = 'Hello'}
PS> TestFunction @ht
100: True
200: Hello
$args:

További információ: about_Splatting.

Paraméterértékek típuskonvertálása

Ha argumentumként ad meg sztringeket olyan paramétereknek, amelyek eltérő típusra számítanak, a PowerShell implicit módon átalakítja a sztringeket a paraméter céltípusává. A speciális függvények a paraméterértékek kulturális invariáns elemzését hajtják végre.

Ezzel szemben a rendszer a lefordított parancsmagok paraméterkötése során kulturális szempontból érzékeny konverziót hajt végre.

Ebben a példában létrehozunk egy parancsmagot és egy szkriptfüggvényt, amely egy [datetime] paramétert vesz igénybe. A jelenlegi kultúra a német beállítások használatára módosul. A paraméter egy német formátumú dátumot ad át.

# 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

Ahogy fentebb látható, a parancsmagok kultúraérzékeny elemzéssel alakítják át a sztringet.

# 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

A speciális függvények kulturális invariáns elemzést használnak, ami az alábbi hibát eredményezi.

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."

További információ: about_Type_Conversion.

Statikus paraméterek

A statikus paraméterek olyan paraméterek, amelyek mindig elérhetők a függvényben. A PowerShell-parancsmagok és szkriptek legtöbb paramétere statikus paraméter.

Az alábbi példa egy ComputerName paraméter deklarációját mutatja be, amely a következő jellemzőkkel rendelkezik:

Kötelező (kötelező).
Bemenetet vesz fel a folyamatból.
Egy sztringtömböt vesz fel bemenetként.

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

`[switch]` Paraméterek

[switch] a paraméterek olyan paraméterek, amelyek nem vesznek fel paraméterértéket. Ehelyett egy logikai igaz vagy hamis értéket közvetítenek jelenlétükkel vagy távollétükkel, így ha egy [switch] paraméter jelen van, igaz értékkel rendelkezik, és ha hiányzik, akkor hamis értéket adnak meg.

A Recurse paraméter Get-ChildItem például egy [switch] paraméter.

Az alábbi példa egy [switch] paraméter definícióját mutatja be, amely lehetővé teheti az adatok bájttömbként való kimenetét:

param([switch]$AsByteArray)

[switch] a paraméterek könnyen használhatók, és előnyben részesítik azokat a logikai paramétereket, amelyek kevésbé természetes szintaxissal rendelkeznek a PowerShellhez.

Paraméter használatához [switch] adja meg a paramétert a parancsban. Például:

-IncludeAll

Logikai paraméter használatához meg kell adnia a paramétert és a logikai értéket.

-IncludeAll $true

Paraméterek létrehozásakor [switch] gondosan válassza ki a paraméter nevét. Győződjön meg arról, hogy a paraméter neve közli a paraméter hatását a felhasználóval. Kerülje a kétértelmű kifejezéseket, például szűrő vagy Értékre utaló maximális.

`[switch]` paramétertervezési szempontok

Ne állítson be alapértelmezett értéket egy [switch] paraméterhez. [switch] a paraméterek alapértelmezés szerint hamisak.
A paraméterek ne legyenek [switch] pozicionálva. Alapértelmezés szerint a [switch] paraméterek ki vannak zárva a pozícióparaméterekből. felülbírálhatja a Paraméter attribútumban lévő felülbírálást, de összezavarhatja a felhasználókat.
A paramétereket úgy tervezheti meg [switch] , hogy azok használata a parancs alapértelmezett viselkedését kevésbé gyakori vagy bonyolultabb módra módosítsa. A parancsok legegyszerűbb viselkedésének az az alapértelmezett viselkedésnek kell lennie, amely nem igényli a paraméterek használatát [switch] .
Ne tegye kötelezővé [switch] a paramétereket. A paraméter kötelezővé tétele [switch] csak akkor hasznos, ha meg kell különböztetni egy paraméterkészletet.
Használja a [switch] paraméterváltozót közvetlenül egy feltételes kifejezésben. A SwitchParameter típus implicit módon logikai értékké alakul át. Például:
```
if ($MySwitch) { ... }
```
A paraméter által [switch] szabályozott viselkedést mindig a paraméter értékére , nem pedig a jelenlétére alapozza. Paraméterek jelenlétének tesztelése [switch] többféleképpen is lehetséges:
- $PSBoundParameters kulcsként tartalmazza a [switch] paraméter nevét
- $MyInvocation.BoundParameters kulcsként tartalmazza a [switch] paraméter nevét
- $PSCmdlet.ParameterSetName, ha a kapcsoló egyedi paraméterkészletet határoz meg
Megadhat például egy explicit értéket a kapcsolóhoz -MySwitch:$false vagy splatting használatával. Ha csak a paraméter meglétét teszteli, a parancs úgy viselkedik, mintha a kapcsoló értéke $true$falsehelyett.

Dinamikus paraméterek

A dinamikus paraméterek egy parancsmag, függvény vagy szkript paraméterei, amelyek csak bizonyos feltételek mellett érhetők el.

Több szolgáltatói parancsmag például olyan paraméterekkel rendelkezik, amelyek csak akkor érhetők el, ha a parancsmagot a szolgáltatói meghajtón vagy a szolgáltatói meghajtó egy adott elérési útján használják. A Kódolás paraméter például csak akkor érhető el a Add-Content, Get-Contentés Set-Content parancsmagokon, ha fájlrendszer-meghajtón használják.

Olyan paramétert is létrehozhat, amely csak akkor jelenik meg, ha egy másik paramétert használ a függvényparancsban, vagy ha egy másik paraméternek van egy bizonyos értéke.

A dinamikus paraméterek hasznosak lehetnek, de csak akkor használják őket, ha szükséges, mert a felhasználók nehezen tudják felderíteni őket. Dinamikus paraméter kereséséhez a felhasználónak a szolgáltató elérési útján kell lennie, a parancsmag Get-Command paraméterét kell használnia, vagy a Get-Help paraméterét kell használnia.

Ha dinamikus paramétert szeretne létrehozni egy függvényhez vagy szkripthez, használja a dynamicparam kulcsszót.

A szintaxis a következő:

dynamicparam {<statement-list>}

Az utasításlistában egy if utasítást használva adja meg azokat a feltételeket, amelyek mellett a paraméter elérhető a függvényben.

Az alábbi példa egy Név és Elérési útnevű standard paraméterekkel rendelkező függvényt, valamint egy KeyCountnevű választható dinamikus paramétert mutat be. A KeyCount paraméter a ByRegistryPath paraméterkészletben található, és Int32típusú. A KeyCount paraméter csak akkor érhető el a Get-Sample függvényben, ha a Elérési út paraméter értéke HKLM:kezdődik, ami azt jelzi, hogy az HKEY_LOCAL_MACHINE beállításjegyzék-meghajtóban van használatban.

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

További információt a RuntimeDefinedParameter típus dokumentációjában talál.

Paraméterek attribútumai

Ez a szakasz a függvényparaméterekhez hozzáadható attribútumokat ismerteti.

Az összes attribútum megadása nem kötelező. Ha azonban kihagyja a CmdletBinding attribútumot, akkor speciális függvényként való felismeréséhez a függvénynek tartalmaznia kell a Paraméter attribútumot.

Minden paraméterdeklarációban egy vagy több attribútumot adhat hozzá. A paraméterdeklarációhoz hozzáadható attribútumok száma nincs korlátozva.

Paraméterattribútum

A Paraméter attribútum a függvényparaméterek attribútumainak deklarálásához használatos.

A paraméter attribútum nem kötelező, és kihagyhatja, ha a függvények egyik paraméteréhez sem kell attribútum. Ha azonban összetett függvényként szeretné felismerni, nem egyszerű függvényként, a függvénynek vagy a CmdletBinding attribútummal, vagy a Paraméter attribútummal kell rendelkeznie, vagy mindkettővel.

A paraméter attribútum argumentumokkal rendelkezik, amelyek meghatározzák a paraméter jellemzőit, például azt, hogy a paraméter kötelező vagy nem kötelező.

Az alábbi szintaxis használatával deklarálhatja a Paraméter attribútumot, egy argumentumot és egy argumentumértéket. Az argumentumot és az értékét tartalmazó zárójeleknek paramétert kell követnie beavatkozó szóköz nélkül.

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

A zárójelen belüli argumentumok vesszővel elválasztása. Az alábbi szintaxis használatával deklarálhatja a Paraméter attribútum két argumentumát.

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

A Paraméter attribútum logikai argumentumtípusa alapértelmezés szerint Hamis, ha az Paraméter attribútumból hiányzik. Állítsa az argumentum értékét úgy, hogy $true vagy csak név szerint listázze az argumentumot. Az alábbi paraméter attribútumok például egyenértékűek.

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

# Boolean arguments can be defined using this shorthand syntax

param(
    [Parameter(Mandatory)]
)

Ha a Paraméter attribútumot argumentumok nélkül használja, a CmdletBinding attribútum használata helyett az attribútum nevét követő zárójelek továbbra is szükségesek.

param(
    [Parameter()]
    $ParameterName
)

Kötelező argumentum

A Mandatory argumentum azt jelzi, hogy a paraméter szükséges. Ha ez az argumentum nincs megadva, a paraméter nem kötelező.

Az alábbi példa deklarálja a ComputerName paramétert. A paraméter kötelezővé tétele a Mandatory argumentum használatával.

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

Pozíció argumentum

A Position argumentum határozza meg, hogy a paraméternév szükséges-e a paraméter parancsban való használatakor. Ha egy paraméterdeklaráció tartalmazza a Position argumentumot, a paraméter neve elhagyható, és a PowerShell a meg nem nevezett paraméterértéket pozíciója vagy sorrendje alapján azonosítja a parancs névtelen paraméterértékeinek listájában.

Ha a Position argumentum nincs megadva, a paraméternévnek vagy a paraméternév aliasának vagy rövidítésének meg kell előznie a paraméter értékét, amikor a paramétert egy parancsban használják.

Alapértelmezés szerint az összes függvényparaméter pozíciós. A PowerShell pozíciószámokat rendel a paraméterekhez abban a sorrendben, hogy a paraméterek deklarálva legyenek a függvényben. A funkció letiltásához állítsa a PositionalBinding attribútum argumentumának értékét $falseértékre. A Position argumentum elsőbbséget élvez a PositionalBinding attribútum argumentumának értékével szemben. További információ: PositionalBinding a about_Functions_CmdletBindingAttribute.

A Position argumentum értéke egész számként van megadva. A 0 az első pozíciót jelöli a parancsban, a 1 a parancs második pozícióját stb.

Ha egy függvénynek nincsenek pozícióparaméterei, a PowerShell az egyes paraméterekhez a paraméterek deklarálási sorrendje alapján rendel pozíciókat. Ajánlott eljárásként azonban ne támaszkodjon erre a feladatra. Ha azt szeretné, hogy a paraméterek pozícióban legyenek, használja a Position argumentumot.

Az alábbi példa deklarálja a ComputerName paramétert. A Position argumentumot 0értékkel használja. Ennek eredményeképpen, ha -ComputerName ki van hagyva a parancsból, az értéknek a parancs első vagy csak névtelen paraméterértékének kell lennie.

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

ParameterSetName argumentum

A ParameterSetName argumentum azt a paraméterkészletet adja meg, amelyhez egy paraméter tartozik. Ha nincs megadva paraméterkészlet, a paraméter a függvény által definiált összes paraméterkészlethez tartozik. Ahhoz, hogy egyedi legyen, minden paraméterkészletnek rendelkeznie kell legalább egy olyan paraméterrel, amely nem tagja semmilyen más paraméterkészletnek.

Jegyzet

Parancsmag vagy függvény esetén legfeljebb 32 paraméterkészlet lehet.

Az alábbi példa egy ComputerName paramétert deklarál a Computer paraméterkészletben, egy UserName paramétert a User paraméterkészletben, valamint egy Összesítő paramétert mindkét paraméterkészletben.

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

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

    [Parameter()]
    [switch]$Summary
)

Minden argumentumban csak egy ParameterSetName értéket adhat meg, és csak egy ParameterSetName argumentumot minden Paraméter attribútumban. Ha egy paramétert egynél több paraméterkészletbe szeretne felvenni, adjon hozzá további paraméter attribútumokat.

Az alábbi példa explicit módon hozzáadja a Summary paramétert a Computer és User paraméterkészletekhez. Az Összegző paraméter nem kötelező a Computer paraméterkészletben, és kötelező a User paraméterkészletben.

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

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

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

További információ a paraméterkészletekről: Paraméterkészletek.

ValueFromPipeline argumentum

A ValueFromPipeline argumentum azt jelzi, hogy a paraméter bemenetet fogad egy folyamatobjektumból. Adja meg ezt az argumentumot, ha a függvény a teljes objektumot elfogadja, nem csak az objektum tulajdonságát.

Az alábbi példa egy ComputerName paramétert deklarál, amely kötelező, és elfogadja a folyamatból a függvénynek átadott objektumot.

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

ValueFromPipelineByPropertyName argumentum

A ValueFromPipelineByPropertyName argumentum azt jelzi, hogy a paraméter egy folyamatobjektum tulajdonságából fogad bemenetet. Az objektumtulajdonságnak ugyanazzal a névvel vagy aliasszal kell rendelkeznie, mint a paraméternek.

Ha például a függvény ComputerName paraméterrel rendelkezik, és a piped objektum rendelkezik ComputerName tulajdonságmal, a ComputerName tulajdonság értéke a függvény ComputerName paraméteréhez van rendelve.

Az alábbi példa egy ComputerName paramétert deklarál, amely kötelező, és fogadja el az objektum ComputerName tulajdonságának bemenetét, amelyet a folyamaton keresztül ad át a függvénynek.

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

Fontolja meg egy függvény implementálását az alábbi argumentum használatával:

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

Ezután az objektum ComputerName tulajdonsággal való pipálásának bemutatója a következő lesz:

[pscustomobject]@{ ComputerName = "HelloWorld" } |
    Test-ValueFromPipelineByPropertyName

Saw that ComputerName was 'HelloWorld'

Jegyzet

A folyamatbemenetet (by Value) vagy (by PropertyName) elfogadó gépelt paraméter lehetővé teszi a delay-bind szkriptblokkok használatát a paraméteren.

A delay-bind szkriptblokk automatikusan fut a ParameterBinding során. Az eredmény a paraméterhez van kötve. A késleltetési kötés nem működik olyan paramétereknél, amelyek ScriptBlock vagy System.Object. A szkriptblokk meghívás nélkül halad át. A delay-bind szkriptblokkokkal kapcsolatos további információkért lásd: about_Script_Blocks.

ValueFromRemainingArguments argumentum

A ValueFromRemainingArguments argumentum azt jelzi, hogy a paraméter elfogadja a parancs összes olyan értékét, amely nincs hozzárendelve a függvény más paramétereihez.

Az alábbi példa egy kötelező Érték paramétert deklarál, és egy Fennmaradó paramétert, amely elfogadja a függvénynek elküldött összes többi paraméterértéket.

function Test-Remainder {
    param(
        [Parameter(Mandatory, Position=0)]
        [string]$Value,

        [Parameter(ValueFromRemainingArguments, Position=1)]
        [string[]]$Remaining
    )

    "Value = $Value"
    "Found $($Remaining.Count) remaining values"

    for ($i = 0; $i -lt $Remaining.Count; $i++) {
        "${i}: $($Remaining[$i])"
    }
}

PS> Test-Remainder first one two three

Value = first
Found 3 remaining values
0: one
1: two
2: three

A PowerShell 6.2-től kezdődően a gyűjtemények eltérően lesznek kezelve, amikor átadják a ValueFromRemainingArgumentsnek. Ha csak egy gyűjteményt ad át, akkor a rendszer a gyűjtemény minden egyes értékét külön elemként kezeli.

PS> Test-Remainder first one, two, three

Value = first
Found 3 remaining values
0: one
1: two
2: three

Ha több olyan értéket ad át, ahol legalább egy nem gyűjtemény, a gyűjtemény egyetlen elemként lesz kezelve.

PS> Test-Remainder first one, two three four

Value = first
Found 3 remaining values
0: one two
1: three
2: four

HelpMessage argumentum

A HelpMessage argumentum egy sztringet határoz meg, amely a paraméter vagy érték rövid leírását tartalmazza. Ha a parancsot a kötelező paraméter nélkül futtatja, a PowerShell kéri a bemenetet. A súgóüzenet megtekintéséhez írja be a !? a parancssorba, és nyomja le Enter.

Az alábbi példa egy kötelező ComputerName paramétert deklarál, valamint egy súgóüzenetet, amely ismerteti a várt paraméterértéket.

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

Példakimenet:

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

Ha nincs megjegyzésalapú súgó a függvényhez, akkor ez az üzenet megjelenik a Get-Help -Full kimenetben.

Ez az argumentum nincs hatással az opcionális paraméterekre.

DontShow argumentum

A DontShow érték általában egy olyan parancs visszamenőleges kompatibilitásának elősegítésére szolgál, ahol egy elavult paraméter nem távolítható el. A DontShow beállítása True elrejti a paramétert a felhasználó elől a lapbővítéshez és az IntelliSense-hez.

A PowerShell v7 (és újabb) DontShow használatával elrejti a következő elavult paramétereket:

A és ConvertTo-CsvExport-Csv paramétere
A Format-Hex paramétere
A és Invoke-RestMethodInvoke-WebRequest paramétere

A DontShow argumentumnak a következő mellékhatásai vannak:

A társított paraméter összes paraméterkészletére hatással van, még akkor is, ha van olyan paraméterkészlet, amelyben a DontShow nincs használatban.
Elrejti a gyakori paramétereket a lapkiegészítésből és az IntelliSense-ből. DontShow nem rejti el a választható gyakori paramétereket: WhatIf, Confirmvagy UseTransaction.

Alias attribútum

Az Alias attribútum egy másik nevet hoz létre a paraméterhez. A paraméterhez hozzárendelhető aliasok száma nincs korlátozva.

Az alábbi példa egy paraméterdeklarációt mutat be, amely hozzáadja a CN és MachineName aliasokat a kötelező ComputerName paraméterhez.

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

Hitelesítőadat-attribútum

A Hitelesítő adatok attribútum jelzi, hogy a paraméter elfogadja a hitelesítő adatokat. Az alábbi példa egy paraméterdeklarációt mutat be, amely a Hitelesítő adatok attribútumot használja.

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

Kísérleti attribútum

A Kísérleti attribútum használatával deklarálhat néhány kódot kísérletiként. Az attribútum teljes leírását a about_Experimental_Featurescímű témakörben talál.

PSDefaultValue attribútum

A PSDefaultValue egy parancsparaméter alapértelmezett értékét adja meg egy szkriptben. Ezt az információt a Get-Help parancsmag jeleníti meg. Az alapértelmezett értékadatok megtekintéséhez a függvénynek megjegyzésalapú súgót kell tartalmaznia. Például:

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

Az alapértelmezett értékadatok megtekintéséhez használja a Get-Help.

Get-Help TestDefaultValue -Parameter Name

-Name <String>

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

PSDefaultValue attribútum argumentumai

Az PSDefaultValue attribútum két argumentummal rendelkezik:

Súgó – Az alapértelmezett értéket leíró sztring. Ezt az információt a Get-Help parancsmag jeleníti meg.
Érték – A paraméter alapértelmezett értéke.

Mindkét argumentum megadása nem kötelező. Ha nem ad meg argumentumokat, akkor Get-Help a paraméterhez rendelt értéket jeleníti meg.

PSTypeName attribútum

A kiterjesztett típusnevek nem használhatók típusdeklarációkban. A PSTypeName* attribútum lehetővé teszi a paraméter típusának kiterjesztett típusra való korlátozását.

Ebben a példában a Test-Connection parancsmag egy kiterjesztett típust ad vissza. A PSTypeName attribútummal a paraméter típusát a kiterjesztett típusra korlátozhatja.

function TestType {
    param(
        [PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
        [psobject]$MtuStatus
    )

    $MtuStatus
}

$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu

System.Elavult attribútum

A már nem támogatott paraméterek megjelöléséhez használja a System.Elavult attribútumot. Ez akkor lehet hasznos, ha el szeretne távolítani egy paramétert egy függvényből, de nem szeretné megszakítani a függvényt használó meglévő szkripteket.

Vegyük például azt a függvényt, amely NoTypeInformation[switch] paraméterrel rendelkezik, amely szabályozza, hogy a típusadatok szerepelnek-e a kimenetben. Azt szeretné, hogy ez a viselkedés legyen az alapértelmezett, és távolítsa el a paramétert a függvényből. Azonban nem szeretné megszakítani a függvényt használó meglévő szkripteket. Megjelölheti a paramétert elavultként, és hozzáadhat egy üzenetet, amely elmagyarázza a módosítást.

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

SupportsWildcards attribútum

A SupportsWildcards attribútum azt jelzi, hogy a paraméter helyettesítő karaktereket fogad el. Az alábbi példa egy paraméterdeklarációt mutat be egy kötelező Elérési út paraméterhez, amely támogatja a helyettesítő karakterek értékeit.

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

Az attribútum használata nem engedélyezi automatikusan a helyettesítő karakterek támogatását. A parancsmag fejlesztőjének implementálnia kell a helyettesítő karakterek bemenetének kezeléséhez szükséges kódot. A támogatott helyettesítő karakterek a mögöttes API-tól vagy a PowerShell-szolgáltatótól függően változhatnak. További információ: about_Wildcards.

Argumentumkiegészítési attribútumok

ArgumentCompletions attribútum

Az ArgumentCompletions attribútum lehetővé teszi, hogy tabulátorkimeneti értékeket adjon hozzá egy adott paraméterhez. Az Argumentumkiegészítések attribútumot minden olyan paraméterhez meg kell határozni, amely lapkimenetet igényel. A ArgumentCompletions attribútum hasonló ValidateSet. Mindkét attribútum a paraméter neve után Tab lenyomásakor megjelenítendő értékek listáját tartalmazza. Az ValidateSetellentétben azonban az értékek nem lesznek érvényesítve.

Ez az attribútum a PowerShell 6.0-ban lett bevezetve.

További információ: about_Functions_Argument_Completion.

ArgumentCompleter attribútum

Az ArgumentCompleter attribútum lehetővé teszi lapkiegészítési értékek hozzáadását egy adott paraméterhez. Az ArgumentCompleter attribútumot minden olyan paraméterhez meg kell határozni, amely lapkimenetet igényel. A dinamikusparaméterekhezhasonlóan a rendszer futásidőben számítja ki az elérhető értékeket, amikor a felhasználó a paraméter neve után lenyomja Tab.

További információ: about_Functions_Argument_Completion.

Paraméter- és változóérvényesítési attribútumok

Az érvényesítési attribútumok közvetlenül a PowerShell-lel tesztelik a felhasználók által a speciális függvény meghívásakor beküldött paraméterértékeket. Ha a paraméterértékek sikertelenek a teszt során, hiba keletkezik, és a függvény nem lesz meghívva. A paraméterérvényesítés csak a megadott bemenetre vonatkozik, és az egyéb értékek, például az alapértelmezett értékek nem lesznek érvényesítve.

Az érvényesítési attribútumokkal is korlátozhatja a változókhoz megadható értékeket.

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

Az érvényesítési attribútumok bármely változóra alkalmazhatók, nem csak paraméterekre. A szkripten belüli változók érvényesítését definiálhatja.

Jegyzet

Ha bármilyen attribútumot gépelt változóval használ, ajánlott az attribútumot a típus előtt deklarálni.

Ha az attribútum és a változó neve előtt sortörést tartalmazó típust deklarál, a típus saját utasításként lesz kezelve.

[string]
[ValidateLength(1,5)] $Text = 'Okay'

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Ha egy típus után érvényesítési attribútumot deklarál, a hozzárendelt érték a típusátalakítás előtt lesz érvényesítve, ami váratlan érvényesítési hibákhoz vezethet.

[string] [ValidateLength(1,5)]$TicketIDFromInt        = 43
[string] [ValidateLength(1,5)]$TicketIDFromString     = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43

MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.

AllowNull validation attribútum

Az AllowNull attribútum lehetővé teszi, hogy egy kötelező paraméter értéke $nulllegyen. Az alábbi példa egy kivonatoló ComputerInfo paramétert deklarál, amely null értékkel rendelkezhet.

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

Jegyzet

Az AllowNull attribútum nem működik, ha a típuskonverter sztringre van állítva, mivel a sztringtípus nem fogad el null értéket. Ehhez a forgatókönyvhöz használhatja az AllowEmptyString attribútumot.

AllowEmptyString érvényesítési attribútum

Az AllowEmptyString attribútum lehetővé teszi, hogy egy kötelező paraméter értéke üres sztring legyen (""). Az alábbi példa egy ComputerName paramétert deklarál, amely üres sztringértékkel rendelkezhet.

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

AllowEmptyCollection validation attribútum

Az AllowEmptyCollection attribútum lehetővé teszi, hogy egy kötelező paraméter értéke üres gyűjtemény @()legyen. Az alábbi példa egy ComputerName paramétert deklarál, amely üres gyűjtési értékkel rendelkezhet.

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

ValidateCount validation attribútum

A ValidateCount attribútum határozza meg a paraméter által elfogadott paraméterértékek minimális és maximális számát. A PowerShell hibát okoz, ha a függvényt meghívó parancs paraméterértékeinek száma kívül esik ezen a tartományon.

A következő paraméterdeklaráció létrehoz egy ComputerName paramétert, amely egy-öt paraméterértéket vesz igénybe.

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

ValidateLength validation attribútum

A ValidateLength attribútum egy paraméter vagy változó értékének minimális és maximális karakterszámát határozza meg. A PowerShell hibát okoz, ha egy paraméterhez vagy változóhoz megadott érték hossza kívül esik a tartományon.

Az alábbi példában minden számítógépnévnek 1-10 karakter hosszúságúnak kell lennie.

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

Az alábbi példában a $text változó értékének legalább egy karakter hosszúságúnak és legfeljebb tíz karakternek kell lennie.

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

ValidatePattern validation attribútum

A ValidatePattern attribútum a paraméterhez vagy változóértékhez képest egy reguláris kifejezést határoz meg. A PowerShell hibát okoz, ha az érték nem egyezik a normál kifejezésmintával.

Az alábbi példában a paraméterértéknek négyjegyű számot kell tartalmaznia, és minden számjegynek nullától kilencig kell lennie.

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

Az alábbi példában a $ticketID változó értékének pontosan négyjegyű számnak kell lennie, és minden számjegynek nullától kilencig számnak kell lennie.

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

ValidateRange érvényesítési attribútum

A ValidateRange attribútum numerikus tartományt vagy ValidateRangeKind enumerálási értéket ad meg minden paraméterhez vagy változóértékhez. A PowerShell hibát okoz, ha bármely érték kívül esik a tartományon.

Az ValidateRangeKind szám a következő értékeket teszi lehetővé:

Positive – Nullánál nagyobb szám.
Negative – Nullánál kisebb szám.
NonPositive – Nullánál kisebb vagy egyenlő szám.
NonNegative – Nullánál nagyobb vagy egyenlő szám.

Az alábbi példában a Kísérletek paraméter értékének nullától tízig kell lennie.

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

Az alábbi példában a $number változó értékének nullától tízig kell lennie.

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

Az alábbi példában a $number változó értékének nullánál nagyobbnak kell lennie.

[ValidateRange("Positive")] [int]$number = 1

ValidateScript validation attribútum

A ValidateScript attribútum egy paraméter vagy változó értékének ellenőrzésére használt szkriptet határoz meg. A PowerShell az értéket a szkriptbe csövezi, és hibát okoz, ha a szkript $false ad vissza, vagy ha a szkript kivételt okoz.

Ha a ValidateScript attribútumot használja, az érvényesítendő érték a $_ változóhoz lesz leképezve. A $_ változóval hivatkozhat a szkriptben szereplő értékre.

Az alábbi példában az EventDate paraméter értékének nagyobbnak vagy egyenlőnek kell lennie az aktuális dátumnál.

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

Az alábbi példában a $date változó értékének az aktuális dátumnál és időnél kisebbnek vagy egyenlőnek kell lennie.

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

Jegyzet

Ha ValidateScripthasznál, nem adhat át $null értéket a paraméternek. Ha null értéket ad át, ValidateScript nem tudja érvényesíteni az argumentumot.

Az alapértelmezett hibaüzenet felülírása

A PowerShell 6-tól kezdve felülbírálhatja az alapértelmezett hibaüzenetet, amely akkor jön létre, ha egy megadott érték érvénytelen a ErrorMessage argumentummal. Adjon meg egy összetett formátumú sztringet. A 0 index összetevő a bemeneti értéket használja. A 1 index összetevő a bemeneti érték ellenőrzéséhez használt ScriptBlock használja.

Az alábbi példában az EventDate paraméter értékének az aktuális dátumnál és időnél nagyobbnak vagy egyenlőnek kell lennie. Ha az érték érvénytelen, a hibaüzenet azt jelzi, hogy a megadott dátum és idő túl régi.

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date)},
        ErrorMessage = "{0} isn't a future date. Specify a later date."
    )]
    [datetime]$EventDate
)

Ha a megadott érték múltbeli dátum, az egyéni hibaüzenet jelenik meg.

Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.

A sztringben további formázást is alkalmazhat, ha nem kötelező sztringösszetevőket formázni.

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date).Date},
        ErrorMessage = "{0:d} isn't a future date. Specify a later date."
    )]
    [datetime]$EventDate
)

Ha a megadott érték múltbeli dátum, az egyéni hibaüzenet jelenik meg.

Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.

ValidateSet attribútum

A ValidateSet attribútum egy paraméter vagy változó érvényes értékeinek készletét adja meg, és lehetővé teszi a lap befejezését. A PowerShell hibát okoz, ha egy paraméter vagy változó értéke nem egyezik meg a készlet egyik értékével. Az alábbi példában a Részletes paraméter értéke csak alacsony, átlag vagy magas lehet.

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

Az alábbi példában a $flavor változó értékének Csokoládé, Strawberry vagy Vanilla értéknek kell lennie.

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

Az ellenőrzés akkor történik, ha a változót még a szkripten belül is hozzárendelik. A következő például futásidőben hibát eredményez:

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

$Message = "bye"

Ez a példa a következő hibát adja vissza futásidőben:

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

A ValidateSet a paraméter értékeinek lapbővítését is lehetővé teszi. További információ: about_Tab_Expansion.

Dynamic ValidateSet értékek osztályok használatával

Egy class használatával dinamikusan hozhatja létre az ValidateSet értékeit futásidőben. Az alábbi példában a $Sound változó érvényes értékei egy class nevű generálódnak, amely három fájlrendszerbeli elérési utat ellenőriz az elérhető hangfájlokhoz:

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

A [SoundNames] osztály ezután dinamikus ValidateSet értékként lesz implementálva az alábbiak szerint:

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

Jegyzet

A IValidateSetValuesGenerator osztály a PowerShell 6.0-ban lett bevezetve

ValidateNotNull validation attribútum

A ValidateNotNull attribútum azt határozza meg, hogy a paraméter értéke nem $null. Ha az érték $null, a PowerShell kivételt emel ki.

A ValidateNotNull attribútum akkor használható, ha a paraméter nem kötelező, és a típus nincs definiálva, vagy olyan típuskonverterrel rendelkezik, amely nem képes implicit módon átalakítani a null értéket, például objektumot. Ha olyan típust ad meg, amely implicit módon konvertál egy null értéket, például egy karakterláncot, akkor a null érték üres sztringgé alakul akkor is, ha a ValidateNotNull attribútumot használja. Ebben a forgatókönyvben használja a ValidateNotNullOrEmpty attribútumot.

Az alábbi példában a azonosító paraméter értéke nem $null.

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

ValidateNotNullOrEmpty validation attribútum

A ValidateNotNullOrEmpty attribútum azt határozza meg, hogy a hozzárendelt érték nem lehet az alábbi értékek egyike sem:

$null
üres sztring ("")
üres tömb (@())

Ha az érték érvénytelen, a PowerShell kivételt eredményez.

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

ValidateNotNullOrWhiteSpace validation attribútum

A ValidateNotNullOrWhiteSpace attribútum azt határozza meg, hogy a hozzárendelt érték nem lehet az alábbi értékek egyike sem:

$null
üres sztring ("")
üres tömb @()
olyan sztring, amely csak szóköz karaktereket tartalmaz, például tabulátorokat, szóközöket, kocsivisszajeleket és új sorokat
olyan tömb, amely üres vagy csak szóköz karaktereket tartalmazó karakterláncokat tartalmaz

Ha az érték érvénytelen, a PowerShell kivételt eredményez.

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

ValidateDrive érvényesítési attribútum

A ValidateDrive attribútum azt határozza meg, hogy a paraméterértéknek az elérési utat kell jelölnie, amely csak az engedélyezett meghajtókra vonatkozik. A PowerShell hibát okoz, ha a paraméter értéke nem az engedélyezett meghajtókra vonatkozik. Az elérési út meglétét a meghajtó kivételével a rendszer nem ellenőrzi.

Relatív elérési út használata esetén az aktuális meghajtónak szerepelnie kell az engedélyezett meghajtók listájában.

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

ValidateUserDrive érvényesítési attribútum

A ValidateUserDrive attribútum azt határozza meg, hogy a paraméterértéknek a User meghajtóban kell lennie. A PowerShell hibát okoz, ha az elérési út egy másik meghajtóra hivatkozik. Az érvényesítési attribútum csak az elérési út meghajtóelőtagjának meglétét ellenőrzi.

Relatív elérési út használata esetén az aktuális meghajtónak Userkell lennie.

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.

A User meghajtót a Just Enough Administration (JEA) munkamenetkonfigurációiban határozhatja meg. Ebben a példában létrehozzuk a Felhasználó: meghajtót.

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

ValidateTrustedData érvényesítési attribútum

Ezt az attribútumot a PowerShell belsőleg használja, és nem külső használatra készült.

Ez az attribútum a PowerShell 6.1.1-ben lett hozzáadva.

Lásd még

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-04-08

about_Functions_Advanced_Parameters

Rövid leírás

Hosszú leírás

Paraméterdeklaráció

Paraméterértékek típuskonvertálása

Statikus paraméterek

[switch] Paraméterek

[switch] paramétertervezési szempontok

Dinamikus paraméterek

Paraméterek attribútumai

Paraméterattribútum

Kötelező argumentum

Pozíció argumentum

ParameterSetName argumentum

ValueFromPipeline argumentum

ValueFromPipelineByPropertyName argumentum

ValueFromRemainingArguments argumentum

HelpMessage argumentum

DontShow argumentum

Alias attribútum

Hitelesítőadat-attribútum

Kísérleti attribútum

PSDefaultValue attribútum

PSDefaultValue attribútum argumentumai

PSTypeName attribútum

System.Elavult attribútum

SupportsWildcards attribútum

Argumentumkiegészítési attribútumok

ArgumentCompletions attribútum

ArgumentCompleter attribútum

Paraméter- és változóérvényesítési attribútumok

AllowNull validation attribútum

AllowEmptyString érvényesítési attribútum

AllowEmptyCollection validation attribútum

ValidateCount validation attribútum

ValidateLength validation attribútum

ValidatePattern validation attribútum

ValidateRange érvényesítési attribútum

ValidateScript validation attribútum

Az alapértelmezett hibaüzenet felülírása

ValidateSet attribútum

Dynamic ValidateSet értékek osztályok használatával

ValidateNotNull validation attribútum

ValidateNotNullOrEmpty validation attribútum

ValidateNotNullOrWhiteSpace validation attribútum

ValidateDrive érvényesítési attribútum

ValidateUserDrive érvényesítési attribútum

ValidateTrustedData érvényesítési attribútum

Lásd még

Visszajelzés

További források

`[switch]` Paraméterek

`[switch]` paramétertervezési szempontok