Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
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 door functiegebruikers worden verzonden met de parameter.
Wanneer u het kenmerk CmdletBinding gebruikt, worden in PowerShell automatisch de algemene parameters toegevoegd. U kunt geen parameters maken die dezelfde namen gebruiken als de algemene parameters. Zie about_CommonParametersvoor meer informatie.
Vanaf PowerShell 3.0 kunt u splatting gebruiken met @args om de parameters in een opdracht weer te geven. Splatting is geldig op eenvoudige en geavanceerde functies. Zie about_Functions en about_Splattingvoor meer informatie.
Parameterdeclaratie
Parameters zijn variabelen die zijn gedeclareerd in de param() instructie van een functie of scriptblock. U kunt het optionele [Parameter()] kenmerk alleen of in combinatie met het [Alias()] kenmerk of een van de parametervalidatiekenmerken gebruiken.
Parameternamen volgen de regels voor namen van variabelen. Parameternamen bestaan uit decimale cijfers, alfabetische tekens en onderstrepingstekens. Zie about_Variablesvoor een volledige lijst met naamgevingsregels.
Belangrijk
Het is mogelijk om een parameter te definiëren die begint met een decimaal cijfer. Het starten van parameternamen met een cijfer wordt niet aanbevolen omdat deze worden behandeld als tekenreekswaarden die als positionele parameters worden doorgegeven.
Bekijk het volgende voorbeeld:
function TestFunction {
param (
[switch] $100,
[string] $200
)
"100: $100"
"200: $200"
}
Als u de parameters probeert te gebruiken, interpreteert PowerShell deze als tekenreeksen die als positionele parameter worden doorgegeven.
PS> TestFunction -100 -200 Hello
100: False
200: -100
$args: -200 Hello
In de uitvoer ziet u dat PowerShell de waarde -100 aan de parametervariabele $200 heeft gebonden. De resterende positiewaarden zijn gebonden aan $args. Als u het probleem wilt omzeilen, kunt u splatting gebruiken om de parameterwaarden door te geven.
PS> $ht = @{100 = $true; 200 = 'Hello'}
PS> TestFunction @ht
100: True
200: Hello
$args:
Zie about_Splattingvoor meer informatie.
Typeconversie van parameterwaarden
Wanneer u tekenreeksen opgeeft als argumenten voor parameters die een ander type verwachten, worden de tekenreeksen impliciet geconverteerd naar het parameterdoeltype. Geavanceerde functies voeren cultuur-invariante parsering van parameterwaarden uit.
Een cultuurgevoelige conversie wordt daarentegen 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 om Duitse instellingen te gebruiken.
Er wordt een Datum met duitse notatie 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."
Zie about_Type_Conversionvoor meer informatie.
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 gebruikt.
- Er wordt een matrix met tekenreeksen als invoer gebruikt.
param(
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[string[]]$ComputerName
)
Parameters aanpassen
Schakelparameters zijn parameters die geen parameterwaarde hebben. In plaats daarvan brengen ze een Booleaanse waar-of-onwaar-waarde over door hun aanwezigheid of afwezigheid, zodat wanneer een schakelparameter aanwezig is, deze een waar waarde heeft en wanneer deze afwezig is, een onwaar waarde heeft.
De parameter Recurse van Get-ChildItem is bijvoorbeeld een switchparameter.
Als u een switchparameter in een functie wilt maken, geeft u het [switch] type op in de parameterdefinitie. In het volgende voorbeeld ziet u de definitie van een switchparameter die kan worden gebruikt om een optie te bieden voor het uitvoeren van gegevens als een bytematrix:
param([switch]$AsByteArray)
Schakelparameters zijn eenvoudig te gebruiken en hebben de voorkeur boven Booleaanse parameters met een minder natuurlijke syntaxis voor PowerShell.
Als u een switchparameter wilt gebruiken, neemt u de parameter op in de opdracht. Bijvoorbeeld:
-IncludeAll
Als u een Booleaanse parameter wilt gebruiken, moet u de parameter en een Booleaanse waarde opgeven.
-IncludeAll $true
Wanneer u switchparameters maakt, kiest u de parameternaam zorgvuldig. Zorg ervoor dat de parameternaam het effect van de parameter aan de gebruiker doorgeeft. Vermijd dubbelzinnige termen, zoals Filter of Maximum die kunnen impliceren dat een waarde vereist is.
Overwegingen voor het ontwerp van parameters wisselen
Stel geen standaardwaarde in voor een switchparameter. Schakel parameter altijd standaard in onwaar.
Maak geen schakelparameters positioneel. Schakelparameters worden standaard uitgesloten van positionele parameters. U dat in het kenmerk parameter van de overschrijven, maar dit kan gebruikers verwarren.
Ontwerpswitchparameters zodat het gebruik van parameters het standaardgedrag van de opdracht wijzigt in een minder gangbare of gecompliceerdere modus. Het eenvoudigste gedrag van een opdracht moet het standaardgedrag zijn dat het gebruik van switchparameters niet vereist.
Maak geen schakelparameters verplicht. Het enige geval waarin het handig is om een schakelparameter verplicht te stellen, is wanneer het nodig is om een parameterset te onderscheiden.
Gebruik de parametervariabele switch rechtstreeks in een voorwaardelijke expressie. Het
SwitchParametertype wordt impliciet geconverteerd naar Booleaanse waarde. Bijvoorbeeld:if ($MySwitch) { ... }Baseer altijd het gedrag dat wordt bepaald door de schakeloptie op de waarde van de switch, niet de aanwezigheid van de parameter. Er zijn verschillende manieren om te testen op de aanwezigheid van switchparameters:
-
$PSBoundParametersbevat de naam van de switchparameter als sleutel -
$MyInvocation.BoundParametersbevat de naam van de switchparameter als sleutel -
$PSCmdlet.ParameterSetNamewanneer de schakeloptie een unieke parameterset definieert
Het is bijvoorbeeld mogelijk om een expliciete waarde op te geven voor de switch met behulp van
-MySwitch:$falseof splatting. Als u alleen test op de aanwezigheid van de parameter, gedraagt de opdracht zich alsof de switchwaarde wordt$truein plaats van$false.-
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 parameter coderen is bijvoorbeeld alleen beschikbaar op het Add-Content, Get-Contenten Set-Content cmdlets 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 zoeken, moet de gebruiker zich in het pad van de provider bevinden, de parameter ArgumentList van de cmdlet Get-Command gebruiken of de parameter Path van Get-Helpgebruiken.
Als u een dynamische parameter voor een functie of script wilt maken, gebruikt u het trefwoord dynamicparam.
De syntaxis is als volgt:
dynamicparam {<statement-list>}
Gebruik in de lijst met instructies een if instructie 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 Pathen een optionele dynamische parameter met de naam KeyCount. De parameter KeyCount bevindt zich in de ByRegistryPath parameterset en heeft een type Int32. De parameter KeyCount is alleen beschikbaar in de functie Get-Sample wanneer de waarde van de parameter Path begint met 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 RuntimeDefinedParameter type 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 als een geavanceerde functie moet worden herkend, 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 aan een parameterdeclaratie kunt toevoegen.
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 kenmerk Parameter hebben, of beide.
Het kenmerk parameter heeft argumenten die de kenmerken van de parameter definiëren, bijvoorbeeld of de parameter verplicht of optioneel is.
Gebruik de volgende syntaxis om de parameter kenmerk, een argument en een argumentwaarde te declareren. De haakjes die het argument en de bijbehorende waarde bevatten, moeten 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 te declareren van het kenmerk parameter.
param(
[Parameter(Argument1=value1, Argument2=value2)]
$ParameterName
)
De Booleaanse argumenttypen van het kenmerk Parameter standaard ingesteld op False- wanneer deze worden weggelaten uit het kenmerk Parameter. Stel de argumentwaarde in op $true of vermeld het argument op naam. De volgende Parameter kenmerken zijn bijvoorbeeld gelijkwaardig.
param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
param(
[Parameter(Mandatory)]
)
Als u het kenmerk Parameter zonder argumenten gebruikt, zijn de haakjes die volgen op de kenmerknaam van het kenmerk CmdletBinding nog steeds vereist.
param(
[Parameter()]
$ParameterName
)
Verplicht argument
Het argument Mandatory 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 argument Mandatory gebruikt om de parameter verplicht te maken.
param(
[Parameter(Mandatory)]
[string[]]$ComputerName
)
Positieargument
Het argument Position bepaalt of de parameternaam vereist is wanneer de parameter wordt gebruikt in een opdracht. Wanneer een parameterdeclaratie het argument Position bevat, kan de parameternaam worden weggelaten en wordt in PowerShell de waarde van de niet-benoemde parameter geïdentificeerd op basis van de positie of volgorde ervan in de lijst met niet-benoemde parameterwaarden in de opdracht.
Als het argument Position 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 worden gedeclareerd in de functie.
Als u deze functie wilt uitschakelen, stelt u de waarde van het argument PositionalBinding van het kenmerk CmdletBinding in op $false. Het argument Position heeft voorrang op de waarde van het PositionalBinding argument van het kenmerk CmdletBinding. Zie PositionalBinding in about_Functions_CmdletBindingAttributevoor meer informatie.
De waarde van het argument Position wordt opgegeven als een geheel getal. Een positiewaarde van 0 vertegenwoordigt de eerste positie in de opdracht, een positiewaarde van 1 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 waarop de parameters worden gedeclareerd. Als best practice vertrouwt u echter niet op deze toewijzing. Als u wilt dat parameters positioneel zijn, gebruikt u het argument Position.
In het volgende voorbeeld wordt de parameter ComputerName declareren. Hierbij wordt het argument Position gebruikt met een waarde van 0. Als -ComputerName wordt weggelaten uit de opdracht, moet de waarde hiervan de eerste of enige naamloze parameterwaarde in de opdracht zijn.
param(
[Parameter(Position=0)]
[string[]]$ComputerName
)
ParameterSetName-argument
Het argument ParameterSetName 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. Als u uniek wilt zijn, moet elke parameterset ten minste één parameter hebben die geen lid is van een andere parameterset.
Notitie
Voor een cmdlet of functie geldt een limiet van 32 parametersets.
In het volgende voorbeeld wordt een ComputerName--parameter in de Computer parameterset, een UserName parameter in de User parameterset en een Summary parameter 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 parameter- kenmerk. Als u een parameter wilt opnemen in meer dan één parameterset, voegt u extra Parameter kenmerken toe.
In het volgende voorbeeld wordt de parameter Summary expliciet toegevoegd aan de parametersets Computer en User. De parameter Summary 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 parametersetsvoor meer informatie over parametersets.
Argument ValueFromPipeline
Het argument ValueFromPipeline geeft aan dat de parameter invoer van een pijplijnobject accepteert. 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 gedeclareerd die verplicht is en een object accepteert dat vanuit de pijplijn wordt doorgegeven aan de functie.
param(
[Parameter(Mandatory, ValueFromPipeline)]
[string[]]$ComputerName
)
Argument ValueFromPipelineByPropertyName
Het argument ValueFromPipelineByPropertyName 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 parameter ComputerName heeft en het object piped een eigenschap ComputerName heeft, wordt de waarde van de eigenschap ComputerName toegewezen aan de parameter ComputerName van de functie.
In het volgende voorbeeld wordt een ComputerName parameter gedeclareerd die verplicht is en invoer accepteert van de eigenschap ComputerName van het object die via de pijplijn wordt doorgegeven aan de functie.
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Overweeg een implementatie van een functie met behulp van dit argument:
function Test-ValueFromPipelineByPropertyName{
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}
Vervolgens zou een demonstratie van het doorspekken van een object met de eigenschap ComputerName zijn:
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
Notitie
Een getypte parameter die pijplijninvoer (by Value) of (by PropertyName) accepteert, maakt het gebruik van scriptblokkeringen voor vertragingsbinding op de parameter mogelijk.
Het scriptblok voor 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 aan te roepen. Zie about_Script_Blocks voor meer informatie over scriptblokkeringen voor vertragingsbindingen.
Argument ValueFromRemainingArguments
Het argument ValueFromRemainingArguments geeft aan dat de parameter alle waarden van de parameter accepteert in de opdracht die niet is toegewezen aan andere parameters van de functie.
In het volgende voorbeeld wordt een waarde parameter gedeclareert die verplicht is en een resterende parameter die alle resterende parameterwaarden accepteert die naar de functie worden verzonden.
function Test-Remainder {
param(
[Parameter(Mandatory, Position=0)]
[string]$Value,
[Parameter(ValueFromRemainingArguments, Position=1)]
[string[]]$Remaining
)
"Value = $Value"
"Found $($Remaining.Count) remaining values"
for ($i = 0; $i -lt $Remaining.Count; $i++) {
"${i}: $($Remaining[$i])"
}
}
PS> Test-Remainder first one two three
Value = first
Found 3 remaining values
0: one
1: two
2: three
Vanaf PowerShell 6.2 worden verzamelingen anders verwerkt wanneer ze worden doorgegeven aan ValueFromRemainingArguments. Als u alleen een verzameling doorgeeft, wordt elke waarde in de verzameling behandeld als een afzonderlijk item.
PS> Test-Remainder first one, two, three
Value = first
Found 3 remaining values
0: one
1: two
2: three
Wanneer u meerdere waarden doorgeeft waarbij ten minste één verzameling geen verzameling is, wordt de verzameling behandeld als één item.
PS> Test-Remainder first one, two three four
Value = first
Found 3 remaining values
0: one two
1: three
2: four
HelpMessage-argument
Het argument HelpMessage geeft een tekenreeks op die een korte beschrijving van de parameter of de bijbehorende waarde bevat. Als u de opdracht zonder de verplichte parameter uitvoert, wordt u door PowerShell gevraagd om invoer. Als u het Help-bericht wilt zien, typt u !? bij de prompt en drukt u op Enter-.
In het volgende voorbeeld wordt een verplichte ComputerName parameter en een Help-bericht met de verwachte parameterwaarde verklaard.
param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]$ComputerName
)
Voorbeelduitvoer:
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]:
Als er geen hulp op basis van opmerkingen is voor de functie, wordt dit bericht weergegeven in de Get-Help -Full-uitvoer.
Dit argument heeft geen effect op optionele parameters.
Argument DontShow
De DontShow-waarde wordt doorgaans gebruikt om compatibiliteit met eerdere versies te ondersteunen voor een opdracht waarbij een verouderde parameter niet kan worden verwijderd. Als u DontShow instelt op True wordt de parameter verborgen voor de gebruiker voor tabbladuitbreiding en IntelliSense.
PowerShell v7 (en hoger) gebruikt DontShow om de volgende verouderde parameters te verbergen:
- De parameter NoTypeInformation van
ConvertTo-CsvenExport-Csv - De parameter Raw van
Format-Hex - De parameter UseBasicParsing van
Invoke-RestMethodenInvoke-WebRequest
Het argument DontShow heeft de volgende bijwerkingen:
- Is van invloed op alle parametersets voor de bijbehorende parameter, zelfs als er een parameterset is waarin
DontShowniet wordt gebruikt. - Hiermee worden algemene parameters verborgen voor het voltooien van tabbladen en IntelliSense.
DontShowverbergt de optionele algemene parameters niet: WhatIf-, bevestigenof UseTransaction-.
Aliaskenmerk
Met het kenmerk Alias wordt een alternatieve naam voor de parameter vastgelegd. Er is geen limiet voor het aantal aliassen dat u aan een parameter kunt toewijzen.
In het volgende voorbeeld ziet u een parameterdeclaratie waarmee de CN- en MachineName aliassen worden toegevoegd aan de verplichte parameter ComputerName.
param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
Referentiekenmerk
Het kenmerk Credential wordt gebruikt om aan te geven dat de parameter referenties accepteert. In het volgende voorbeeld ziet u een parameterdeclaratie die gebruikmaakt van het kenmerk Credential.
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
Experimenteel kenmerk
Gebruik het kenmerk Experimenteel om code als experimenteel te declareren. Zie about_Experimental_Featuresvoor een volledige beschrijving van het kenmerk.
KENMERK PSDefaultValue
De PSDefaultValue- geeft de standaardwaarde van een opdrachtparameter in een script op. Deze informatie wordt weergegeven door de Get-Help cmdlet. Als u de standaardwaardegegevens wilt zien, moet de functie hulp op basis van opmerkingen bevatten. Bijvoorbeeld:
<#
.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
}
Gebruik Get-Help om de standaardwaardegegevens weer te geven.
Get-Help TestDefaultValue -Parameter Name
-Name <String>
Required? false
Position? 1
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false
Kenmerkargumenten PSDefaultValue
Het kenmerk PSDefaultValue heeft twee argumenten:
-
Help-: een tekenreeks die de standaardwaarde beschrijft. Deze informatie wordt weergegeven door de
Get-Helpcmdlet. - waarde : de standaardwaarde van de parameter.
Beide argumenten zijn optioneel. Als u geen argumenten opgeeft, geeft Get-Help de waarde weer die aan de parameter is toegewezen.
PSTypeName-kenmerk
U kunt geen uitgebreide typenamen gebruiken in een typedeclaratie. Met het kenmerk PSTypeName* kunt u het type van de parameter beperken tot het uitgebreide type.
In dit voorbeeld retourneert de Test-Connection cmdlet een uitgebreid type. U kunt het kenmerk PSTypeName gebruiken om het type van de parameter te beperken tot het uitgebreide type.
function TestType {
param(
[PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
[psobject]$MtuStatus
)
$MtuStatus
}
$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu
System.Verouderd kenmerk
Gebruik het kenmerk System.Obsolete om parameters te markeren die niet meer worden ondersteund. Dit kan handig zijn als u een parameter uit een functie wilt verwijderen, maar u niet wilt dat bestaande scripts die gebruikmaken van de functie, worden verbroken.
Denk bijvoorbeeld aan een functie met een NoTypeInformation- switchparameter waarmee wordt bepaald of typegegevens zijn opgenomen in de uitvoer. U wilt dat gedrag de standaardinstelling maken en de parameter uit de functie verwijderen. U wilt echter geen bestaande scripts verbreken die gebruikmaken van de functie. U kunt de parameter markeren als verouderd en een bericht toevoegen dat de wijziging uitlegt.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
Ondersteunt het kenmerkWildcards
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 Path parameter die ondersteuning biedt voor jokertekenwaarden.
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
Als u dit kenmerk gebruikt, wordt ondersteuning voor jokertekens niet automatisch ingeschakeld. De cmdlet-ontwikkelaar moet de code implementeren om de invoer met jokertekens af te handelen. De ondersteunde jokertekens kunnen variëren afhankelijk van de onderliggende API of PowerShell-provider. Zie about_Wildcardsvoor meer informatie.
Kenmerken voor voltooiing van argument
Kenmerk ArgumentCompletions
Met het kenmerk ArgumentCompletions kunt u tabvoltooiingswaarden toevoegen aan een specifieke parameter. Een kenmerk ArgumentCompletions moet worden gedefinieerd voor elke parameter die tabvoltooiing nodig heeft. Het kenmerk ArgumentCompletions is vergelijkbaar met ValidateSet-. Bij beide kenmerken wordt een lijst met waarden weergegeven wanneer de gebruiker op Tab drukt na de parameternaam. In tegenstelling tot ValidateSetworden de waarden echter niet gevalideerd.
Dit kenmerk is geïntroduceerd in PowerShell 6.0.
Zie about_Functions_Argument_Completionvoor meer informatie.
Kenmerk ArgumentCompleter
Met het kenmerk ArgumentCompleter kunt u tabvoltooiingswaarden toevoegen aan een specifieke parameter. Een kenmerk ArgumentCompleter moet worden gedefinieerd voor elke parameter die tabvoltooiing nodig heeft. Net als dynamische parameters, worden de beschikbare waarden tijdens runtime berekend wanneer de gebruiker op Tab drukt na de parameternaam.
Zie about_Functions_Argument_Completionvoor 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 voor variabelen kunnen opgeven.
[AllowNull()] [int]$number = 7
Validatiekenmerken kunnen worden toegepast op elke variabele, niet alleen op parameters. U kunt validatie definiëren voor elke variabele in een script.
Notitie
Wanneer u kenmerken met een getypte variabele gebruikt, is het raadzaam om het kenmerk vóór het type te declareren.
Als u een type declareert met een regeleinde vóór het kenmerk en de naam van de variabele, wordt het type behandeld als een eigen instructie.
[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True String System.Object
Als u een validatiekenmerk na een type declareert, wordt de waarde die wordt toegewezen, gevalideerd vóór de typeconversie, wat kan leiden tot onverwachte validatiefouten.
[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.
Validatiekenmerk AllowNull
Met het kenmerk AllowNull kan de waarde van een verplichte parameter worden $null. In het volgende voorbeeld wordt een hashtabel ComputerInfo- parameter declareert die een null--waarde kan hebben.
param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]$ComputerInfo
)
Notitie
De AllowNull-kenmerk 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 parameter ComputerName declareert 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 declareert die een lege verzamelingswaarde kan hebben.
param(
[Parameter(Mandatory)]
[AllowEmptyCollection()]
[string[]]$ComputerName
)
Validatiekenmerk ValidateCount
Het kenmerk ValidateCount geeft het minimum- en maximum aantal parameterwaarden op dat een parameter accepteert. 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
)
ValidateLength-validatiekenmerk
Met het kenmerk ValidateLength wordt het minimum- en maximum aantal tekens in een parameter of variabele waarde opgegeven. 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 $text minimaal één teken lang zijn en maximaal tien tekens.
[ValidateLength(1,10)] [string] $text = 'valid'
Validatiekenmerk ValidatePattern
Met het kenmerk ValidatePattern geeft u 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]{4}")]
[string[]]$ComputerName
)
In het volgende voorbeeld moet de waarde van de variabele $ticketID exact een getal van vier cijfers zijn en moet elk cijfer een getal nul tot negen zijn.
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111
Validatiekenmerk ValidateRange
De ValidateRange kenmerk geeft een numeriek bereik of een ValidateRangeKind opsommingswaarde op voor elke parameter of variabele waarde. PowerShell genereert een fout als een waarde buiten dat bereik valt.
Met de ValidateRangeKind enum zijn de volgende waarden toegestaan:
-
Positive- Een getal groter dan nul. -
Negative- Een getal kleiner dan nul. -
NonPositive- 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.
[ValidateRange(0,10)] [int]$number = 5
In het volgende voorbeeld moet de waarde van de variabele $number groter zijn dan nul.
[ValidateRange("Positive")] [int]$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 $false retourneert 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 kleiner dan of gelijk zijn aan de huidige datum en tijd.
[ValidateScript({$_ -le (Get-Date)})] [datetime]$date = (Get-Date)
Notitie
Als u ValidateScript-gebruikt, kunt u geen $null waarde doorgeven aan de parameter. Wanneer u een null-waarde doorgeeft ValidateScript- het argument niet kan valideren.
Het standaardfoutbericht overschrijven
Vanaf PowerShell 6 kunt u het standaardfoutbericht overschrijven dat wordt gegenereerd wanneer een opgegeven waarde ongeldig is met het argument ErrorMessage. Geef een tekenreeks met samengestelde notatie op. Het 0 indexonderdeel maakt gebruik van de invoerwaarde.
Het 1 indexonderdeel maakt gebruik van de ScriptBlock- gebruikt om de invoerwaarde te valideren.
In het volgende voorbeeld moet de waarde van de parameter EventDate groter dan of gelijk zijn aan de huidige datum en tijd. Als de waarde ongeldig is, wordt in het foutbericht gerapporteerd dat de opgegeven datum en tijd te oud zijn.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date)},
ErrorMessage = "{0} isn't a future date. Specify a later date."
)]
[datetime]$EventDate
)
Wanneer de opgegeven waarde een eerdere datum is, wordt het aangepaste foutbericht geretourneerd.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.
U kunt verdere opmaak in de tekenreeks toepassen met optionele opmaaktekenreeksonderdelen.
In het volgende voorbeeld moet de waarde van de parameter EventDate groter dan of gelijk zijn aan de huidige datum en tijd. Als de waarde ongeldig is, wordt in het foutbericht aangegeven dat de opgegeven datum te oud is.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date).Date},
ErrorMessage = "{0:d} isn't a future date. Specify a later date."
)]
[datetime]$EventDate
)
Wanneer de opgegeven waarde een eerdere datum is, wordt het aangepaste foutbericht geretourneerd.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.
ValidateSet-kenmerk
Met het kenmerk ValidateSet wordt een set geldige waarden voor een parameter of variabele opgegeven en kan tabvoltooiing worden ingeschakeld. 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 gebruikt, kunt u ook tabuitbreiding van waarden voor die parameter inschakelen. Zie about_Tab_Expansionvoor meer informatie.
Dynamic ValidateSet-waarden met behulp van klassen
U kunt tijdens runtime een class gebruiken om de waarden voor ValidateSet- dynamisch te genereren. In het volgende voorbeeld worden de geldige waarden voor de variabele $Sound gegenereerd via een class met de naam SoundNames waarmee drie bestandssysteempaden worden gecontroleerd 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 klasse [SoundNames] wordt vervolgens als een dynamische ValidateSet-waarde als volgt geïmplementeerd:
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 worden $null. Wanneer de waarde is $null, genereert PowerShell een uitzondering.
Het kenmerk ValidateNotNull is ontworpen om te worden gebruikt wanneer de parameter optioneel is en het type niet gedefinieerd is of een typeconversieprogramma heeft dat een null-waarde niet impliciet kan converteren, zoals object. Als u een type opgeeft dat impliciet een null-waarde converteert, zoals een tekenreeks, wordt de null-waarde geconverteerd naar een lege tekenreeks, zelfs wanneer u het kenmerk ValidateNotNull gebruikt. Gebruik voor dit scenario het kenmerk ValidateNotNullOrEmpty.
In het volgende voorbeeld kan de waarde van de parameter Id niet worden $null.
param(
[Parameter()]
[ValidateNotNull()]
$Id
)
ValidatiekenmerkNotNullOrEmpty
Het kenmerk ValidateNotNullOrEmpty geeft aan dat de toegewezen waarde geen van de volgende waarden mag zijn:
$null- een lege tekenreeks (
"") - een lege matrix (
@())
Wanneer de waarde ongeldig is, genereert PowerShell een uitzondering.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]$UserName
)
ValidatiekenmerkNotNullOrWhiteSpace
De ValidateNotNullOrWhiteSpace kenmerk geeft aan dat de toegewezen waarde geen van de volgende waarden mag zijn:
$null- een lege tekenreeks (
"") - een lege matrix
@() - een tekenreeks die alleen spaties bevat, zoals tabs, spaties, regelterugloop en nieuwe regels
- een matrix die tekenreeksen bevat die leeg zijn of alleen spaties bevatten
Wanneer de waarde ongeldig is, genereert PowerShell een uitzondering.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrWhiteSpace()]
[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 schijf. 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 moet worden aangegeven in het User station. PowerShell genereert een fout als het pad naar een ander station verwijst. Het validatiekenmerk test alleen op het bestaan van het stationsvoorvoegsel van het pad.
Als u een relatief pad gebruikt, moet het huidige station Userzijn.
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 User station definiëren in JEA-sessieconfiguraties (Just Enough Administration). In dit voorbeeld maken we het station User: drive.
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 wordt intern gebruikt door PowerShell zelf en is niet bedoeld voor extern gebruik.
Dit kenmerk is toegevoegd in PowerShell 6.1.1.
Zie ook
Met ons samenwerken op GitHub
De bron voor deze inhoud vindt u op GitHub, waar u ook problemen en pull-aanvragen kunt maken en controleren. Bekijk onze gids voor inzenders voor meer informatie.
