Leer en inglés

Compartir a través de

about_Comments

  • Artículo

Descripción breve

Describe cómo usar comentarios de PowerShell y enumera casos de uso especiales.

Descripción larga

Puede escribir comentarios para anotar o estructurar el código de PowerShell para ayudar con la legibilidad. Cuando se ejecuta el código, PowerShell omite el texto del comentario.

Los comentarios proporcionan contexto importante a los lectores del código. Debe usar comentarios para los siguientes fines:

  • Explicar código complejo en términos más sencillos
  • Explicar por qué se eligió un enfoque determinado
  • Casos perimetrales de documentos que se deben tener en cuenta
  • Proporcionar vínculos a material de referencia auxiliar

Algunos comentarios tienen un significado especial en PowerShell. Consulte comentarios especiales.

Estilos de comentario de PowerShell

PowerShell admite dos estilos de comentario:

  • comentarios de una sola línea comenzar con el carácter hash (#) y terminar con una nueva línea. El # puede ir precedido por texto que no forma parte del comentario, incluido el espacio en blanco. Los comentarios de una sola línea colocados en la misma línea que el código fuente sin comentario se conocen como comentarios de fin de línea.

  • Bloquear comentarios comenzar con <# y terminar con #>. Un comentario de bloque puede abarcar cualquier número de líneas y se puede incluir antes, después o en medio del código fuente sin comentario. Todo el texto del bloque se trata como parte del mismo comentario, incluido el espacio en blanco.

    Importante

    Puede incluir comentarios de una sola línea dentro de un comentario de bloque. Sin embargo, no se pueden anidar comentarios en bloques. Si intenta anidar comentarios de bloque, el comentario del bloque externo termina en el primer #> encontrado.

Ejemplos

Ejemplo 1: Comentario de una sola línea

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

Ejemplo 2: Bloquear comentario

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

Ejemplo 3: Comentario de fin de línea

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

Ejemplo 4: Comentario de bloque insertado

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

Ejemplo 5: Ejemplo completo

PowerShell 
<#
    .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
)

Comentarios especiales

PowerShell incluye varias palabras clave de comentario para admitir usos específicos.

Ayuda basada en comentarios

Puede escribir contenido de ayuda basado en comentarios para funciones y scripts mediante comentarios de una sola línea o de bloque. Los usuarios pueden usar el cmdlet Get-Help para ver la ayuda basada en comentarios de una función o script. PowerShell define 15 palabras clave de comentario que se pueden usar para proporcionar información como la descripción y el uso de ejemplo.

PowerShell 
<#
    .DESCRIPTION
    Comment-based help using a block comment.
#>
function Get-Function { }
PowerShell 
# .DESCRIPTION
# Comment-based help using multiple single-line comments.
function Get-Function { }

Para obtener más información, consulte:

#Requires

La instrucción #Requires impide que se ejecute un script a menos que la sesión de PowerShell actual cumpla los requisitos previos especificados. #Requires puede aparecer en cualquier línea de un script, pero se procesa de la misma manera independientemente de la posición.

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

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

Para obtener más información, vea about_Requires.

Bloque de firma

Los scripts se pueden firmar para que cumplan las directivas de ejecución de PowerShell. Una vez firmado, se agrega un bloque de firma al final de un script. Este bloque toma la forma de varios comentarios de una sola línea, que PowerShell lee antes de ejecutar el script.

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

Para obtener más información, vea about_signing.

Tinglado

En sistemas similares a Unix, un shebang (#!) es una directiva que se usa al principio de un script para indicar qué shell se debe usar para ejecutar el script. Shebang no forma parte del lenguaje de PowerShell. PowerShell lo interpreta como un comentario normal. Shebang es interpretado por el sistema operativo.

En el ejemplo siguiente, shebang garantiza que PowerShell ejecute el script cuando se invoca el script desde un contexto que no es de PowerShell.

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

Marcadores de región del editor de código

Algunos editores de código admiten marcadores de región que permiten contraer y expandir secciones de código. Para PowerShell, los marcadores de región son comentarios que comienzan por #region y terminan con #endregion. Los marcadores de región deben estar al principio de una línea. Los marcadores de región se admiten en PowerShell ISE y en Visual Studio Code con la extensión de PowerShell. Los marcadores de región no forman parte del lenguaje de PowerShell. PowerShell los interpreta como comentarios normales.

Para obtener más información, consulte la sección Plegado de la Edición básica en Visual Studio Code documentación.

Comentarios en tokens de cadena

# y <# #> no tienen un significado especial dentro de un expandible o cadena textual. PowerShell interpreta literalmente los caracteres.

PowerShell 
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.

Sin embargo, algunas características de PowerShell están diseñadas para trabajar con cadenas que contienen comentarios. La interpretación del comentario depende de la característica específica.

Comentarios de expresiones regulares

Las expresiones regulares (regex) de PowerShell usan el motor regex de .NET , que admite dos estilos de comentario:

  • Comentario insertado ((?#))
  • Comentario de fin de línea (#)

Los comentarios regex son compatibles con todas las características basadas en regex en PowerShell. Por ejemplo:

PowerShell 
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

Nota

Un comentario regex de fin de línea requiere la construcción (?x) o la opción IgnorePatternWhitespace.

Para obtener más información, consulte:

Comentarios JSON

A partir de PowerShell 6.0, el cmdlet ConvertFrom-Json admite los siguientes estilos de comentario JSON:

  • Comentario de una sola línea (//)
  • Bloquear comentario (/* */)

Nota

El cmdlet Invoke-RestMethod deserializa automáticamente los datos JSON recibidos. En PowerShell 6.0 y versiones posteriores, se permiten comentarios en los datos JSON.

Por ejemplo:

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

Advertencia

A partir de PowerShell 7.4, el cmdlet Test-Json ya no admite JSON con comentarios. Se devuelve un error si el JSON incluye comentarios. En versiones compatibles anteriores a la versión 7.4, Test-Json analiza correctamente JSON con comentarios. En PowerShell 7.5, Test-Json incluye una opción para omitir los comentarios JSON.

Comentarios CSV

Import-Csv y ConvertFrom-Csv admiten el formato de registro extendido W3C. Las líneas que comienzan con el carácter hash (#) se tratan como comentarios y se omiten a menos que el comentario comience con #Fields: y contenga una lista delimitada de nombres de columna. En ese caso, el cmdlet usa esos nombres de columna. Este es el formato estándar para Windows IIS y otros registros de servidor web. Para obtener más información, vea formato de archivo de registro extendido.

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

En Windows PowerShell 5.1, el export-csv predeterminado y comportamiento de ConvertTo-Csv consiste en incluir información de tipo en forma de comentario #TYPE. A partir de PowerShell 6.0, el valor predeterminado no es incluir el comentario, pero esto se puede invalidar con el parámetro IncludeTypeInformation.

PowerShell 
[pscustomobject] @{ Foo = 'Bar' } | ConvertTo-Csv -IncludeTypeInformation
Output 
#TYPE System.Management.Automation.PSCustomObject
"Foo"
"Bar"

Cuando se incluye un comentario #TYPE en datos CSV, Import-Csv y ConvertFrom-Csv usar esta información para establecer la propiedad pstypenames de los objetos deserializados.

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

$var = $test | ConvertTo-Csv -IncludeTypeInformation | ConvertFrom-Csv
$var.pstypenames
Output 
Test
CSV:Test

comentarios de ConvertFrom-StringData

Dentro de sus datos de cadena, el cmdlet ConvertFrom-StringData trata las líneas a partir de # como comentarios. Para obtener más información, consulte:

Notas

  • No se pueden anidar los comentarios de bloque. En el ejemplo siguiente, Baz no forma parte del comentario.

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

  • <# #> no tiene ningún significado especial dentro de un comentario de una sola línea. # no tiene ningún significado especial dentro de un comentario de bloque.

  • Para tratarse como comentario, el carácter de comentario no debe formar parte de un token que no sea de comentario. En el ejemplo siguiente, #Bar y <#Bar#> forman parte del token de Foo.... Por lo tanto, no se tratan como comentarios.

    PowerShell 
    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 [...]