about_Functions_Advanced_Parameters
Kort beskrivning
Förklarar hur du lägger till parametrar i avancerade funktioner.
Lång beskrivning
Du kan lägga till parametrar till de avancerade funktioner som du skriver och använda parameterattribut och argument för att begränsa de parametervärden som funktionsanvändare skickar med parametern.
När du använder attributet CmdletBinding lägger PowerShell automatiskt till de gemensamma parametrarna. Du kan inte skapa några parametrar som använder samma namn som de gemensamma parametrarna. Mer information finns i about_CommonParameters.
Från och med PowerShell 3.0 kan du använda splatting med @Args för att representera parametrarna i ett kommando. Plattning är giltigt för enkla och avancerade funktioner. Mer information finns i about_Functions och about_Splatting.
Typkonvertering av parametervärden
När du anger strängar som argument till parametrar som förväntar sig en annan typ konverterar PowerShell implicit strängarna till parametermåltypen. Avancerade funktioner utför kulturvariant parsning av parametervärden.
Däremot utförs en kulturkänslig konvertering under parameterbindningen för kompilerade cmdletar.
I det här exemplet skapar vi en cmdlet och en skriptfunktion som tar en [datetime] parameter. Den aktuella kulturen ändras för att använda tyska inställningar.
Ett tyskformaterat datum skickas till parametern.
# 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
Som du ser ovan använder cmdletar kulturkänslig parsning för att konvertera strängen.
# 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
Avancerade funktioner använder kulturvariant parsning, vilket resulterar i följande fel.
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."
Statiska parametrar
Statiska parametrar är parametrar som alltid är tillgängliga i funktionen. De flesta parametrar i PowerShell-cmdletar och skript är statiska parametrar.
I följande exempel visas deklarationen för en ComputerName-parameter som har följande egenskaper:
- Det är obligatoriskt (krävs).
- Den tar indata från pipelinen.
- Det tar en matris med strängar som indata.
param(
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[string[]]$ComputerName
)
Växla parametrar
Växelparametrar är parametrar som inte har något parametervärde. I stället förmedlar de ett booleskt true-or-false-värde genom sin närvaro eller frånvaro, så att när en växelparameter finns har den ett sant värde och när det saknas har det ett falskt värde.
Parametern Get-ChildItem Recurse för är till exempel en växelparameter.
Om du vill skapa en växelparameter i en funktion anger du switch typen i parameterdefinitionen.
Funktionen kan till exempel ha ett alternativ för att mata ut data som en bytematris:
param([switch]$AsByteArray)
Växlingsparametrar är enkla att använda och föredras framför booleska parametrar, som har en mindre naturlig syntax för PowerShell.
Om du till exempel vill använda en växelparameter skriver användaren parametern i kommandot .
-IncludeAll
Om du vill använda en boolesk parameter skriver användaren parametern och ett booleskt värde.
-IncludeAll $true
När du skapar växelparametrar väljer du parameternamnet noggrant. Kontrollera att parameternamnet förmedlar effekten av parametern till användaren. Undvik tvetydiga termer, till exempel Filter eller Maximum som kan innebära att ett värde krävs.
Designöverväganden för switchparameter
Växlingsparametrar bör inte ges standardvärden. De bör alltid vara falska som standard.
Växelparametrar undantas som standard från positionsparametrar. Även om andra parametrar är implicit positionella är inte switchparametrarna det. Du kan åsidosätta det i parameterattributet, men det förvirrar användarna.
Växla parametrar bör utformas så att inställningen flyttar ett kommando från standardbeteendet till ett mindre vanligt eller mer komplicerat läge. Det enklaste beteendet för ett kommando bör vara standardbeteendet som inte kräver användning av växelparametrar.
Växlingsparametrar bör inte vara obligatoriska. Det enda fall där det är nödvändigt att göra en växelparameter obligatorisk är när det behövs för att särskilja en parameteruppsättning.
Du kan uttryckligen ange en växel från ett booleskt värde med
-MySwitch:$boolValueoch i splatting med$params = @{ MySwitch = $boolValue }.Växelparametrar är av typen
SwitchParameter, som implicit konverteras till booleskt värde. Parametervariabeln kan användas direkt i ett villkorsuttryck. Till exempel:if ($MySwitch) { ... }Du behöver inte skriva
if ($MySwitch.IsPresent) { ... }
Dynamiska parametrar
Dynamiska parametrar är parametrar för en cmdlet, funktion eller skript som endast är tillgängliga under vissa förhållanden.
Till exempel har flera provider-cmdletar parametrar som endast är tillgängliga när cmdleten används på providerenheten eller i en viss sökväg för providerenheten. Till exempel är kodningsparametern tillgänglig på Add-Contentcmdletarna , Get-Contentoch Set-Content endast när den används på en filsystemenhet.
Du kan också skapa en parameter som bara visas när en annan parameter används i funktionskommandot eller när en annan parameter har ett visst värde.
Dynamiska parametrar kan vara användbara, men använd dem bara när det behövs, eftersom de kan vara svåra för användarna att identifiera. Om du vill hitta en dynamisk parameter måste användaren vara i providersökvägen, använda parametern ArgumentList för cmdleten Get-Command eller använda parametern Path i Get-Help.
Använd nyckelordet dynamicparam för att skapa en dynamisk parameter för en funktion eller ett skript.
Syntaxen ser ut så här:
dynamicparam {<statement-list>}
I instruktionslistan använder du en if -instruktion för att ange de villkor under vilka parametern är tillgänglig i funktionen.
I följande exempel visas en funktion med standardparametrar med namnet Namn och Sökväg och en valfri dynamisk parameter med namnet KeyCount. Parametern KeyCount finns i parameteruppsättningen ByRegistryPath och har en typ av Int32. Parametern KeyCount är endast tillgänglig i Get-Sample funktionen när värdet för parametern Path börjar med HKLM:, vilket anger att den används i HKEY_LOCAL_MACHINE registerenheten.
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
}
}
}
Mer information finns i dokumentationen för typen RuntimeDefinedParameter .
Parametrars attribut
I det här avsnittet beskrivs de attribut som du kan lägga till i funktionsparametrar.
Alla attribut är valfria. Men om du utelämnar attributet CmdletBinding måste funktionen innehålla parameterattributet för att kunna identifieras som en avancerad funktion.
Du kan lägga till ett eller flera attribut i varje parameterdeklaration. Det finns ingen gräns för antalet attribut som du kan lägga till i en parameterdeklaration.
Parameterattribut
Parameterattributet används för att deklarera attributen för funktionsparametrar.
Parameterattributet är valfritt och du kan utelämna det om ingen av parametrarna i dina funktioner behöver attribut. Men för att kunna identifieras som en avancerad funktion, i stället för en enkel funktion, måste en funktion ha antingen attributet CmdletBinding eller parameterattributet eller båda.
Parameterattributet har argument som definierar parameterns egenskaper, till exempel om parametern är obligatorisk eller valfri.
Använd följande syntax för att deklarera parameterattributet, ett argument och ett argumentvärde. De parenteser som omger argumentet och dess värde måste följa parametern utan mellanliggande blanksteg.
param(
[Parameter(Argument=value)]
$ParameterName
)
Använd kommatecken för att avgränsa argument inom parenteserna. Använd följande syntax för att deklarera två argument för parameterattributet.
param(
[Parameter(Argument1=value1, Argument2=value2)]
$ParameterName
)
De booleska argumenttyperna för parameterattributet är standardvärdet False när de utelämnas från parameterattributet. Ange argumentvärdet till $true eller visa bara argumentet efter namn. Följande parameterattribut är till exempel likvärdiga.
param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
param(
[Parameter(Mandatory)]
)
Om du använder parameterattributet utan argument, som ett alternativ till att använda attributet CmdletBinding , krävs fortfarande de parenteser som följer attributnamnet.
param(
[Parameter()]
$ParameterName
)
Obligatoriskt argument
Argumentet Mandatory anger att parametern krävs. Om det här argumentet inte anges är parametern valfri.
I följande exempel deklareras parametern ComputerName . Det använder Mandatory argumentet för att göra parametern obligatorisk.
param(
[Parameter(Mandatory)]
[string[]]$ComputerName
)
Positionsargument
Argumentet Position avgör om parameternamnet krävs när parametern används i ett kommando. När en parameterdeklaration innehåller Position argumentet kan parameternamnet utelämnas och PowerShell identifierar det namnlösa parametervärdet efter dess position, eller ordning, i listan över namnlösa parametervärden i kommandot.
Position Om argumentet inte anges måste parameternamnet, eller ett parameternamnsalias eller förkortning, föregå parametervärdet när parametern används i ett kommando.
Som standard är alla funktionsparametrar positionella. PowerShell tilldelar positionsnummer till parametrar i den ordning parametrarna deklareras i funktionen.
Om du vill inaktivera den här funktionen anger du värdet för PositionalBinding argumentet för attributet CmdletBinding till $False. Argumentet Position har företräde framför värdet för PositionalBinding argumentet för attributet CmdletBinding . Mer information PositionalBinding finns i about_Functions_CmdletBindingAttribute.
Värdet för Position argumentet anges som ett heltal. Ett positionsvärde på 0 representerar den första positionen i kommandot, ett positionsvärde på 1 representerar den andra positionen i kommandot och så vidare.
Om en funktion inte har några positionsparametrar tilldelar PowerShell positioner till varje parameter baserat på den ordning som parametrarna deklareras. Vi rekommenderar dock att du inte förlitar dig på den här tilldelningen. Använd argumentet när du vill att parametrarna ska vara positionella Position .
I följande exempel deklareras parametern ComputerName . Det använder Position argumentet med värdet 0. När -ComputerName det utelämnas från kommandot måste därför dess värde vara det första eller enda namnlösa parametervärdet i kommandot.
param(
[Parameter(Position=0)]
[string[]]$ComputerName
)
ParameterSetName-argument
Argumentet ParameterSetName anger parameteruppsättningen som en parameter tillhör. Om ingen parameteruppsättning har angetts tillhör parametern alla parameteruppsättningar som definierats av funktionen. För att vara unik måste varje parameteruppsättning ha minst en parameter som inte är medlem i någon annan parameteruppsättning.
Kommentar
För en cmdlet eller funktion finns det en gräns på 32 parameteruppsättningar.
I följande exempel deklareras en Parameter för ComputerName i parameteruppsättningen Computer , en UserName-parameter i parameteruppsättningen User och en sammanfattningsparameter i båda parameteruppsättningarna.
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter()]
[switch]$Summary
)
Du kan bara ange ett ParameterSetName värde i varje argument och bara ett ParameterSetName argument i varje parameterattribut . Om du vill inkludera en parameter i fler än en parameteruppsättning lägger du till ytterligare parameterattribut .
I följande exempel läggs parametern Sammanfattning uttryckligen till i parameteruppsättningarna Computer och User . Parametern Sammanfattning är valfri i parameteruppsättningen Computer och obligatorisk i parameteruppsättningen User .
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter(ParameterSetName="Computer")]
[Parameter(Mandatory, ParameterSetName="User")]
[switch]$Summary
)
Mer information om parameteruppsättningar finns i Om parameteruppsättningar.
ValueFromPipeline-argument
Argumentet ValueFromPipeline anger att parametern accepterar indata från ett pipelineobjekt. Ange det här argumentet om funktionen accepterar hela objektet, inte bara en egenskap för objektet.
I följande exempel deklareras en ComputerName-parameter som är obligatorisk och accepterar ett objekt som skickas till funktionen från pipelinen.
param(
[Parameter(Mandatory, ValueFromPipeline)]
[string[]]$ComputerName
)
ValueFromPipelineByPropertyName-argument
Argumentet ValueFromPipelineByPropertyName anger att parametern accepterar indata från en egenskap för ett pipelineobjekt. Objektegenskapen måste ha samma namn eller alias som parametern.
Om funktionen till exempel har en ComputerName-parameter och det piped-objektet har en ComputerName-egenskap tilldelas värdet för egenskapen ComputerName till funktionens ComputerName-parameter .
I följande exempel deklareras en ComputerName-parameter som är obligatorisk och accepterar indata från objektets ComputerName-egenskap som skickas till funktionen via pipelinen.
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Överväg en implementering av en funktion med hjälp av det här argumentet:
function Test-ValueFromPipelineByPropertyName{
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}
Sedan skulle en demonstration av piping ett objekt med egenskapen ComputerName vara:
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
Kommentar
En angiven parameter som accepterar pipelineindata (by Value) eller (by PropertyName) möjliggör användning av skriptblock med fördröjningsbindning på parametern.
Skriptblocket för fördröjningsbindning körs automatiskt under ParameterBinding. Resultatet är bundet till parametern. Fördröjningsbindning fungerar inte för parametrar som definierats som typ ScriptBlock eller System.Object. Skriptblocket skickas utan att anropas. Mer information om skriptblock med fördröjningsbindning finns i about_Script_Blocks.
ValueFromRemainingArguments-argument
Argumentet ValueFromRemainingArguments anger att parametern accepterar alla parametervärden i kommandot som inte har tilldelats till andra parametrar i funktionen.
I följande exempel deklareras en värdeparameter som är obligatorisk och en återstående parameter som accepterar alla återstående parametervärden som skickas till funktionen.
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-argument
Argumentet HelpMessage anger en sträng som innehåller en kort beskrivning av parametern eller dess värde. Om du kör kommandot utan den obligatoriska parametern ber PowerShell dig om indata. Om du vill se hjälpmeddelandet skriver du !? i kommandotolken och trycker på Retur.
I följande exempel deklareras en obligatorisk ComputerName-parameter och ett hjälpmeddelande som förklarar det förväntade parametervärdet.
param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]$ComputerName
)
Exempel på utdata>
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]:
Om det inte finns någon kommentarsbaserad hjälp för funktionen visas det här meddelandet i Get-Help -Full utdata.
Det här argumentet har ingen effekt på valfria parametrar.
Aliasattribut
Aliasattributet upprättar ett alternativt namn för parametern. Det finns ingen gräns för antalet alias som du kan tilldela till en parameter.
I följande exempel visas en parameterdeklaration som lägger till CN- och MachineName-alias till den obligatoriska parametern ComputerName .
param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
Attribut för autentiseringsuppgifter
Attributet Credential används för att indikera att parametern accepterar autentiseringsuppgifter. I följande exempel visas en parameterdeklaration som använder attributet Credential .
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
Experimentellt attribut
Använd attributet Experimental för att deklarera viss kod som experimentell. En fullständig beskrivning av attributet finns i about_Experimental_Features.
PSDefaultValue-attribut
PSDefaultValue anger standardvärdet för en kommandoparameter i ett skript. Den här informationen visas av cmdleten Get-Help . Om du vill se standardvärdeinformationen måste funktionen innehålla kommentarsbaserad hjälp. Till exempel:
<#
.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
}
Använd Get-Help för att se standardvärdeinformationen.
Get-Help TestDefaultValue -Parameter name
-Name <String>
Required? false
Position? 1
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false
Attributargument för PSDefaultValue
Attributet PSDefaultValue har två argument:
- Hjälp – en sträng som beskriver standardvärdet. Den här informationen visas av cmdleten
Get-Help. - Värde – standardvärdet för parametern.
Båda argumenten är valfria. Om du inte anger några argument Get-Help visas värdet som tilldelats parametern.
PSTypeName-attribut
Du kan inte använda utökade typnamn i en typdeklaration. Med attributet PSTypeName* kan du begränsa parametertypen till den utökade typen.
I det här exemplet returnerar cmdleten Test-Connection en utökad typ. Du kan använda attributet PSTypeName för att begränsa parametertypen till den utökade typen.
function TestType {
param(
[PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
[psobject]$MtuStatus
)
$MtuStatus
}
$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu
System.Obsolete-attribut
Använd attributet System.Obsolete för att markera parametrar som inte längre stöds. Detta kan vara användbart när du vill ta bort en parameter från en funktion, men du inte vill bryta befintliga skript som använder funktionen.
Tänk dig till exempel en funktion som har en NoTypeInformation-växelparameter som styr om typinformation ingår i utdata. Du vill göra det beteendet till standard och ta bort parametern från funktionen. Du vill dock inte bryta befintliga skript som använder funktionen. Du kan markera parametern som föråldrad och lägga till ett meddelande som förklarar ändringen.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
SupportsWildcards-attribut
Attributet SupportsWildcards används för att indikera att parametern accepterar jokerteckenvärden. I följande exempel visas en parameterdeklaration för en obligatorisk sökvägsparameter som stöder jokerteckenvärden.
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
Om du använder det här attributet aktiveras inte stöd för jokertecken automatiskt. Cmdlet-utvecklaren måste implementera koden för att hantera jokerteckenindata. Jokertecken som stöds kan variera beroende på det underliggande API:et eller PowerShell-providern. Mer information finns i about_Wildcards.
Attribut för slutförande av argument
Attributet ArgumentCompletions
Med attributet ArgumentCompletions kan du lägga till tabbavslutsvärden till en specifik parameter. Ett ArgumentCompletions-attribut måste definieras för varje parameter som behöver tabbslut. Attributet ArgumentCompletions liknar ValidateSet. Båda attributen tar en lista med värden som ska visas när användaren trycker på Tabb efter parameternamnet. Men till skillnad från ValidateSet verifieras inte värdena.
Det här attributet introducerades i PowerShell 6.0.
Mer information finns i about_Functions_Argument_Completion.
Attributet ArgumentCompleter
Med attributet ArgumentCompleter kan du lägga till tabbavslutsvärden till en specifik parameter. Ett ArgumentCompleter-attribut måste definieras för varje parameter som behöver tabbslut. Precis som dynamiskaparametrar beräknas de tillgängliga värdena vid körning när användaren trycker på Tabb efter parameternamnet.
Mer information finns i about_Functions_Argument_Completion.
Parameter- och variabelverifieringsattribut
Verifieringsattribut dirigerar PowerShell för att testa de parametervärden som användarna skickar när de anropar den avancerade funktionen. Om parametervärdena misslyckas genereras ett fel och funktionen anropas inte. Parameterverifiering tillämpas endast på indata och andra värden som standardvärden verifieras inte.
Du kan också använda valideringsattributen för att begränsa de värden som användare kan ange för variabler.
[AllowNull()] [int]$number = 7
Valideringsattribut kan tillämpas på alla variabler, inte bara parametrar. Du kan definiera validering för valfri variabel i ett skript.
Kommentar
När du använder attribut med en typvariabel är det bästa praxis att deklarera attributet före typen.
Om du deklarerar en typ med en radbrytning före attributet och variabelnamnet behandlas typen som en egen instruktion.
[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True String System.Object
Om du deklarerar ett valideringsattribut efter en typ verifieras värdet som tilldelas före typkonverteringen, vilket kan leda till oväntade valideringsfel.
[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-valideringsattribut
Attributet AllowNull tillåter att värdet för en obligatorisk parameter är $null. I följande exempel deklareras en hashtable ComputerInfo-parameter som kan ha ett null-värde .
param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]$ComputerInfo
)
Kommentar
Attributet AllowNull fungerar inte om typkonverteraren är inställd på sträng eftersom strängtypen inte accepterar ett null-värde. Du kan använda attributet AllowEmptyString för det här scenariot.
Valideringsattribut för AllowEmptyString
Attributet AllowEmptyString tillåter att värdet för en obligatorisk parameter är en tom sträng (""). I följande exempel deklareras en Parameter för ComputerName som kan ha ett tomt strängvärde.
param(
[Parameter(Mandatory)]
[AllowEmptyString()]
[string]$ComputerName
)
Valideringsattribut för AllowEmptyCollection
Attributet AllowEmptyCollection tillåter att värdet för en obligatorisk parameter är en tom samling @(). I följande exempel deklareras en Parameter för ComputerName som kan ha ett tomt samlingsvärde.
param(
[Parameter(Mandatory)]
[AllowEmptyCollection()]
[string[]]$ComputerName
)
Valideringsattribut för ValidateCount
Attributet ValidateCount anger det lägsta och högsta antalet parametervärden som en parameter accepterar. PowerShell genererar ett fel om antalet parametervärden i kommandot som anropar funktionen ligger utanför det intervallet.
Följande parameterdeklaration skapar en ComputerName-parameter som tar ett till fem parametervärden.
param(
[Parameter(Mandatory)]
[ValidateCount(1,5)]
[string[]]$ComputerName
)
Valideringsattribut för ValidateLength
Attributet ValidateLength anger det minsta och högsta antalet tecken i en parameter eller variabel. PowerShell genererar ett fel om längden på ett värde som angetts för en parameter eller en variabel ligger utanför intervallet.
I följande exempel måste varje datornamn ha ett till tio tecken.
param(
[Parameter(Mandatory)]
[ValidateLength(1,10)]
[string[]]$ComputerName
)
I följande exempel måste värdet för variabeln $text vara minst ett tecken långt och högst tio tecken.
[ValidateLength(1,10)] [string] $text = 'valid'
Valideringsattribut för ValidatePattern
Attributet ValidatePattern anger ett reguljärt uttryck som jämförs med parametern eller variabelvärdet. PowerShell genererar ett fel om värdet inte matchar mönstret för reguljära uttryck.
I följande exempel måste parametervärdet innehålla ett fyrsiffrigt tal och varje siffra måste vara talet noll till nio.
param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9]{4}")]
[string[]]$ComputerName
)
I följande exempel måste värdet för variabeln $ticketID vara exakt ett fyrsiffrigt tal och varje siffra måste vara talet noll till nio.
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111
Valideringsattribut för ValidateRange
Attributet ValidateRange anger ett numeriskt intervall eller ett ValidateRangeKind-uppräkningsvärde för varje parameter eller variabelvärde. PowerShell genererar ett fel om något värde ligger utanför det intervallet.
Uppräkningen ValidateRangeKind tillåter följande värden:
Positive- Ett tal som är större än noll.Negative- Ett tal som är mindre än noll.NonPositive- Ett tal som är mindre än eller lika med noll.NonNegative- Ett tal som är större än eller lika med noll.
I följande exempel måste värdet för parametern Attempts vara mellan noll och tio.
param(
[Parameter(Mandatory)]
[ValidateRange(0,10)]
[Int]$Attempts
)
I följande exempel måste värdet för variabeln $number vara mellan noll och tio.
[ValidateRange(0,10)] [int]$number = 5
I följande exempel måste värdet för variabeln $number vara större än noll.
[ValidateRange("Positive")] [int]$number = 1
Valideringsattribut för ValidateScript
Attributet ValidateScript anger ett skript som används för att verifiera en parameter eller ett variabelvärde. PowerShell skickar värdet till skriptet och genererar ett fel om skriptet returnerar $false eller om skriptet utlöser ett undantag.
När du använder attributet ValidateScript mappas värdet som verifieras till variabeln $_ . Du kan använda variabeln $_ för att referera till värdet i skriptet.
I följande exempel måste värdet för parametern EventDate vara större än eller lika med det aktuella datumet.
param(
[Parameter(Mandatory)]
[ValidateScript({$_ -ge (Get-Date)})]
[DateTime]$EventDate
)
I följande exempel måste värdet för variabeln $date vara mindre än eller lika med aktuellt datum och tid.
[ValidateScript({$_ -le (Get-Date)})] [DateTime]$date = (Get-Date)
Kommentar
Om du använder ValidateScript kan du inte skicka ett $null värde till parametern. När du skickar ett null-värde kan ValidateScript inte verifiera argumentet.
Åsidosätta standardfelmeddelandet
Från och med PowerShell 6 kan du åsidosätta standardfelmeddelandet som genereras när ett angivet värde är ogiltigt med ErrorMessage argumentet. Ange en sammansatt formatsträng. Indexkomponenten 0 använder indatavärdet.
Indexkomponenten 1 använder ScriptBlock som används för att verifiera indatavärdet.
I följande exempel måste värdet för parametern EventDate vara större än eller lika med aktuellt datum och tid. Om värdet är ogiltigt rapporterar felmeddelandet att angivet datum och tid är för gammalt.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date)},
ErrorMessage = "{0} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
När det angivna värdet är ett tidigare datum returneras det anpassade felmeddelandet.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.
Du kan använda ytterligare formatering i strängen med valfria formatsträngskomponenter.
I följande exempel måste värdet för parametern EventDate vara större än eller lika med aktuellt datum och tid. Om värdet är ogiltigt rapporterar felmeddelandet att det angivna datumet är för gammalt.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date).Date},
ErrorMessage = "{0:d} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
När det angivna värdet är ett tidigare datum returneras det anpassade felmeddelandet.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.
Attributet ValidateSet
Attributet ValidateSet anger en uppsättning giltiga värden för en parameter eller variabel och aktiverar tabbar. PowerShell genererar ett fel om en parameter eller ett variabelvärde inte matchar ett värde i uppsättningen. I följande exempel kan värdet för parametern Detail bara vara Low, Average eller High.
param(
[Parameter(Mandatory)]
[ValidateSet("Low", "Average", "High")]
[string[]]$Detail
)
I följande exempel måste värdet för variabeln $flavor vara antingen Chocolate, Strawberry eller Vanilla.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"
Verifieringen sker när variabeln tilldelas även i skriptet. Följande resulterar till exempel i ett fel vid körning:
param(
[ValidateSet("hello", "world")]
[string]$Message
)
$Message = "bye"
Det här exemplet returnerar följande fel vid körning:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Använd ValidateSet även aktivera flikexpansion av värden för den parametern. Mer information finns i about_Tab_Expansion.
Dynamiska ValidateSet-värden med hjälp av klasser
Du kan använda en klass för att dynamiskt generera värdena för ValidateSet vid körning. I följande exempel genereras giltiga värden för variabeln $Sound via en klass med namnet SoundNames som kontrollerar tre filsystemsökvägar efter tillgängliga ljudfiler:
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
}
}
Klassen [SoundNames] implementeras sedan som ett dynamiskt ValidateSet-värde enligt följande:
param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Kommentar
Klassen IValidateSetValuesGenerator introducerades i PowerShell 6.0
Valideringsattribut för ValidateNotNull
Attributet ValidateNotNull anger att parametervärdet inte får vara $null. När värdet är $nullgenererar PowerShell ett undantag.
Attributet ValidateNotNull är utformat för att användas när parametern är valfri och typen är odefinierad eller har en typkonverterare som inte implicit kan konvertera ett null-värde som -objekt. Om du anger en typ som implicit konverterar ett null-värde, till exempel en sträng, konverteras null-värdet till en tom sträng även när attributet ValidateNotNull används. I det här scenariot använder du attributet ValidateNotNullOrEmpty .
I följande exempel kan värdet för ID-parametern inte vara $null.
param(
[Parameter()]
[ValidateNotNull()]
$ID
)
Valideringsattribut för ValidateNotNullOrEmpty
Attributet ValidateNotNullOrEmpty anger att det tilldelade värdet inte får vara något av följande värden:
$null- en tom sträng (
"") - en tom matris (
@())
När värdet är ogiltigt genererar PowerShell ett undantag.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]$UserName
)
Valideringsattributet ValidateNotNullOrWhiteSpace
Attributet ValidateNotNullOrWhiteSpace anger att det tilldelade värdet inte får vara något av följande värden:
$null- en tom sträng (
"") - en tom matris
@() - en sträng som endast innehåller blankstegstecken, till exempel flikar, blanksteg, vagnreturer och nya radlinjer
- en matris som innehåller alla strängar som är tomma eller endast innehåller blankstegstecken
När värdet är ogiltigt genererar PowerShell ett undantag.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrWhiteSpace()]
[string[]]$UserName
)
Valideringsattribut för ValidateDrive
Attributet ValidateDrive anger att parametervärdet måste representera sökvägen, som endast refererar till tillåtna enheter. PowerShell genererar ett fel om parametervärdet refererar till andra enheter än de som tillåts. Förekomsten av sökvägen, förutom själva enheten, verifieras inte.
Om du använder relativ sökväg måste den aktuella enheten finnas i listan över tillåtna enheter.
param(
[ValidateDrive("C", "D", "Variable", "Function")]
[string]$Path
)
Valideringsattribut för ValidateUserDrive
Attributet ValidateUserDrive anger att parametervärdet måste representeras på User enheten. PowerShell genererar ett fel om sökvägen refererar till en annan enhet. Verifieringsattributet testar endast förekomsten av enhetsprefixet för sökvägen.
Om du använder relativ sökväg måste den aktuella enheten vara 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.
Du kan definiera User enheten i JEA-sessionskonfigurationer (Just Enough Administration). I det här exemplet skapar vi enheten Användare: .
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
Valideringsattribut för ValidateTrustedData
Det här attributet lades till i PowerShell 6.1.1.
För närvarande används attributet internt av Själva PowerShell och är inte avsett för extern användning.
