About Functions Advanced Parameters (Dansk)

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

Short description

Explains how to add parameters to advanced functions.,

Lang beskrivelse

Du kan tilføje parametre til de avancerede funktioner, du skriver, og brugeparameterattributter og argumenter for at begrænse parameterværdierne, som funktionsbrugere indsender med parameteren.

de parametre, du tilføjer til din funktion, er tilgængelige for brugerne i tillæg til de fælles parametre, som Po .ershell automatisk tilføjer til alle cmdlets og avancerede funktioner. For mere information om PowerShell commonparameters, se about_CommonParameters.

begynder i Po .ershell 3.,0, kan du bruge splatting med @Args til at repræsentereparametrene i en kommando. Splatting er gyldig på simple og advancedfunctions. For mere information, se about_Functions and about_splatting.

Type konvertering af parameterværdier

Når du leverer strenge som argumenter til parametre, der forventer en anden type, konverterer Po .ershell implicit strengene til parametermåltypen.Avancerede funktioner udfører kultur-invariant parsing af parameterværdier.

derimod udføres en kulturfølsom konvertering under parameterbinding for kompilerede cmdlets.,

i dette eksempel opretter vi en cmdlet og en scriptfunktion, der tager en parameter. Den aktuelle kultur ændres til at bruge tyske indstillinger.En tysk-formateret dato overføres til parameteren.

Dienstag, 19. Juni 2018 00:00:00

som vist ovenfor bruger cmdlets kulturfølsom parsing til at konvertere strengen.avancerede funktioner bruger Kultur-invariant parsing, hvilket resulterer ifølgende fejl.

statiske parametre

statiske parametre er parametre, der altid er tilgængelige i funktionen.,De fleste parametre i Po .ershell cmdlets og scripts er statiske parametre.

følgende eksempel viser erklæringen af en Computernavn parameterder har følgende egenskaber:

• det er obligatorisk (påkrævet).
• det tager input fra rørledningen.
• det tager en række strenge som input.

Param( ] $ComputerName)

attributter for parametre

dette afsnit beskriver de attributter, som du kan tilføje til funktionsparametre.

alle attributter er valgfrie., Men hvis du udelader Cmdletbindingattribut, så for at blive anerkendt som en avanceret funktion, skal funktioneninkludere Parameterattributten.

Du kan tilføje en eller flere attributter i hver parameterdeklaration. Der er ingen grænse for antallet af attributter, som du kan tilføje til en parameterdeklaration.

Parameterattribut

Parameterattributten bruges til at erklære attributterne for functionparameters.parameterattributten er valgfri, og du kan udelade den, hvis ingen af parametrene for dine funktioner har brug for attributter., Men for at blive anerkendt som en avanceret funktion, snarere end en simpel funktion, skal en funktion enten have CmdletBinding-attributten eller Parameterattributten eller begge dele.

Parameterattributten har argumenter, der definerer egenskaberne afparameteren, såsom om parameteren er obligatorisk eller valgfri.

Brug følgende syntaks til at erklære Parameterattributten, et argument og en argumentværdi. Parenteserne, der omslutter argumentet og dets værdiskal følge Parameter uden mellemliggende rum.,

Param( $ParameterName)

brug kommaer til at adskille argumenter i parenteserne. Brug følgendesynta.til at erklære to argumenter for Parameterattributten.

Param( )

de boolske argument typer af parameteren attribut standard til Falsewhhen udeladt fra parameteren attribut. Indstil argumentværdien til$true eller bare liste argumentet ved navn. For eksempel følgendeparameter attributter er ækvivalente.,

Hvis du bruger Parameterattributten uden argumenter, som et alternativ tilved hjælp af CmdletBinding-attributten, er parenteserne, der følger attributnavnet, stadig påkrævet.

Param( $ParameterName)

Obligatoriske argument

Mandatory argument angiver, at parameteren er påkrævet. Hvis dette argument ikke er angivet, er parameteren valgfri.

følgende eksempel erklærer Computernavn parameter. Det brugerMandatory argument for at gøre parameteren obligatorisk.,

Param( ] $ComputerName)

Position argument

Position argument bestemmer, om parameteren navn er påkrævet whenthe parameter bruges i en kommando. Når en parameterdeklaration indeholder argumentetPosition, kan parameternavnet udelades, og Po .ershellidentificerer den navngivne parameterværdi ved sin position eller rækkefølge i listen af navngivne parameterværdier i kommandoen.,

hvis argumentetPosition ikke er angivet, skal parameternavnet eller et parameternavn eller forkortelse gå forud for parameterværdien, når parameteren bruges i en kommando.

som standard er alle funktionsparametre positionelle. Po .ershell tildeler positiontal til parametre i den rækkefølge, hvor parametrene er angivet ifunktion. For at deaktivere denne funktion skal du indstille værdien afPositionalBindingargumentet for CmdletBinding-attributten til$False., ArgumentetPositionhar forrang for værdien af argumentet PositionalBinding for CmdletBinding-attributten. For mere information, se PositionalBindingi about_Functions_CmdletBindingAttribute.

værdien afPosition argumentet er angivet som et heltal. En positionværdi på 0 repræsenterer den første position i kommandoen, en positionværdi af 1 repræsenterer den anden position i kommandoen og så videre.,

hvis en funktion ikke har nogen positionsparametre, tildeler Po .ershell positioner tilhver parameter baseret på den rækkefølge, hvor parametrene er erklæret.Men, som en bedste praksis, ikke stole på denne opgave. Når du vilparametre skal være positionelle, skal du brugePosition argument.

følgende eksempel erklærer Computernavn parameter. Det brugerPosition argument med en værdi på 0. Som et resultat, når -ComputerName isomitted fra kommando, skal dens værdi være den første eller eneste unavngivne parameterværdi i kommandoen.,

Param( ] $ComputerName)

ParameterSetName argument

ParameterSetName argument angiver den parameter, som aparameter tilhører. Hvis der ikke er angivet noget parametersæt, tilhører parameterenalle parametersæt defineret af funktionen. Derfor, for at være unik, eachparameter sæt skal have mindst én parameter, der ikke er medlem af nogen otherparameter sæt.

følgende eksempel erklærer et Computernavn parameter i Computerparameter sæt, et Brugernavn parameter i User parameter sæt, og aSummary parameter i både parametersæt.

Du kan kun angive en ParameterSetName værdi i det enkelte argument, og kun enParameterSetName argument i hvert Parameter attribut. For at indikere, at aparameter vises i mere end et parametersæt, skal du tilføje yderligere Parameterattributter.,

følgende eksempel tilføjer eksplicit parameteren resum.til parametersætteneComputerog User. Parameteren resum is er valgfri i parametersættet Computer og obligatorisk i parametersættet User.

For mere information om parametersæt, se om parametersæt.

ValueFromPipeline argument

ValueFromPipeline argument angiver, at parameteren accepterer inputfrom en rørledning objekt., Angiv dette argument, hvis funktionen acceptererentire objekt, ikke kun en egenskab af objektet.

følgende eksempel erklærer en Computernavn parameter, der er obligatoriskog accepterer et objekt, der er gået til funktionen fra rørledningen.

Param( ] $ComputerName)

ValueFromPipelineByPropertyName argument

ValueFromPipelineByPropertyName argument angiver, at parameteraccepts input fra en ejendom af en rørledning objekt. Objektegenskaben skalhar samme navn eller alias som parameteren.,

For eksempel, hvis funktionen har en Computernavn parameter, og pipedobject har et Computernavn ejendom, værdien af ComputerNameproperty henføres til den funktion Computernavn parameter.følgende eksempel erklærer en Computernavn parameter, der er obligatorisk og accepterer input fra objektets Computernavn ejendom, der er gået til funktionen gennem rørledningen.,

Param( ] $ComputerName)

ValueFromRemainingArguments argument

ValueFromRemainingArguments argument angiver, at parameteren acceptsall parameter-værdier i den kommando, der ikke er tildelt otherparameters af funktion.

følgende eksempel erklærer en Værdi parameter, der er obligatorisk og aRemaining parameter, der accepterer alle de resterende parametre thatare forelagt funktion.

Found 2 elements0: one1: two

HelpMessage argument

HelpMessage argument angiver en streng, der indeholder en kort beskrivelseaf parameteren eller dens værdi. Po .ershell viser denne meddelelse i promptder vises, når en obligatorisk parameterværdi mangler fra en kommando. Dette argument har ingen indflydelse på valgfrie parametre.

følgende eksempel erklærer en obligatorisk Computernavn parameter og ahelp besked, der forklarer den forventede parameter værdi.,

Hvis der ikke er nogen anden kommentarbaseret hjælpesynta.til funktionen (for eksempel .SYNOPSIS), vises denne meddelelse også iGet-Help output.

Param( ] $ComputerName)

Alias attribut

Alias attributten etablerer et alternativt navn for parameteren.Der er ingen grænse for antallet af aliaser, som du kan tildele en parameter.

følgende eksempel viser en parameter erklæring, der tilføjer CN andmachinename aliaser til den obligatoriske ComputerName parameter.,

Param( ] $ComputerName)

SupportsWildcards attribut

SupportsWildcards attribut anvendes til at angive, at parameteraccepts wildcard værdier. Følgende eksempel viser en parameterdeklarationfor en obligatorisk Stiparameter, der understøtter wildildcard-værdier.

Param( ] $Path)

brug af denne attribut aktiverer ikke automatisk supportildcard-understøttelse. Cmdletudvikleren skal implementere koden for at håndtere wildildcard-indgangen. Wildildcardssupported kan variere afhængigt af den underliggende API eller Po .ershell udbyder. Formore oplysninger, se about_ .ildcards.,

Parameter og variable valideringsattributter

Valideringsattributter direkte Po .ershell for at teste de parameterværdier, som brugerindsende, når de kalder den avancerede funktion. Hvis parameterværdierne mislykkes thetest, genereres en fejl, og funktionen kaldes ikke. Parameter validationis kun anvendes på input og andre værdier som standard valuesare ikke valideret.

Du kan også bruge valideringsattributterne til at begrænse de værdier, som brugere kan angive for variabler., Når du bruger en type konverter sammen med avalidering attribut, typen konverter skal defineres før attributten.

 $number = 7

allo .null Validering attribut

attributten Allo .null tillader værdien af en obligatorisk parameter at være$null. Følgende eksempel erklærer en Hashtable ComputerInfo parameter, der kan have en null-værdi.

Param( $ComputerInfo)

allo .emptystring validation attribut

attributten Allo .emptystring tillader værdien af en obligatorisk parameter at være en tom streng (""). Følgende eksempel erklærer en ComputerNameparameter, der kan have en tom streng værdi.

Param( $ComputerName)

AllowEmptyCollection validering attribut

AllowEmptyCollection attribut gør det muligt at værdien af en mandatoryparameter at være en tom collection @()., Følgende eksempel erklærer aComputerName parameter, der kan have en tom indsamling værdi.

Param( ] $ComputerName)

ValidateCount validation attribut

ValidateCount attributten angiver det minimale og maksimale antal parameterværdier, som en parameter accepterer. Po .ershell genererer en fejl, hvisantal parameterværdier i kommandoen, der kalder funktionen, ligger uden for det område.

følgende parameter erklæring skaber en Computernavn parameter, dertager en til fem parameterværdier.,

Param( ] $ComputerName)

Valideringsattribut for Valideringslængde

attributten ValidateLength specificerer det minimale og maksimale antal tegn i en parameter eller variabel værdi. Po .ershell genererer en fejl, hvislængden af en værdi angivet for en parameter eller en variabel er uden for området.

i det følgende eksempel skal hvert computernavn have et til ti tegn.

Param( ] $ComputerName)

I det følgende eksempel, er den værdi af variabel $number skal være en minimumof et tegn i længden, og højst ti tegn.,

$number = '01'

validatepattern validation attribut

attributten ValidatePattern specificerer et regulært udtryk, der sammenlignes med parameteren eller den variable værdi. Po .ershell genererer en fejl, hvisværdien svarer ikke til det regulære udtryksmønster.,

i det følgende eksempel skal parameterværdien indeholde et firecifret tal, og hvert ciffer skal være et tal nul til ni.

Param( ")] ] $ComputerName)

i det følgende eksempel skal værdien af variablen $number være nøjagtigt etfirecifret tal, og hvert ciffer skal være et tal nul til ni.

$")]$number = 1111

ValidateRange validering attribut

ValidateRange attribut angiver et numerisk interval eller aValidateRangeKind enum værdi for hver parameter eller variabel værdi.Po .ershell genererer en fejl, hvis en værdi er uden for dette interval.,

ValidateRangeKind enum giver mulighed for følgende værdier:

• Positiv – Et tal større end nul.
• negativ-et tal mindre end nul.
• NonPositive-et tal mindre end eller lig med nul.
• NonNegative-et tal større end eller lig med nul.

i det følgende eksempel skal værdien af Forsøgsparameteren væremellem nul og ti.

Param( $Attempts)

i det følgende eksempel skal værdien af variablen $number være mellem nul og ti.,

$number = 5

i det følgende eksempel skal værdien af variablen $number være størreend nul.

$number = 1

ValidateScript validering attribut

ValidateScript attribut angiver et script, der bruges til at validere aparameter eller variabel værdi. PowerShell rør værdien til det script, andgenerates en fejl, hvis scriptet returnerer $false, eller hvis scriptet kaster anexception.,

Når du bruger attributten ValidateScript, kortlægges værdien, der valideres, til variablen $_. Du kan bruge variablen$_ til at henvise til værdien i scriptet.

i det følgende eksempel skal værdien af parameteren EventDate være større end eller lig med den aktuelle dato.

Param( $EventDate)

i det følgende eksempel skal værdien af variablen $date være størreend eller lig med den aktuelle dato og klokkeslæt.,

$date = (Get-Date)

ValidateSet-attributten

ValidateSet-attributten specificerer et sæt gyldige værdier for en parametereller-variabel og aktiverer udfyldelse af faner. Po .ershell genererer en fejl, hvis aparameter eller variabel værdi ikke matcher en værdi i sættet. I det følgendeeksempel kan værdien af Detaljeparameteren kun være lav, gennemsnitlig eller høj.,

Param( ] $Detail)

i det følgende eksempel skal værdien af variablen $flavor være entenchokolade, jordbær eller vanille.

$flavor = "Strawberry"

valideringen sker, når denne variabel er tildelt selv inden for thescript. For eksempel, efter resulterer i en fejl på runtime:

Param( $Message)$Message = "bye"

Dynamisk validateSet værdier

Du kan bruge en Klasse for dynamisk at generere værdier for ValidateSetat runtime., I det følgende eksempel, de gyldige værdier for variablen$Sound genereres via en Klasse ved navn SoundNames, der kontrollerer threefilesystem stier til rådighed lyd filer:

class derefter gennemføres som en dynamisk ValidateSet valueas følger:

Param( )] $Sound)

ValidateNotNull validering attribut

ValidateNotNull attribut angiver, at parameteren kan ikke være$null. Po .ershell genererer en fejl, hvis parameterværdien er $null.,attributten ValidateNotNull er designet til at blive brugt, når parameteren er valgfri, og typen er udefineret eller har en typekonverter, der implicit kan konvertere en null-værdi som objekt. Hvis du angiver en type, der implicit konverterer en null-værdi, såsom en streng, konverteres null-værdien til en tom streng, selv når du bruger ValidateNotNullattribute. I dette scenario skal du bruge ValidateNotNullOrEmpty

i det følgende eksempel kan værdien af ID-parameteren ikke være $null.,

Param( $ID)

ValidateNotNullOrEmpty validering attribut

ValidateNotNullOrEmpty attribut angiver, at parameteren valuecan ikke være $null og kan ikke være en tom streng (""). PowerShell genererer anerror hvis parameter er brugt i et funktionskald, men dens værdi er $null, anempty strengen (""), eller et tomt array @().,

Param( ] $UserName)

ValidateDrive validation attribut

ValidateDrive attributten angiver, at parameterværdien skal repræsentere stien, der kun henviser til tilladte drev. Po .ershellgenererer en fejl, hvis parameterværdien refererer til andre drev endtillo .ed. Eksistensen af stien, bortset fra selve drevet, er ikke verificeret.

Hvis du bruger relativ sti, skal det aktuelle drev være på listen over tilladte drev.,

Param( $Path)

ValidateUserDrive validering attribut

ValidateUserDrive attribut angiver, at parameteren værdi mustrepresent den sti, der er med henvisning til User i bil. Po .ershell genererer anerror, hvis stien refererer til et andet drev. Valideringsattributten kuntest for eksistensen af drevdelen af stien.

Hvis du bruger relativ sti, skal det aktuelle drev være 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 definere User kør i Bare Nok Administration (ÆA) sessionconfigurations. I dette eksempel opretter vi brugeren: drev.

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

True

ValidateTrustedData validering attribut

Denne attribut blev tilføjet i PowerShell 6.1.1.

på dette tidspunkt bruges attributten internt af Po .ershell selv og er ikkeberegnet til ekstern brug.,

dynamiske parametre

dynamiske parametre er parametre for en cmdlet, funktion eller script, der kun er tilgængelig under visse betingelser.for eksempel har flere cmdlets fra udbyderen parametre, der kun er tilgængeligenår cmdlet ‘ en bruges i udbyderdrevet eller i en bestemt sti i provider-drevet. For eksempel, Kodning parameter er kun tilgængelig påAdd-Content Get-Content og Set-Content cmdlets kun, når det bruges ina file system drev.,

Du kan også oprette en parameter, der kun vises, når en anden parameter erbruges i funktionskommandoen eller når en anden parameter har en bestemt værdi.

dynamiske parametre kan være nyttige, men brug dem kun når det er nødvendigt, fordide kan være svært for brugerne at opdage. For at finde en dynamisk parameter skalbrugeren være i udbyderstien, bruge Argumentlisteparameteren forGet-Command cmdlet, eller brug Stiparameteren Get-Help.

for at oprette en dynamisk parameter for en funktion eller et script skal du bruge DynamicParam nøgleord.,

syntaks er som følger:

DynamicParam {<statement-list>}

I oversigten, skal du bruge en If erklæring for at angive de betingelser, underwhich den parameter er kun tilgængelig i funktionen.

brug New-Object cmdlet til at oprette aSystem.Forvaltning.Automation.RuntimeDefinedParameter objekt til at repræsentereparameteren og angive dens navn.

Du kan bruge en New-Object kommando til at oprette aSystem.Forvaltning.Automation.,ParameterAttribute objekt til at repræsentereattributter af parameteren, såsom obligatorisk, Position, orValueFromPipeline eller dens parameter sæt.

følgende eksempel viser en prøvefunktion med standardparametre namedName og Path, og en valgfri dynamisk parameter ved navn DP1. TheDP1 parameter er i PSet1 parameter sæt og er en type Int32.,Den DP1 parameter er kun tilgængelig i Get-Sample fungerer kun, når thevalue af Stien parameter, der starter med HKLM:, der angiver, at det er beingused i HKEY_LOCAL_MACHINE registreringsdatabasen kørsel.

For mere information, seeRuntimeDefinedParameter.

s .itch parametre

S .itch parametre er parametre uden parameterværdi. De er effektive, når de bruges og kun har en effekt.

For eksempel noprofile parameteren for Po .ershell.e .e er en s .itchparameter.,

for at oprette en s .itchparameter i en funktion skal du angive Switch skriv iparameter definition.

For eksempel:

Param(<ParameterName>)

Eller du kan bruge en anden metode:

Param( $<ParameterName>)

Skift parametre, der er nemme at bruge og er foretrukket over Boolean parametre,som har en mere vanskelig syntaks.for eksempel for at bruge en s .itchparameter skriver brugeren parameteren ikommando.

-IncludeAll

for at bruge en boolsk parameter skriver brugeren parameteren og en boolsk værdi.,

-IncludeAll:$true

Når du opretter s .itchparametre, skal du vælge parameternavnet omhyggeligt. Vær sikker på, at parameternavnet kommunikerer effekten af parameteren til brugeren.Undgå tvetydige udtryk, såsom Filter eller maksimum, der kan indebære avalue er påkrævet.

ArgumentCompleter attribut

attributten ArgumentCompleter giver dig mulighed for at tilføje fane fuldførelsesværdier til en bestemt parameter. En ArgumentCompleter attribut skal defineres forhver parameter, der skal fanen færdiggørelse., I lighed med DynamicParameters beregnes de tilgængelige værdier ved runtime, når brugeren trykker på fanen efter parameternavnet.

for at tilføje en ArgumentCompleter attribut, skal du definere et script blokder bestemmer værdierne. Scriptblokken skal tage følgendeparametre i nedenstående rækkefølge. Parameterens navne betyder ikke noget somværdierne leveres positivt.,

syntaks er som følger:

ArgumentCompleter script blokken

script blok parametre er indstillet til følgende værdier:

• $commandName (Position 0) – Denne parameter er indstillet til navnet på thecommand, som script blok er at give tab-afslutningen.
• $parameterName (Position 1) – denne parameter er indstillet til parameteren whhosevalue kræver fane afslutning.
• $wordToComplete (Position 2) – Denne parameter er indstillet til værdi brugeren hasprovided før de trykkede Tab., Din script blok skal useethis værdi til at bestemme fanen færdiggørelse værdier.
• $commandAst (Position 3) – Denne parameter er indstillet til det Abstrakte SyntaxTree (AST) for den aktuelle indtastningslinje. For mere information, seeAst klasse.
• $fakeBoundParameters (Position 4) – Denne parameter er angivet til en hashtablecontaining $PSBoundParameters til cmdlet, før brugeren pressedTab. For mere information, seeabout_Automatic_Variables.,

ArgumentCompleter script-blokken skal rulles værdier med thepipeline, som f.eks. ForEach-Object Where-Object, eller en anden egnet metode.Returnering af en række værdier får Po .ershell til at behandle hele arrayet asone tab-færdiggørelsesværdi.

følgende eksempel tilføjer fanefyldning til Værdiparameteren. Hvis Kunværdiparameteren er angivet, vises alle mulige værdier eller argumenter for værdi. Når parameteren Type er angivet, viser parameteren value kun de mulige værdier for den pågældende type.,

derudover sikrer-like operatøren, at hvis brugeren skriver følgendekommando og bruger fanen færdiggørelse, returneres kun Apple.

Test-ArgumentCompleter -Type Fruits -Value A

Se også

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute