About Functions Advanced Parameters (Română)

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

Short description

Explains how to add parameters to advanced functions.,

descriere

puteți adăuga parametri de funcții avansate pe care le scrie, și useparameter atribute și argumente pentru a limita valorile parametrilor care functionusers prezinte cu parametru.parametrii pe care îi adăugați funcției dvs. sunt disponibili utilizatorilor în plus față de parametrii comuni pe care PowerShell îi adaugă automat la toate cmdleturile și funcțiile avansate. Pentru mai multe informații despre PowerShell commonparameters, consultați about_CommonParameters.

începând cu PowerShell 3.,0, puteți utiliza splatting cu @Args pentru a reprezenta parametrii într-o comandă. Splatting este valabil pe Simplu și avansatfuncții. Pentru mai multe informații, consultați about_Functions andabout_Splatting.

type conversia valorilor parametrilor

când furnizați șiruri ca argumente pentru parametrii care se așteaptă la un alt tip, PowerShell convertește implicit șirurile la tipul țintă al parametrului.Funcțiile avansate efectuează analiza culturii invariante a valorilor parametrilor.în schimb, o conversie sensibilă la cultură este efectuată în timpul legării parametrilor pentru cmdleturile compilate.,

în acest exemplu, creăm un cmdlet și o funcție script care iau un parametru. Cultura actuală este modificată pentru a utiliza setările germane.O dată formatată în limba germană este transmisă parametrului.

Dienstag, 19. Juni 2018 00:00:00

după cum se arată mai sus, cmdleturile folosesc parsarea sensibilă la cultură pentru a converti șirul.

funcțiile avansate utilizează parsarea cultură-invariantă, ceea ce duce la următoarea eroare.

parametrii statici

parametrii statici sunt parametri care sunt întotdeauna disponibili în funcție.,Majoritatea parametrilor din cmdleturile și scripturile PowerShell sunt parametri statici.

următorul exemplu arată declarația unui ComputerName parametercare are următoarele caracteristici:

• este obligatoriu (obligatoriu).
• este nevoie de intrare din conductă.
• este nevoie de o serie de șiruri ca intrare.

Param( ] $ComputerName)

atributele parametrilor

această secțiune descrie atributele pe care le puteți adăuga la parametrii funcției.

toate atributele sunt opționale., Cu toate acestea, dacă omiteți CmdletBindingattribute, apoi pentru a fi recunoscut ca o funcție avansată, funcția trebuieinclude atributul parametrului.

puteți adăuga unul sau mai multe atribute în fiecare declarație de parametri. Nu avem o limită la numărul de atribute pe care le puteți adăuga la un parameterdeclaration.

atribut parametru

atributul parametru este utilizat pentru a declara atributele functionparameters.

atributul parametru este opțional și îl puteți omite dacă niciunul dinparametrii funcțiilor dvs. nu au nevoie de atribute., Dar, pentru a fi recunoscută ca o funcție avansată, mai degrabă decât o funcție simplă, o funcție trebuie să aibă fie atributul CmdletBinding, fie atributul parametru, sau ambele.

atributul parametru are argumente care definesc caracteristicileparametrul, cum ar fi dacă parametrul este obligatoriu sau opțional.

utilizați următoarea sintaxă pentru a declara atributul parametru,un argument și o valoare argument. Parantezele care cuprind argumentul și valoarea acestuiatrebuie să urmeze parametrul fără spațiu intermediar.,

Param( $ParameterName)

utilizați virgule pentru a separa argumentele în paranteze. Utilizați următoarelesyntax pentru a declara două argumente ale atributului parametrului.

Param( )

tipurile de argument boolean ale atributului parametru implicit la Falsewhen omis din atributul parametru. Setați valoarea argumentului la$true sau doar listați argumentul după nume. De exemplu, următoareleatributele parametrului sunt echivalente.,

Dacă utilizați Parametrul atribut fără argumente, ca o alternativă tousing la CmdletBinding atribut, parantezele care urmează theattribute numele sunt încă necesare.

Param( $ParameterName)

Obligatorie argument

Mandatory argument indică faptul că parametrul este necesar. Dacă acestargument nu este specificat, parametrul este opțional.

următorul exemplu declară parametrul ComputerName. Utilizează argumentulMandatory pentru a face parametrul obligatoriu.,

Param( ] $ComputerName)

Poziția argument

Position argument determină dacă numele parametrului este necesară atunci când parametrul este utilizat într-o comandă. Atunci când un parametru declarație includePosition argument, nume parametru poate fi omis și PowerShellidentifies fără nume parametru valoarea de poziția sa, sau ordine, în listof anonim valorile parametrilor în comandă.,

Position argument nu este specificat, numele parametrului, sau un parametername alias sau abrevierea, trebuie să preceadă valoarea parametrului ori de câte ori theparameter este utilizat într-o comandă.

în mod implicit, toți parametrii funcției sunt poziționali. PowerShell atribuie pozițianumere parametrilor în ordinea în care parametrii sunt declarați înfuncție. Pentru a dezactiva această caracteristică, setați valoarea de PositionalBindingargument al CmdletBinding atribut $False., Positionargument are prioritate față de valoarea din PositionalBinding argument al CmdletBinding atribut. Pentru mai multe informații, consultați PositionalBindingîn about_Functions_CmdletBindingAttribute.

valoarea argumentului Position este specificată ca un număr întreg. O valoare a poziției 0 reprezintă prima poziție în comandă, o valoare a poziției 1 reprezintă a doua poziție în comandă și așa mai departe.,dacă o funcție nu are parametri poziționali, PowerShell atribuie pozițiifiecare parametru în funcție de ordinea în care sunt declarați parametrii.Cu toate acestea, ca o bună practică, nu vă bazați pe această sarcină. Când dorițiparametrii să fie poziționali, utilizați argumentul Position.

următorul exemplu declară parametrul ComputerName. Utilizează argumentulPosition cu o valoare de 0. Ca urmare, atunci când -ComputerName isomitted de comandă, valoarea sa trebuie să fie primul sau singurul anonim parametervalue în comandă.,

Param( ] $ComputerName)

ParameterSetName argument

ParameterSetName argument specifică set de parametri la care aparameter aparține. Dacă nu este specificat niciun set de parametri, parametrul aparținetoate seturile de parametri definite de funcție. Prin urmare, pentru a fi unic, fiecare set de parametri trebuie să aibă cel puțin un parametru care nu este membru al altui set de parametri.

următorul exemplu declară un Numecomputer parametru în Computerset de parametri, un nume de Utilizator parametru în User set de parametri, și aSummary parametru în ambele seturi de parametri.

puteți specifica un singur valoare în fiecare argument și doar un argument în fiecare atribut parametru. Pentru a indica faptul că aparameter apare în mai mult de un set de parametri, adăugați Parametruatribute suplimentare.,

următorul exemplu adaugă în mod explicit Rezumatul parametruComputer și User seturi de parametri. Rezumatul parametru este opțional în Computer set de parametri și obligatorie în User set de parametri.

Pentru mai multe informații despre seturile de parametri, consultați despre seturile de parametri.

ValueFromPipeline argument

ValueFromPipeline argument indică faptul că parametrul acceptă inputfrom o conducta de obiect., Specificați acest argument dacă funcția acceptăobiect de obiect, nu doar o proprietate a obiectului.

următorul exemplu declară un parametru de nume de computer care este obligatoriuși acceptă un obiect care a trecut la funcția din conductă.

Param( ] $ComputerName)

ValueFromPipelineByPropertyName argument

ValueFromPipelineByPropertyName argument indică faptul că parameteraccepts de intrare de la o proprietate a unei conducte de obiect. Proprietatea obiectului trebuie să aibă același nume sau alias ca parametrul.,de exemplu, dacă funcția are un parametru ComputerName și pipedobject are o proprietate ComputerName, valoarea ComputerNameproperty este atribuită parametrului ComputerName al funcției.

următorul exemplu declară un parametru ComputerName care este obligatoryand acceptă intrare din proprietatea ComputerName obiectului care a trecut la funcția prin conducta.,

Param( ] $ComputerName)

ValueFromRemainingArguments argument

ValueFromRemainingArguments argument indică faptul că parametrul acceptsall parametrul valorile în comandă, care nu sunt atribuite otherparameters din funcție.

următorul exemplu declară un parametru de valoare care este obligatoriu și parametrul aRemaining care acceptă toate valorile parametrilor rămași care sunt trimise funcției.

Found 2 elements0: one1: two

HelpMessage argument

HelpMessage argument specifică un șir care conține o scurtă descriptionof parametrul sau valoarea acestuia. PowerShell afișează acest mesaj în promptcare apare atunci când o valoare a parametrului obligatoriu lipsește dintr-o comandă. Acestargument nu are niciun efect asupra parametrilor opționali.

următorul exemplu declară un parametru ComputerName obligatoriu și un mesaj ahelp care explică valoarea parametrului așteptat.,

Dacă nu există nici un alt comentariu pe bază ajuta syntaxfor funcția (de exemplu, .SYNOPSIS), atunci acest mesaj, de asemenea, apare înGet-Help ieșire.

Param( ] $ComputerName)

atribut Alias

atributul Alias stabilește un nume alternativ pentru parametru.Nu există nicio limită a numărului de pseudonime pe care le puteți atribui unui parametru.

următorul exemplu arată o declarație de parametri care adaugă pseudonimele CN andMachineName la parametrul ComputerName obligatoriu.,

Param( ] $ComputerName)

SupportsWildcards atribut

SupportsWildcards atribut este folosit pentru a indica faptul că parameteraccepts wildcard valori. Următorul exemplu arată o declarație de parametripentru un parametru de cale obligatoriu care acceptă valori wildcard.

Param( ] $Path)

utilizarea acestui atribut nu permite automat suportul wildcard. Cmdletdeveloper trebuie să pună în aplicare Codul să se ocupe de intrare wildcard. Wildcardssupported poate varia în funcție de API-ul de bază sau de furnizorul PowerShell. Formore informații, vezi about_Wildcards.,

Parametru și variabile de validare atribute

Validare atribute directe PowerShell pentru a testa valorile parametrilor care userssubmit atunci când ei numesc funcții avansate. Dacă valorile parametrilor nu reușesc, se generează o eroare și funcția nu este apelată. Validationis parametru aplicat numai la intrare furnizate și orice alte valori, cum ar fi valorile implicite nu sunt validate.de asemenea, puteți utiliza atributele de validare pentru a restricționa valorile pe care utilizatorii le pot specifica pentru variabile., Când utilizați un convertor de tip împreună cu atributul avalidation, convertorul de tip trebuie definit înainte de atribut.

 $number = 7

AllowNull validare atribut

AllowNull atribut permite valoarea unui parametru obligatoriu să fie$null. Următorul exemplu declară un parametru computerinfo hashtable care poate avea o valoare nulă.

Param( $ComputerInfo)

AllowEmptyString validare atribut

AllowEmptyString atribut permite valoarea unui parametru obligatoriu să fie un șir gol (""). Următorul exemplu declară un Computernameparametru care poate avea o valoare de șir goală.

Param( $ComputerName)

AllowEmptyCollection validare atribut

AllowEmptyCollection atribut permite valoarea unui mandatoryparameter să fie o colecție goală @()., Următorul exemplu declară parametrul aComputerName care poate avea o valoare de colectare goală.

Param( ] $ComputerName)

ValidateCount validare atribut

ValidateCount atribut specifică numărul minim și maxim ofparameter valori care acceptă un parametru. PowerShell generează o eroare dacănumărul de valori ale parametrilor din comanda care apelează funcția este în afara acestui interval.

următoarea declarație de parametri creează un parametru de nume de calcul careia una până la cinci valori ale parametrilor.,

Param( ] $ComputerName)

ValidateLength validare atribut

ValidateLength atribut specifică numărul minim și maxim ofcharacters într-un parametru sau o valoare variabilă. PowerShell generează o eroare dacălungimea unei valori specificate pentru un parametru sau o variabilă este în afara intervalului.

în exemplul următor, fiecare nume de computer trebuie să aibă unul până la zece caractere.

Param( ] $ComputerName)

În exemplul următor, valoarea variabilei $number trebuie să fie un minimumof un personaj în lungime, și un maxim de zece caractere.,

$number = '01'

ValidatePattern validare atribut

ValidatePattern atribut specifică o expresie regulată care’scompared la parametrul sau valoarea variabilei. PowerShell generează o eroare dacăvaloarea nu se potrivește cu modelul de expresie regulată.,

în exemplul următor, valoarea parametrului trebuie să conțină un număr de patru cifre și fiecare cifră trebuie să fie un număr de la zero la nouă.

Param( ")] ] $ComputerName)

În exemplul următor, valoarea variabilei $number trebuie să fie exact patru cifre, fiecare cifră trebuie să fie un număr de la zero la nouă.

$")]$number = 1111

ValidateRange validare atribut

ValidateRange atribut specifică un interval numeric sau aValidateRangeKind enum valoare pentru fiecare parametru sau o valoare variabilă.PowerShell generează o eroare dacă orice valoare este în afara acestui interval.,

ValidateRangeKind enum permite următoarele valori:

• pozitiv-un număr mai mare decât zero.
• negativ-un număr mai mic decât zero.
• Nonpozitiv-un număr mai mic sau egal cu zero.
• Nonnegativ – un număr mai mare sau egal cu zero.

în exemplul următor, valoarea parametrului încercări trebuie să fieîntre zero și zece.

Param( $Attempts)

În exemplul următor, valoarea variabilei $number trebuie să fie betweenzero și zece.,

$number = 5

În exemplul următor, valoarea variabilei $number trebuie să fie mai mare de zero.

$number = 1

ValidateScript validare atribut

ValidateScript atribut specifică un script care este utilizat pentru a valida aparameter sau valoarea variabilei. PowerShell conducte valoarea la script-ul, andgenerates o eroare dacă script-ul se întoarce $false sau dacă script-ul aruncă anexception.,

când utilizați atributul ValidateScript, valoarea care este validată este mapată la variabila $_. Puteți utiliza variabila $_ pentru a vă referi lavaloarea din script.

în exemplul următor, valoarea parametrului EventDate trebuie să fiemai mare sau egală cu data curentă.

Param( $EventDate)

În exemplul următor, valoarea variabilei $date trebuie să fie mai mare sau egală cu data curentă și ora.,

$date = (Get-Date)

ValidateSet atribut

ValidateSet atribut specifică un set de valori valide pentru un parameteror variabilă și permite finalizarea tab. PowerShell generează o eroare dacă aparameter sau valoarea variabilă nu se potrivește cu o valoare din set. În cele ce urmeazăexemplu, valoarea parametrului detaliu poate fi doar scăzută, medie, sauînălțime.,

Param( ] $Detail)

În exemplul următor, valoarea variabilei $flavor trebuie să fie eitherChocolate, Capsuni sau Vanilie.

$flavor = "Strawberry"

validarea are loc ori de câte ori această variabilă este atribuită chiar și în thescript. De exemplu, următoarele rezultate într-o eroare la runtime:

Param( $Message)$Message = "bye"

Dinamic validateSet valori

puteți folosi o Clasă pentru a genera dinamic valorile pentru ValidateSetat de execuție., În următorul exemplu, valorile valide pentru variabila$Sound sunt generate printr-o Clasă de nume SoundNames care verifică threefilesystem căi disponibile pentru fișiere de sunet:

clasa este apoi pus în aplicare ca o dinamică ValidateSet valueas cum urmează:

Param( )] $Sound)

ValidateNotNull validare atribut

ValidateNotNull atribut specifică faptul că valoarea parametrului nu poate fi$null. PowerShell generează o eroare dacă valoarea parametrului este $null.,

ValidateNotNull atribut este conceput pentru a fi utilizat atunci când parametrul isoptional și tipul este nedefinit sau a unui tip converter, care poate’timplicitly converti o valoare nulă ca obiect. Dacă specificați un tip care va converti implicit o valoare nulă, cum ar fi un șir, valoarea nulăeste convertit într-un șir gol chiar și atunci când se utilizează ValidateNotNullattribute. Pentru acest scenariu folosi ValidateNotNullOrEmpty

În exemplul următor, valoarea ID parametru nu poate fi $null.,

Param( $ID)

ValidateNotNullOrEmpty validare atribut

ValidateNotNullOrEmpty atribut specifică faptul că parametrul valuecan nu fi $null și nu poate fi un șir gol (""). PowerShell generează anerror dacă parametrul este utilizat într-un apel de funcție, dar valoarea sa este $null, anempty string (""), sau un array gol @().,

Param( ] $UserName)

ValidateDrive validare atribut

ValidateDrive atribut specifică faptul că valoarea parametrului mustrepresent calea, care se referă la permis numai unități. PowerShellgenerates o eroare în cazul în care valoarea parametrului se referă la alte unități theaallowed. Existența căii, cu excepția unității în sine, nu este verificată.

Dacă utilizați calea relativă, unitatea curentă trebuie să fie în lista de unități permise.,

Param( $Path)

ValidateUserDrive validare atribut

ValidateUserDrive atribut specifică faptul că valoarea parametrului mustrepresent calea, care se referă la User disk. PowerShell generează anerror dacă calea se referă la o unitate diferită. Atributul de validare onlytests pentru existența porțiunii de unitate a căii.

Dacă utilizați calea relativă, unitatea curentă trebuie să fie 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.

puteți defini User cu mașina în Doar Suficient de Administrare (JEA) sessionconfigurations. Pentru acest exemplu, creăm utilizatorul: drive.

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

True

ValidateTrustedData validare atribut

Acest atribut a fost adăugat în PowerShell 6.1.1.în acest moment, atributul este utilizat intern de PowerShell în sine și nu estedestinate utilizării externe.,

parametrii dinamici

parametrii dinamici sunt parametrii unui cmdlet, funcție sau script care suntdisponibile numai în anumite condiții.de exemplu, mai multe cmdleturi ale furnizorului au parametri care sunt disponibili numaicând cmdletul este utilizat în unitatea furnizorului sau într-o anumită cale a unității furnizorului. De exemplu, Codificarea parametru este disponibil peAdd-Content, Get-Content și Set-Content cmdlets numai atunci când este folosit ina sistem de fișiere cu mașina.,de asemenea, puteți crea un parametru care apare numai atunci când este un alt parametrutilizat în comanda funcției sau când un alt parametru are o anumită valoare.parametrii dinamici pot fi folositori, dar folosiți-i numai atunci când este necesar, deoareceele pot fi dificil de descoperit de utilizatori. Pentru a găsi un parametru dinamic, theuser trebuie să fie în provider cale, de a folosi ArgumentList parametru alGet-Command cmdlet-ului, sau de a folosi Calea de parametrul Get-Help.

pentru a crea un parametru dinamic pentru o funcție sau un script, utilizați cuvântul cheie DynamicParam.,

sintaxa este după cum urmează:

DynamicParam {<statement-list>}

În declarația listă, utilizați un If declarație care să precizeze condițiile underwhich parametrul este disponibil în funcție.

utilizațiNew-Object cmdlet pentru a crea aSystem.Managementul.Automatizare.RuntimeDefinedParameter obiect pentru a reprezentaparametrul și specificați numele acestuia.

puteți utiliza o comandă New-Object pentru a crea aSystem.Managementul.Automatizare.,ParameterAttribute obiect să representattributes de parametru, cum ar fi Obligatorie, Poziția, orValueFromPipeline sau set de parametri.

următorul exemplu arată o funcție de probă cu parametrii standard namedName și Path și un parametru dinamic opțional numit DP1. TheDP1 parametru este în PSet1 set de parametri și are un tip de Int32.,La DP1 parametru este disponibil în Get-Sample funcție numai atunci când valoarea tragerilor din Calea parametru începe cu HKLM:, indicând că este beingused în HKEY_LOCAL_MACHINE registru conduce.

Pentru mai multe informații, a se vedeauntimedefinedparameter.

parametrii comutatorului

parametrii comutatorului sunt parametri fără valoare de parametru. Sunt eficiente numai atunci când sunt utilizate și au un singur efect.

de exemplu, parametrul NoProfile al powershell.exe este un parametru de comutare.,

pentru a crea un parametru de comutare într-o funcție, specificați tipul Switch dindefiniția parametrului.

De exemplu:

Param(<ParameterName>)

Sau, puteți utiliza o altă metodă:

Param( $<ParameterName>)

Comutator parametri sunt ușor de utilizat și sunt de preferat peste Boolean parametri,care au o mult mai dificil de sintaxă.

de exemplu, pentru a utiliza un parametru de comutare, utilizatorul introduce parametrul încomandă.

-IncludeAll

pentru a utiliza un parametru Boolean, utilizatorul introduce parametrul și o valoare booleană.,

-IncludeAll:$true

când creați parametrii comutatorului, alegeți cu atenție numele parametrului. Fii sigurcă numele parametrului comunică efectul parametrului utilizatorului.Evitați termeni ambigui, cum ar fi filtru sau maxim care ar putea implica avalue este necesară.

ArgumentCompleter atribut

ArgumentCompleter atribut vă permite să adăugați fila finalizarea valori toa parametru specific. Un atribut ArgumentCompleter trebuie definit pentrufiecare parametru care are nevoie de completarea filei., Similar cu DynamicParameters, valorile disponibile sunt calculate în timpul rulării când utilizatorul apasă Tabafter numele parametrului.

pentru a adăuga un Argumentatributul Completer, trebuie să definiți un bloc de scriptcare determină valorile. Blocul de script trebuie să ia următoareleparametrii în ordinea specificată mai jos. Numele parametrului nu contează asvalorile sunt furnizate pozițional.,

sintaxa este după cum urmează:

ArgumentCompleter bloc de script

bloc de script parametrii sunt setate la următoarele valori:

• $commandName (Poziția 0) – Acest parametru este setat la numele de thecommand pentru care blocul script este furnizarea de finalizarea tab.
• $parameterName (Poziția 1) – Acest parametru este setat la parametrul whosevalue necesită finalizarea tab.
• $wordToComplete (Poziția 2) – Acest parametru este setat la valoarea utilizatorul hasprovided înainte au apăsat Tab., Blocul dvs. de script ar trebui să foloseascăaceastă valoare pentru a determina valorile de finalizare a filelor.
• $commandAst (poziția 3) – acest parametru este setat la Sintaxtree Abstract (AST) pentru linia de intrare curentă. Pentru mai multe informații, a se vedeast Class.
• $fakeBoundParameters (locul 4) – Acest parametru este setat la o hashtablecontaining $PSBoundParameters pentru cmdlet-ului, înainte ca utilizatorul pressedTab. Pentru mai multe informații, a se vedea about_automatic_variables.,

ArgumentCompleter bloc de script-ul trebuie să se deruleze valorile folosind thepipeline, cum ar fi ForEach-Object, Where-Object, sau o altă metodă adecvată.Returnarea unui tablou de valori face ca PowerShell să trateze întreaga valoare de completare a filei asone.

următorul exemplu adaugă completarea filei la parametrul valoare. Dacă este specificat numai parametrul de valoare, sunt afișate toate valorile posibile sau argumentele forValue. Când parametrul Type este specificat, parametrul theValue afișează numai valorile posibile pentru acel tip.,

În plus, -like operatorul se asigură că, dacă utilizatorul tipuri de followingcommand și folosește Fila de finalizare, doar Apple este returnat.

Test-ArgumentCompleter -Type Fruits -Value A

Vezi și

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute