Megosztás a következőn keresztül:

about_Functions_Advanced_Parameters

  • Cikk

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.

Az attribútum használatakor a CmdletBinding 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 a splatting használatával @Args jelölheti 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é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 paramétert használó szkriptfüggvényt [datetime] . 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."

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
)

Paraméterek váltása

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

A Recurse paraméter Get-ChildItem például egy kapcsolóparaméter.

Ha kapcsolóparamétert szeretne létrehozni egy függvényben, adja meg a switch típust a paraméterdefinícióban.

Előfordulhat például, hogy a függvénynek lehetősége van arra, hogy bájttömbként adja ki az adatokat:

param([switch]$AsByteArray)

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

Egy kapcsolóparaméter használatához például a felhasználó a parancsba írja be a paramétert.

-IncludeAll

Logikai paraméter használatához a felhasználó be írja a paramétert és egy logikai értéket.

-IncludeAll $true

Kapcsolóparaméterek létrehozásakor 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 a szűrőt vagy a maximumot , amelyek értékre utalhatnak.

Paramétertervezési szempontok váltása

  • A kapcsolóparamétereknek nem szabad alapértelmezett értékeket adni. Alapértelmezés szerint mindig hamis legyen.

  • A kapcsolóparaméterek alapértelmezés szerint ki vannak zárva a pozícióparaméterekből. Még akkor sem, ha más paraméterek implicit módon pozicionáltak, a kapcsolóparaméterek nem. Ezt felülbírálhatja a Paraméter attribútumban, de ez összezavarja a felhasználókat.

  • A kapcsolóparamétereket úgy kell megtervezni, hogy a beállításuk egy parancsot az alapértelmezett viselkedésről egy kevésbé gyakori vagy bonyolultabb módba helyez át. A parancsok legegyszerűbb viselkedésének az alapértelmezett viselkedésnek kell lennie, amely nem igényli a kapcsolóparaméterek használatát.

  • A kapcsolóparaméterek nem kötelezőek. Az egyetlen eset, amikor kötelezővé kell tenni egy kapcsolóparamétert, ha meg kell különböztetni egy paraméterkészletet.

  • A logikai kapcsolót explicit módon meg lehet adni a logikai értékekkel -MySwitch:$boolValue , és azokkal $params = @{ MySwitch = $boolValue }is lehet fröccsenni.

  • A kapcsolóparaméterek típusa SwitchParameterlogikai értékre konvertálható. A paraméterváltozó közvetlenül használható feltételes kifejezésekben. Példa:

    if ($MySwitch) { ... }

    Nincs szükség írásra if ($MySwitch.IsPresent) { ... }

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ában kell lennie, a parancsmag Argumentumlista paraméterét Get-Command kell használnia, vagy a parancsmag Elérési út paraméterét kell használnia Get-Help.

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

A szintaxis a következő:

dynamicparam {<statement-list>}

Az utasításlistában egy utasítás használatával if 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 út nevű standard paraméterekkel rendelkező függvényt, valamint egy KeyCount nevű opcionális dinamikus paramétert mutat be. A KeyCount paraméter a ByRegistryPath paraméterkészletben található, és típusa Int32. A KeyCount paraméter csak akkor érhető el a Get-Sample függvényben, ha az Elérési út paraméter értéke a HKLM:beállításjegyzék-meghajtón HKEY_LOCAL_MACHINE való használatot jelzi.

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ókért tekintse meg a RuntimeDefinedParameter típus dokumentációját.

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álható.

A Paraméter attribútum nem kötelező, és kihagyhatja, ha a függvények egyik paraméterének sem igényel attribútumokat. 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 annak értékét tartalmazó zárójeleknek a 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. A paraméterattribútum két argumentumának deklarálásához használja az alábbi szintaxist.

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

A Paraméter attribútum logikai argumentumtípusa alapértelmezés szerint Hamis, ha a Paraméter attribútumból hiányzik. Állítsa be az argumentum értékét név $true szerint, vagy csak listázhatja az argumentumot. A következő paraméterattribú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 alternatívaként továbbra is szükség van az attribútum nevét követő zárójelekre.

param(
    [Parameter()]
    $ParameterName
)

Kötelező argumentum

Az Mandatory argumentum azt jelzi, hogy a paraméter megadása kötelező. Ha ez az argumentum nincs megadva, a paraméter nem kötelező.

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

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

Pozíció argumentum

Az Position argumentum meghatározza, hogy szükség van-e a paraméter nevére, ha a paramétert egy parancsban használják. Ha egy paraméterdeklaráció tartalmazza az Position argumentumot, a paraméter neve kihagyható, é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 az 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 CmdletBinding attribútum argumentumának PositionalBinding értékét a következőre$False: . Az Position argumentum elsőbbséget élvez a PositionalBinding CmdletBinding attribútum argumentumának értékével szemben. További információ: PositionalBinding about_Functions_CmdletBindingAttribute.

Az argumentum értéke Position egész számként van megadva. A 0 pozícióérték a parancs első pozícióját, az 1-et pedig a parancs második pozícióját jelöli, és így tovább.

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 az Position argumentumot.

Az alábbi példa deklarálja a ComputerName paramétert. Az argumentum értéke Position 0. Ennek eredményeképpen a parancsból kihagyott -ComputerName értéknek a parancs első vagy egyetlen névtelen paraméterértékének kell lennie.

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

ParameterSetName argumentum

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

Feljegyzés

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, és egy Summary 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 minden paraméterattribútumban csak egy ParameterSetName argumentumot. Ha egy paramétert egynél több paraméterkészletbe szeretne felvenni, adjon hozzá további paraméterattribútumokat .

Az alábbi példa explicit módon hozzáadja az Összegzés paramétert a és User a Computer 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
)

A paraméterkészletekről további információt a Paraméterkészletek ismertetése című témakörben talál.

ValueFromPipeline argumentum

Az 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 olyan 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

Az 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 vezetékes objektum SzámítógépNév tulajdonsága van, a ComputerName tulajdonság értéke a függvény ComputerName paraméteréhez lesz rendelve.

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

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 egy 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'

Feljegyzés

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 a ScriptBlock vagy System.Object típusú paramétereknél. A szkriptblokk meghívás nélkül halad át. A késleltetett kötésű szkriptblokkokkal kapcsolatos további információkért lásd about_Script_Blocks.

ValueFromRemainingArguments argumentum

Az 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ékparamétert és egy fennmaradó paramétert deklarál, amely elfogadja a függvénynek elküldött összes fennmaradó paraméterértéket.

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

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

    "Found $($Remaining.Count) elements"

    for ($i = 0; $i -lt $Remaining.Count; $i++) {
        "${i}: $($Remaining[$i])"
    }
}
Test-Remainder first one,two

Found 2 elements
0: one
1: two

HelpMessage argumentum

Az HelpMessage argumentum egy sztringet ad 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 parancssorba, és nyomja le az Enter billentyűt.

Az alábbi példa egy kötelező ComputerName paramétert és egy súgóüzenetet deklarál, 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élda a kimenetre:

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.

Alias attribútum

Az Alias attribútum egy alternatív 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őadat attribútum azt 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őadat 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_Features cí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élda:

<#
    .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ékinformációk megtekintésére szolgál 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

A PSDefaultValue attribútumnak két argumentuma van:

  • 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ék jelenik 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

Használja a System.Elavult attribútumot a már nem támogatott paraméterek megjelöléséhez. 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 kapcsolóparaméterrel rendelkezik, amely szabályozza, hogy a kimenet tartalmazza-e a típusadatokat. 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.")]
    [SwitchParameter]$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 olyan 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 lapkiegészítési értékek hozzáadását egy adott paraméterhez. Minden olyan paraméterhez meg kell határozni egy Argumentumkiegészítés attribútumot, amely lapkiegészítést igényel. Az ArgumentCompletions attribútum a ValidateSethez hasonló. Mindkét attribútum tartalmazza a megjelenítendő értékek listáját, amikor a felhasználó lenyomja a Tab billentyűt a paraméter neve után. A ValidateSettől eltérően azonban a rendszer nem érvényesíti az értékeket.

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. Minden olyan paraméterhez meg kell határozni egy ArgumentCompleter attribútumot, amely lapkimenetet igényel. A dinamikusparaméterekhez hasonlóan a rendszer futásidőben számítja ki az elérhető értékeket, amikor a felhasználó lenyomja a Tab billentyűt a paraméter neve után.

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.

Feljegyzés

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 egy kötelező paraméter $nullértékét. Az alábbi példa egy null értékű kivonatoló ComputerInfo paramétert deklarál.

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

Feljegyzés

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 (""). 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 Olyan 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

Az ValidateLength attribútum egy paraméter vagy változó értékének karaktereinek minimális és maximális szá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 változó $text é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 egy olyan reguláris kifejezést határoz meg, amely a paraméterrel vagy a változó értékével van összehasonlítva. 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 változó $ticketID é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 enum é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 enumerálás 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 változó $number értékének nullától tízig kell lennie.

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

Az alábbi példában a változó $number é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 ad meg. A PowerShell az értéket a szkriptbe csövezi, és hibát okoz, ha a szkript visszatér $false , vagy ha a szkript kivételt okoz.

A ValidateScript attribútum használatakor az érvényesítendő érték a változóhoz $_ lesz leképezve. A változóval $_ hivatkozhat a szkriptben lévő értékre.

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

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

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

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

Feljegyzés

Ha ValidateScriptet használ, nem adhat át $null értéket a paraméternek. Null érték megadásakor a 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 az ErrorMessage argumentummal. Adjon meg egy összetett formátumsztringet. Az 0 index összetevő a bemeneti értéket használja. Az 1 index összetevő a ScriptBlock használatával ellenőrzi a bemeneti értéket.

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 és időnél. 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.

További formázást is alkalmazhat a sztringben opcionális formázási sztringösszetevőkkel.

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 és időnél. Ha az érték érvénytelen, a hibaüzenet azt jelzi, hogy a megadott dátum túl régi.

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 engedélyezi a lapkizárást. 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 Detail paraméter értéke csak alacsony, átlag vagy magas lehet.

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

A következő példában a változó $flavor értékének Csokoládé, Eper 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 paraméter ValidateSet értékeinek lapbővítése is engedélyezve van. További információ: about_Tab_Expansion.

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

Osztály használatával dinamikusan hozhatja létre a ValidateSet értékeit futásidőben. Az alábbi példában a változó $Sound érvényes értékei egy SoundNames nevű osztályon keresztül jönnek létre, amely három fájlrendszer elérési útját ellenőrzi az elérhető hangfájlok esetében:

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

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

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

Feljegyzés

Az 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 lehet $null. Ha az érték az, a $nullPowerShell kivételt emel ki.

A ValidateNotNull attribútum akkor használható, ha a paraméter nem kötelező, és a típus nem definiált, vagy olyan típuskonverterrel rendelkezik, amely nem képes implicit módon null értéket konvertálni, például objektumot. Ha olyan típust ad meg, amely implicit módon konvertál egy null értéket( például egy sztringet), akkor a null érték üres sztringgé lesz konvertálva, még akkor is, ha az ValidateNotNull attribútumot használja. Ebben az esetben használja a ValidateNotNullOrEmpty attribútumot.

Az alábbi példában az azonosító paraméter értéke nem lehet$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 kell lennie User.

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 meghajtókat a Just Enough Administration (JEA) munkamenetkonfigurációiban határozhatja meg User . 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

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

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

Lásd még