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 i 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.
De parametrar som du lägger till i funktionen är tillgängliga för användarna utöver de vanliga parametrar som PowerShell lägger till automatiskt i alla cmdletar och avancerade funktioner. Mer information om vanliga PowerShell-parametrar 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. Splatting ä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 av 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 RecurseGet-ChildItem
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. Se till att parameternamnet kommunicerar parameterns effekt 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äxelparametrar 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 växlingsparametrarna inte 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 standardfunktionen 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äxelparametrar bör inte vara obligatoriska. Det enda fallet 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 ställa in en växel från ett booleskt värde med
-MySwitch:$boolValue
och 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. Exempel:if ($MySwitch) { ... }
Du behöver inte skriva
if ($MySwitch.IsPresent) { ... }
Dynamiska parametrar
Dynamiska parametrar är parametrar för en cmdlet, funktion eller ett 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 i providerenheten eller i en viss sökväg till providerenheten. Till exempel är kodningsparametern tillgänglig på Add-Content
cmdletarna , Get-Content
och Set-Content
endast när den används i 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. För att 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 för Get-Help
.
Om du vill skapa en dynamisk parameter för en funktion eller ett skript använder du nyckelordet DynamicParam
.
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
. KeyCount-parametern är endast tillgänglig i Get-Sample
funktionen när värdet för parametern Path börjar med HKLM:
, vilket indikerar 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. Parenteserna som omger argumentet och dess värde måste följa Parameter 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)]
)
De booleska argumenttyperna för parameterattributet är standardvärdet Falskt när det 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 parenteserna 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 som 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å i vilken ordning parametrarna deklareras.
Men vi rekommenderar att du inte förlitar dig på den här tilldelningen. När du vill att parametrarna ska vara positionella använder du Position
argumentet .
I följande exempel deklareras parametern ComputerName . Det använder Position
argumentet med värdet 0. -ComputerName
När 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 anges tillhör parametern alla parameteruppsättningar som definierats av funktionen. För att vara unik måste varje parameteruppsättning därför ha minst en parameter som inte är medlem i någon annan parameteruppsättning.
Anteckning
För en cmdlet eller funktion finns det en gräns på 32 parameteruppsättningar.
I följande exempel deklareras en ComputerName-parameter 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 ange att en parameter visas i fler än en parameteruppsättning lägger du till ytterligare parameterattribut .
I följande exempel läggs parametern Summary uttryckligen till i parameteruppsättningarna Computer
och User
. Parametern Summary ä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 egenskapen ComputerName , tilldelas värdet för egenskapen ComputerName till funktionens parameter ComputerName .
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
)
Anteckning
En typifierad parameter som accepterar pipelineindata (by Value
) eller (by PropertyName
) möjliggör användning av skriptblock med fördröjd bindning 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.
Du kan läsa om skriptblock med fördröjningsbindning här about_Script_Blocks.md.
ValueFromRemainingArguments-argument
Argumentet ValueFromRemainingArguments
anger att parametern accepterar alla parametervärden i kommandot som inte är tilldelade 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(
[string]
[Parameter(Mandatory, Position=0)]
$Value,
[string[]]
[Parameter(Position=1, ValueFromRemainingArguments)]
$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
Anteckning
Före PowerShell 6.2 anslöts samlingen ValueFromRemainingArguments som en enda entitet under index 0.
HelpMessage-argument
Argumentet HelpMessage
anger en sträng som innehåller en kort beskrivning av parametern eller dess värde. PowerShell visar det här meddelandet i prompten som visas när ett obligatoriskt parametervärde saknas i ett kommando. Det här argumentet har ingen effekt på valfria parametrar.
I följande exempel deklareras en obligatorisk ComputerName-parameter och ett hjälpmeddelande som förklarar det förväntade parametervärdet.
Om det inte finns någon annan kommentarsbaserad hjälpsyntax för funktionen (till exempel .SYNOPSIS
) visas även det här meddelandet i Get-Help
utdata.
Param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]
$ComputerName
)
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 aliaset CN och MachineName i den obligatoriska parametern ComputerName .
Param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]
$ComputerName
)
SupportsWildcards-attribut
Attributet SupportsWildcards används för att ange att parametern accepterar jokerteckenvärden. I följande exempel visas en parameterdeklaration för en obligatorisk Path-parameter 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. De jokertecken som stöds kan variera beroende på det underliggande API:et eller PowerShell-providern. Mer information finns i about_Wildcards.
Attribut för argumentslutförande
Attributet ArgumentCompletions
Med attributet ArgumentCompletions kan du lägga till tabbifyllningsvä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.
ArgumentCompleter-attribut
Med attributet ArgumentCompleter kan du lägga till tabbifyllningsvärden till en specifik parameter. Ett ArgumentCompleter-attribut måste definieras för varje parameter som behöver tabbslut. Precis som DynamicParameters 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.
Attribut för parameter- och variabelverifiering
Valideringsattributen dirigerar PowerShell för att testa de parametervärden som användare skickar när de anropar den avancerade funktionen. Om parametervärdena inte klarar testet genereras ett fel och funktionen anropas inte. Parametervalidering 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. När du använder en typkonverterare tillsammans med ett valideringsattribut måste typkonverteraren definieras före attributet.
[int32][AllowNull()] $number = 7
Anteckning
Valideringsattribut kan tillämpas på alla variabler, inte bara parametrar. Du kan definiera validering för valfri variabel i ett skript.
Attributet AllowNull-verifiering
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
)
Anteckning
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 ComputerName-parameter 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 ComputerName-parameter 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 lägsta 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 $number
vara minst ett tecken långt och högst tio tecken.
[Int32][ValidateLength(1,10)]$number = '01'
Anteckning
I det här exemplet omsluts värdet för 01
med enkla citattecken. Attributet ValidateLength accepterar inte ett tal utan att vara omslutet med citattecken.
ValidPattern-valideringsattribut
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 ett tal noll till nio.
Param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
[string[]]
$ComputerName
)
I följande exempel måste värdet för variabeln $number
vara exakt ett fyrsiffrigt tal, och varje siffra måste vara ett tal noll till nio.
[Int32][ValidatePattern("^[0-9][0-9][0-9][0-9]$")]$number = 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 intervallet.
ValidateRangeKind-uppräkningen tillåter följande värden:
- Positivt – ett tal som är större än noll.
- Negativ – 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.
[Int32][ValidateRange(0,10)]$number = 5
I följande exempel måste värdet för variabeln $number
vara större än noll.
[Int32][ValidateRange("Positive")]$number = 1
ValidScript-valideringsattribut
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 större än eller lika med aktuellt datum och tid.
[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)
Anteckning
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.
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 Choklad, Jordgubb eller Vanilj.
[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
)
Anteckning
Klassen IValidateSetValuesGenerator
introducerades i PowerShell 6.0
ValidateNotNull-valideringsattribut
Attributet ValidateNotNull anger att parametervärdet inte får vara $null
. PowerShell genererar ett fel om parametervärdet är $null
.
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 ValidateNotNullOrEmpty
I följande exempel kan värdet för ID-parametern inte vara $null
.
Param(
[Parameter()]
[ValidateNotNull()]
$ID
)
ValidNotNullOrEmpty-verifieringsattribut
Attributet ValidateNotNullOrEmpty anger att parametervärdet inte kan vara $null
och inte får vara en tom sträng (""
). PowerShell genererar ett fel om parametern används i ett funktionsanrop, men dess värde är $null
, en tom sträng (""
) eller en tom matris @()
.
Param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[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 tillåtna. 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
)
ValidUserDrive-valideringsattribut
Attributet ValidateUserDrive anger att parametervärdet måste representera sökvägen, som refererar till User
enheten. PowerShell genererar ett fel om sökvägen refererar till en annan enhet. Valideringsattributet testar endast förekomsten av enhetsdelen av 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
ValidTrustedData-valideringsattribut
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.