Différences

Ci-dessous, les différences entre deux révisions de la page.

--- dev:powershell:parametres [2023/06/13 10:30] – créée yoann
+++ dev:powershell:parametres [2023/08/27 19:50] (Version actuelle) – yoann
@@ Ligne 2: / Ligne 2: @@
-====== PowerShell : Utiliser des paramètres ======
+====== PowerShell : Utiliser des paramètres nommés ======
-Pour plus de flexibilité, les scripts peuvent accepter des paramètres.
+Pour plus de flexibilité, les scripts et les fonctions peuvent accepter des paramètres nommés.
-On déclare les paramètres en début de script avec l'appel de **''Param()''**:
+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 (
-  $aFirstParam,
+  $FirstParam,
-  $aSecondParam,
+  $SecondParam,
-  $aThirdParam
+  $ThirdParam
 )
 </code>
-Param() recoit des variables, elles peuvent être fortement typées :
+<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 (
@@ Ligne 22: / Ligne 50: @@
 )
 </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 :
@@ Ligne 33: / Ligne 77: @@
 )
 </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

wikinotes

Outils pour utilisateurs

Outils du site

Différences

Outils de la page