about_Functions_Advanced_Parameters
Korte beschrijving
Hierin wordt uitgelegd hoe u parameters toevoegt aan geavanceerde functies.
Lange beschrijving
U kunt parameters toevoegen aan de geavanceerde functies die u schrijft en parameterkenmerken en -argumenten gebruiken om de parameterwaarden te beperken die functiegebruikers met de parameter verzenden.
De parameters die u aan uw functie toevoegt, zijn beschikbaar voor gebruikers, naast de algemene parameters die PowerShell automatisch toevoegt aan alle cmdlets en geavanceerde functies. Zie about_CommonParameters voor meer informatie over de algemene PowerShell-parameters.
Vanaf PowerShell 3.0 kunt u splatting @Args gebruiken om de parameters in een opdracht weer te geven. Splatting is geldig op eenvoudige en geavanceerde functies. Zie about_Functions en about_Splatting voor meer informatie.
Typeconversie van parameterwaarden
Wanneer u tekenreeksen opgeeft als argumenten voor parameters die een ander type verwachten, converteert PowerShell de tekenreeksen impliciet naar het parameterdoeltype. Geavanceerde functies voeren cultuur-invariant parseren van parameterwaarden uit.
Daarentegen wordt een cultuurgevoelige conversie uitgevoerd tijdens de parameterbinding voor gecompileerde cmdlets.
In dit voorbeeld maken we een cmdlet en een scriptfunctie die een [datetime] parameter gebruiken. De huidige cultuur wordt gewijzigd in het gebruik van Duitse instellingen.
Een Duits opgemaakte datum wordt doorgegeven aan de parameter.
# 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
Zoals hierboven wordt weergegeven, gebruiken cmdlets cultuurgevoelige parsering om de tekenreeks te converteren.
# 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
Geavanceerde functies maken gebruik van cultuur-invariant parseren, wat resulteert in de volgende fout.
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."
Statische parameters
Statische parameters zijn parameters die altijd beschikbaar zijn in de functie. De meeste parameters in PowerShell-cmdlets en -scripts zijn statische parameters.
In het volgende voorbeeld ziet u de declaratie van een ComputerName-parameter met de volgende kenmerken:
- Dit is verplicht (vereist).
- Er wordt invoer uit de pijplijn opgehaald.
- Er wordt een matrix met tekenreeksen als invoer gebruikt.
Param(
[Parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[string[]]
$ComputerName
)
Parameters wisselen
Switchparameters zijn parameters die geen parameterwaarde hebben. In plaats daarvan brengen ze een Booleaanse waarde waar of onwaar over door hun aanwezigheid of afwezigheid, zodat wanneer een switchparameter aanwezig is een werkelijke waarde heeft en wanneer deze afwezig is, een onwaar-waarde heeft.
De recurse-parameter is Get-ChildItem bijvoorbeeld een switchparameter.
Als u een switchparameter in een functie wilt maken, geeft u het switch type op in de parameterdefinitie.
Uw functie kan bijvoorbeeld een optie hebben om gegevens als bytematrix uit te voeren:
Param([switch]$AsByteArray)
Switchparameters zijn eenvoudig te gebruiken en hebben de voorkeur boven Booleaanse parameters, die een minder natuurlijke syntaxis hebben voor PowerShell.
Als u bijvoorbeeld een switchparameter wilt gebruiken, typt de gebruiker de parameter in de opdracht.
-IncludeAll
Als u een Booleaanse parameter wilt gebruiken, typt de gebruiker de parameter en een Booleaanse waarde.
-IncludeAll $true
Wanneer u switchparameters maakt, kiest u de parameternaam zorgvuldig. Zorg ervoor dat de parameternaam het effect van de parameter aan de gebruiker communiceert. Vermijd dubbelzinnige termen, zoals Filter of Maximum die kunnen impliceren dat een waarde vereist is.
Overwegingen bij het wijzigen van parameterontwerp
Schakelparameters mogen geen standaardwaarden krijgen. Ze moeten altijd standaard onwaar zijn.
Schakelparameters worden standaard uitgesloten van positionele parameters. Zelfs wanneer andere parameters impliciet positioneel zijn, zijn schakelparameters dat niet. U kunt dit overschrijven in het parameterkenmerk, maar dit leidt tot verwarring tussen gebruikers.
Schakelparameters moeten zo worden ontworpen dat ze een opdracht van de standaardfunctionaliteit verplaatsen naar een minder gangbare of gecompliceerdere modus. Het eenvoudigste gedrag van een opdracht moet het standaardgedrag zijn dat niet het gebruik van switchparameters vereist.
Schakelparameters mogen niet verplicht zijn. Het enige geval waarin het noodzakelijk is om een switchparameter verplicht te maken, is wanneer het nodig is om een parameterset te onderscheiden.
Expliciet een schakeloptie instellen van een Booleaanse waarde kan worden uitgevoerd met
-MySwitch:$boolValueen in splatting met$params = @{ MySwitch = $boolValue }.Schakelparameters zijn van het type
SwitchParameter, die impliciet worden geconverteerd naar Booleaanse waarde. De parametervariabele kan rechtstreeks in een voorwaardelijke expressie worden gebruikt. Bijvoorbeeld:if ($MySwitch) { ... }U hoeft niet te schrijven
if ($MySwitch.IsPresent) { ... }
Dynamische parameters
Dynamische parameters zijn parameters van een cmdlet, functie of script die alleen beschikbaar zijn onder bepaalde voorwaarden.
Verschillende provider-cmdlets hebben bijvoorbeeld parameters die alleen beschikbaar zijn wanneer de cmdlet wordt gebruikt in het providerstation of in een bepaald pad van het providerstation. De coderingsparameter is bijvoorbeeld alleen beschikbaar op de Add-ContentGet-Content, en Set-Content cmdlets alleen wanneer deze wordt gebruikt in een bestandssysteemstation.
U kunt ook een parameter maken die alleen wordt weergegeven wanneer een andere parameter wordt gebruikt in de functieopdracht of wanneer een andere parameter een bepaalde waarde heeft.
Dynamische parameters kunnen nuttig zijn, maar ze alleen gebruiken wanneer dat nodig is, omdat ze moeilijk kunnen worden gedetecteerd door gebruikers. Als u een dynamische parameter wilt vinden, moet de gebruiker zich in het providerpad bevinden, de parameter ArgumentList van de Get-Command cmdlet gebruiken of de parameter Path van Get-Helpgebruiken.
Als u een dynamische parameter voor een functie of script wilt maken, gebruikt u het DynamicParam trefwoord.
De syntaxis is als volgt:
dynamicparam {<statement-list>}
Gebruik een if instructie in de lijst met instructies om de voorwaarden op te geven waaronder de parameter beschikbaar is in de functie.
In het volgende voorbeeld ziet u een functie met standaardparameters met de naam Name en Path en een optionele dynamische parameter met de naam KeyCount. De KeyCount-parameter bevindt zich in de ByRegistryPath parameterset en heeft een type Int32. De KeyCount-parameter is alleen beschikbaar in de Get-Sample functie wanneer de waarde van de parameter Path begint, HKLM:waarmee wordt aangegeven dat deze wordt gebruikt in het HKEY_LOCAL_MACHINE registerstation.
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
}
}
}
Zie de documentatie voor het type RuntimeDefinedParameter voor meer informatie.
Kenmerken van parameters
In deze sectie worden de kenmerken beschreven die u kunt toevoegen aan functieparameters.
Alle kenmerken zijn optioneel. Als u echter het kenmerk CmdletBinding weglaat en vervolgens moet worden herkend als een geavanceerde functie, moet de functie het kenmerk Parameter bevatten.
U kunt een of meerdere kenmerken toevoegen in elke parameterdeclaratie. Er is geen limiet voor het aantal kenmerken dat u kunt toevoegen aan een parameterdeclaratie.
Parameterkenmerk
Het kenmerk Parameter wordt gebruikt om de kenmerken van functieparameters te declareren.
Het kenmerk Parameter is optioneel en u kunt dit weglaten als geen van de parameters van uw functies kenmerken nodig heeft. Maar om te worden herkend als een geavanceerde functie, in plaats van een eenvoudige functie, moet een functie het kenmerk CmdletBinding of het parameterkenmerk hebben, of beide.
Het kenmerk Parameter heeft argumenten die de kenmerken van de parameter definiëren, zoals of de parameter verplicht of optioneel is.
Gebruik de volgende syntaxis om het parameterkenmerk , een argument en een argumentwaarde te declareren. De haakjes tussen het argument en de waarde moeten de parameter volgen zonder tussenliggende ruimte.
Param(
[Parameter(Argument=value)]
$ParameterName
)
Gebruik komma's om argumenten tussen haakjes te scheiden. Gebruik de volgende syntaxis om twee argumenten van het parameterkenmerk te declareren.
Param(
[Parameter(Argument1=value1,
Argument2=value2)]
)
De Booleaanse argumenttypen van het parameterkenmerk worden standaard ingesteld op False wanneer deze worden weggelaten uit het parameterkenmerk . Stel de argumentwaarde in op $true of geef het argument alleen op naam weer. De volgende parameterkenmerken zijn bijvoorbeeld gelijkwaardig.
Param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
Param(
[Parameter(Mandatory)]
)
Als u het parameterkenmerk zonder argumenten gebruikt, zijn de haakjes die volgen op de kenmerk kenmerk CmdletBinding nog steeds vereist.
Param(
[Parameter()]
$ParameterName
)
Verplicht argument
Het Mandatory argument geeft aan dat de parameter is vereist. Als dit argument niet is opgegeven, is de parameter optioneel.
In het volgende voorbeeld wordt de parameter ComputerName declareren. Hierbij wordt het Mandatory argument gebruikt om de parameter verplicht te maken.
Param(
[Parameter(Mandatory)]
[string[]]
$ComputerName
)
Positieargument
Het Position argument bepaalt of de parameternaam vereist is wanneer de parameter wordt gebruikt in een opdracht. Wanneer een parameterdeclaratie het Position argument bevat, kan de parameternaam worden weggelaten en identificeert PowerShell de waarde van de parameter zonder naam op basis van de positie of volgorde in de lijst met niet-benoemde parameterwaarden in de opdracht.
Als het Position argument niet is opgegeven, moet de parameternaam of een parameternaamalias of afkorting voorafgaan aan de parameterwaarde wanneer de parameter wordt gebruikt in een opdracht.
Standaard zijn alle functieparameters positioneel. PowerShell wijst positienummers toe aan parameters in de volgorde waarin de parameters in de functie worden gedeclareerd. Als u deze functie wilt uitschakelen, stelt u de waarde van het PositionalBinding argument van het kenmerk CmdletBinding in op $False. Het Position argument heeft voorrang op de waarde van het argument van het PositionalBinding kenmerk CmdletBinding . Zie PositionalBindingabout_Functions_CmdletBindingAttribute voor meer informatie.
De waarde van het Position argument wordt opgegeven als een geheel getal. Een positiewaarde van 0 vertegenwoordigt de eerste positie in de opdracht, een positiewaarde van 1 vertegenwoordigt de tweede positie in de opdracht, enzovoort.
Als een functie geen positionele parameters heeft, wijst PowerShell posities toe aan elke parameter op basis van de volgorde waarin de parameters worden gedeclareerd.
Als best practice vertrouwt u echter niet op deze toewijzing. Als u wilt dat parameters positioneel zijn, gebruikt u het Position argument.
In het volgende voorbeeld wordt de parameter ComputerName declareren. Het argument wordt gebruikt Position met een waarde van 0. Als de -ComputerName opdracht wordt weggelaten, moet de waarde de eerste of enige naamloze parameterwaarde in de opdracht zijn.
Param(
[Parameter(Position=0)]
[string[]]
$ComputerName
)
ParameterSetName-argument
Het ParameterSetName argument geeft de parameterset aan waartoe een parameter behoort. Als er geen parameterset is opgegeven, behoort de parameter tot alle parametersets die door de functie zijn gedefinieerd. Daarom moet elke parameterset minimaal één parameter hebben die geen lid is van een andere parameterset om uniek te zijn.
Notitie
Voor een cmdlet of functie is er een limiet van 32 parametersets.
In het volgende voorbeeld wordt een computernaamparameter in de Computer parameterset, een gebruikersnaamparameter in de User parameterset en een samenvattingsparameter in beide parametersets declareren.
Param(
[Parameter(Mandatory,
ParameterSetName="Computer")]
[string[]]
$ComputerName,
[Parameter(Mandatory,
ParameterSetName="User")]
[string[]]
$UserName,
[Parameter()]
[switch]
$Summary
)
U kunt slechts één ParameterSetName waarde opgeven in elk argument en slechts één ParameterSetName argument in elk parameterkenmerk . Als u wilt aangeven dat een parameter wordt weergegeven in meer dan één parameterset, voegt u extra parameterkenmerken toe.
In het volgende voorbeeld wordt de samenvattingsparameter expliciet toegevoegd aan de Computer en User parametersets. De parameter Samenvatting is optioneel in de Computer parameterset en verplicht in de User parameterset.
Param(
[Parameter(Mandatory,
ParameterSetName="Computer")]
[string[]]
$ComputerName,
[Parameter(Mandatory,
ParameterSetName="User")]
[string[]]
$UserName,
[Parameter(ParameterSetName="Computer")]
[Parameter(Mandatory, ParameterSetName="User")]
[switch]
$Summary
)
Zie Over parametersets voor meer informatie over parametersets.
Argument ValueFromPipeline
Het ValueFromPipeline argument geeft aan dat de parameter invoer accepteert van een pijplijnobject. Geef dit argument op als de functie het hele object accepteert, niet alleen een eigenschap van het object.
In het volgende voorbeeld wordt een ComputerName-parameter declareren die verplicht is en een object accepteert dat wordt doorgegeven aan de functie vanuit de pijplijn.
Param(
[Parameter(Mandatory,
ValueFromPipeline)]
[string[]]
$ComputerName
)
Argument ValueFromPipelineByPropertyName
Het ValueFromPipelineByPropertyName argument geeft aan dat de parameter invoer accepteert van een eigenschap van een pijplijnobject. De objecteigenschap moet dezelfde naam of alias hebben als de parameter.
Als de functie bijvoorbeeld een computernaamparameter heeft en het object piped een ComputerName-eigenschap heeft, wordt de waarde van de eigenschap ComputerName toegewezen aan de parameter ComputerName van de functie.
In het volgende voorbeeld wordt een computernaamparameter declareren die verplicht is en invoer accepteert van de computernaameigenschap van het object die via de pijplijn wordt doorgegeven aan de functie.
Param(
[Parameter(Mandatory,
ValueFromPipelineByPropertyName)]
[string[]]
$ComputerName
)
Notitie
Een getypte parameter die pijplijninvoer accepteert (by Value) of (by PropertyName) maakt het gebruik van scriptblokken voor vertragingsbinding mogelijk voor de parameter.
Het scriptblok vertragingsbinding wordt automatisch uitgevoerd tijdens ParameterBinding. Het resultaat is gebonden aan de parameter. Vertragingsbinding werkt niet voor parameters die zijn gedefinieerd als type ScriptBlock of System.Object. Het scriptblok wordt doorgegeven zonder te worden aangeroepen.
U kunt hier about_Script_Blocks.md lezen over scriptblokken voor vertragingsbinding.
Argument ValueFromRemainingArguments
Het ValueFromRemainingArguments argument geeft aan dat de parameter alle waarden van de parameter accepteert in de opdracht die niet zijn toegewezen aan andere parameters van de functie.
In het volgende voorbeeld wordt een waardeparameter declareren die verplicht is en een resterende parameter die alle resterende parameterwaarden accepteert die worden verzonden naar de functie.
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
Notitie
Vóór PowerShell 6.2 werd de verzameling ValueFromRemainingArguments toegevoegd als één entiteit onder index 0.
HelpMessage-argument
Met HelpMessage het argument wordt een tekenreeks opgegeven die een korte beschrijving van de parameter of de bijbehorende waarde bevat. In PowerShell wordt dit bericht weergegeven in de prompt die wordt weergegeven wanneer een verplichte parameterwaarde ontbreekt in een opdracht. Dit argument heeft geen invloed op optionele parameters.
In het volgende voorbeeld wordt een verplichte ComputerName-parameter en een Help-bericht weergegeven met de verwachte parameterwaarde.
Als er geen andere hulpsyntaxis op basis van opmerkingen voor de functie (bijvoorbeeld .SYNOPSIS) is, wordt dit bericht ook weergegeven in Get-Help de uitvoer.
Param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]
$ComputerName
)
Aliaskenmerk
Het aliaskenmerk brengt een alternatieve naam voor de parameter tot stand. Er is geen limiet voor het aantal aliassen dat u kunt toewijzen aan een parameter.
In het volgende voorbeeld ziet u een parameterdeclaratie waarmee de aliassen CN en MachineName worden toegevoegd aan de verplichte parameter ComputerName .
Param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]
$ComputerName
)
Het kenmerk SupportsWildcards
Het kenmerk SupportsWildcards wordt gebruikt om aan te geven dat de parameter jokertekenwaarden accepteert. In het volgende voorbeeld ziet u een parameterdeclaratie voor een verplichte padparameter die jokertekenwaarden ondersteunt.
Param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]
$Path
)
Met dit kenmerk wordt ondersteuning voor jokertekens niet automatisch ingeschakeld. De cmdlet-ontwikkelaar moet de code implementeren om de invoer van jokertekens af te handelen. De ondersteunde jokertekens kunnen variëren afhankelijk van de onderliggende API of PowerShell-provider. Zie about_Wildcards voor meer informatie.
Kenmerken voor het voltooien van argumenten
Kenmerk ArgumentCompletions
Met het kenmerk ArgumentCompletions kunt u tabvoltooiingswaarden toevoegen aan een specifieke parameter. Er moet een kenmerk ArgumentCompletions worden gedefinieerd voor elke parameter die tabvoltooiing nodig heeft. Het kenmerk ArgumentCompletions is vergelijkbaar met ValidateSet. Beide kenmerken nemen een lijst met waarden weer wanneer de gebruiker op Tab drukt na de parameternaam. In tegenstelling tot ValidateSet worden de waarden echter niet gevalideerd.
Dit kenmerk is geïntroduceerd in PowerShell 6.0.
Zie about_Functions_Argument_Completion voor meer informatie.
Kenmerk ArgumentCompleter
Met het kenmerk ArgumentCompleter kunt u tabvoltooiingswaarden toevoegen aan een specifieke parameter. Er moet een kenmerk ArgumentCompleter worden gedefinieerd voor elke parameter die tabvoltooiing nodig heeft. Net als bij DynamicParameters worden de beschikbare waarden tijdens runtime berekend wanneer de gebruiker op Tab drukt na de parameternaam.
Zie about_Functions_Argument_Completion voor meer informatie.
Parameter- en variabelevalidatiekenmerken
Validatiekenmerken sturen PowerShell om de parameterwaarden te testen die gebruikers indienen wanneer ze de geavanceerde functie aanroepen. Als de parameterwaarden mislukken, wordt er een fout gegenereerd en wordt de functie niet aangeroepen. Parametervalidatie wordt alleen toegepast op de opgegeven invoer en andere waarden, zoals standaardwaarden, worden niet gevalideerd.
U kunt ook de validatiekenmerken gebruiken om de waarden te beperken die gebruikers kunnen opgeven voor variabelen. Wanneer u een typeconversieprogramma samen met een validatiekenmerk gebruikt, moet het typeconversieprogramma worden gedefinieerd vóór het kenmerk.
[int32][AllowNull()] $number = 7
Notitie
Validatiekenmerken kunnen worden toegepast op elke variabele, niet alleen op parameters. U kunt validatie definiëren voor elke variabele in een script.
Validatiekenmerk AllowNull
Met het kenmerk AllowNull kan de waarde van een verplichte parameter worden gebruikt $null. In het volgende voorbeeld wordt een hashtable ComputerInfo-parameter declareren die een null-waarde kan hebben.
Param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]
$ComputerInfo
)
Notitie
Het kenmerk AllowNull werkt niet als het typeconversieprogramma is ingesteld op tekenreeks omdat het tekenreekstype geen null-waarde accepteert. U kunt het kenmerk AllowEmptyString voor dit scenario gebruiken.
Validatiekenmerk AllowEmptyString
Met het kenmerk AllowEmptyString kan de waarde van een verplichte parameter een lege tekenreeks ("") zijn. In het volgende voorbeeld wordt een ComputerName-parameter declareerd die een lege tekenreekswaarde kan hebben.
Param(
[Parameter(Mandatory)]
[AllowEmptyString()]
[string]
$ComputerName
)
Validatiekenmerk AllowEmptyCollection
Met het kenmerk AllowEmptyCollection kan de waarde van een verplichte parameter een lege verzameling @()zijn. In het volgende voorbeeld wordt een ComputerName-parameter declareren die een lege verzamelingswaarde kan hebben.
Param(
[Parameter(Mandatory)]
[AllowEmptyCollection()]
[string[]]
$ComputerName
)
Validatiekenmerk ValidateCount
Het kenmerk ValidateCount geeft het minimum- en maximumaantal parameterwaarden op dat door een parameter wordt geaccepteerd. PowerShell genereert een fout als het aantal parameterwaarden in de opdracht waarmee de functie wordt aangeroepen zich buiten dat bereik bevindt.
Met de volgende parameterdeclaratie maakt u een ComputerName-parameter die één tot vijf parameterwaarden accepteert.
Param(
[Parameter(Mandatory)]
[ValidateCount(1,5)]
[string[]]
$ComputerName
)
Validatiekenmerk ValidateLength
Het kenmerk ValidateLength geeft het minimum- en maximum aantal tekens in een parameter of variabele waarde op. PowerShell genereert een fout als de lengte van een waarde die is opgegeven voor een parameter of variabele buiten het bereik valt.
In het volgende voorbeeld moet elke computernaam één tot tien tekens bevatten.
Param(
[Parameter(Mandatory)]
[ValidateLength(1,10)]
[string[]]
$ComputerName
)
In het volgende voorbeeld moet de waarde van de variabele $number minimaal één teken lang zijn en maximaal tien tekens.
[Int32][ValidateLength(1,10)]$number = '01'
Notitie
In dit voorbeeld wordt de waarde tussen 01 enkele aanhalingstekens verpakt. Het kenmerk ValidateLength accepteert geen getal zonder tussen aanhalingstekens te worden geplaatst.
Validatiekenmerk ValidatePattern
Het kenmerk ValidatePattern geeft een reguliere expressie op die wordt vergeleken met de parameter of variabele waarde. PowerShell genereert een fout als de waarde niet overeenkomt met het reguliere expressiepatroon.
In het volgende voorbeeld moet de parameterwaarde een getal van vier cijfers bevatten en moet elk cijfer een getal nul tot negen zijn.
Param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
[string[]]
$ComputerName
)
In het volgende voorbeeld moet de waarde van de variabele $number exact een viercijferig getal zijn en moet elk cijfer een getal nul tot negen zijn.
[Int32][ValidatePattern("^[0-9][0-9][0-9][0-9]$")]$number = 1111
Validatiekenmerk ValidateRange
Het kenmerk ValidateRange specificeert een numeriek bereik of een ValidateRangeKind-opsommingswaarde voor elke parameter of variabele waarde. PowerShell genereert een fout als een waarde buiten dat bereik valt.
De enum ValidateRangeKind biedt de volgende waarden:
- Positief : een getal groter dan nul.
- Negatief : een getal kleiner dan nul.
- Niet-positief : een getal kleiner dan of gelijk aan nul.
- NonNegative : een getal groter dan of gelijk aan nul.
In het volgende voorbeeld moet de waarde van de parameter Pogingen tussen nul en tien zijn.
Param(
[Parameter(Mandatory)]
[ValidateRange(0,10)]
[Int]
$Attempts
)
In het volgende voorbeeld moet de waarde van de variabele $number tussen nul en tien zijn.
[Int32][ValidateRange(0,10)]$number = 5
In het volgende voorbeeld moet de waarde van de variabele $number groter zijn dan nul.
[Int32][ValidateRange("Positive")]$number = 1
Validatiekenmerk validateScript
Het kenmerk ValidateScript geeft een script op dat wordt gebruikt om een parameter of variabele waarde te valideren. PowerShell geeft de waarde door aan het script en genereert een fout als het script retourneert $false of als het script een uitzondering genereert.
Wanneer u het kenmerk ValidateScript gebruikt, wordt de waarde die wordt gevalideerd toegewezen aan de $_ variabele. U kunt de $_ variabele gebruiken om te verwijzen naar de waarde in het script.
In het volgende voorbeeld moet de waarde van de parameter EventDate groter dan of gelijk zijn aan de huidige datum.
Param(
[Parameter(Mandatory)]
[ValidateScript({$_ -ge (Get-Date)})]
[DateTime]
$EventDate
)
In het volgende voorbeeld moet de waarde van de variabele $date groter zijn dan of gelijk zijn aan de huidige datum en tijd.
[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)
Notitie
Als u ValidateScript gebruikt, kunt u geen $null waarde doorgeven aan de parameter. Wanneer u een null-waarde ValidScript doorgeeft, kan het argument niet worden gevalideerd.
Kenmerk ValidateSet
Het kenmerk ValidateSet specificeert een set geldige waarden voor een parameter of variabele en schakelt tabvoltooiing in. PowerShell genereert een fout als een parameter of variabele waarde niet overeenkomt met een waarde in de set. In het volgende voorbeeld kan de waarde van de parameter Detail alleen Laag, Gemiddeld of Hoog zijn.
Param(
[Parameter(Mandatory)]
[ValidateSet("Low", "Average", "High")]
[string[]]
$Detail
)
In het volgende voorbeeld moet de waarde van de variabele $flavor chocolade, aardbeien of Vanille zijn.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"
De validatie vindt plaats wanneer die variabele zelfs binnen het script wordt toegewezen. Het volgende resulteert bijvoorbeeld in een fout tijdens runtime:
Param(
[ValidateSet("hello", "world")]
[string]$Message
)
$Message = "bye"
In dit voorbeeld wordt de volgende fout geretourneerd tijdens runtime:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Als u ValidateSet ook tabuitbreiding van waarden voor die parameter inschakelt. Zie about_Tab_Expansion voor meer informatie.
Dynamische ValidateSet-waarden met klassen
U kunt een klasse gebruiken om de waarden voor ValidateSet tijdens runtime dynamisch te genereren. In het volgende voorbeeld worden de geldige waarden voor de variabele $Sound gegenereerd via een klasse met de naam SoundNames die drie bestandssysteempaden controleert op beschikbare geluidsbestanden:
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
}
}
De [SoundNames] klasse wordt vervolgens als volgt geïmplementeerd als een dynamische ValidateSet-waarde :
Param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Notitie
De IValidateSetValuesGenerator klasse is geïntroduceerd in PowerShell 6.0
ValidatiekenmerkNotNull
Het kenmerk ValidateNotNull geeft aan dat de parameterwaarde niet kan zijn $null. PowerShell genereert een fout als de parameterwaarde is $null.
Het kenmerk ValidateNotNull is ontworpen om te worden gebruikt wanneer de parameter optioneel is en het type niet is gedefinieerd of een typeconversieprogramma heeft dat een null-waarde zoals een object niet impliciet kan converteren. Als u een type opgeeft dat impliciet een null-waarde zoals een tekenreeks converteert, wordt de null-waarde geconverteerd naar een lege tekenreeks, zelfs wanneer u het kenmerk ValidateNotNull gebruikt. Gebruik voor dit scenario de ValidateNotNullOrEmpty
In het volgende voorbeeld kan de waarde van de id-parameter niet zijn $null.
Param(
[Parameter()]
[ValidateNotNull()]
$ID
)
ValidatiekenmerkNotNullOrEmpty
Het kenmerk ValidateNotNullOrEmpty geeft aan dat de parameterwaarde niet mag zijn $null en geen lege tekenreeks ("") kan zijn. PowerShell genereert een fout als de parameter wordt gebruikt in een functieaanroep, maar de waarde is $null, een lege tekenreeks ("") of een lege matrix @().
Param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]
$UserName
)
Validatiekenmerk van ValidateDrive
Het kenmerk ValidateDrive geeft aan dat de parameterwaarde het pad moet vertegenwoordigen, dat alleen verwijst naar toegestane stations. PowerShell genereert een fout als de parameterwaarde verwijst naar andere stations dan de toegestane. Het bestaan van het pad, met uitzondering van het station zelf, wordt niet geverifieerd.
Als u een relatief pad gebruikt, moet het huidige station in de lijst met toegestane stations staan.
Param(
[ValidateDrive("C", "D", "Variable", "Function")]
[string]$Path
)
Validatiekenmerk ValidateUserDrive
Het kenmerk ValidateUserDrive geeft aan dat de parameterwaarde het pad moet vertegenwoordigen dat verwijst naar User station. PowerShell genereert een fout als het pad naar een ander station verwijst. Het validatiekenmerk test alleen op het bestaan van het stationsgedeelte van het pad.
Als u een relatief pad gebruikt, moet het huidige station zijn 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.
U kunt station definiëren User in JEA-sessieconfiguraties (Just Enough Administration). In dit voorbeeld maken we de gebruiker: station.
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
ValidatiekenmerkTrustedData
Dit kenmerk is toegevoegd in PowerShell 6.1.1.
Op dit moment wordt het kenmerk intern gebruikt door PowerShell zelf en is het niet bedoeld voor extern gebruik.