{{tag>dev powershell}}


====== 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()''**:
<code powershell>
# Début de script aScript.ps1
Param (
  $FirstParam,
  $SecondParam,
  $ThirdParam
)
</code>

<code powershell>
function aFunctionName {
  Param(
    $FirstParam,
    $SecondParam,
    $ThirdParam
  )
  BEGIN{}
  PROCESS{}
  END{}
}

</code>

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.

<code powershell>
# 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
</code>

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 :
<code powershell>
Param (
  [int] $TankID,
  [float] $WaterLevel
)
</code>

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

<code powershell>
Param (
  [int] $TankID,
  [float] $WaterLevel,
  [Switch] $ResetCounters
)

If ($ResetCounters -eq $True)
{
   # L'option -ResetCounters a été saisie lors de l'appel
}
</code>


L'utilisation d'un décorateur permet d'ajouter des attributs aux paramètres :
  * Caractère obligatoire ou non ;
  * Message d'aide

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

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

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

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

<code powershell>
Param(
    [Parameter(Mandatory)]
    [ValidateSet("Low", "Average", "High")]
    [string[]]$Detail
)
</code>

===== 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 [[https://learn.microsoft.com/fr-fr/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-7.3|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 :
<code powershell>
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} )"
}
</code>

L'avantage de ce code est qu'il a un comportement attendu avec les appels suivants :
<code powershell>
aFonctionName
$Verbose = False

aFonctionName -Verbose
$Verbose = True

aFonctionName -Verbose:$false
$Verbose = False

aFonctionName  -Verbose:$true
$Verbose = True
</code>


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

<code powershell>
# 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
</code>


===== Références =====

  * https://learn.microsoft.com/fr-fr/training/modules/use-methods-to-accept-user-inputs-windows-powershell-scripts/6-pass-parameters-script
  * https://aka.ms/about-functions-advanced-parameters