Share via


about_Functions_Advanced_Parameters

Kort beskrivning

Förklarar hur du lägger till parametrar i avancerade funktioner.

Lång beskrivning

Du kan lägga till parametrar i de avancerade funktioner som du skriver och använda parameterattribut och argument för att begränsa de parametervärden som funktionsanvändare skickar med parametern.

De parametrar som du lägger till i funktionen är tillgängliga för användarna utöver de vanliga parametrar som PowerShell lägger till automatiskt i alla cmdletar och avancerade funktioner. Mer information om vanliga PowerShell-parametrar finns i about_CommonParameters.

Från och med PowerShell 3.0 kan du använda splatting med @Args för att representera parametrarna i ett kommando. Splatting är giltigt för enkla och avancerade funktioner. Mer information finns i about_Functions och about_Splatting.

Typkonvertering av parametervärden

När du anger strängar som argument till parametrar som förväntar sig en annan typ konverterar PowerShell implicit strängarna till parametermåltypen. Avancerade funktioner utför kulturvariant parsning av parametervärden.

Däremot utförs en kulturkänslig konvertering under parameterbindningen för kompilerade cmdletar.

I det här exemplet skapar vi en cmdlet och en skriptfunktion som tar en [datetime] parameter. Den aktuella kulturen ändras för att använda tyska inställningar. Ett tyskformaterat datum skickas till parametern.

# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
  using System;
  using System.Management.Automation;
  [Cmdlet("Get", "Date_Cmdlet")]
  public class GetFooCmdlet : Cmdlet {

    [Parameter(Position=0)]
    public DateTime Date { get; set; }

    protected override void ProcessRecord() {
      WriteObject(Date);
    }
  }
'@ -PassThru | % Assembly | Import-Module

[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'

Get-Date_Cmdlet $dateStr
Dienstag, 19. Juni 2018 00:00:00

Som du ser ovan använder cmdletar kulturkänslig parsning för att konvertera strängen.

# Define an equivalent function.
function Get-Date_Func {
  param(
    [DateTime] $Date
  )
  process {
    $Date
  }
}

[cultureinfo]::CurrentCulture = 'de-DE'

# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'

Get-Date_Func $dateStr

Avancerade funktioner använder kulturvariant parsning, vilket resulterar i följande fel.

Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error: "String
'19-06-2018' was not recognized as a valid DateTime."

Statiska parametrar

Statiska parametrar är parametrar som alltid är tillgängliga i funktionen. De flesta parametrar i PowerShell-cmdletar och skript är statiska parametrar.

I följande exempel visas deklarationen av en ComputerName-parameter som har följande egenskaper:

  • Det är obligatoriskt (krävs).
  • Den tar indata från pipelinen.
  • Det tar en matris med strängar som indata.
Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [string[]]
    $ComputerName
)

Växla parametrar

Växelparametrar är parametrar som inte har något parametervärde. I stället förmedlar de ett booleskt true-or-false-värde genom sin närvaro eller frånvaro, så att när en växelparameter finns har den ett sant värde och när det saknas har det ett falskt värde.

Parametern RecurseGet-ChildItem för är till exempel en växelparameter.

Om du vill skapa en växelparameter i en funktion anger du switch typen i parameterdefinitionen.

Funktionen kan till exempel ha ett alternativ för att mata ut data som en bytematris:

Param([switch]$AsByteArray)

Växlingsparametrar är enkla att använda och föredras framför booleska parametrar, som har en mindre naturlig syntax för PowerShell.

Om du till exempel vill använda en växelparameter skriver användaren parametern i kommandot .

-IncludeAll

Om du vill använda en boolesk parameter skriver användaren parametern och ett booleskt värde.

-IncludeAll $true

När du skapar växelparametrar väljer du parameternamnet noggrant. Se till att parameternamnet kommunicerar parameterns effekt till användaren. Undvik tvetydiga termer, till exempel Filter eller Maximum som kan innebära att ett värde krävs.

Designöverväganden för switchparameter

  • Växelparametrar bör inte ges standardvärden. De bör alltid vara falska som standard.

  • Växelparametrar undantas som standard från positionsparametrar. Även om andra parametrar är implicit positionella är växlingsparametrarna inte det. Du kan åsidosätta det i parameterattributet, men det förvirrar användarna.

  • Växla parametrar bör utformas så att inställningen flyttar ett kommando från standardfunktionen till ett mindre vanligt eller mer komplicerat läge. Det enklaste beteendet för ett kommando bör vara standardbeteendet som inte kräver användning av växelparametrar.

  • Växelparametrar bör inte vara obligatoriska. Det enda fallet där det är nödvändigt att göra en växelparameter obligatorisk är när det behövs för att särskilja en parameteruppsättning.

  • Du kan uttryckligen ställa in en växel från ett booleskt värde med -MySwitch:$boolValue och i splatting med $params = @{ MySwitch = $boolValue }.

  • Växelparametrar är av typen SwitchParameter, som implicit konverteras till booleskt värde. Parametervariabeln kan användas direkt i ett villkorsuttryck. Exempel:

    if ($MySwitch) { ... }

    Du behöver inte skriva if ($MySwitch.IsPresent) { ... }

Dynamiska parametrar

Dynamiska parametrar är parametrar för en cmdlet, funktion eller ett skript som endast är tillgängliga under vissa förhållanden.

Till exempel har flera provider-cmdletar parametrar som endast är tillgängliga när cmdleten används i providerenheten eller i en viss sökväg till providerenheten. Till exempel är kodningsparametern tillgänglig på Add-Contentcmdletarna , Get-Contentoch Set-Content endast när den används i en filsystemenhet.

Du kan också skapa en parameter som bara visas när en annan parameter används i funktionskommandot eller när en annan parameter har ett visst värde.

Dynamiska parametrar kan vara användbara, men använd dem bara när det behövs, eftersom de kan vara svåra för användarna att identifiera. För att hitta en dynamisk parameter måste användaren vara i providersökvägen, använda parametern ArgumentList för cmdleten Get-Command eller använda parametern Path för Get-Help.

Om du vill skapa en dynamisk parameter för en funktion eller ett skript använder du nyckelordet DynamicParam .

Syntaxen ser ut så här:

dynamicparam {<statement-list>}

I instruktionslistan använder du en if -instruktion för att ange de villkor under vilka parametern är tillgänglig i funktionen.

I följande exempel visas en funktion med standardparametrar med namnet Namn och Sökväg och en valfri dynamisk parameter med namnet KeyCount. Parametern KeyCount finns i parameteruppsättningen ByRegistryPath och har en typ av Int32. KeyCount-parametern är endast tillgänglig i Get-Sample funktionen när värdet för parametern Path börjar med HKLM:, vilket indikerar att den används i HKEY_LOCAL_MACHINE registerenheten.

function Get-Sample {
  [CmdletBinding()]
  Param([string]$Name, [string]$Path)

  DynamicParam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
          ParameterSetName = "ByRegistryPath"
          Mandatory = $false
      }

      $attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
      $attributeCollection.Add($parameterAttribute)

      $dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
        'KeyCount', [Int32], $attributeCollection
      )

      $paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
      $paramDictionary.Add('KeyCount', $dynParam1)
      return $paramDictionary
    }
  }
}

Mer information finns i dokumentationen för typen RuntimeDefinedParameter .

Parametrars attribut

I det här avsnittet beskrivs de attribut som du kan lägga till i funktionsparametrar.

Alla attribut är valfria. Men om du utelämnar attributet CmdletBinding måste funktionen innehålla parameterattributet för att kunna identifieras som en avancerad funktion.

Du kan lägga till ett eller flera attribut i varje parameterdeklaration. Det finns ingen gräns för antalet attribut som du kan lägga till i en parameterdeklaration.

Parameterattribut

Parameterattributet används för att deklarera attributen för funktionsparametrar.

Parameterattributet är valfritt och du kan utelämna det om ingen av parametrarna i dina funktioner behöver attribut. Men för att kunna identifieras som en avancerad funktion, i stället för en enkel funktion, måste en funktion ha antingen attributet CmdletBinding eller parameterattributet eller båda.

Parameterattributet har argument som definierar parameterns egenskaper, till exempel om parametern är obligatorisk eller valfri.

Använd följande syntax för att deklarera parameterattributet , ett argument och ett argumentvärde. Parenteserna som omger argumentet och dess värde måste följa Parameter utan mellanliggande blanksteg.

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

Använd kommatecken för att avgränsa argument inom parenteserna. Använd följande syntax för att deklarera två argument för parameterattributet .

Param(
    [Parameter(Argument1=value1,
    Argument2=value2)]
)

De booleska argumenttyperna för parameterattributet är standardvärdet Falskt när det utelämnas från parameterattributet . Ange argumentvärdet till $true eller visa bara argumentet efter namn. Följande parameterattribut är till exempel likvärdiga.

Param(
    [Parameter(Mandatory=$true)]
)

# Boolean arguments can be defined using this shorthand syntax

Param(
    [Parameter(Mandatory)]
)

Om du använder parameterattributet utan argument, som ett alternativ till att använda attributet CmdletBinding , krävs fortfarande parenteserna som följer attributnamnet.

Param(
    [Parameter()]
    $ParameterName
)

Obligatoriskt argument

Argumentet Mandatory anger att parametern krävs. Om det här argumentet inte anges är parametern valfri.

I följande exempel deklareras parametern ComputerName . Det använder Mandatory argumentet för att göra parametern obligatorisk.

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

Positionsargument

Argumentet Position avgör om parameternamnet krävs när parametern används i ett kommando. När en parameterdeklaration innehåller Position argumentet kan parameternamnet utelämnas och PowerShell identifierar det namnlösa parametervärdet efter dess position, eller ordning, i listan över namnlösa parametervärden i kommandot.

Position Om argumentet inte anges måste parameternamnet, eller ett parameternamnsalias eller förkortning, föregå parametervärdet när parametern används i ett kommando.

Som standard är alla funktionsparametrar positionella. PowerShell tilldelar positionsnummer till parametrar i den ordning som parametrarna deklareras i funktionen. Om du vill inaktivera den här funktionen anger du värdet för PositionalBinding argumentet för attributet CmdletBinding till $False. Argumentet Position har företräde framför värdet för PositionalBinding argumentet för attributet CmdletBinding . Mer information PositionalBinding finns i about_Functions_CmdletBindingAttribute.

Värdet för Position argumentet anges som ett heltal. Ett positionsvärde på 0 representerar den första positionen i kommandot, ett positionsvärde på 1 representerar den andra positionen i kommandot och så vidare.

Om en funktion inte har några positionsparametrar tilldelar PowerShell positioner till varje parameter baserat på i vilken ordning parametrarna deklareras. Men vi rekommenderar att du inte förlitar dig på den här tilldelningen. När du vill att parametrarna ska vara positionella använder du Position argumentet .

I följande exempel deklareras parametern ComputerName . Det använder Position argumentet med värdet 0. -ComputerName När utelämnas från kommandot måste därför dess värde vara det första eller enda namnlösa parametervärdet i kommandot.

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

ParameterSetName-argument

Argumentet ParameterSetName anger parameteruppsättningen som en parameter tillhör. Om ingen parameteruppsättning anges tillhör parametern alla parameteruppsättningar som definierats av funktionen. För att vara unik måste varje parameteruppsättning därför ha minst en parameter som inte är medlem i någon annan parameteruppsättning.

Anteckning

För en cmdlet eller funktion finns det en gräns på 32 parameteruppsättningar.

I följande exempel deklareras en ComputerName-parameter i parameteruppsättningen Computer , en UserName-parameter i parameteruppsättningen User och en sammanfattningsparameter i båda parameteruppsättningarna.

Param(
    [Parameter(Mandatory,
    ParameterSetName="Computer")]
    [string[]]
    $ComputerName,

    [Parameter(Mandatory,
    ParameterSetName="User")]
    [string[]]
    $UserName,

    [Parameter()]
    [switch]
    $Summary
)

Du kan bara ange ett ParameterSetName värde i varje argument och bara ett ParameterSetName argument i varje parameterattribut . Om du vill ange att en parameter visas i fler än en parameteruppsättning lägger du till ytterligare parameterattribut .

I följande exempel läggs parametern Summary uttryckligen till i parameteruppsättningarna Computer och User . Parametern Summary är valfri i parameteruppsättningen Computer och obligatorisk i parameteruppsättningen User .

Param(
    [Parameter(Mandatory,
    ParameterSetName="Computer")]
    [string[]]
    $ComputerName,

    [Parameter(Mandatory,
    ParameterSetName="User")]
    [string[]]
    $UserName,

    [Parameter(ParameterSetName="Computer")]
    [Parameter(Mandatory, ParameterSetName="User")]
    [switch]
    $Summary
)

Mer information om parameteruppsättningar finns i Om parameteruppsättningar.

ValueFromPipeline-argument

Argumentet ValueFromPipeline anger att parametern accepterar indata från ett pipelineobjekt. Ange det här argumentet om funktionen accepterar hela objektet, inte bara en egenskap för objektet.

I följande exempel deklareras en ComputerName-parameter som är obligatorisk och accepterar ett objekt som skickas till funktionen från pipelinen.

Param(
    [Parameter(Mandatory,
    ValueFromPipeline)]
    [string[]]
    $ComputerName
)

ValueFromPipelineByPropertyName-argument

Argumentet ValueFromPipelineByPropertyName anger att parametern accepterar indata från en egenskap för ett pipelineobjekt. Objektegenskapen måste ha samma namn eller alias som parametern .

Om funktionen till exempel har en ComputerName-parameter och det piped-objektet har egenskapen ComputerName , tilldelas värdet för egenskapen ComputerName till funktionens parameter ComputerName .

I följande exempel deklareras en ComputerName-parameter som är obligatorisk och accepterar indata från objektets ComputerName-egenskap som skickas till funktionen via pipelinen.

Param(
    [Parameter(Mandatory,
    ValueFromPipelineByPropertyName)]
    [string[]]
    $ComputerName
)

Anteckning

En typifierad parameter som accepterar pipelineindata (by Value) eller (by PropertyName) möjliggör användning av skriptblock med fördröjd bindning på parametern .

Skriptblocket för fördröjningsbindning körs automatiskt under ParameterBinding. Resultatet är bundet till parametern . Fördröjningsbindning fungerar inte för parametrar som definierats som typ ScriptBlock eller System.Object. Skriptblocket skickas utan att anropas.

Du kan läsa om skriptblock med fördröjningsbindning här about_Script_Blocks.md.

ValueFromRemainingArguments-argument

Argumentet ValueFromRemainingArguments anger att parametern accepterar alla parametervärden i kommandot som inte är tilldelade till andra parametrar i funktionen.

I följande exempel deklareras en värdeparameter som är obligatorisk och en återstående parameter som accepterar alla återstående parametervärden som skickas till funktionen.

function Test-Remainder
{
     param(
         [string]
         [Parameter(Mandatory, Position=0)]
         $Value,
         [string[]]
         [Parameter(Position=1, ValueFromRemainingArguments)]
         $Remaining)
     "Found $($Remaining.Count) elements"
     for ($i = 0; $i -lt $Remaining.Count; $i++)
     {
        "${i}: $($Remaining[$i])"
     }
}
Test-Remainder first one,two
Found 2 elements
0: one
1: two

Anteckning

Före PowerShell 6.2 anslöts samlingen ValueFromRemainingArguments som en enda entitet under index 0.

HelpMessage-argument

Argumentet HelpMessage anger en sträng som innehåller en kort beskrivning av parametern eller dess värde. PowerShell visar det här meddelandet i prompten som visas när ett obligatoriskt parametervärde saknas i ett kommando. Det här argumentet har ingen effekt på valfria parametrar.

I följande exempel deklareras en obligatorisk ComputerName-parameter och ett hjälpmeddelande som förklarar det förväntade parametervärdet.

Om det inte finns någon annan kommentarsbaserad hjälpsyntax för funktionen (till exempel .SYNOPSIS) visas även det här meddelandet i Get-Help utdata.

Param(
    [Parameter(Mandatory,
    HelpMessage="Enter one or more computer names separated by commas.")]
    [string[]]
    $ComputerName
)

Aliasattribut

Aliasattributet upprättar ett alternativt namn för parametern . Det finns ingen gräns för antalet alias som du kan tilldela till en parameter.

I följande exempel visas en parameterdeklaration som lägger till aliaset CN och MachineName i den obligatoriska parametern ComputerName .

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

SupportsWildcards-attribut

Attributet SupportsWildcards används för att ange att parametern accepterar jokerteckenvärden. I följande exempel visas en parameterdeklaration för en obligatorisk Path-parameter som stöder jokerteckenvärden.

Param(
    [Parameter(Mandatory)]
    [SupportsWildcards()]
    [string[]]
    $Path
)

Om du använder det här attributet aktiveras inte stöd för jokertecken automatiskt. Cmdlet-utvecklaren måste implementera koden för att hantera jokerteckenindata. De jokertecken som stöds kan variera beroende på det underliggande API:et eller PowerShell-providern. Mer information finns i about_Wildcards.

Attribut för argumentslutförande

Attributet ArgumentCompletions

Med attributet ArgumentCompletions kan du lägga till tabbifyllningsvärden till en specifik parameter. Ett ArgumentCompletions-attribut måste definieras för varje parameter som behöver tabbslut. Attributet ArgumentCompletions liknar ValidateSet. Båda attributen tar en lista med värden som ska visas när användaren trycker på Tabb efter parameternamnet. Men till skillnad från ValidateSet verifieras inte värdena.

Det här attributet introducerades i PowerShell 6.0.

Mer information finns i about_Functions_Argument_Completion.

ArgumentCompleter-attribut

Med attributet ArgumentCompleter kan du lägga till tabbifyllningsvärden till en specifik parameter. Ett ArgumentCompleter-attribut måste definieras för varje parameter som behöver tabbslut. Precis som DynamicParameters beräknas de tillgängliga värdena vid körning när användaren trycker på Tabb efter parameternamnet.

Mer information finns i about_Functions_Argument_Completion.

Attribut för parameter- och variabelverifiering

Valideringsattributen dirigerar PowerShell för att testa de parametervärden som användare skickar när de anropar den avancerade funktionen. Om parametervärdena inte klarar testet genereras ett fel och funktionen anropas inte. Parametervalidering tillämpas endast på indata och andra värden som standardvärden verifieras inte.

Du kan också använda valideringsattributen för att begränsa de värden som användare kan ange för variabler. När du använder en typkonverterare tillsammans med ett valideringsattribut måste typkonverteraren definieras före attributet.

[int32][AllowNull()] $number = 7

Anteckning

Valideringsattribut kan tillämpas på alla variabler, inte bara parametrar. Du kan definiera validering för valfri variabel i ett skript.

Attributet AllowNull-verifiering

Attributet AllowNull tillåter att värdet för en obligatorisk parameter är $null. I följande exempel deklareras en hashtable ComputerInfo-parameter som kan ha ett null-värde .

Param(
    [Parameter(Mandatory)]
    [AllowNull()]
    [hashtable]
    $ComputerInfo
)

Anteckning

Attributet AllowNull fungerar inte om typkonverteraren är inställd på sträng eftersom strängtypen inte accepterar ett null-värde. Du kan använda attributet AllowEmptyString för det här scenariot.

Valideringsattribut för AllowEmptyString

Attributet AllowEmptyString tillåter att värdet för en obligatorisk parameter är en tom sträng (""). I följande exempel deklareras en ComputerName-parameter som kan ha ett tomt strängvärde.

Param(
    [Parameter(Mandatory)]
    [AllowEmptyString()]
    [string]
    $ComputerName
)

Valideringsattribut för AllowEmptyCollection

Attributet AllowEmptyCollection tillåter att värdet för en obligatorisk parameter är en tom samling @(). I följande exempel deklareras en ComputerName-parameter som kan ha ett tomt samlingsvärde.

Param(
    [Parameter(Mandatory)]
    [AllowEmptyCollection()]
    [string[]]
    $ComputerName
)

Valideringsattribut för ValidateCount

Attributet ValidateCount anger det lägsta och högsta antalet parametervärden som en parameter accepterar. PowerShell genererar ett fel om antalet parametervärden i kommandot som anropar funktionen ligger utanför det intervallet.

Följande parameterdeklaration skapar en ComputerName-parameter som tar ett till fem parametervärden.

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

Valideringsattribut för ValidateLength

Attributet ValidateLength anger det lägsta och högsta antalet tecken i en parameter eller variabel. PowerShell genererar ett fel om längden på ett värde som angetts för en parameter eller en variabel ligger utanför intervallet.

I följande exempel måste varje datornamn ha ett till tio tecken.

Param(
    [Parameter(Mandatory)]
    [ValidateLength(1,10)]
    [string[]]
    $ComputerName
)

I följande exempel måste värdet för variabeln $number vara minst ett tecken långt och högst tio tecken.

[Int32][ValidateLength(1,10)]$number = '01'

Anteckning

I det här exemplet omsluts värdet för 01 med enkla citattecken. Attributet ValidateLength accepterar inte ett tal utan att vara omslutet med citattecken.

ValidPattern-valideringsattribut

Attributet ValidatePattern anger ett reguljärt uttryck som jämförs med parametern eller variabelvärdet. PowerShell genererar ett fel om värdet inte matchar mönstret för reguljära uttryck.

I följande exempel måste parametervärdet innehålla ett fyrsiffrigt tal och varje siffra måste vara ett tal noll till nio.

Param(
    [Parameter(Mandatory)]
    [ValidatePattern("[0-9][0-9][0-9][0-9]")]
    [string[]]
    $ComputerName
)

I följande exempel måste värdet för variabeln $number vara exakt ett fyrsiffrigt tal, och varje siffra måste vara ett tal noll till nio.

[Int32][ValidatePattern("^[0-9][0-9][0-9][0-9]$")]$number = 1111

Valideringsattribut för ValidateRange

Attributet ValidateRange anger ett numeriskt intervall eller ett ValidateRangeKind-uppräkningsvärde för varje parameter eller variabelvärde. PowerShell genererar ett fel om något värde ligger utanför intervallet.

ValidateRangeKind-uppräkningen tillåter följande värden:

  • Positivt – ett tal som är större än noll.
  • Negativ – ett tal som är mindre än noll.
  • NonPositive – ett tal som är mindre än eller lika med noll.
  • NonNegative – Ett tal som är större än eller lika med noll.

I följande exempel måste värdet för parametern Attempts vara mellan noll och tio.

Param(
    [Parameter(Mandatory)]
    [ValidateRange(0,10)]
    [Int]
    $Attempts
)

I följande exempel måste värdet för variabeln $number vara mellan noll och tio.

[Int32][ValidateRange(0,10)]$number = 5

I följande exempel måste värdet för variabeln $number vara större än noll.

[Int32][ValidateRange("Positive")]$number = 1

ValidScript-valideringsattribut

Attributet ValidateScript anger ett skript som används för att verifiera en parameter eller ett variabelvärde. PowerShell skickar värdet till skriptet och genererar ett fel om skriptet returnerar $false eller om skriptet utlöser ett undantag.

När du använder attributet ValidateScript mappas värdet som verifieras till variabeln $_ . Du kan använda variabeln $_ för att referera till värdet i skriptet.

I följande exempel måste värdet för parametern EventDate vara större än eller lika med det aktuella datumet.

Param(
    [Parameter(Mandatory)]
    [ValidateScript({$_ -ge (Get-Date)})]
    [DateTime]
    $EventDate
)

I följande exempel måste värdet för variabeln $date vara större än eller lika med aktuellt datum och tid.

[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)

Anteckning

Om du använder ValidateScript kan du inte skicka ett $null värde till parametern. När du skickar ett null-värde kan ValidateScript inte verifiera argumentet.

Attributet ValidateSet

Attributet ValidateSet anger en uppsättning giltiga värden för en parameter eller variabel och aktiverar tabbar. PowerShell genererar ett fel om en parameter eller ett variabelvärde inte matchar ett värde i uppsättningen. I följande exempel kan värdet för parametern Detail bara vara Low, Average eller High.

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

I följande exempel måste värdet för variabeln $flavor vara antingen Choklad, Jordgubb eller Vanilj.

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

Verifieringen sker när variabeln tilldelas även i skriptet. Följande resulterar till exempel i ett fel vid körning:

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

$Message = "bye"

Det här exemplet returnerar följande fel vid körning:

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

Använd ValidateSet även aktivera flikexpansion av värden för den parametern. Mer information finns i about_Tab_Expansion.

Dynamiska ValidateSet-värden med hjälp av klasser

Du kan använda en klass för att dynamiskt generera värdena för ValidateSet vid körning. I följande exempel genereras giltiga värden för variabeln $Sound via en klass med namnet SoundNames som kontrollerar tre filsystemsökvägar efter tillgängliga ljudfiler:

Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [string[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
            '/Library/Sounds','~/Library/Sounds'
        $SoundNames = ForEach ($SoundPath in $SoundPaths) {
            If (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [string[]] $SoundNames
    }
}

Klassen [SoundNames] implementeras sedan som ett dynamiskt ValidateSet-värde enligt följande:

Param(
    [ValidateSet([SoundNames])]
    [string]$Sound
)

Anteckning

Klassen IValidateSetValuesGenerator introducerades i PowerShell 6.0

ValidateNotNull-valideringsattribut

Attributet ValidateNotNull anger att parametervärdet inte får vara $null. PowerShell genererar ett fel om parametervärdet är $null.

Attributet ValidateNotNull är utformat för att användas när parametern är valfri och typen är odefinierad eller har en typkonverterare som inte implicit kan konvertera ett null-värde som -objekt. Om du anger en typ som implicit konverterar ett null-värde, till exempel en sträng, konverteras null-värdet till en tom sträng även när attributet ValidateNotNull används. I det här scenariot använder du ValidateNotNullOrEmpty

I följande exempel kan värdet för ID-parametern inte vara $null.

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

ValidNotNullOrEmpty-verifieringsattribut

Attributet ValidateNotNullOrEmpty anger att parametervärdet inte kan vara $null och inte får vara en tom sträng (""). PowerShell genererar ett fel om parametern används i ett funktionsanrop, men dess värde är $null, en tom sträng ("") eller en tom matris @().

Param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string[]]
    $UserName
)

ValidEringsattribut för ValidateDrive

Attributet ValidateDrive anger att parametervärdet måste representera sökvägen, som endast refererar till tillåtna enheter. PowerShell genererar ett fel om parametervärdet refererar till andra enheter än tillåtna. Förekomsten av sökvägen, förutom själva enheten, verifieras inte.

Om du använder relativ sökväg måste den aktuella enheten finnas i listan över tillåtna enheter.

Param(
    [ValidateDrive("C", "D", "Variable", "Function")]
    [string]$Path
)

ValidUserDrive-valideringsattribut

Attributet ValidateUserDrive anger att parametervärdet måste representera sökvägen, som refererar till User enheten. PowerShell genererar ett fel om sökvägen refererar till en annan enhet. Valideringsattributet testar endast förekomsten av enhetsdelen av sökvägen.

Om du använder relativ sökväg måste den aktuella enheten vara User.

function Test-UserDrivePath{
    [OutputType([bool])]
    Param(
      [Parameter(Mandatory, Position=0)][ValidateUserDrive()][string]$Path
      )
    $True
}

Test-UserDrivePath -Path C:\
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.

Du kan definiera User enheten i JEA-sessionskonfigurationer (Just Enough Administration). I det här exemplet skapar vi enheten Användare: .

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH
Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
User               75.76         24.24 FileSystem    C:\Users\ExampleUser
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True

ValidTrustedData-valideringsattribut

Det här attributet lades till i PowerShell 6.1.1.

För närvarande används attributet internt av Själva PowerShell och är inte avsett för extern användning.

Se även