About Functions Advanced Parameters (Svenska)

• 10/27/2020
• 20 minutes to read
• • S
  • s
  • s
  • c
  • g

Short description

Explains how to add parameters to advanced functions.,

lång beskrivning

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

de parametrar som du lägger till i din funktion är tillgängliga för användare utöver de vanliga parametrar som PowerShell automatiskt lägger till i alla cmdlets och Advanced funktioner. För mer information om PowerShell commonparameters, se about_CommonParameters.

börjar i PowerShell 3.,0, Du kan använda splatting med @Args för att representera parametrarna i ett kommando. Splatting gäller på enkla och avanceradefunktioner. Mer information finns i about_Functions andabout_Splatting.

typkonvertering av parametervärden

När du levererar strängar som argument till parametrar som förväntar sig en annantyp konverterar PowerShell implicit strängarna till parametermåltypen.Avancerade funktioner utför kultur-invariant tolkning av parametervärden.

däremot utförs en kulturkänslig konvertering under parameterbindning för kompilerade cmdlets.,

i det här exemplet skapar vi en cmdlet och en scriptfunktion som tar en – parameter. Den nuvarande kulturen ändras för att använda tyska inställningar.Ett tyskt formaterat datum skickas till parametern.

Dienstag, 19. Juni 2018 00:00:00

som visas ovan använder cmdlets kulturkänslig tolkning för att konvertera strängen.

avancerade funktioner använder culture-invariant parsing, vilket resulterar iföljande fel.

statiska parametrar

statiska parametrar är parametrar som alltid är tillgängliga i funktionen.,De flesta parametrar i PowerShell cmdlets och skript är statiska parametrar.

följande exempel visar deklarationen för en datornamnparameter som har följande egenskaper:

• Det är obligatoriskt (obligatoriskt).
• Det tar inmatning från rörledningen.
• Det tar en rad strängar som ingång.

Param( ] $ComputerName)

attribut för parametrar

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

alla attribut är valfria., Men om du utelämnar CmdletBindingattribute, måste funktionen innehålla Parameterattributet för att 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 parameterdeclaration.

Parameterattribut

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

Parameterattributet är valfritt, och du kan utelämna det om ingen avparametrarna för dina funktioner behöver attribut., Men för att bli erkänd som envancerad funktion, snarare än en enkel funktion, måste en funktion ha antingen CmdletBinding-attributet 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. De parenteser som omsluter argumentet och dess värdemåste följa Parameter utan mellanliggande utrymme.,

Param( $ParameterName)

använd kommatecken för att skilja argument inom parentes. Använd följande syntax för att förklara två argument för Parameterattributet.

Param( )

de booleska argumenttyperna för Parameterattributet som standard för Falsknär de utelämnats från Parameterattributet. Ange argumentvärdet till$true eller bara lista argumentet med namn. Till exempel, följandeparameter attribut är likvärdiga.,

om du använder Parameterattributet utan argument, som ett alternativ till att använda attributet CmdletBinding, krävs fortfarande de parenteser som följer attributets namn.

Param( $ParameterName)

obligatoriskt argument

argumentetMandatory indikerar att parametern krävs. Om dettaargument inte anges är parametern valfri.

följande exempel förklarar parametern datornamn. Den använder argumentetMandatory för att göra parametern obligatorisk.,

Param( ] $ComputerName)

positionsargument

argumentetPosition avgör om parameternamnet krävs närparametern används i ett kommando. När en parameterdeklaration innehåller argumentetPosition kan parameternamnet utelämnas och Powershellidentifierar det namnlösa parametervärdet med dess position eller ordning i listan över namnlösa parametervärden i kommandot.,

om argumentetPosition inte anges måste parameternamnet eller ett parametername-alias eller förkortning föregå parametervärdet närparametern används i ett kommando.

som standard är alla funktionsparametrar positionerade. PowerShell tilldelar positionnummer till parametrar i den ordning som parametrarna deklareras ifunktion. För att inaktivera den här funktionen anger du värdet förPositionalBindingargumentet för CmdletBinding-attributet till$False., ArgumentetPositionhar företräde framför värdet för argumentetPositionalBinding för cmdletbinding-attributet. Mer information finns i PositionalBindingI about_Functions_CmdletBindingAttribute.

värdet för argumentetPosition anges som ett heltal. En positionvärde på 0 representerar den första positionen i kommandot, ett positionsvärdeav 1 representerar den andra positionen i kommandot och så vidare.,

om en funktion inte har några positionsparametrar, tilldelar PowerShell positioner tillvarje parameter baserat på den ordning i vilken parametrarna deklareras.Men som en bästa praxis, lita inte på detta uppdrag. Använd argumentet Position när du vill attparametrar ska vara positionella.

följande exempel förklarar parametern datornamn. Den använder argumentetPosition med ett värde på 0. Som ett resultat, när -ComputerName isomitted från kommandot, dess värde måste vara den första eller endast namnlösa parametervalue i kommandot.,

Param( ] $ComputerName)

ParameterSetName argument

argumentet ParameterSetName anger den parameter som aparameter tillhör. Om ingen parameterinställning anges hör parametern tillalla parameterinställningar som definieras av funktionen. För att vara unik måste eachparameter set ha minst en parameter som inte är medlem i någon annanparameter-uppsättning.

följande exempel förklarar en Datornameparameter i parameteruppsättningen Computer, en Användarnameparameter i parameteruppsättningen User och parameteruppsättningen aSummary i båda parameteruppsättningarna.

Du kan bara ange ettParameterSetName – värde i varje argument och endast ettParameterSetName – argument i varje Parameterattribut. För att indikera att aparameter visas i mer än en parameterinställning, Lägg till ytterligare Parameterattributes.,

i följande exempel läggs Sammanfattningsparametern uttryckligen till parameteruppsättningarnaComputeroch User. Parametern sammanfattning är valfri i parameteruppsättningenComputer och obligatorisk i parameteruppsättningenUser.

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

ValueFromPipeline argument

argumentetValueFromPipeline indikerar att parametern accepterar inputfrom ett rörledningsobjekt., Ange detta argument om funktionen accepterarentire-objekt, inte bara en egenskap hos objektet.

följande exempel förklarar en Datornamnsparameter som är mandatoryoch accepterar ett objekt som har överförts till funktionen från rörledningen.

Param( ] $ComputerName)

ValueFromPipelineByPropertyName argument

argumentetValueFromPipelineByPropertyName indikerar att parameteraccepts matas in från en egenskap hos ett rörledningsobjekt. Objektegenskapen måste ha samma namn eller alias som parametern.,

om funktionen till exempel har en Datornameparameter och pipedobject har en Datornamegenskap tilldelas värdet för Datornameproperty till funktionens Datornameparameter.

följande exempel förklarar en Datornameparameter som är mandatoryoch accepterar inmatning från objektets Datornamegenskap som har överförts tillfunktionen genom rörledningen.,

Param( ] $ComputerName)

ValueFromRemainingArguments argument

argumentetValueFromRemainingArguments indikerar att parametern accepteralla parameterns värden i kommandot som inte är tilldelade till andraparametrar för funktionen.

följande exempel anger en Värdeparameter som är obligatorisk och aRemaining parameter som accepterar alla återstående parametervärden som skickas in till funktionen.

Found 2 elements0: one1: two

HelpMessage argument

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

följande exempel förklarar en obligatorisk dataparameter och ahelp-meddelande som förklarar det förväntade parametervärdet.,

om det inte finns någon annan kommentarbaserad hjälpsyntaxför funktionen (till exempel .SYNOPSIS) visas det här meddelandet också iGet-Help -utmatningen.

Param( ] $ComputerName)

Aliasattribut

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

följande exempel visar en parameterdeklaration som lägger till CN-ochmachinename-alias till den obligatoriska parametern ComputerName.,

Param( ] $ComputerName)

supportswildcards attribute

attributet SupportsWildcards används för att indikera att parameteraccepts wildcard-värden. Följande exempel visar en parameterdeklarationför en obligatorisk Sökvägsparameter som stöder jokervärden.

Param( ] $Path)

med det här attributet aktiveras inte wildcard-stöd automatiskt. Cmdletdeveloper måste implementera koden för att hantera jokertecken ingång. Wildcardssupported kan variera beroende på den underliggande API-eller PowerShell-leverantören. Formore information, se about_Wildcards.,

Parameter-och variabelvalideringsattribut

Valideringsattribut direkt PowerShell för att testa de parametervärden som userssubmit använder när de anropar advanced-funktionen. Om parametervärdena misslyckas MedTest genereras ett fel och funktionen anropas inte. Parameterveridering tillämpas endast på den ingång som tillhandahålls och andra värden som standardvärden valideras inte.

Du kan också använda valideringsattributen för att begränsa de värden somanvändare kan ange för variabler., När du använder en typomvandlare tillsammans med attributet avalidation måste typomvandlaren definieras före attributet.

 $number = 7

attributet AllowNull validation

attributet AllowNull tillåter värdet för en obligatorisk parameter att vara$null. Följande exempel förklarar en hashtable ComputerInfo parameterthat kan ha ett null-värde.

Param( $ComputerInfo)

AllowEmptyString validation attribute

attributet AllowEmptyString tillåter värdet för en obligatorisk parameter att vara en tom sträng (""). Följande exempel förklarar en Datornameparameter som kan ha ett tomt strängvärde.

Param( $ComputerName)

AllowEmptyCollection validation attribute

attributet AllowEmptyCollection tillåter värdet för en mandatoryparameter att vara en tom samling@()., I följande exempel förklaras aComputerName-parameter som kan ha ett tomt insamlingsvärde.

Param( ] $ComputerName)

ValidateCount validation attribute

attributet ValidateCount specificerar det lägsta och högsta antalparameter-värden som en parameter accepterar. PowerShell genererar ett fel omantal parametervärden i kommandot som anropar funktionen är utom räckhåll.

följande parameterdeklaration skapar en Datornameparameter som tar ett till fem parametervärden.,

Param( ] $ComputerName)

validatelength validation attribute

attributet ValidateLength specificerar det lägsta och högsta antalet characters i en parameter eller ett variabelvärde. PowerShell genererar ett fel omlängden på ett värde som anges 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( ] $ComputerName)

i följande exempel måste värdet för variabeln$number vara ett minimumav ett tecken i längd och högst tio tecken.,

$number = '01'

ValidatePattern validation attribute

attributet ValidatePattern specificerar ett reguljärt uttryck som ärjämfört med parametern eller variabelvärdet. PowerShell genererar ett fel omvärdet matchar inte det reguljära uttrycksmönstret.,

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

Param( ")] ] $ComputerName)

i följande exempel måste värdet på variabeln$number vara exakt fyra siffror, och varje siffra måste vara ett nummer noll till nio.

$")]$number = 1111

validaterange valideringsattribut

validaterange-attributet anger ett numeriskt intervall eller avalidaterangekind-enumvärde för varje parameter eller variabelvärde.PowerShell genererar ett fel om något värde ligger utanför det intervallet.,

ValidateRangeKind enum tillåter följande värden:

• positiv – ett tal större än noll.
• negativ – ett tal mindre än noll.
• NonPositive – ett tal 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 på Försöksparametern varamellan noll och tio.

Param( $Attempts)

i följande exempel måste värdet för variabeln$number vara mellanzero och ten.,

$number = 5

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

$number = 1

validatescript valideringsattribut

validatescript-attributet anger ett skript som används för att validera aparameter eller variabelvärde. PowerShell rör värdet manus, andgenerates ett fel om skriptet returnerar $false eller om skriptet kastar anexception.,

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

i följande exempel måste värdet på eventdate-parametern varastörre än eller lika med det aktuella datumet.

Param( $EventDate)

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

$date = (Get-Date)

ValidateSet attribute

attributet ValidateSet specificerar en uppsättning giltiga värden för en parameterellervariabel och aktiverar flikkomplettering. PowerShell genererar ett fel om aparameter eller variabelvärde inte matchar ett värde i uppsättningen. I följandeexempel kan värdet på Detaljparametern endast vara låg, genomsnittlig ellerhög.,

Param( ] $Detail)

i följande exempel måste värdet på variabeln$flavor vara antingen choklad, jordgubbe eller vanilj.

$flavor = "Strawberry"

valideringen sker när variabeln tilldelas även inom thescript. Till exempel resulterar följande i ett fel vid körning:

Param( $Message)$Message = "bye"

dynamiska validateSet värden

Du kan använda en klass för att dynamiskt generera värdena för ValidateSetat runtime., I följande exempel, giltiga värden för variabeln$Sound genereras via en Klass som heter SoundNames som kontrollerar threefilesystem vägar för tillgängliga ljudfiler:

klass sedan genomförs som en dynamisk ValidateSet valueas på följande sätt:

Param( )] $Sound)

ValidateNotNull validering attribut

ValidateNotNull attributet anger att värdet för parametern kan inte vara$null. PowerShell genererar ett fel om parametervärdet är $null.,

attributet ValidateNotNull är utformat för att användas när parametern isoptional och typen är odefinierad eller har en typomvandlare som enkelt kan konvertera ett null-värde som objekt. Om du anger en typ somsom implicit konverterar ett null-värde som en sträng konverteras null-värdet till en tom sträng även när du använder ValidateNotNullattribute. För detta scenario använd ValidateNotNullOrEmpty

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

Param( $ID)

ValidateNotNullOrEmpty validation attribute

attributet ValidateNotNullOrEmpty anger att parametern valuecan inte kan vara$null och kan inte vara en tom sträng (""). PowerShell genererar anerror om parametern används i ett funktionssamtal, men dess värde är $null, anempty string ("") eller en tom array@().,

Param( ] $UserName)

Validedrive valideringsattribut

attributet Validedrive anger att parametervärdet mustrepresent sökvägen, som endast avser tillåtna enheter. PowerShellgenerates ett fel om parametervärdet avser andra enheter än detillåten. Förekomsten av vägen, förutom själva enheten, är inte verifierad.

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

Param( $Path)

ValidateUserDrive valideringsattribut

attributet ValidateUserDrive anger att parametervärdet måsterepresentera sökvägen, som hänvisar tillUser enhet. PowerShell genererar anerror om sökvägen refererar till en annan enhet. Valideringsattributet baratester för förekomsten av kördelen av sökvägen.

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

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The pathargument 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'. Cannotfind drive. A drive with the name 'User' does not exist.

Du kan definiera User kör i just Enough Administration (JEA) sessionconfigurations. I det här exemplet skapar vi användaren: drive.

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH

True

ValidateTrustedData validation attribute

det här attributet lades till i PowerShell 6.1.1.

vid denna tidpunkt används attributet internt av PowerShell själv och är inteavsedd för extern användning.,

dynamiska parametrar

dynamiska parametrar är parametrar för en cmdlet, funktion eller skript som endast ärtillgängliga under vissa förutsättningar.

till exempel, flera leverantör cmdlets har parametrar som endast är tillgängliga när cmdlet används i provider drive, eller i en viss väg avprovider drive. Kodningsparametern är till exempel tillgänglig påAdd-Content, Get-Content och Set-Content cmdlets endast när den används Ina-filsystemenheten.,

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 endast när det behövs, eftersomde kan vara svårt för användare att upptäcka. För att hitta en dynamisk parameter måste användaren vara i leverantörssökvägen, använd Argumentlistparametern förGet-Command cmdlet eller använd Sökvägsparametern förGet-Help.

för att skapa en dynamisk parameter för en funktion eller ett skript, använd nyckelordetDynamicParam.,

syntaxen är som följer:

DynamicParam {<statement-list>}

använd en If – sats för att ange de villkor under vilka parametern är tillgänglig i funktionen.

användNew-Object cmdlet för att skapa aSystem.Förvaltning.Automation.RuntimeDefinedParameter objekt att representeraparametern och ange dess namn.

Du kan använda kommandotNew-Object för att skapa asystem.Förvaltning.Automation.,ParameterAttribute objekt att representeraattributes av parametern, såsom obligatorisk, Position, orValueFromPipeline eller dess parameterinställning.

följande exempel visar en provfunktion med standardparametrar namnnamn och sökväg och en valfri dynamisk parameter som heter DP1. Parametern DP1 finns i parametern PSet1 och har en typ av Int32.,DP1-parametern är endast tillgänglig i funktionen Get-Sample när värdet för Sökvägsparametern börjar med HKLM:, vilket indikerar att den används i registret HKEY_LOCAL_MACHINE.

För mer information, seeRuntimeDefinedParameter.

Switchparametrar

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

till exempel noprofile parametern för powershell.exe är en switchparameter.,

för att skapa en omkopplingsparameter i en funktion, angeSwitch – typen iparameterdefinitionen.

till exempel:

Param(<ParameterName>)

eller, du kan använda en annan metod:

Param( $<ParameterName>)

Switchparametrar är lätta att använda och föredras över Booleska parametrar,som har en svårare syntax.

om du till exempel vill använda en omkopplingsparameter skriver användaren parametern in thecommand.

-IncludeAll

för att använda en boolesk parameter skriver användaren parametern och ett booleskt värde.,

-IncludeAll:$true

När du skapar switchparametrar väljer du parameternamnet noggrant. Var säkeratt parameternamnet kommunicerar effekten av parametern till användaren.Undvik tvetydiga termer, såsom Filter eller Maximum som kan innebära avalue krävs.

ArgumentCompleter attribute

ArgumentCompleter attribute tillåter dig att lägga till tabellkompletteringsvärden till en specifik parameter. Ett ArgumentCompleter-attribut måste definieras förvarje parameter som behöver flikkomplettering., I likhet med DynamicParameters beräknas detillgängliga värdena vid körning när användaren trycker på Tabafter parameternamnet.

om du vill lägga till ett ArgumentCompleter-attribut måste du definiera ett scriptblock som bestämmer värdena. Scriptblocket måste ta följandeparametrar i den ordning som anges nedan. Parameterns namn spelar ingen roll somvärdena tillhandahålls positionellt.,

syntaxen är som följer:

ArgumentCompleter script block

scriptblockparametrarna är inställda på följande värden:

• $commandName (Position 0) – denna parameter är inställd på namnet påkommandot för vilket scriptblocket tillhandahåller flikkomplettering.
• $parameterName (Position 1) – Denna parameter är inställd på parametern whosevalue kräver flikkomplettering.
• $wordToComplete (Position 2) – Denna parameter är inställd på att värdera användaren har tillhandahållit innan de tryckte på flik., Ditt scriptblock ska användadetta värde för att bestämma tabellkompletteringsvärden.
• $commandAst (Position 3) – Denna parameter är inställd på den abstrakta SyntaxTree (AST) för den aktuella inmatningsraden. För mer information, seast klass.
• $fakeBoundParameters (Position 4) – Denna parameter är inställd på en hashtableinnehåller$PSBoundParameters för cmdlet, innan användaren pressadetab. För mer information, seaabout_automatic_variables.,

ArgumentCompleter scriptblocket måste avrulla värdena med hjälp av thepipeline, till exempelForEach-Object,Where-Object, eller en annan lämplig metod.Att returnera en rad värden gör att PowerShell behandlar hela arrayen asone tab completion value.

följande exempel lägger till flikkomplettering till Värdeparametern. Om endastvärdeparametern anges visas alla möjliga värden eller argument förvärde. När typparametern är angiven visar parametern value endast de möjliga värdena för den typen.,

dessutom-like operatören ser till att om användaren skriver följandecommand och använder Flikkomplettering, endast Apple returneras.

Test-ArgumentCompleter -Type Fruits -Value A

Se även

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_functions_outputtypeattribute