PowerShell : Utiliser des paramètres nommés

Pour plus de flexibilité, les scripts et les fonctions peuvent accepter des paramètres nommés.

On déclare les paramètres nommés en début de script ou de fonction avec le bloc Param():

# Début de script aScript.ps1
Param (
  $FirstParam,
  $SecondParam,
  $ThirdParam
)

function aFunctionName {
  Param(
    $FirstParam,
    $SecondParam,
    $ThirdParam
  )
  BEGIN{}
  PROCESS{}
  END{}
}

Avec des paramètres déclarés ainsi, l'utilisateur peut appeler le script et bénéficier de l'autocomplétion sur les options de la même manière que pour les cmdlets.

# Appel du script avec les paramètres nommés :
aScript.ps1 -FirstParam aValue1 -SecondParam aValue2 -ThirdParam aValue3
 
# On appelle une fonction de la même manière
aFunctionName -FirstParam aValue1 -SecondParam aValue2 -ThirdParam aValue3

S'il n'y a pas de bloc Param() en début de script les données fournies au script à l’exécution sont tout de même accessible dans la variable $args.

Param() reçoit des variables, elles peuvent être fortement typées :

Param (
  [int] $TankID,
  [float] $WaterLevel
)

Le type Switch permet de facilement tester si une option a été fournie lors de l'appel

Param (
  [int] $TankID,
  [float] $WaterLevel,
  [Switch] $ResetCounters
)
 
If ($ResetCounters -eq $True)
{
   # L'option -ResetCounters a été saisie lors de l'appel
}

L'utilisation d'un décorateur permet d'ajouter des attributs aux paramètres :

Caractère obligatoire ou non ;
Message d'aide

Param (
  [Parameter(Mandatory, HelpMessage = 'Cistern identidier')] [int] $TankID,
  [Parameter(Mandatory, HelpMessage = 'Water level in meters') ][float] $WaterLevel
)

Pour ajouter de l'aide sur le paramètre, il existe l'attribut PSDefaultValue

Param(
   [Parameter(Mandatory, HelpMessage = 'Cistern identidier')]
   [PSDefaultValue(Help='Current directory', Value=102)]
   [int] $TankID = 102
)

On peut également introduire des tests de validation des paramètres. La validation peut s'appliquer aux variables en général

Param(
    [Parameter(Mandatory)]
    [ValidateSet("Low", "Average", "High")]
    [string[]]$Detail
)

Utiliser les paramètres courants

Les fonctions nommées peuvent hériter des paramètres courants comme -Verbose ou -Debug. Pour une informations exhaustive confère A propos des paramètres courants (Microsoft Learn).

Dans l'exemple ci-dessous on exploite le paramètre courant -Verbose dans une fonction nommée :

function aFonctionName {
  Param(
    # Nécessaire pour lier les paramètres courants
    [CmdletBinding()]
  )
 
  # Affiche un message avec la valeur de l'option Verbose si elle est positionnée, false sinon.
   Write-Host "`$Verbose = $( if ( $PSBoundParameters.ContainsKey('Verbose') ){$PSBoundParameters['Verbose']}else{$false} )"
}

L'avantage de ce code est qu'il a un comportement attendu avec les appels suivants :

aFonctionName
$Verbose = False
 
aFonctionName -Verbose
$Verbose = True
 
aFonctionName -Verbose:$false
$Verbose = False
 
aFonctionName  -Verbose:$true
$Verbose = True

Les variables $PSCmdlet.MyInvocation.BoundParameters et $PSBoundParameters référencent le même objet : on peut les utiliser indifféremment :

# Tester la présence du paramètre courant Verbose
$PSCmdlet.MyInvocation.BoundParameters["Verbose"].IsPresent
$PSCmdlet.MyInvocation.BoundParameters.ContainsKey('Verbose')
 
$PSBoundParameters["Verbose"].IsPresent
$PSBoundParameters.ContainsKey('Verbose')
 
 
# Accéder à la valeur du paramètre courant Verbose
$PSCmdlet.MyInvocation.BoundParameters['Verbose']
$PSBoundParameters['Verbose']
$PSBoundParameters.Item('Verbose')
$PSBoundParameters.verbose

Références

wikinotes

Outils pour utilisateurs

Outils du site

Table des matières

PowerShell : Utiliser des paramètres nommés

Utiliser les paramètres courants

Références

Outils de la page