Funcții și param() în PowerShell

function Verb-Substantiv {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)] [tip]$Parametru,
        [tip]$Optional = valoare
    )
    ...
}

Ce face Funcții și param()

Definești o funcție cu function Nume { ... } și o apelezi ca pe orice comandă: Nume -Parametru valoare, fără paranteze și fără virgule între argumente. Parametrii se declară în blocul param( ), cu tip opțional și valoare implicită: [string]$Nume = 'prietene'. Convenția este numele Verb-Substantiv, cu un verb aprobat (lista o vezi cu Get-Verb).

O funcție nu „returnează” doar ce pui după return: orice valoare nefolosită din corpul ei ajunge în ieșire. return doar iese din funcție (opțional cu o valoare). De aceea mesajele pentru utilizator se scriu cu Write-Host sau Write-Verbose, nu ca text liber, dacă nu vrei să le prinzi în rezultat.

Cu [CmdletBinding()] deasupra lui param() funcția devine avansată (din Windows PowerShell 2.0): primește automat parametrii comuni (-Verbose, -ErrorAction, -WhatIf dacă adaugi SupportsShouldProcess) și refuză parametrii necunoscuți. Atributul [Parameter(Mandatory)] face un parametru obligatoriu: dacă lipsește, PowerShell îl cere în consolă. Alte atribute utile: [ValidateSet('Iasi','Cluj')], [ValidateRange(1,10)], [ValidateNotNullOrEmpty()], iar [switch]$Detaliat definește un comutator fără valoare.

Parametri

Parametru	Descriere
function Nume { }	Definește funcția în sesiunea sau scriptul curent.
param( )	Declară parametrii; trebuie să fie prima instrucțiune din funcție (după atribute).
[tip]$P = valoare	Parametru cu tip și valoare implicită.
[CmdletBinding()]	Funcție avansată: parametri comuni (-Verbose, -ErrorAction…).
[Parameter(Mandatory)]	Parametru obligatoriu; forma lungă este Mandatory=$true.
[Parameter(Position=0)]	Parametrul poate fi dat fără nume, pe poziția indicată.
[Parameter(ValueFromPipeline)]	Parametrul primește obiecte din pipeline (folosit cu blocul process { }).
[ValidateSet(...)]	Acceptă doar valorile din listă și le oferă la Tab.
[switch]$Comutator	Parametru fără valoare: prezent înseamnă $true.
return	Iese din funcție; valoarea dată se adaugă la ieșire.

Exemple

Exemplul 1: Funcție cu valoare implicită

Fără argument se folosește valoarea implicită. Apelul nu are paranteze.

function Get-Salut {
    param(
        [string]$Nume = 'prietene'
    )
    "Salut, $Nume!"
}
Get-Salut
Get-Salut -Nume Ana

Ieșire în terminal

Salut, prietene!
Salut, Ana!

Exemplul 2: Funcție avansată cu parametru obligatoriu și -Verbose

[CmdletBinding()] aduce -Verbose; mesajul lui Write-Verbose apare doar când îl ceri.

function Get-Total {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [decimal]$Pret,
        [int]$Cantitate = 1
    )
    Write-Verbose "Calculez $Cantitate x $Pret"
    $Pret * $Cantitate
}
Get-Total -Pret 12.5 -Cantitate 3 -Verbose

Ieșire în terminal

VERBOSE: Calculez 3 x 12.5
37.5

Exemplul 3: Ce se întâmplă când lipsește parametrul obligatoriu

PowerShell oprește apelul și cere valoarea în consolă. Într-un script rulat fără consolă interactivă, apelul eșuează.

Get-Total

Ieșire în terminal

cmdlet Get-Total at command pipeline position 1
Supply values for the following parameters:
Pret:

Greșeli frecvente

• Să apelezi funcția ca în alte limbaje: Get-Total(12.5, 3) trimite un singur argument, un tablou. Scrie Get-Total -Pret 12.5 -Cantitate 3 sau Get-Total 12.5 3.
• Să lași text sau rezultate de metode nefolosite în funcție (de exemplu indexul întors de ArrayList.Add()): ajung în valoarea întoarsă. Pune $null = în față sau folosește Write-Verbose.
• Să apelezi funcția înainte de definiție într-un script: PowerShell citește scriptul de sus în jos, deci definiția trebuie să fie deasupra apelului.
• Să dai unui [switch] valoare implicită $true: documentația recomandă ca un comutator să fie implicit fals.

Comenzi înrudite

• try / catch / finally: try/catch prinde erorile care opresc o comandă, iar finally rulează mereu; pentru erorile obișnuite ale cmdlet-urilor pui -ErrorAction Stop.
• Write-Host / Write-Output: Write-Host scrie text doar pe ecran (cu culori), Write-Output trimite valori în pipeline, unde pot fi salvate într-o variabilă sau prelucrate.
• Variabile și tipuri: Variabilele încep cu $, primesc orice obiect .NET și pot fi legate de un tip ([int], [string], [datetime]); .GetType() arată tipul.
• $PROFILE: Variabila $PROFILE conține calea scriptului care rulează la fiecare pornire a PowerShell, unde îți pui aliasurile și funcțiile.
• Pipeline (|): Operatorul | trimite obiectele unei comenzi, unul câte unul, comenzii următoare; $_ este obiectul curent, iar && și || înlănțuie comenzi.