• 2/27/2019
  • 12 minute pentru a citi
    • S
    • s

Scurtă descriere

Descrie modul de a crea și de a folosi funcții în PowerShell.

Long description

o funcție este o listă de declarații PowerShell care are un nume pe care youassign. Când executați o funcție, introduceți numele funcției. Declarațiile din listă rulează ca și cum le-ați fi tastat la promptul de comandă.,funcțiile pot fi la fel de simple ca:

function Get-PowerShellProcess { Get-Process PowerShell }

o funcție poate fi, de asemenea, la fel de complexă ca un cmdlet sau un program de aplicație.la fel ca cmdleturile, funcțiile pot avea parametri. Parametrii pot fi numiți, poziționali, comutați sau parametri dinamici. Parametrii funcției pot fi citițidin linia de comandă sau din conductă.

funcțiile pot returna valori care pot fi afișate, atribuite variabilelor sau transferate altor funcții sau cmdleturi. De asemenea, puteți specifica o valoare returnată folosindcuvântul cheie return., return cuvântul cheie nu afectează sau suprima otheroutput revenit de la funcția dumneavoastră. Cu toate acestea, cuvântul cheie return iese din funcția de la acea linie. Pentru mai multe informații, consultați about_Return.

funcția declarația de listă pot conține diferite tipuri de declarație listswith cuvinte cheie Begin, Process și End. Aceste declarații listshandle de intrare din conducta diferit.

un filtru este un tip special de funcție care utilizează cuvântul cheieFilter.,

funcții pot acționa, de asemenea, ca cmdlets. Puteți crea o funcție care funcționeazăla fel ca un cmdlet fără a utiliza programarea C#. Pentru mai multe informații,consultați about_Functions_Advanced.,

Sintaxa

aceasta este sintaxa pentru o funcție:

O funcție include următoarele elemente:

  • Function cuvinte cheie
  • Un domeniu de aplicare (opțional)
  • Un nume pe care le selectați
  • Orice număr de parametri numit (opțional)
  • Una sau mai multe comenzi PowerShell închise în acolade {}

Pentru mai multe informații despre Dynamicparam cuvinte cheie și parametrii dinamici infunctions, seeabout_Functions_Advanced_Parameters.,

funcții Simple

funcțiile nu trebuie să fie complicate pentru a fi utile. Cel mai simplu functionshave următorul format:

function <function-name> {statements}

De exemplu, următoarea funcție începe PowerShell cu termen asAdministrator opțiune.

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

Pentru a utiliza funcția, tipul: Start-PSAdmin

Pentru a adăuga declarații a funcției, fiecare tip de declarație pe o linie separată, oruse un semi-colon ; pentru a separa declarații.,

de exemplu, următoarea funcție găsește toate fișierele .jpg din Directorul utilizatorului curent care au fost modificate după data de începere.puteți crea un set de instrumente de funcții mici utile. Adăugați aceste funcții la profilul dvs. PowerShell, așa cum este descris în about_Profiles și mai târziu înacest subiect.

nume de funcții

puteți atribui orice nume unei funcții, dar funcțiile pe care le partajați cualtele ar trebui să respecte regulile de denumire stabilite pentru comenzile allPowerShell.,numele funcțiilor ar trebui să fie format dintr-o pereche verb-substantiv în care verbulidentifică acțiunea pe care o îndeplinește funcția și substantivul identifică elementul pe care cmdletul își îndeplinește acțiunea.funcțiile trebuie să utilizeze verbele standard care au fost aprobate pentru comenzile allPowerShell. Aceste verbe ne ajută să ne păstrăm numele de comandăsimplu, consecvent și ușor de înțeles de către utilizatori.

Pentru mai multe informații despre verbele PowerShell standard, consultați verbele Aprobateîn Microsoft Docs.,

funcții cu parametrii

puteți utiliza parametrii cu funcții, inclusiv parametrii numiți, parametrii poziționalparametrii, parametrii comutatorului și parametrii dinamici. Pentru mai multe informațiidespre parametrii dinamici în funcții, a se vedeaabout_functions_advanced_parameters.

parametrii numiți

puteți defini orice număr de parametri numiți. Puteți include o valoare implicităpentru parametrii numiți, așa cum este descris mai târziu în acest subiect.,

puteți defini parametrii în interiorul acolade folosind Param cuvinte cheie, după cum se arată în următorul exemplu de sintaxa:

function <name> { param ($parameter1$parameter2]) <statement list>}

de asemenea, puteți defini parametrii în afara bretele fără Param cuvinte cheie,așa cum se arată în următorul exemplu de sintaxă:

function <name> $parameter1$parameter2])] { <statement list>}

mai Jos este un exemplu de această sintaxă alternativă.

Function Add-Numbers($one, $two) { $one + $two}

în timp ce prima metodă este preferată, nu există nicio diferență între aceste douămetode.,

când executați funcția, valoarea pe care o furnizați pentru un parametru este atribuităo variabilă care conține numele parametrului. Valoarea acestei variabile poate fiutilizat în funcție.

următorul exemplu este o funcție numită Get-SmallFiles. Această funcțieare un parametru $Size., Funcția afișează toate fișierele care sunt mai mic de valoarea $Size parametru, și exclude directoare:

function Get-SmallFiles { Param($Size) Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer }}

În funcție, puteți folosi $Size variabilă, care este numele definite pentru parametru.pentru a utiliza această funcție, tastați următoarea comandă: 

Get-SmallFiles -Size 50

de asemenea, puteți introduce o valoare pentru un parametru numit fără numele parametrului.,De exemplu, următoarea comandă dă același rezultat ca și o comandă thatnames Dimensiunea parametru:

Get-SmallFiles 50

Pentru a defini o valoare implicită pentru un parametru, tastați un semn egal și valueafter numele parametrului, așa cum se arată în următoarea variație aGet-SmallFiles exemplu:

function Get-SmallFiles ($Size = 100) { Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer }}

Dacă tastați Get-SmallFiles fără o valoare, funcția atribuie 100 la$size. Dacă furnizați o valoare, funcția utilizează această valoare.,

Opțional, puteți oferi o scurtă ajuta șir care descrie defaultvalue de parametru, prin adăugarea PSDefaultValue atribut pentru a thedescription de parametru, și specificarea Ajuta proprietate ofPSDefaultValue. Pentru a oferi un ajutor șir care descrie valoarea implicită(100) a Dimensiunea parametru în Get-SmallFiles function, se adaugă thePSDefaultValue atribut așa cum se arată în următorul exemplu.

function Get-SmallFiles { param ( $Size = 100 )}

Pentru mai multe informații despre PSDefaultValue atribut de clasă, seePSDefaultValue Atribut Membri.,

parametri poziționali

un parametru pozițional este un parametru fără un nume de parametru. PowerShell utilizează ordinea valorii parametrului pentru a asocia fiecare valoare a parametrului cu un parametru în funcție.

când utilizați parametrii poziționali, tastați una sau mai multe valori după numele funcției. Valorile parametrilor poziționali sunt atribuite variabilei matrice$args.Valoarea care urmează numele funcției este atribuită primei poziții în $argsarray,$args.,

următoarele Get-Extension funcția adaugă .txt extensie de nume de fișier pentru un fișierul numele de aprovizionare:

function Get-Extension { $name = $args + ".txt" $name}
Get-Extension myTextFile
myTextFile.txt

Comutator Parametrii

Un comutator este un parametru care nu are nevoie de o valoare. În schimb, tastaținumele funcției urmat de numele parametrului switch.,

Pentru a defini un comutator parametru, specificați tipul înainte de parametername, așa cum se arată în următorul exemplu:

function Switch-Item { param ($on) if ($on) { "Switch on" } else { "Switch off" }}

atunci Când tastați On parametrul comutatorul de după numele funcției, functiondisplays „activat”. Fără parametrul de comutare, se afișează „opriți”.,

Switch-Item -on
Switch on
Switch-Item
Switch off

de asemenea, puteți atribui o valoare Booleană la un comutator atunci când executați funcția, după cum se arată în următorul exemplu:

Switch-Item -on:$true
Switch on
Switch-Item -on:$false
Switch off

Utilizarea Splatting pentru a Reprezenta Parametrii de Comandă

puteți folosi splatting pentru a reprezenta parametrii de comandă. Această caracteristicăeste introdus în Windows PowerShell 3.0.utilizați această tehnică în funcțiile care apelează comenzi în sesiune., Nutrebuie să declarați sau să enumerați parametrii comenzii sau să modificați funcțiaatunci când parametrii comenzii se schimbă.

următoarea funcție eșantion apeleazăGet-Command cmdlet. Comanda foloseste@Args pentru a reprezenta parametrii Get-Command.

function Get-MyCommand { Get-Command @Args }

puteți folosi toate parametrii de Get-Command când te chemGet-MyCommand function. Parametrii și valorile parametrilor sunt transmise cătrecomandă utilizând @Args.,

Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName----------- ---- ----------Cmdlet Get-ChildItem Microsoft.PowerShell.Management

@Args caracteristică utilizează $Args automata parametru, care representsundeclared cmdlet parametrii și valorile de la celelalte argumente.

Pentru mai multe informații despre splatting, consultați about_Splatting.

obiecte de conducte la funcții

orice funcție poate lua de intrare de la conducta. Puteți controla modul în care un functionprocesses de intrare de la conducta folosind Begin, Process și Endcuvinte cheie., Următorul exemplu de sintaxa arată cele trei cuvinte cheie:

function <name> { begin {<statement list>} process {<statement list>} end {<statement list>}}

Begin declarație listă se execută o singură dată, la începutul thefunction.

Important

Dacă funcția definește un Begin, Process sau End bloc, toate codemust locuiesc în acele blocuri. Nici un cod nu va fi recunoscut în afara blocurilordacă oricare dintre blocuri sunt definite.

lista de instrucțiuni Process rulează o singură dată pentru fiecare obiect din conductă.,În timp ce blocul Process rulează, fiecare obiect de conductă este atribuit variabilei automate$_, un obiect de conductă la un moment dat.

după ce funcția primește toate obiectele din conductă, lista de instrucțiuni Endrulează o singură dată. Dacă nu Begin, Process sau End keywordsare folosit, toate declarațiile sunt tratat ca un End declarație listă.

următoarea funcție utilizează cuvântul cheieProcess., Funcția displaysexamples din conducta:

function Get-Pipeline{ process {"The value is: $_"}}

Pentru a demonstra această funcție, introduceți o listă de numere separate prin virgule, după cum se arată în următorul exemplu:

1,2,4 | Get-Pipeline
The value is: 1The value is: 2The value is: 4

atunci Când utilizați o funcție într-o conductă, obiectele adus la funcția areassigned la $input automată variabilă. Funcția rulează declarații cuBegin cuvinte cheie înainte ca orice obiecte să provină din conductă., Funcția runsstatements cu End cuvinte cheie după ce toate obiectele au fost primite de la conducte.

următorul exemplu arată $input automată variabilă cu Begin șiEnd cuvinte cheie.

function Get-PipelineBeginEnd{ begin {"Begin: The input is $input"} end {"End: The input is $input" }}

Dacă această funcție este de a rula prin utilizarea conductei, se afișează followingresults:

1,2,4 | Get-PipelineBeginEnd
Begin: The input isEnd: The input is 1 2 4

Begin declarație ruleaza, funcția nu are intrare de la thepipeline., Instrucțiunea End rulează după ce funcția are valorile.

Dacă funcția are un Process cuvinte cheie, fiecare obiect în $input este removedfrom $input și atribuite $_. Următorul exemplu are un Processdeclarație de lista:

function Get-PipelineInput{ process {"Processing: $_ " } end {"End: The input is: $input" }}

În acest exemplu, fiecare obiect care este adus la funcția este trimis laProcess declarație listă. Declarațiile Process rulează pe fiecare obiect, unobject la un moment dat., $input automată variabilă este gol, atunci când functionreaches End cuvinte cheie.

1,2,4 | Get-PipelineInput
Processing: 1Processing: 2Processing: 4End: The input is:

Pentru mai multe informații, consultați Utilizarea Recenzorii

Filtru

Un filtru este un tip de funcție care ruleaza pe fiecare obiect în conducte. Afilter seamănă cu o funcție cu toate declarațiile sale într-un bloc Process.,

sintaxa unui filtru este după cum urmează:

filter <name> {<statement list>}

următorul filtru nevoie de intrări de jurnal de conducta si apoi displayseither la intrarea întreg sau doar mesajul porțiunea de intrare:

filter Get-ErrorLog ($message){ if ($message) { Out-Host -InputObject $_.Message } else { $_ }}

Funcție de domeniul de Aplicare

O funcție există în domeniul în care a fost creat.

dacă o funcție face parte dintr-un script, funcția este disponibilă pentru statementswithin acel script. În mod implicit, o funcție dintr-un script nu este disponibilă la promptul de comandă.

puteți specifica domeniul de aplicare al unei funcții., De exemplu, funcția este adăugată ladomeniul global în următorul exemplu:

function global:Get-DependentSvs { Get-Service | Where-Object {$_.DependentServices}}

când o funcție este în domeniul global,puteți utiliza funcția în scripturi, în funcții și la linia de comandă.

funcțiile creează în mod normal un domeniu de aplicare. Elementele create într-o funcție, cum ar fivariabile, există numai în domeniul funcției.

Pentru mai multe informații despre domeniul de aplicare în PowerShell, a se vedeaabout_scopes.,

Găsirea și Gestionarea Funcții Utilizarea Funcției: Conduce

Toate funcțiile și filtre în PowerShell sunt automat storedin Function: disk. Această unitate este expusă de furnizorul PowerShellFunction.

atunci Când se referă la Function: disk, tastați un colon după Funcție, așa cum ai face atunci când face referire la C sau D drive-ul unui computer.,

următoarea comandă afișează toate funcțiile în actuala sesiune ofPowerShell:

Get-ChildItem function:

comenzile în funcție sunt stocate ca un bloc de script în definitionproperty din funcție. De exemplu, pentru a afișa comenzile din Helpfunction care vine cu PowerShell, tip:

(Get-ChildItem function:help).Definition

de asemenea, puteți folosi următoarea sintaxă.

$function:help

Pentru mai multe informații despre Function: disk, consultați ajutorul topicfor Funcția furnizor. Tip Get-Help Function.,

reutilizarea funcțiilor în sesiuni noi

când tastați o funcție la promptul de comandă PowerShell, funcția devine parte a sesiunii curente. Este disponibil până la sfârșitul sesiunii.pentru a utiliza funcția în toate sesiunile PowerShell, adăugați funcțiala profilul PowerShell. Pentru mai multe informații despre profiluri,consultați about_Profiles.de asemenea, puteți salva funcția într-un fișier script PowerShell. Tip yourfunction într-un fișier text, apoi salvați fișierul cu .ps1 fișier nameextension.,

scrierea ajutor pentru funcții

Get-Help cmdlet devine ajutor pentru funcții, precum și pentru cmdlets, furnizori, și script-uri. Pentru a obține ajutor pentru o funcție, tastați Get-Help followedby numele funcției.

De exemplu, pentru a obține ajutor pentru Get-MyDisks funcția, tip:

Get-Help Get-MyDisks

puteți scrie ajuta pentru o funcție prin utilizarea fie a doi followingmethods:

  • Comentariu pe bază de Ajutor pentru Funcțiile

    de a Crea un subiect de ajutor folosind cuvinte cheie speciale în comentarii., Pentru a crea ajutor bazat pe comment pentru o funcție, comentariile trebuie plasate laînceputul sau sfârșitul corpului funcției sau pe liniile care preced cuvântul funcțional. Pentru mai multe informații despre ajutorul bazat pe comentarii, a se vedeaabout_comment_based_help.

  • ajutor bazat pe XML pentru funcții

    creați un subiect de ajutor bazat pe XML, cum ar fi tipul care este de obicei createdfor cmdlets. Ajutorul bazat pe XML este necesar dacă localizați subiecte de ajutor în mai multe limbi.

    pentru a asocia funcția cu subiectul de ajutor bazat pe XML, utilizați cuvântul cheie de ajutor bazat pe comentarii.ExternalHelp., Fără acest cuvânt cheie, Get-Helpnu poate găsi funcția de subiect de ajutor și solicită să Get-Help pentru functionreturn numai generate de auto-ajutor.

    Pentru mai multe informații despre cuvântul cheie ExternalHelp, a se vedeaabout_comment_based_help. Pentru mai multe informațiidespre ajutor bazat pe XML, a se vedeacum se scrie ajutor Cmdlet.

A se vedea, de asemenea,

about_Automatic_Variables