Compartir a través de

A Ayuda basada en comentarios

Nota editorial

Importante

La Especificación del lenguaje de Windows PowerShell 3.0 se publicó en diciembre de 2012 y se basa en Windows PowerShell 3.0. Esta especificación no refleja el estado actual de PowerShell. No hay ningún plan para actualizar esta documentación para reflejar el estado actual. Esta documentación se presenta aquí para obtener referencia histórica.

El documento de especificación está disponible como un documento de Microsoft Word del Centro de descarga de Microsoft en: https://www.microsoft.com/download/details.aspx?id=36389 Ese documento de Word se ha convertido para su presentación aquí en Microsoft Learn. Durante la conversión, se han realizado algunos cambios editoriales para dar cabida al formato de la plataforma Docs. Se han corregido algunos errores tipográficos y menores.

PowerShell proporciona un mecanismo para que los programadores documenten sus scripts mediante directivas de comentarios especiales. Los comentarios que usan esta sintaxis se denominan comentarios de ayuda. El cmdlet Get-Help genera documentación a partir de estas directivas.

A.1 Introducción

Un comentario de ayuda contiene una directiva de ayuda con el formato .nombre seguido en una o varias líneas posteriores por el texto del contenido de ayuda. El comentario de ayuda se puede componer de una serie de comentarios de una sola línea o de un comentario delimitado (§2.2.3). El conjunto de comentarios que comprende la documentación de una sola entidad se denomina tema de ayuda.

Por ejemplo

# <help-directive-1>
# <help-content-1>
...

# <help-directive-n>
# <help-content-n>

o

<#
<help-directive-1>
<help-content-1>
...

<help-directive-n>
<help-content-n>
#>

Todas las líneas de un tema de ayuda deben ser contiguas. Si un tema de ayuda sigue un comentario que no forma parte de ese tema, debe haber al menos una línea en blanco entre los dos.

Las directivas pueden aparecer en cualquier orden y algunas de las directivas pueden aparecer varias veces.

En los nombres de directiva no se distingue mayúsculas de minúsculas.

Al documentar una función, los temas de ayuda pueden aparecer en una de estas tres ubicaciones:

  • Inmediatamente antes de la definición de función sin más de una línea en blanco entre la última línea de la ayuda de la función y la línea que contiene la instrucción de función.
  • Dentro del cuerpo de la función inmediatamente después del corchete de apertura.
  • Dentro del cuerpo de la función inmediatamente anterior al corchete de cierre.

Al documentar un archivo de script, los temas de ayuda pueden aparecer en una de estas dos ubicaciones:

  • Al principio del archivo de script, precedido opcionalmente solo de comentarios y líneas en blanco. Si el primer elemento del script después de la ayuda es una definición de función, debe haber al menos dos líneas en blanco entre el final de la ayuda del script y esa declaración de función. De lo contrario, la ayuda se interpretará como que se aplica a la función en lugar del archivo de script.
  • Al final del archivo de script.

A.2 Directivas de ayuda

A.2.1 . DESCRIPCIÓN

Sintaxis:

.DESCRIPTION

Descripción:

Esta directiva permite una descripción detallada de la función o script. (La directiva .SYNOPSIS (§A.2.11) está pensada para una breve descripción). Esta directiva solo se puede usar una vez en cada tema.

Ejemplos:

<#
.DESCRIPTION
Computes Base to the power Exponent. Supports non-negative integer
powers only.
#>

A.2.2 . EJEMPLO

Sintaxis:

.EXAMPLE

Descripción:

Esta directiva permite mostrar un ejemplo de uso de comandos.

Si esta directiva se produce varias veces, cada bloque de contenido de ayuda asociado se muestra como ejemplo independiente.

Ejemplos:

<#
.EXAMPLE
Get-Power 3 4
81

.EXAMPLE
Get-Power -Base 3 -Exponent 4
81
#>

A.2.3 .EXTERNALHELP

Sintaxis:

.EXTERNALHELP <XMLHelpFilePath>

Descripción:

Esta directiva especifica la ruta de acceso a un archivo de ayuda basado en XML para el script o la función.

Aunque la ayuda basada en comentarios es más fácil de implementar, se requiere ayuda basada en XML si se necesita un control más preciso sobre el contenido de ayuda o si los temas de ayuda se van a traducir a varios idiomas. Esta especificación no define los detalles de la ayuda basada en XML.

Ejemplos:

<#
.EXTERNALHELP C:\MyScripts\Update-Month-Help.xml
#>

A.2.4 .FORWARDHELPCATEGORY

Sintaxis:

.FORWARDHELPCATEGORY <Category>

Descripción:

Especifica la categoría de ayuda del elemento en ForwardHelpTargetName (§A.2.5). Los valores válidos son Alias, Todos, Cmdlet, Script externo, Preguntas frecuentes, Filtro, Función, General, Glosario, Archivo de ayuda, Proveedory Comando de script. Use esta directiva para evitar conflictos cuando haya comandos con el mismo nombre.

Ejemplos:

Vea la sección A.2.5.

A.2.5 .FORWARDHELPTARGETNAME

Sintaxis:

.FORWARDHELPTARGETNAME <Command-Name>

Descripción:

Redirige al tema de ayuda especificado por <Command-Name>.

Ejemplos:

function Help {
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
    ...
}

El comando Get-Help help se trata como si fuera Get-Help Get-Help en su lugar.

A.2.6 .INPUTS

Sintaxis:

.INPUTS

Descripción:

La canalización se puede usar para canalizar uno o varios objetos a un script o función. Esta directiva se usa para describir estos objetos y sus tipos.

Si esta directiva se produce varias veces, cada bloque de contenido de ayuda asociado se recopila en la única entrada de documentación, en el orden léxico de las directivas.

Ejemplos:

<#
.INPUTS
None. You cannot pipe objects to Get-Power.

.INPUTS
For the Value parameter, one or more objects of any kind can be written
to the pipeline. However, the object is converted to a string before it
is added to the item.
#>
function Process-Thing {
    param ( ...
        [Parameter(ValueFromPipeline=$true)]
        [Object[]]$Value,
        ...
    )
    ...
}

Sintaxis:

.LINK

Descripción:

Esta directiva especifica el nombre de un tema relacionado.

Si esta directiva se produce varias veces, cada bloque de contenido de ayuda asociado se recopila en la única entrada de documentación, en el orden léxico de las directivas.

El contenido de la directiva Link también puede incluir un URI a una versión en línea del mismo tema de ayuda. La versión en línea se abre cuando se invoca Get-Help con el parámetro Online. El URI debe comenzar con "http" o "https".

Ejemplos:

<#
.LINK
Online version: http://www.acmecorp.com/widget.html

.LINK
Set-ProcedureName
#>

A.2.8 . NOTAS

Sintaxis:

.NOTES

Descripción:

Esta directiva permite proporcionar información adicional sobre la función o el script. Esta directiva solo se puede usar una vez en cada tema.

Ejemplos:

<#
.NOTES
*arbitrary text goes here*
#>

A.2.9 . SALIDAS

Sintaxis:

.OUTPUTS

Descripción:

Esta directiva se usa para describir los objetos de salida mediante un comando .

Si esta directiva se produce varias veces, cada bloque de contenido de ayuda asociado se recopila en la única entrada de documentación, en el orden léxico de las directivas.

Ejemplos:

<#
.OUTPUTS
double - Get-Power returns Base to the power Exponent.

.OUTPUTS
None unless the -PassThru switch parameter is used.
#>

A.2.10 . PARÁMETRO

Sintaxis:

.PARAMETER <Parameter-Name>

Descripción:

Esta directiva permite una descripción detallada del parámetro especificado. Esta directiva se puede usar una vez para cada parámetro. Las directivas de parámetro pueden aparecer en cualquier orden en el bloque de comentarios; sin embargo, el orden en el que sus parámetros correspondientes se definen realmente en el origen determina el orden en el que aparecen los parámetros y sus descripciones en la documentación resultante.

Un formato alternativo implica colocar un comentario de descripción de parámetro inmediatamente antes de la declaración del nombre de la variable de parámetro correspondiente. Si el origen contiene un comentario de descripción de parámetro y una directiva Parameter, se usa la descripción asociada a la directiva Parameter.

Ejemplos:

<#
.PARAMETER Base
The integer value to be raised to the Exponent-th power.

.PARAMETER Exponent
The integer exponent to which Base is to be raised.
#>

function Get-Power {
    param ([long]$Base, [int]$Exponent)
    ...
}

function Get-Power {
    param ([long]
        # The integer value to be raised to the Exponent-th power.
        $Base,
        [int]
        # The integer exponent to which Base is to be raised.
        $Exponent
    )
    ...
}

A.2.11 . SINOPSIS

Sintaxis:

.SYNOPSIS

Descripción:

Esta directiva permite una breve descripción de la función o script. (La directiva .DESCRIPTION (§A.2.1) está pensada para una descripción detallada). Esta directiva solo se puede usar una vez en cada tema.

Ejemplos:

<#
.SYNOPSIS
Computes Base to the power Exponent.
#>
  • Last updated on