Delen via

about_Functions_Advanced_Parameters

  • Artikel

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

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 met @Args gebruiken om de parameters in een opdracht weer te geven. Splatting is geldig voor 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, worden de tekenreeksen impliciet geconverteerd naar het doeltype van de parameter. Geavanceerde functies voeren cultuur-invariant parseren 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. Een datum in Duitse notatie 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 weergegeven, maken cmdlets gebruik van 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 die de volgende kenmerken heeft:

  • 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
)

Schakelen tussen parameters

Schakelparameters zijn parameters die geen parameterwaarde hebben. In plaats daarvan brengen ze een Booleaanse waar-of-onwaar-waarde over via hun aanwezigheid of afwezigheid, zodat wanneer een switchparameter aanwezig is, deze een true-waarde heeft en wanneer deze niet aanwezig is, een onwaar-waarde .

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.

Uw functie kan bijvoorbeeld een optie hebben om gegevens als een bytematrix uit te voeren:

param([switch]$AsByteArray)

Schakelparameters 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

Kies bij het maken van switchparameters zorgvuldig de parameternaam. 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 bij het ontwerp van de switchparameter

  • Schakelparameters mogen geen standaardwaarden krijgen. Ze moeten altijd standaard worden ingesteld op false.

  • Schakelparameters worden standaard uitgesloten van positionele parameters. Zelfs wanneer andere parameters impliciet positioneel zijn, zijn switchparameters dat niet. U kunt dit overschrijven in het kenmerk Parameter, maar dit brengt gebruikers in verwarring.

  • Schakelparameters moeten zo zijn ontworpen dat een opdracht wordt verplaatst van het standaardgedrag naar een minder algemene of complexere modus. Het eenvoudigste gedrag van een opdracht moet het standaardgedrag zijn waarvoor het gebruik van schakelparameters niet is vereist.

  • Schakelparameters moeten niet verplicht zijn. Het enige geval waarin het nodig is om een schakelparameter verplicht te maken, is wanneer deze nodig is om een parameterset te onderscheiden.

  • Het expliciet instellen van een schakeloptie van een booleaanse waarde kan worden uitgevoerd met -MySwitch:$boolValue en in splatting met $params = @{ MySwitch = $boolValue }.

  • Schakelparameters zijn van het type SwitchParameter, dat impliciet wordt 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-Contentcmdlets , Get-Contenten Set-Content 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 gebruik ze alleen 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 pad van de provider bevinden, de parameter ArgumentList van de Get-Command cmdlet gebruiken of de path-parameter 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 in de instructielijst 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 naam en pad, en een optionele dynamische parameter met de naam KeyCount. De parameter KeyCount bevindt zich in de ByRegistryPath parameterset en heeft het type Int32. De parameter KeyCount is alleen beschikbaar in de Get-Sample functie 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 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 cmdletBinding-kenmerk weglaat, moet de functie het kenmerk Parameter bevatten om te worden herkend als een geavanceerde functie.

U kunt een of meer 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 kenmerk Parameter hebben, of beide.

Het kenmerk Parameter heeft argumenten waarmee de kenmerken van de parameter worden gedefinieerd, zoals of de parameter verplicht of optioneel is.

Gebruik de volgende syntaxis om het parameterkenmerk , een argument en een argumentwaarde te declareren. De haakjes die het argument en de waarde ervan omsluiten, moeten parameter volgen zonder tussenruimte.

param(
    [Parameter(Argument=value)]
    $ParameterName
)

Gebruik komma's om argumenten tussen haakjes te scheiden. Gebruik de volgende syntaxis om twee argumenten van het kenmerk Parameter te declareren.

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

De booleaanse argumenttypen van het parameterkenmerk zijn standaard ingesteld op Onwaar wanneer deze worden weggelaten uit het parameterkenmerk . Stel de argumentwaarde in op $true of vermeld het argument alleen op naam. 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 kenmerk Parameter zonder argumenten gebruikt, als alternatief voor het gebruik van het cmdletBinding-kenmerk , zijn de haakjes die volgen op de kenmerknaam 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. Het argument wordt gebruikt Mandatory om de parameter verplicht te maken.

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

Positieargument

Het Position argument bepaalt of de parameternaam is vereist wanneer de parameter wordt gebruikt in een opdracht. Wanneer een parameterdeclaratie het Position argument bevat, kan de parameternaam worden weggelaten en identificeert PowerShell de naamloze parameterwaarde op basis van de positie of volgorde in de lijst met naamloze parameterwaarden in de opdracht.

Als het Position argument niet is opgegeven, moet de parameternaam of een alias of afkorting van de parameternaam 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 PositionalBinding argument van het cmdletBinding-kenmerk in op $False. Het Position argument heeft voorrang op de waarde van het PositionalBinding argument van het kenmerk CmdletBinding . Zie voor meer informatie PositionalBinding in about_Functions_CmdletBindingAttribute.

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 waarop de parameters worden gedeclareerd. Als best practice kunt u echter niet vertrouwen 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 Position wordt gebruikt met de waarde 0. Als gevolg hiervan, wanneer -ComputerName wordt weggelaten in de opdracht, 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. Om uniek te 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 de parameter ComputerName in de Computer parameterset, de parameter UserName in de User parameterset en de parameter Summary 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 een parameter wilt opnemen in meer dan één parameterset, voegt u extra parameterkenmerken toe.

In het volgende voorbeeld wordt de parameter Summary expliciet toegevoegd aan de Computer parametersets 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 parametersets voor meer informatie over parametersets.

Argument ValueFromPipeline

Het ValueFromPipeline argument 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 declareren 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 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 de parameter ComputerName heeft en het object piped een eigenschap ComputerName heeft, wordt de waarde van de eigenschap ComputerName toegewezen aan de computernaamparameter van de functie.

In het volgende voorbeeld wordt een ComputerName-parameter declareren die verplicht is en invoer accepteert van de eigenschap ComputerName van het object die via de pijplijn aan de functie wordt doorgegeven.

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 doorsniëren 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 scriptblokken met vertragingsbinding op de parameter mogelijk.

Het scriptblok delay-bind wordt automatisch uitgevoerd tijdens ParameterBinding. Het resultaat is gebonden aan de parameter . Vertragingsbinding werkt niet voor parameters die zijn gedefinieerd als het type ScriptBlock of System.Object. Het scriptblok wordt doorgegeven zonder te worden aangeroepen. Zie about_Script_Blocks voor meer informatie over scriptblokken voorvertragingsbinding.

Argument ValueFromRemainingArguments

Het ValueFromRemainingArguments argument geeft aan dat de parameter alle waarden van de parameter in de opdracht accepteert die niet zijn toegewezen aan andere parameters van de functie.

Het volgende voorbeeld declareert een waardeparameter 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(Position=1, ValueFromRemainingArguments)]
        [string[]]$Remaining
    )

    "Found $($Remaining.Count) elements"

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

Found 2 elements
0: one
1: two

HelpMessage-argument

Het HelpMessage argument geeft een tekenreeks op die een korte beschrijving van de parameter of de waarde bevat. Als u de opdracht uitvoert zonder de verplichte parameter, vraagt PowerShell u om invoer. Als u het Help-bericht wilt zien, typt !? u bij de prompt en drukt u op Enter.

Het volgende voorbeeld declareert een verplichte ComputerName-parameter en een Help-bericht met uitleg van de verwachte parameterwaarde.

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 voor de functie is, wordt dit bericht weergegeven in de Get-Help -Full uitvoer.

Dit argument heeft geen invloed op optionele parameters.

Aliaskenmerk

Het kenmerk Alias stelt een alternatieve naam voor de parameter in. 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 aliassen CN en MachineName worden toegevoegd aan de verplichte computernaamparameter .

param(
    [Parameter(Mandatory)]
    [Alias("CN","MachineName")]
    [string[]]$ComputerName
)

Referentiekenmerk

Het kenmerk Referentie wordt gebruikt om aan te geven dat de parameter referenties accepteert. In het volgende voorbeeld ziet u een parameterdeclaratie die gebruikmaakt van het kenmerk Referentie .

param(
    [Parameter()]
    [System.Management.Automation.Credential()]
    [PSCredential]$Credential
)

Experimenteel kenmerk

Gebruik het kenmerk Experimental om bepaalde code als experimenteel te declareren. Zie about_Experimental_Features voor 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 informatie over de standaardwaarde wilt zien, moet de functie help 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 informatie over de standaardwaarde 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-Help cmdlet.
  • Waarde : de standaardwaarde van de parameter.

Beide argumenten zijn optioneel. Als u geen argumenten opgeeft, Get-Help wordt de waarde weergegeven die aan de parameter is toegewezen.

KENMERK PSTypeName

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

Kenmerk System.Obsolete

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 geen bestaande scripts wilt verbreken die de functie gebruiken.

Denk bijvoorbeeld aan een functie met een NoTypeInformation-schakelparameter die bepaalt of typegegevens worden opgenomen in de uitvoer. U wilt dit gedrag als standaard instellen 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 met een uitleg van de wijziging.

param(
    [System.Obsolete("The NoTypeInformation parameter is obsolete.")]
    [SwitchParameter]$NoTypeInformation
)

SupportsWildcards-kenmerk

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
)

Als u dit kenmerk gebruikt, wordt ondersteuning voor jokertekens niet automatisch ingeschakeld. De cmdlet-ontwikkelaar moet de code implementeren om de invoer van jokertekens te verwerken. De ondersteunde jokertekens kunnen variëren, afhankelijk van de onderliggende API of PowerShell-provider. Zie about_Wildcards voor meer informatie.

Kenmerken van argumentvoltooiing

Kenmerk ArgumentCompletions

Met het kenmerk ArgumentCompletions kunt u voltooiingswaarden voor tabbladen toevoegen aan een specifieke parameter. Er moet een ArgumentCompletions-kenmerk worden gedefinieerd voor elke parameter waarvoor tabs moeten worden voltooid. Het kenmerk ArgumentCompletions is vergelijkbaar met ValidateSet. Voor beide kenmerken wordt een lijst met waarden gebruikt die moet worden weergegeven 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 voltooiingswaarden voor tabbladen toevoegen aan een specifieke parameter. Er moet een ArgumentCompleter-kenmerk worden gedefinieerd voor elke parameter waarvoor tabs moeten worden voltooid. Net als DynamicParameters worden de beschikbare waarden berekend tijdens runtime wanneer de gebruiker op Tab drukt na de parameternaam.

Zie about_Functions_Argument_Completion voor meer informatie.

Validatiekenmerken van parameters en variabelen

Met validatiekenmerken wordt PowerShell om de parameterwaarden te testen die gebruikers indienen wanneer ze de geavanceerde functie aanroepen. Als de parameterwaarden niet slagen voor de test, 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.

[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 declareert na een type, 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.

AllowNull-validatiekenmerk

Met het kenmerk AllowNull kan de waarde van een verplichte parameter worden ingesteld $nullop . 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 type conversieprogramma is ingesteld op tekenreeks, omdat het tekenreekstype geen null-waarde accepteert. U kunt het kenmerk AllowEmptyString gebruiken voor dit scenario.

AllowEmptyString-validatiekenmerk

Met het kenmerk AllowEmptyString kan de waarde van een verplichte parameter een lege tekenreeks () zijn."" In het volgende voorbeeld wordt een ComputerName-parameter declareren 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 een parameter accepteert. PowerShell genereert een fout als het aantal parameterwaarden in de opdracht die de functie aanroept, buiten dat bereik valt.

Met de volgende parameterdeclaratie maakt u een ComputerName-parameter die één tot vijf parameterwaarden gebruikt.

param(
    [Parameter(Mandatory)]
    [ValidateCount(1,5)]
    [string[]]$ComputerName
)

Validatiekenmerk ValidateLength

Het kenmerk ValidateLength geeft het minimum- en maximum aantal tekens in een parameter of variabelewaarde 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 $text minimaal één teken lang zijn en maximaal tien tekens.

[ValidateLength(1,10)] [string] $text = 'valid'

Validatiekenmerk ValidatePattern

Het kenmerk ValidatePattern geeft een reguliere expressie op die wordt vergeleken met de parameter of variabelewaarde. 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 elk cijfer een getal van nul tot negen.

param(
    [Parameter(Mandatory)]
    [ValidatePattern("[0-9]{4}")]
    [string[]]$ComputerName
)

In het volgende voorbeeld moet de waarde van de variabele $ticketID precies een getal van vier cijfers zijn en moet elk cijfer een getal van nul tot negen zijn.

[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111

Validatiekenmerk ValidateRange

Het kenmerk ValidateRange geeft een numeriek bereik of een ValidateRangeKind enum-waarde op voor elke parameter of variabele waarde. PowerShell genereert een fout als een waarde buiten dit bereik valt.

De enum ValidateRangeKind maakt de volgende waarden mogelijk:

  • Positief : een getal groter dan nul.
  • Negatief : een getal kleiner dan nul.
  • NonPositive : een getal dat kleiner is dan of gelijk is aan nul.
  • NonNegatief : een getal groter dan of gelijk aan nul.

In het volgende voorbeeld moet de waarde van de parameter Attempts 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 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 zijn 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 zijn 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 waarde doorgeven $null aan de parameter. Wanneer u een null-waarde doorgeeft, kan ValidateScript het argument niet valideren.

Het standaardfoutbericht overschrijven

Vanaf PowerShell 6 kunt u het standaardfoutbericht overschrijven dat wordt gegenereerd wanneer een opgegeven waarde ongeldig is met het ErrorMessage argument. Geef een tekenreeks voor samengestelde indeling op. Het 0 indexonderdeel gebruikt de invoerwaarde. Het 1 indexonderdeel maakt gebruik van het ScriptBlock dat wordt gebruikt om de invoerwaarde te valideren.

In het volgende voorbeeld moet de waarde van de parameter EventDate groter zijn dan of gelijk zijn aan de huidige datum en tijd. Als de waarde ongeldig is, wordt in het foutbericht gemeld 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 datum in het verleden 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 toepassen in de tekenreeks met optionele opmaaktekenreeksonderdelen.

In het volgende voorbeeld moet de waarde van de parameter EventDate groter zijn dan of gelijk zijn aan de huidige datum en tijd. Als de waarde ongeldig is, wordt in het foutbericht gemeld 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 datum in het verleden is, wordt het aangepaste foutbericht geretourneerd.

Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.

Kenmerk ValidateSet

Het kenmerk ValidateSet geeft een set geldige waarden op voor een parameter of variabele en maakt voltooiing van tabbladen mogelijk. 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 detailparameter alleen Laag, Gemiddelde of Hoog zijn.

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

In het volgende voorbeeld moet de waarde van de variabele $flavor Chocolade, Aardbei of Vanille zijn.

[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"

De validatie vindt plaats wanneer die variabele wordt toegewezen, zelfs binnen het script. Het volgende resulteert bijvoorbeeld in een fout tijdens runtime:

param(
    [ValidateSet("hello", "world")]
    [string]$Message
)

$Message = "bye"

In dit voorbeeld wordt de volgende fout tijdens runtime geretourneerd:

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

Door ValidateSet ook tabuitbreiding van waarden voor die parameter in te schakelen. Zie about_Tab_Expansion voor meer informatie.

Dynamische ValidateWaarden instellen met behulp van 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

Validatiekenmerk ValidateNotNull

Het kenmerk ValidateNotNull geeft aan dat de parameterwaarde niet mag zijn $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 is gedefinieerd of een typeconversieprogramma heeft dat niet impliciet een null-waarde zoals een object kan converteren. 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 het kenmerk ValidateNotNull wordt gebruikt. Gebruik voor dit scenario het kenmerk ValidateNotNullOrEmpty .

In het volgende voorbeeld mag de waarde van de id-parameter niet zijn $null.

param(
    [Parameter()]
    [ValidateNotNull()]
    $ID
)

Validatiekenmerk ValidateNotNullOrEmpty

Het kenmerk ValidateNotNullOrEmpty geeft aan dat de toegewezen waarde niet een 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
)

Validatiekenmerk 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 moet vertegenwoordigen in het User station. PowerShell genereert een fout als het pad naar een ander station verwijst. Het validatiekenmerk test alleen op de aanwezigheid van het stationsvoorvoegsel 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 het station Gebruiker: .

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

Validatiekenmerk ValidateTrustedData

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.

Zie ook