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 door functiegebruikers worden verzonden met de parameter.

Wanneer u het CmdletBinding kenmerk gebruikt, worden in PowerShell automatisch de algemene parameters toegevoegd. U kunt geen parameters maken die dezelfde namen gebruiken als de algemene parameters. Zie about_CommonParameters voor meer informatie.

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, 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 gebruikt. 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."

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 wisselen

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 werkelijke waarde heeft en wanneer deze afwezig is, een onwaar-waarde heeft.

De parameter Get-ChildItem Recurse 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 uit te voeren als een bytematrix:

param([switch]$AsByteArray)

Switchparameters zijn eenvoudig te gebruiken en hebben de voorkeur boven Booleaanse parameters, die een minder natuurlijke syntaxis voor PowerShell hebben.

Als u bijvoorbeeld een schakelparameter 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 doorgeeft. Vermijd dubbelzinnige termen, zoals Filter of Maximum die kunnen impliceren dat een waarde vereist is.

Overwegingen voor het ontwerp van parameters wisselen

  • 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 kenmerk Parameter, maar dit zal gebruikers verwarren.

  • Schakelparameters moeten zo worden ontworpen dat ze een opdracht van het standaardgedrag verplaatsen naar een minder gangbare of gecompliceerdere modus. Het eenvoudigste gedrag van een opdracht moet het standaardgedrag zijn dat het gebruik van switchparameters niet vereist.

  • Schakelparameters mogen niet verplicht zijn. Het enige geval waarin het noodzakelijk is om een switchparameter verplicht te stellen, 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, die impliciet worden geconverteerd naar Booleaanse waarde. De parametervariabele kan rechtstreeks in een voorwaardelijke expressie worden gebruikt. Voorbeeld:

    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-Content, Get-Contenten 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 pad van de provider bevinden, de parameter ArgumentList van de Get-Command cmdlet gebruiken of de padparameter van Get-Help.

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 parameter KeyCount bevindt zich in de ByRegistryPath parameterset en heeft een 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 kenmerk CmdletBinding weglaat, moet de functie het kenmerk Parameter bevatten om te worden herkend als een geavanceerde functie.

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 parameterkenmerk 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 als u wilt 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 die het argument en de waarde bevatten, moeten parameter volgen zonder tussenliggende spatie.

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)]
    $ParameterName
)

De Booleaanse argumenttypen van het parameterkenmerk worden standaard ingesteld op False als deze worden weggelaten uit het parameterkenmerk . Stel de argumentwaarde in op $true of geef het argument op naam weer. De volgende parameterkenmerken zijn bijvoorbeeld equivalent.

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 na de kenmerknaam van het kenmerk CmdletBinding nog steeds vereist.

param(
    [Parameter()]
    $ParameterName
)

Verplicht argument

Het Mandatory argument geeft aan dat de parameter vereist is. 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 vereist is wanneer de parameter wordt gebruikt in een opdracht. Wanneer een parameterdeclaratie het Position argument 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 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 worden gedeclareerd in de functie. Als u deze functie wilt uitschakelen, stelt u de waarde van het argument van het PositionalBinding kenmerk CmdletBinding in op $False. Het Position argument heeft voorrang op de waarde van het argument van het PositionalBinding kenmerk CmdletBinding . Zie about_Functions_CmdletBindingAttribute voor meer informatie.PositionalBinding

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 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 de waarde 0. Als de opdracht wordt weggelaten, moet de waarde hiervan -ComputerName de eerste of enige naamloze parameterwaarde in de opdracht zijn.

param(
    [Parameter(Position=0)]
    [string[]]$ComputerName
)

ParameterSetName-argument

Het ParameterSetName argument specificeert de parameterset 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 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 een parameter wilt opnemen 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 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 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 eigenschap ComputerName heeft, wordt de waarde van de eigenschap ComputerName toegewezen aan de parameter ComputerName van de functie.

In het volgende voorbeeld wordt een computernaamparameter gedeclareerd die verplicht is en invoer accepteert van de computernaam-eigenschap 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 doorspeken van een object met de eigenschap ComputerName het volgende 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 voor 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 type ScriptBlock of System.Object. Het scriptblok wordt doorgegeven zonder aan te roepen. Zie about_Script_Blocks voor meer informatie over vertragingsbindingsscriptblokken.

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.

In het volgende voorbeeld wordt een waardeparameter 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(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 ervan 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 aangegeven met 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 is voor de functie, wordt dit bericht weergegeven in de Get-Help -Full uitvoer.

Dit argument heeft geen effect op optionele parameters.

Aliaskenmerk

Het aliaskenmerk brengt een alternatieve naam voor de parameter tot stand. 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 voor CN en MachineName worden toegevoegd aan de verplichte parameter ComputerName .

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 experimentele kenmerk om 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 standaardwaardegegevens wilt zien, moet de functie hulp op basis van opmerkingen bevatten. Voorbeeld:

<#
    .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 dit 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-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.

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.Verouderd 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 worden 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 padparameter 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_Wildcards voor meer informatie.

Kenmerken voor voltooiing 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. Bij beide kenmerken wordt een lijst met waarden 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 tabvoltooiingswaarden toevoegen aan een specifieke parameter. Er moet een kenmerk ArgumentCompleter 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_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 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 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 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 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 wordt een ComputerName-parameter gemaakt die één tot vijf parameterwaarden accepteert.

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

ValidateLength-validatiekenmerk

Het kenmerk ValidateLength specificeert het minimum- en maximumaantal tekens in een parameter of variabele waarde. 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 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 viercijferig getal zijn en moet elk cijfer een getal 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 dat bereik valt.

Met de enum ValidateRangeKind 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 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 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, 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 opmaak op. Het 0 indexonderdeel maakt gebruik van 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 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 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 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

Het kenmerk ValidateSet geeft een set geldige waarden op 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, 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, 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 ValidateSet u ook tabuitbreiding van waarden voor die parameter inschakelt. Zie about_Tab_Expansion voor meer informatie.

Dynamic ValidateSet-waarden met behulp van klassen

U kunt een klasse gebruiken om de waarden dynamisch te genereren voor ValidateSet tijdens runtime. 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. 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 zoals object niet impliciet 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 u het kenmerk ValidateNotNull gebruikt. Gebruik voor dit scenario het kenmerk 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 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

Het kenmerk ValidateNotNullOrWhiteSpace geeft aan dat de toegewezen waarde geen van de volgende waarden kan 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 weergegeven 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 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 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 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