Partager via

à_propos_des_Commentaires

  • Article

Brève description

Décrit comment utiliser des commentaires PowerShell et répertorie des cas d’usage spéciaux.

Description longue

Vous pouvez écrire des commentaires pour annoter ou structurer votre code PowerShell pour faciliter la lisibilité. Lorsque votre code est exécuté, le texte de commentaire est ignoré par PowerShell.

Les commentaires fournissent un contexte important aux lecteurs du code. Vous devez utiliser des commentaires à des fins suivantes :

  • Expliquer le code complexe en termes plus simples
  • Expliquer pourquoi une approche particulière a été choisie
  • Documenter les cas extrêmes à prendre en compte
  • Fournir des liens vers des documents de référence à l'appui

Certains commentaires ont une signification particulière dans PowerShell. Voir Commentaires spéciaux.

Styles de commentaires PowerShell

PowerShell prend en charge deux styles de commentaire :

  • Les commentaires à ligne unique commencent par le caractère de hachage (#) et se terminent par une nouvelle ligne. La # peut être précédée d’un texte qui ne fait pas partie du commentaire, y compris l’espace blanc. Les commentaires à ligne unique placés sur la même ligne que le code source non commenté sont appelés commentaires de fin de ligne.

  • Bloquer les commentaires commencent par <# et se terminent par #>. Un commentaire de bloc peut s’étendre sur n’importe quel nombre de lignes et peut être inclus avant, après ou au milieu du code source non commenté. Tout le texte dans le bloc est traité dans le cadre du même commentaire, y compris les espaces blancs.

    Important

    Vous pouvez inclure des commentaires à ligne unique dans un commentaire de bloc. Toutefois, vous ne pouvez pas imbriquer les commentaires de bloc. Si vous tentez d’imbriquer les commentaires de bloc, le commentaire de bloc externe se termine au premier #> rencontré.

Exemples

Exemple 1 : commentaire à ligne unique

# This is a single-line comment.
# This is also a single-line comment.

Exemple 2 : Bloquer le commentaire

<#
    This is a block comment.
    Text within the block is a part of the same comment.
Whitespace is unimportant in a block comment.
#>

Exemple 3 : commentaire de fin de ligne

$var = 4 # This is an end-of-line comment

Exemple 4 : commentaire de bloc inline

'Foo'; <# This is an inline block comment #> 'Bar'

Exemple 5 : Exemple complet

<#
    .DESCRIPTION
    Demonstrates PowerShell's different comment styles.
#>
param (
    [string] $Param1, # End-of-line comment
    <# Inline block comment #> $Param2
)

$var = 1, <# Inline block comment #> 2, 2

# Single-line comment.
# Another single-line comment.
$var.Where(
    <# Arg1 note #> { $_ -eq 2 },
    <# Arg2 note #> 'First',
    <# Arg3 note #> 1
)

Commentaires spéciaux

PowerShell inclut plusieurs mots clés de commentaire pour prendre en charge des utilisations spécifiques.

Aide basée sur les commentaires

Vous pouvez écrire du contenu d’aide basé sur des commentaires pour les fonctions et les scripts à l’aide de commentaires monolignes ou de blocs. Les utilisateurs peuvent utiliser l’applet de commande Get-Help pour afficher l’aide basée sur les commentaires pour une fonction ou un script. PowerShell définit 15 mots clés de commentaire qui peuvent être utilisés pour fournir des informations telles que la description et l’exemple d’utilisation.

<#
    .DESCRIPTION
    Comment-based help using a block comment.
#>
function Get-Function { }

# .DESCRIPTION
# Comment-based help using multiple single-line comments.
function Get-Function { }

Pour plus d’informations, consultez :

#Requires

L’instruction #Requires empêche l’exécution d’un script, sauf si la session PowerShell actuelle répond aux conditions préalables spécifiées. #Requires peut apparaître sur n’importe quelle ligne d’un script, mais elle est traitée de la même manière, quelle que soit la position.

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0

param (
    [Parameter(Mandatory)]
    [string[]] $Path
)

Pour plus d’informations, consultez about_Requires.

Bloc de signature

Les scripts peuvent être signés afin qu’ils soient conformes aux stratégies d’exécution PowerShell. Une fois signé, un bloc de signature est ajouté à la fin d’un script. Ce bloc prend la forme de plusieurs commentaires à ligne unique, qui sont lus par PowerShell avant l’exécution du script.

# SIG # Begin signature block
# ...
# SIG # End signature block

Pour plus d'informations, consultez about_signing.

Shebang

Dans les systèmes de type Unix, un shebang (#!) est une directive utilisée au début d’un script pour indiquer quel interpréteur de commandes doit être utilisé pour exécuter le script. Shebang ne fait pas partie du langage PowerShell. PowerShell l’interprète comme un commentaire régulier. Shebang est interprété par le système d’exploitation.

Dans l’exemple suivant, le shebang garantit que PowerShell exécute le script lorsque le script est appelé à partir d’un contexte non-PowerShell.

#!/usr/bin/env pwsh
Write-Host 'Begin script'

Marqueurs de région de l’éditeur de code

Certains éditeurs de code prennent en charge les marqueurs de région qui vous permettent de réduire et de développer des sections de code. Pour PowerShell, les marqueurs de région sont des commentaires qui commencent par #region et se terminent par #endregion. Les marqueurs de région doivent être au début d’une ligne. Les marqueurs de région sont pris en charge dans PowerShell ISE et dans Visual Studio Code avec l’extension PowerShell. Les marqueurs de région ne font pas partie du langage PowerShell. PowerShell les interprète comme des commentaires réguliers.

Pour plus d'informations, consultez la section Pliage de la documentation Édition de base dans Visual Studio Code.

Commentaires dans les jetons de chaîne

# et <# #> n'ont pas de signification particulière dans une chaîne extensible ou verbatim. PowerShell interprète littéralement les caractères.

PS> '# This is not interpreted as a comment.'
# This is not interpreted as a comment.

PS> "This is <# also not interpreted #> as a comment."
This is <# also not interpreted #> as a comment.

Toutefois, certaines fonctionnalités PowerShell sont conçues pour fonctionner avec des chaînes qui contiennent des commentaires. L’interprétation du commentaire dépend de la fonctionnalité spécifique.

Commentaires dans une expression régulière

Les expressions régulières (regex) dans PowerShell utilisent le moteur regex .NET , qui prend en charge deux styles de commentaire :

  • Commentaire inline ((?#))
  • Commentaire de fin de ligne (#)

Les commentaires de regex sont pris en charge par toutes les fonctionnalités basées sur regex dans PowerShell. Par exemple:

PS> 'book' -match '(?# This is an inline comment)oo'
True

PS> 'book' -match '(?x)oo# This is an end-of-line comment'
True

PS> $regex = 'oo # This is an end-of-line comment'
PS> 'book' -split $regex, 0, 'IgnorePatternWhitespace'
b
k

Remarque

Un commentaire regex de fin de ligne nécessite la construction (?x) ou l’option IgnorePatternWhitespace.

Pour plus d’informations, consultez :

Commentaires JSON

À compter de PowerShell 6.0, l’applet de commande ConvertFrom-Json prend en charge les styles de commentaires JSON suivants :

  • Commentaire à ligne unique (//)
  • Bloquer le commentaire (/* */)

Remarque

L’applet de commande Invoke-RestMethod désérialise automatiquement les données JSON reçues. Dans PowerShell 6.0, les commentaires sont autorisés dans les données JSON.

Par exemple:

'{
    "Foo": "Bar" // This is a single-line comment
}' | ConvertFrom-Json

Foo
---
Bar

Avertissement

Depuis PowerShell 7.4, l’applet de commande Test-Json ne prend plus en charge JSON avec des commentaires. Une erreur est retournée si le json inclut des commentaires. Dans les versions prises en charge antérieures à la version 7.4, Test-Json analyse correctement JSON avec des commentaires. Dans PowerShell 7.5, Test-Json inclut une option permettant d’ignorer les commentaires JSON.

Commentaires CSV

Import-Csv et ConvertFrom-Csv prennent en charge le format de journal étendu W3C. Les lignes commençant par le caractère de hachage (#) sont traitées comme des commentaires et ignorées, sauf si le commentaire commence par #Fields: et contient la liste délimitée des noms de colonnes. Dans ce cas, l’applet de commande utilise ces noms de colonnes. Il s’agit du format standard pour Windows IIS et d’autres journaux de serveur web. Pour plus d’informations, consultez le Format de Fichier Journal Étendu .

@'
# This is a CSV comment
Col1,Col2
Val1,Val2
'@ | ConvertFrom-Csv

Col1 Col2
---- ----
Val1 Val2

Dans Windows PowerShell 5.1, le comportement par défaut d'Export-Csv et de ConvertTo-Csv est d'inclure des informations de type sous la forme d'un commentaire#TYPE. À compter de PowerShell 6.0, la valeur par défaut n’est pas d’inclure le commentaire, mais elle peut être remplacée par le paramètre IncludeTypeInformation.

[pscustomobject] @{ Foo = 'Bar' } | ConvertTo-Csv -IncludeTypeInformation

#TYPE System.Management.Automation.PSCustomObject
"Foo"
"Bar"

Lorsqu’un commentaire #TYPE est inclus dans les données CSV, Import-Csv et ConvertFrom-Csv utilisez ces informations pour définir la propriété pstypenames des objets désérialisés.

class Test { $Foo = 'Bar' }
$test = [Test]::new()

$var = $test | ConvertTo-Csv -IncludeTypeInformation | ConvertFrom-Csv
$var.pstypenames

Test
CSV:Test

Commentaires ConvertFrom-StringData

Dans ses données de chaîne, la cmdlet ConvertFrom-StringData traite les lignes commençant par # comme des commentaires. Pour plus d’informations, consultez :

Notes

  • Les commentaires de bloc ne peuvent pas être imbriqués. Dans l’exemple suivant, Baz ne fait pas partie du commentaire.

    <#
'Foo'
<# 'Bar' #>
'Baz'
#>

  • <# #> n’a aucune signification particulière dans un commentaire à une seule ligne. # n’a aucune signification particulière dans un commentaire de bloc.

  • Pour être traité en tant que commentaire, le caractère de commentaire ne doit pas faire partie d’un jeton sans commentaire. Dans l’exemple suivant, #Bar et <#Bar#> font partie du jeton Foo.... Par conséquent, ils ne sont pas traités comme des commentaires.

    PS> Foo#Bar
Foo#Bar: The term 'Foo#Bar' is not recognized as a name [...]

PS> Foo<#Bar#>
Foo<#Bar#>: The term 'Foo<#Bar#>' is not recognized as a name [...]