About Functions Advanced Parameters (Norsk)

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

Short description

Explains how to add parameters to advanced functions.,

Lang beskrivelse

kan Du legge til parametere for avanserte funksjoner som du skriver, og useparameter attributter og argumenter for å begrense parameterverdier som functionusers sende med parameteren.

De parametere som du kan legge til funksjonen er tilgjengelig for brukere i additionto felles parametere som PowerShell legger automatisk til alle cmdlets andadvanced funksjoner. For mer informasjon om PowerShell commonparameters, se about_CommonParameters.

i Begynnelsen PowerShell-3.,0, kan du bruke splatting med @Args for å representthe parametre i en kommando. Splatting er gyldig på enkle og advancedfunctions. For mer informasjon, se about_Functions andabout_Splatting.

Skriv konvertering av parameter-verdier

Når du oppgir strenger som argumenter til parametere som forventer en differenttype, PowerShell implisitt konverterer strenger til parameteren måltype.Avanserte funksjoner utføre kultur-invariant analysering av parameterverdier.

i motsetning, en kultur-sensitive konverteringen er utført i løpet parameterbinding for samlet cmdlets.,

I dette eksempelet skal vi lage en cmdlet og et script funksjon som tar en – parameteren. Dagens kultur er endret for å bruke tysk innstillinger.En tysk-formatert datoen er gått til parameter.

Dienstag, 19. Juni 2018 00:00:00

Som vist ovenfor, cmdletene bruker kultur-sensitive parsing for å konvertere strengen.

Avanserte funksjoner bruker kultur-invariant parsing, som resulterer i thefollowing feil.

Statiske parametre

Statiske parametre er parametere som alltid er tilgjengelige i funksjon.,De fleste parametre i PowerShell cmdlets og skript er statiske parametre.

følgende eksempel viser erklæringen av en Datamaskinnavn parameterthat har følgende egenskaper:

• Det er obligatorisk (obligatorisk).
• Det tar input fra rørledningen.
• Det tar en array med strenger som input.

Param( ] $ComputerName)

Attributter av parametere

Dette avsnittet beskriver attributtene som du kan legge til funksjon parametere.

Alle attributter er valgfritt., Imidlertid, hvis du utelater CmdletBindingattribute, for så å bli anerkjent som en avansert funksjon, funksjonen mustinclude Parameteren attributtet.

Du kan legge til ett eller flere attributter i hver parameter erklæring. Det’sno grense for antall attributter som du kan legge til et parameterdeclaration.

– Parameteren attributt

Parameteren attributtet brukes til å erklære attributter av functionparameters.

Parameteren egenskapen er valgfri, og du kan utelate det hvis ingen av theparameters av din funksjonene må attributter., Men, for å bli anerkjent som anadvanced funksjon, snarere enn en enkel funksjon, en funksjon må ha eitherthe CmdletBinding attributt eller Parameteren attributt, eller begge deler.

Parameteren attributtet har argumenter som definerer egenskapene ofthe parameter, for eksempel om parameteren er obligatorisk eller valgfri.

du Bruke følgende syntaks for å forkynne Parameter-attributtet, et argument,og et argument verdi. Parentesene som omslutter argument og dens valuemust følge Parameter uten mellomrom.,

Param( $ParameterName)

Bruk komma for å skille argumenter i parentes. Bruk followingsyntax å erklære to argumenter for Parameteren-attributtet.

Param( )

Den boolske argument typer Parameteren attributt standard Falsewhen utelatt fra Parameter-attributtet. Angi argumentet verdien til$true eller bare liste argumentet av navnet. For eksempel, den followingParameter attributter er tilsvarende.,

Hvis du bruker Parameteren attributt uten argumenter, som et alternativ tousing den CmdletBinding-attributtet, parenteser som følge theattribute navnet er fortsatt nødvendig.

Param( $ParameterName)

Obligatorisk argumentet

Mandatory argumentet indikerer at parameteren er obligatorisk. Hvis thisargument er ikke angitt, parameteren er valgfri.

følgende eksempel erklærer Datamaskinnavn parameter. Den brukerMandatory argument for å gjøre parameteren er obligatorisk.,

Param( ] $ComputerName)

Posisjon argumentet

Position argumentet avgjør om parameteren navn er nødvendig whenthe parameteren brukes i en kommando. Når en parameter erklæringen omfatterPosition argumentet parameter navn, kan være utelatt, og PowerShellidentifies det ikke navngitt parameter verdi av sin posisjon, eller for, i listof ikke navngitt parameter verdier i kommandoen.,

Hvis Position argumentet ikke er angitt, parameter navn, eller en parametername alias eller forkortelse, må gå forut for parameteren verdi når theparameter er brukt i en kommando.

som standard, alle funksjonen parametere er stedsbestemt. PowerShell tildeler positionnumbers til parametre i den rekkefølgen de parameterne som er angitt i thefunction. For å deaktivere denne funksjonen, angir du verdien for PositionalBindingargument av CmdletBinding attributtet til $False., Positionargumentet har forrang over verdien av PositionalBinding argumentet ofthe CmdletBinding attributtet. For mer informasjon, se PositionalBindingi about_Functions_CmdletBindingAttribute.

verdi Position argumentet er angitt som et heltall. En positionvalue 0 representerer den første posisjonen i kommandoen, en posisjon valueof 1 representerer den andre posisjonen i kommando, og så videre.,

Hvis en funksjon har ikke stedsbestemt parametre, PowerShell tildeler stillinger toeach parameter basert på i hvilken rekkefølge de parameterne som er erklært.Men, som en av beste praksis, ikke stole på seg denne oppgaven. Når du wantparameters å være stedsbestemt, bruk Position argument.

følgende eksempel erklærer Datamaskinnavn parameter. Den brukerPosition argumentet med en verdi på 0. Som et resultat, når -ComputerName isomitted fra kommando, verdien må være den første eller eneste navnløse parametervalue i kommandoen.,

Param( ] $ComputerName)

ParameterSetName argumentet

ParameterSetName argumentet angir parameteren satt til som aparameter tilhører. Hvis ingen parametersettet er angitt, parameter tilhører toall parameteren angir definert av funksjon. Derfor, for å være unik, eachparameter sett må ha minst én parameter som ikke er medlem av noen otherparameter sett.

følgende eksempel erklærer en Datamaskinnavn parameter i Computerparameter angi et Brukernavn parameter i User parametersett, og aSummary parameter i både parametersett.

Du kan angi bare en ParameterSetName verdi i hvert argument og bare enParameterSetName argument i hver Parameter-attributtet. For å indikere at aparameter vises i mer enn én parameter set, legge til flere Parameterattributes.,

følgende eksempel eksplisitt legger Oppsummering parameteren tilComputer og User parametersett. Oppsummering parameteren er valgfri inthe Computer parametersett og obligatorisk i User parametersett.

For mer informasjon om parameteren angir, kan du se Om parametersett.

ValueFromPipeline argumentet

ValueFromPipeline argumentet indikerer at parameteren aksepterer inputfrom en rørledning objekt., Angi dette argumentet hvis funksjonen aksepterer avhele objekt, ikke bare en egenskap ved objektet.

følgende eksempel erklærer en Datamaskinnavn parameter som er mandatoryand aksepterer et objekt som sendes til funksjonen fra rørledningen.

Param( ] $ComputerName)

ValueFromPipelineByPropertyName argumentet

ValueFromPipelineByPropertyName argumentet angir at parameteraccepts innspill fra en eiendom av en rørledning objekt. Objektet eiendom musthave samme navn eller alias som parameter.,

For eksempel, hvis funksjon har et Datamaskinnavn parameter, og pipedobject har et Datamaskinnavn eiendom, verdien av ComputerNameproperty er tildelt funksjonen er Datamaskinnavn parameter.

følgende eksempel erklærer en Datamaskinnavn parameter som er mandatoryand aksepterer inndata fra objektet er Datamaskinnavn eiendom som sendes til funksjonen gjennom rørledningen.,

Param( ] $ComputerName)

ValueFromRemainingArguments argumentet

ValueFromRemainingArguments argumentet indikerer at parameteren acceptsall parameterens verdier i kommandoen som ikke er tilordnet til otherparameters av funksjon.

følgende eksempel erklærer en Verdi parameteren som er obligatorisk og aRemaining parameter som aksepterer alle de resterende parameterverdier thatare sendes til funksjonen.

Found 2 elements0: one1: two

HelpMessage argumentet

HelpMessage argumentet angir en streng som inneholder en kort prosjektbeskrivelse parameteren eller dets verdi. PowerShell viser denne meldingen i promptthat vises når en obligatorisk parameter verdi mangler fra en kommando. Thisargument har ingen effekt på valgfrie parametere.

følgende eksempel erklærer en obligatorisk Datamaskinnavn parameter og ahelp melding som forklarer den forventede parameter verdi.,

Hvis det er ingen annen kommentar-basert hjelp syntaxfor funksjonen (for eksempel .SYNOPSIS) så denne meldingen viser seg også iGet-Help utdata.

Param( ] $ComputerName)

Alias-attributt

Alias-attributtet etablerer et alternativt navn for parameter.Det er ingen grense for antall aliaser som du kan tilordne til en parameter.

følgende eksempel viser en parameter erklæring som legger til CN andMachineName aliaser til den obligatoriske Datamaskinnavn parameter.,

Param( ] $ComputerName)

SupportsWildcards attributt

SupportsWildcards attributtet brukes til å indikere at parameteraccepts jokertegn verdier. Følgende eksempel viser en parameter declarationfor en obligatorisk Banen parameter som støtter jokertegn verdier.

Param( ] $Path)

ved Hjelp av dette attributtet ikke automatisk aktivere jokertegn støtte. Den cmdletdeveloper må implementere kode for å håndtere jokertegn inngang. Den wildcardssupported kan variere i henhold til de underliggende API eller PowerShell leverandør. Mer informasjon, se about_Wildcards.,

– Parameteren og variable validering attributter

Validering attributter direkte PowerShell til å teste parameterverdier som userssubmit når de kaller avansert funksjon. Hvis parameter verdier mislykkes thetest, det genereres en feil, og funksjonen er ikke kalt. Parameteren validationis bare brukt til inndata er gitt og eventuelle andre verdier som standard valuesare ikke validert.

Du kan også bruke validering attributter for å begrense verdier thatusers kan angi for variabler., Når du bruker en skriver konverter sammen med avalidation attributtet type converter må være definert før attributtet.

 $number = 7

AllowNull validering attributt

AllowNull attributt gjør at verdien av en obligatorisk parameter for å være$null. Følgende eksempel erklærer en hashtable ComputerInfo parameterthat kan ha en null-verdi.

Param( $ComputerInfo)

AllowEmptyString validering attributt

AllowEmptyString attributt gjør at verdien av en obligatorisk parameter tobe en tom streng (""). Følgende eksempel erklærer en ComputerNameparameter som kan ha en tom streng verdi.

Param( $ComputerName)

AllowEmptyCollection validering attributt

AllowEmptyCollection attributt gjør at verdien av en mandatoryparameter å være en tom collection @()., Følgende eksempel erklærer aComputerName parameter som kan ha en tom samling verdi.

Param( ] $ComputerName)

ValidateCount validering attributt

ValidateCount attributtet angir minimum og maksimum antall ofparameter verdier som en parameter aksepterer. PowerShell genererer en feil hvis thenumber av parameterverdier i kommandoen som kaller funksjonen er outsidethat utvalg.

følgende parameter erklæringen skaper et Datamaskinnavn parameter thattakes ett til fem faste verdier.,

Param( ] $ComputerName)

ValidateLength validering attributt

ValidateLength attributtet angir minimum og maksimum antall ofcharacters i en parameter eller variabel verdi. PowerShell genererer en feil ifthe lengden av en verdi som er angitt for en parameter eller en variabel er utenfor therange.

I følgende eksempel, hver datamaskin navn må ha en til ti tegn.

Param( ] $ComputerName)

I følgende eksempel verdien av variabelen $number må være en minimumof ett tegn i lengde, og maksimalt ti tegn.,

$number = '01'

ValidatePattern validering attributt

ValidatePattern attributtet angir et vanlig uttrykk som’scompared til parameter eller variabel verdi. PowerShell genererer en feil ifthe-verdien ikke matcher det regulære uttrykk.,

I det følgende eksemplet, parameterverdien må inneholde en fire-sifret tall,og hvert siffer må være et tall null til ni.

Param( ")] ] $ComputerName)

I følgende eksempel verdien av variabelen $number må være nøyaktig afire-sifret nummer, og hvert siffer må være et tall null til ni.

$")]$number = 1111

ValidateRange validering attributt

ValidateRange attributtet angir en numerisk område eller aValidateRangeKind enum-verdi for hver parameter eller variabel verdi.PowerShell genererer en feil hvis noen verdi er utenfor dette området.,

ValidateRangeKind enum gir følgende verdier:

• Positive – Et tall som er større enn null.
• Negative – Et tall mindre enn null.
• NonPositive – Et tall mindre enn eller lik null.
• Ikkenegative – Et tall som er større enn eller lik null.

I følgende eksempel verdien av Forsøk parameteren må bebetween null og ti.

Param( $Attempts)

I følgende eksempel verdien av variabelen $number må være betweenzero og ti.,

$number = 5

I følgende eksempel verdien av variabelen $number må være greaterthan null.

$number = 1

ValidateScript validering attributt

ValidateScript attributtet angir et skript som brukes til å validere aparameter eller variabel verdi. PowerShell rør verdien til skriptet, andgenerates en feil hvis scriptet returnerer $false eller hvis skriptet kaster anexception.,

Når du bruker ValidateScript attributt, verdien som blir validatedis tilordnet til $_ variabel. Du kan bruke $_ variabel for å se thevalue i skriptet.

I følgende eksempel verdien av EventDate parameteren må begreater enn eller lik dagens dato.

Param( $EventDate)

I følgende eksempel verdien av variabelen $date må være greaterthan eller lik gjeldende dato og klokkeslett.,

$date = (Get-Date)

ValidateSet attributt

ValidateSet attributtet angir et sett med gyldige verdier for en parameteror variabel, og gjør det mulig tab for ferdigstillelse. PowerShell genererer en feil hvis aparameter eller variabel verdi ikke tilsvarer en verdi i settet. I followingexample, verdien av Detalj-parameteren kan kun være Lav, Gjennomsnittlig, orHigh.,

Param( ] $Detail)

I følgende eksempel verdien av variabelen $flavor må være eitherChocolate, Jordbær, eller Vanilje.

$flavor = "Strawberry"

validering skjer når den variabelen er tilordnet selv innenfor thescript. For eksempel, følgende resultater i en feil ved kjøring:

Param( $Message)$Message = "bye"

Dynamisk validateSet verdier

Du kan bruke en Klasse til å dynamisk generere verdier for ValidateSetat runtime., I følgende eksempel gyldige verdier for variabelen$Sound er generert via en Klasse som heter SoundNames som kontrollerer threefilesystem baner tilgjengelig for lyd filer:

klassen er så gjennomført som en dynamisk ValidateSet valueas følger:

Param( )] $Sound)

ValidateNotNull validering attributt

ValidateNotNull attributtet angir at parameterverdien kan ikke være$null. PowerShell genererer en feil hvis parameteren verdi $null.,

ValidateNotNull attributtet er utformet for å brukes når parameteren isoptional og typen er udefinert eller har en type converter som kan’timplicitly konvertere en null-verdi som objekt. Hvis du angir en skriver thatthat vil automatisk konvertere en null-verdi som en streng, null valueis konvertert til en tom streng, selv når du bruker ValidateNotNullattribute. For dette scenariet bruker ValidateNotNullOrEmpty

I følgende eksempel verdien av ID-parameteren kan ikke være $null.,

Param( $ID)

ValidateNotNullOrEmpty validering attributt

ValidateNotNullOrEmpty attributtet angir at parameteren valuecan ikke være $null, og kan ikke være en tom streng (""). PowerShell genererer anerror hvis parameteren brukes i en funksjon ringe, men verdien er $null, anempty strengen (""), eller en tom matrise @().,

Param( ] $UserName)

ValidateDrive validering attributt

ValidateDrive attributtet angir at parameterverdien mustrepresent banen, det er med henvisning til lov stasjoner bare. PowerShellgenerates en feil hvis parameteren verdi refererer til andre stasjoner enn theallowed. Eksistensen av banen, bortsett fra selve stasjonen, er ikke bekreftet.

Hvis du bruker relativ bane, den nåværende stasjonen må være i lov stasjon-listen.,

Param( $Path)

ValidateUserDrive validering attributt

ValidateUserDrive attributtet angir at parameterverdien mustrepresent banen, som henviser til User kjør. PowerShell genererer anerror hvis banen refererer til en annen stasjon. Validering attributt onlytests for eksistensen av stasjonen del av banen.

Hvis du bruker relativ bane, den nåværende stasjonen må 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 angi User kjør i Akkurat Nok Administration (JEA) sessionconfigurations. For dette eksempelet er vi opprette Brukeren: – stasjonen.

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

True

ValidateTrustedData validering attributt

Dette attributtet ble lagt i PowerShell 6.1.1.

På denne tiden, attributtet brukes internt av PowerShell seg selv, og er notintended for ekstern bruk.,

Dynamiske parametre

Dynamiske parametre er parametere til en cmdlet, funksjon, eller skript som areavailable bare under visse betingelser.

For eksempel, flere leverandøren cmdlets har parametre som er tilgjengelige onlywhen cmdleten er brukt i leverandør-stasjonen, eller i en bestemt bane av theprovider stasjonen. For eksempel, Koding parameter er tilgjengelig påAdd-Content, Get-Content, og Set-Content cmdlets bare når det er brukt ina file system-stasjonen.,

Du kan også opprette en parameter som bare vises når en annen parameter isused i funksjon kommando eller når en annen parameter har en viss verdi.

Dynamiske parametre kan være nyttig, men bruker dem bare når det er nødvendig, becausethey kan være vanskelig for brukere å oppdage. Å finne en dynamisk parameter, theuser må være i leverandør-bane, bruk ArgumentList av parameterenGet-Command cmdlet, eller bruke Banen av parameteren Get-Help.

for Å lage en dynamisk parameter for en funksjon eller et skript, kan du bruke DynamicParamsøkeord.,

syntaksen er som følger:

DynamicParam {<statement-list>}

I uttalelsen listen, kan du bruke en If uttalelse for å angi betingelsene underwhich parameteren er tilgjengelig i funksjon.

for New-Object cmdlet for å skape aSystem.Management.Automatisering.RuntimeDefinedParameter objekt til representthe parameter og angi navnet.

Du kan bruke en New-Object kommando for å opprette aSystem.Management.Automatisering.,ParameterAttribute objekt til representattributes av parameter, for eksempel Obligatorisk, Posisjon, orValueFromPipeline eller dets parametersett.

følgende eksempel viser et eksempel på en funksjon med standard parametre namedName og Bane, og en valgfri dynamisk parameter som heter DP1. TheDP1 parameteren er i PSet1 parametersett og har en type Int32.,Den DP1 parameter er tilgjengelig i Get-Sample – funksjonen bare når thevalue av Banen parameter som starter med HKLM:, noe som indikerer at det beingused i HKEY_LOCAL_MACHINE register drive.

For mer informasjon, seeRuntimeDefinedParameter.

Slå parametere

Slå parametere er parametere med ingen parameter verdi. De er effectiveonly når de er brukt og har bare en effekt.

For eksempel, NoProfile parameter av powershell.exe-er en switchparameter.,

for Å lage en bryter parameter i en funksjon, må du angi Switch skriv i theparameter definisjon.

For eksempel slik:

Param(<ParameterName>)

Eller, du kan bruke en annen metode:

Param( $<ParameterName>)

Slå på parametere som er enkel å bruke og er foretrukket over Boolske variabler som har en mer vanskelig syntaks.

For eksempel, for å bruke en bryter parameter, brukeren typer parameteren i thecommand.

-IncludeAll

for Å bruke en Boolsk parameter, brukeren skriver inn parameter og en Boolsk verdi.,

-IncludeAll:$true

Når du oppretter bytte parametre, kan du velge parameter navn nøye. Bli surethat parameteren navn kommuniserer effekten av parameter til brukeren.Unngå tvetydige begreper, som Filter eller Maksimalt kan antyde avalue er nødvendig.

ArgumentCompleter attributt

ArgumentCompleter attributtet kan du legge til kategorien ferdigstillelse verdier toa parameter. En ArgumentCompleter attributtet må være definert foreach parameter som må tab for ferdigstillelse., Lik DynamicParameters, theavailable verdiene er beregnet ved kjøring når brukeren trykker Tabafter parameteren navn.

for Å legge til en ArgumentCompleter attributt, må du definere et skript blockthat bestemmer verdier. Skriptet blokk må ta followingparameters i den rekkefølgen som er angitt nedenfor. Parameteren navn ikke saken asthe verdier er gitt positionally.,

syntaksen er som følger:

ArgumentCompleter script blokk

skriptet blokkere parametere er satt til følgende verdier:

• $commandName (Posisjon 0) – Denne parameteren er satt til navnet av thecommand som skriptet blokk er å gi tab for ferdigstillelse.
• $parameterName (Posisjon 1) – Denne parameteren er satt til parameter whosevalue krever tab for ferdigstillelse.
• $wordToComplete (Posisjon 2) – Denne parameteren er satt til verdi for brukeren hasprovided før de trykket Kategorien., Skriptet blokkere bør usethis verdi for å avgjøre kategorien ferdigstillelse verdier.
• $commandAst (Posisjon 3) – Denne parameteren er satt til Abstrakt SyntaxTree (AST) for den gjeldende inngangen linje. For mer informasjon, seeAst Klasse.
• $fakeBoundParameters (Posisjon 4) – Denne parameteren er satt til en hashtablecontaining $PSBoundParameters for cmdleten, før brukeren pressedTab. For mer informasjon, seeabout_Automatic_Variables.,

ArgumentCompleter script blokk må rulle verdiene med thepipeline, for eksempel ForEach-Object, Where-Object eller annen egnet metode.Returnerer en matrise med verdier fører til PowerShell til å behandle hele matrisen asone kategorien ferdigstillelse verdi.

følgende eksempel legger til kategorien ferdigstillelse til den Verdi som parameter. Hvis onlythe Verdien for parameteren er angitt, vil alle mulige verdier, eller argumenter, forValue vises. Når parameter er angitt, theValue parameteren vises kun mulige verdier for denne typen.,

I tillegg, -like operatør sikrer at hvis brukeren skriver inn followingcommand og bruker Tab-completion, bare Apple er returnert.

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