Share via

Om avancerade functions-parametrar

  • Artikel

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 was not recognized as a valid
 DateTime."
At line:13 char:15
+ Get-Date_Func $dateStr
+               ~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Get-Date_Func], ParameterBindingArgumentTransformationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Get-Date_Func

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
)

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=$true)]
    [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. Vi rekommenderar dock att du inte förlitar dig på den här tilldelningen. Använd argumentet när du vill att parametrarna ska vara positionella Position .

I följande exempel deklareras parametern ComputerName . Det använder Position argumentet med värdet 0. -ComputerName När det 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 därför varje parameteruppsättning 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 Parameter för ComputerName i parameteruppsättningen Computer , en UserName-parameter i parameteruppsättningen User och en sammanfattningsparameter i båda parameteruppsättningarna.

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

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

    [Parameter(Mandatory=$false)]
    [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 Sammanfattning uttryckligen till i parameteruppsättningarna Computer och User . Parametern Sammanfattning är valfri i parameteruppsättningen Computer och obligatorisk i parameteruppsättningen User .

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

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

    [Parameter(Mandatory=$false, ParameterSetName="Computer")]
    [Parameter(Mandatory=$true, 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=$true,
    ValueFromPipeline=$true)]
    [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 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 egenskapen ComputerName som skickas till funktionen via pipelinen.

Param(
    [Parameter(Mandatory=$true,
    ValueFromPipelineByPropertyName=$true)]
    [String[]]
    $ComputerName
)

Anteckning

En typad parameter som accepterar pipelineindata (by Value) eller (by PropertyName) möjliggör användning av skriptblock med fördröjningsbindning 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 = $true, 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 enskild 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 påverkar inte 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=$true,
    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 aliasen CN och MachineName i den obligatoriska parametern ComputerName .

Param(
    [Parameter(Mandatory=$true)]
    [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=$true)]
    [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 parameter- och variabelverifiering

Valideringsattribut dirigerar PowerShell för att testa de parametervärden som användarna 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å de angivna 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ändarna 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

AllowNull-valideringsattribut

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=$true)]
    [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 Parameter för ComputerName som kan ha ett tomt strängvärde.

Param(
    [Parameter(Mandatory=$true)]
    [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 Parameter för ComputerName som kan ha ett tomt samlingsvärde.

Param(
    [Parameter(Mandatory=$true)]
    [AllowEmptyCollection()]
    [String[]]
    $ComputerName
)

ValidCount-valideringsattribut

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

Följande parameterdeklaration skapar en Parameter för ComputerName som tar ett till fem parametervärden.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateCount(1,5)]
    [String[]]
    $ComputerName
)

ValidLength-valideringsattribut

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=$true)]
    [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=$true)]
    [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=$true)]
    [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=$true)]
    [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=$true)]
    [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"

Dynamiska validateSet-värden

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
)

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(Mandatory=$false)]
    [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=$true)]
    [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. Sökvägens existens, 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
)

Valideringsattribut för ValidateUserDrive

Attributet ValidateUserDrive anger att parametervärdet måste representera sökvägen, som refererar till User enhet. 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 enhet 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

```powershell
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

True

ValidTrustedData-valideringsattribut

Det här attributet har lagts 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.

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 bara är tillgängliga när cmdleten används i providerenheten eller i en viss sökväg till providerenheten. Till exempel är parametern Encoding endast tillgänglig på Add-Contentcmdletarna , Get-Contentoch Set-Content när den används på 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. Om du vill 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 Get-HelpPath för .

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.

Använd cmdleten New-Object för att skapa ett System.Management.Automation.RuntimeDefinedParameter-objekt för att representera parametern och ange dess namn.

Du kan använda ett New-Object kommando för att skapa ett System.Management.Automation.ParameterAttribute-objekt som representerar attribut för parametern, till exempel Obligatorisk,Position eller ValueFromPipeline eller dess parameteruppsättning.

I följande exempel visas en exempelfunktion med standardparametrar med namnet Namn och Sökväg och en valfri dynamisk parameter med namnet DP1. Parametern DP1 finns i parameteruppsättningen PSet1 och har en typ av Int32. Parametern DP1 ä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:"))
    {
      $attributes = New-Object -Type `
        System.Management.Automation.ParameterAttribute
      $attributes.ParameterSetName = "PSet1"
      $attributes.Mandatory = $false
      $attributeCollection = New-Object `
        -Type System.Collections.ObjectModel.Collection[System.Attribute]
      $attributeCollection.Add($attributes)

      $dynParam1 = New-Object -Type `
        System.Management.Automation.RuntimeDefinedParameter("DP1", [Int32],
          $attributeCollection)

      $paramDictionary = New-Object `
        -Type System.Management.Automation.RuntimeDefinedParameterDictionary
      $paramDictionary.Add("DP1", $dynParam1)
      return $paramDictionary
    }
  }
}

Mer information finns i RuntimeDefinedParameter.

Växla parametrar

Växelparametrar är parametrar utan parametervärde. De är bara effektiva när de används och har bara en effekt.

Parametern NoProfile för powershell.exe är till exempel en växelparameter.

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

Exempel:

Param([Switch]<ParameterName>)

Eller så kan du använda en annan metod:

Param(
    [Parameter(Mandatory=$false)]
    [Switch]
    $<ParameterName>
)

Växelparametrar är enkla att använda och föredras framför booleska parametrar, som har en svårare syntax.

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 förmedlar effekten av parametern till användaren. Undvik tvetydiga termer, till exempel Filter eller Maximum som kan innebära att ett värde krävs.

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.

Om du vill lägga till ett ArgumentCompleter-attribut måste du definiera ett skriptblock som bestämmer värdena. Skriptblocket måste ha följande parametrar i den ordning som anges nedan. Parameternamnen spelar ingen roll eftersom värdena anges positionmässigt.

Syntaxen ser ut så här:

Param(
    [Parameter(Mandatory)]
    [ArgumentCompleter({
        param ( $commandName,
                $parameterName,
                $wordToComplete,
                $commandAst,
                $fakeBoundParameters )
        # Perform calculation of tab completed values here.
    })]
)

ArgumentCompleter-skriptblock

Skriptblockparametrarna anges till följande värden:

  • $commandName (Position 0) – Den här parametern är inställd på namnet på det kommando som skriptblocket tillhandahåller tabbifyllning för.
  • $parameterName (Position 1) – Den här parametern är inställd på den parameter vars värde kräver tabbifyllning.
  • $wordToComplete (Position 2) – Den här parametern är inställd på det värde som användaren har angett innan de trycker på Tabb. Skriptblocket bör använda det här värdet för att fastställa tabbifyllningsvärden.
  • $commandAst (Position 3) – Den här parametern är inställd på AST (Abstract Syntax Tree) för den aktuella indataraden. Mer information finns i Ast-klass.
  • $fakeBoundParameters (Position 4) – Den här parametern är inställd på en hash-tabell som innehåller $PSBoundParameters för cmdleten innan användaren tryckte på Tabb. Mer information finns i about_Automatic_Variables.

Skriptblocket ArgumentCompleter måste avregistrera värdena med pipelinen, till exempel ForEach-Object, Where-Objecteller en annan lämplig metod. Om du returnerar en matris med värden behandlar PowerShell hela matrisen som ett slutförandevärde för en flik.

I följande exempel läggs tabbifyllning till i parametern Value . Om endast värdeparametern anges visas alla möjliga värden eller argument för Värde. När parametern Type anges visar parametern Value endast möjliga värden för den typen.

Dessutom ser operatorn -like till att endast Apple returneras om användaren skriver följande kommando och använder tabbifyllning.

Test-ArgumentCompleter -Type Fruits -Value A

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,
        [Parameter(Mandatory=$true)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )

            $possibleValues = @{
                Fruits = @('Apple', 'Orange', 'Banana')
                Vegetables = @('Tomato', 'Squash', 'Corn')
            }
            if ($fakeBoundParameters.ContainsKey('Type'))
            {
                $possibleValues[$fakeBoundParameters.Type] | Where-Object {
                    $_ -like "$wordToComplete*"
                }
            }
            else
            {
                $possibleValues.Values | ForEach-Object {$_}
            }
        } )]
        $Value
      )
}

Se även

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute