TEMA
about_Comment_Based_Help
DESCRIPCIÓN BREVE
Describe cómo escribir temas de Ayuda basada en comentarios para funciones
y scripts.
DESCRIPCIÓN DETALLADA
Se pueden escribir temas de Ayuda basada en comentarios para
funciones y scripts utilizando palabras clave de comentario de
Ayuda especiales.
El cmdlet Get-Help muestra la Ayuda basada en comentarios en el
mismo formato en que muestra los temas de Ayuda de cmdlet que se
generan a partir de los archivos XML. Los usuarios pueden
utilizar todos los parámetros de Get-Help, tales como Detailed,
Full, Example y Online, a fin de mostrar la Ayuda de funciones y scripts.
También es posible escribir archivos de Ayuda basada en XML para
scripts y funciones utilizando palabras clave de comentario de
Ayuda, y redirigir a los usuarios a un archivo de Ayuda diferente.
En este tema se explica cómo escribir temas de Ayuda para
funciones y scripts. Para obtener información sobre cómo mostrar
los temas de Ayuda de los scripts y las funciones, vea Get-Help.
SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS
La sintaxis de la Ayuda basada en comentarios es la siguiente:
# .< palabra clave de ayuda>
# <contenido de ayuda>
-o bien,
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>
La Ayuda basada en comentarios se escribe como una serie de comentarios.
Se puede escribir un símbolo de comentario (#) delante de cada línea de
comentarios, o bien utilizar los símbolos "<#" y "#>" para crear un
bloque de comentario. Todas las líneas contenidas en el bloque de
comentario se interpretan como comentarios.
Todas las líneas de un tema de Ayuda basada en comentarios deben
ser contiguas. Si un tema de Ayuda basada en comentarios está
situado justo tras un comentario que no forma parte del tema de
Ayuda, debe dejarse por lo menos una línea en blanco entre la
última línea de comentario que no es de Ayuda y el principio de
la Ayuda basada en comentarios.
Las palabras clave definen cada sección de la Ayuda basada en
comentarios. Cada palabra clave va precedida de un punto (.). Las
palabras clave pueden aparecer en cualquier orden. Los nombres de
las palabras clave no distinguen entre mayúsculas y minúsculas.
Por ejemplo, la palabra clave Description precede a una
descripción de una función o un script.
<#
.Description
Get-Function muestra el nombre y la sintaxis de todas las
funciones de la sesión.
#>
El bloque de comentario debe contener una palabra clave por lo
menos. Algunas de las palabras clave, como EXAMPLE, pueden
aparecer muchas veces en el mismo bloque de comentario. El
contenido de Ayuda correspondiente a cada palabra clave comienza
en la línea que figura después de la palabra clave y puede
abarcar varias líneas.
SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS EN LAS FUNCIONES
La Ayuda basada en comentarios de una función puede aparecer en
una de las tres ubicaciones siguientes:
-- Al principio del cuerpo de la función.
-- Al final del cuerpo de la función.
-- Antes de la palabra clave Function. No puede haber más de
una línea en blanco entre última línea de la Ayuda la de
función y la palabra clave Function.
Por ejemplo:
function MiFunción
{
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>
<comandos de función>
}
-o bien,
function MiFunción
{
<comandos de función>
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>
}
-o bien,
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>
function MiFunción { }
SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS EN LOS SCRIPTS
La Ayuda basada en comentarios de un script puede aparecer en una
de las dos ubicaciones siguientes en el script.
-- Al principio del archivo de script. La Ayuda del script
solamente puede ir precedida en el script por comentarios y
líneas en blanco.
-- Si el primer elemento del cuerpo del script (después de la
Ayuda) es una declaración de función, debe haber por lo menos
dos líneas en blanco entre el fin de la Ayuda del script y la
declaración de función. De lo contrario, la Ayuda se
interpretará como si correspondiese a la función y no al script.
-- Al final del archivo de script.
Por ejemplo:
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>
function MiFunción { }
-o bien,
function MiFunción { }
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>
PALABRAS CLAVE DE LA AYUDA BASADA EN COMENTARIOS
A continuación se enumeran las palabras clave válidas de Ayuda
basada en comentarios, en el orden en que suelen aparecer en un
tema de Ayuda, junto con su uso previsto.
Estas palabras clave pueden aparecer en cualquier orden en la
Ayuda basada en comentarios y no distinguen entre mayúsculas y
minúsculas.
.SYNOPSIS
Descripción breve de la función o el script. Esta palabra
clave solo se puede utilizar una vez en cada tema.
.DESCRIPTION
Descripción detallada de la función o el script. Esta palabra
clave solo se puede utilizar una vez en cada tema.
.PARAMETER <Nombre-del-parámetro>
Descripción de un parámetro. Se puede incluir una palabra
clave Parameter por cada parámetro que haya en la sintaxis de
la función o el script.
Las palabras clave Parameter pueden aparecer en cualquier
orden dentro el bloque de comentario; sin embargo, la sintaxis
de la función o el script determina en qué orden aparecerán los
parámetros (y sus descripciones respectivas) en el tema de Ayuda.
Para cambiar el orden, deberá cambiar la sintaxis.
También se puede especificar la descripción de un parámetro
incluyendo un comentario en la sintaxis de la función o del
script inmediatamente antes del nombre de variable del parámetro.
Si utiliza un comentario de sintaxis y una palabra clave
Parameter, se utilizará la descripción asociada a la palabra
clave Parameter y se omitirá el comentario de sintaxis.
.EXAMPLE
Comando de ejemplo que utiliza la función o el script, y que
puede ir seguido, opcionalmente, por un ejemplo de resultado
y una descripción. Repita esta palabra clave por cada ejemplo.
.INPUTS
Los tipos de Microsoft .NET Framework de los objetos que se pueden
canalizar a la función o al script. También se puede incluir una
descripción de los objetos de entrada.
.OUTPUTS
El tipo de .NET Framework de los objetos que el cmdlet devuelve.
También se puede incluir una descripción de los objetos devueltos.
.NOTES
Información adicional sobre la función o el script.
.LINK
Nombre de un tema relacionado. Repita esta palabra clave por
cada tema relacionado.
Este contenido aparece en la sección Vínculos relacionados
del tema de Ayuda.
El contenido de la palabra clave Link también puede incluir
un identificador uniforme de recursos (URI)a una versión en pantalla
del mismo tema de Ayuda. La versión en pantalla se abre cuando se
utiliza el parámetro Online de Get-Help. El identificador URI debe
comenzar con "http" o "https".
.COMPONENT
Tecnología o característica que la función o el script utiliza,
o con la que está relacionado. Este contenido aparece cuando el
comando Get-Help incluye el parámetro Component de Get-Help.
.ROLE
Rol de usuario correspondiente al tema de Ayuda. Este
contenido aparece cuando el comando Get-Help incluye el
parámetro Role de Get-Help.
.FUNCTIONALITY
Uso previsto de la función. Este contenido aparece cuando el
comando Get-Help incluye el parámetro Functionality de Get-Help.
.FORWARDHELPTARGETNAME <Nombre-del-comando>
Redirige al usuario al tema de Ayuda del comando especificado.
Es posible redirigir a los usuarios a cualquier tema de Ayuda,
incluso a los correspondientes a una función, un script,
un cmdlet o un proveedor.
.FORWARDHELPCATEGORY <Categoría>
Especifica la categoría de Ayuda del elemento en ForwardHelpTargetName.
Los valores válidos son Alias, Cmdlet, HelpFile, Function, Provider,
General, FAQ, Glossary, ScriptCommand, ExternalScript, Filter o All.
Utilice esta palabra clave para evitar conflictos cuando existan
comandos con el mismo nombre.
.REMOTEHELPRUNSPACE <variable-PSSession>
Especifica una sesión que contiene el tema de Ayuda. Escriba
una variable que contenga una sesión PSSession. El cmdlet
Export-PSSession utiliza esta palabra clave para buscar los
temas de Ayuda correspondientes a los comandos exportados.
.EXTERNALHELP <Ruta de acceso del archivo de Ayuda XML>
Especifica la ruta de acceso a un archivo de Ayuda basada en
XML correspondiente a un script o una función.
En Windows Vista y en las versiones de Windows posteriores,
si la ruta especificada contiene subdirectorios específicos
de la referencia cultural de la interfaz de usuario, Get-Help
busca de forma recursiva en todos ellos hasta encontrar un
archivo XML con el nombre del script o la función, de acuerdo
con las normas de reserva de idioma establecidas para Windows
Vista, exactamente igual que hace con todos los temas de
Ayuda basados en XML.
Para obtener más información sobre el formato de los archivos de Ayuda
basada en XML para los cmdlet, vea el tema acerca de cómo crear Ayuda
de cmdlets en MSDN Library (Microsoft Developer Network)en
https://go.microsoft.com/fwlink/?LinkID=123415
CONTENIDO AUTOGENERADO
El cmdlet Get-Help genera automáticamente el nombre, la sintaxis,
la lista de parámetros, la tabla de atributos del parámetro, los
parámetros comunes y las notas.
Nombre:
La sección de nombre de un tema de Ayuda de una función
se toma del nombre de la función que figura en la
sintaxis de la función. El nombre de un tema de Ayuda de
script se toma del nombre de archivo del script. Para
cambiar el nombre o su uso de mayúsculas, cambie la
sintaxis de la función o el nombre del archivo de script.
Sintaxis:
La sección de sintaxis del tema de Ayuda se genera a
partir de la sintaxis de la función o del script. Para
agregar detalles a la sintaxis del tema de Ayuda, como el
tipo de .NET Framework de un parámetro, añádalos a la sintaxis.
Si no especifica un tipo de parámetro, el tipo "Object" se
inserta como valor predeterminado.
Lista de parámetros:
La lista de parámetros del tema de Ayuda se genera a
partir de la sintaxis de la función o del script y de las
descripciones que se agregan mediante la palabra clave
Parameters. Los parámetros de función aparecen en sección
"Parámetros" del tema de Ayuda en el mismo orden en que
aparecen en la sintaxis de la función o del script. La
ortografía y el uso de mayúsculas de los nombres de los
parámetros también se toman de la sintaxis; el nombre de
parámetro especificado por la palabra clave Parameter no
tiene efecto en ello.
Parámetros comunes:
Los parámetros comunes se agregan a la sintaxis y a la
lista de parámetros del tema de Ayuda, aunque no tengan
ningún efecto. Para obtener más información sobre los
parámetros comunes, vea about_CommonParameters.
Tabla de atributos del parámetro:
Get-Help genera la tabla de atributos del parámetro que
aparece cuando se utilizan l os parámetros Full o
Parameter de Get-Help. El valor de los atributos
Requerido, Posición y Valor predeterminado se toma de la
sintaxis de la función o del script.
Notas:
La sección de notas del tema de Ayuda se genera
automáticamente a partir del nombre de la función o del
script. Su contenido no se puede modificar ni verse afectado.
EJEMPLOS
Ejemplo 1: Ayuda basada en comentarios de una función
En la función de ejemplo siguiente se incluye Ayuda basada en
comentarios:
function Add-Extension
{
param ([cadena]$Name,[cadena]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Agrega una extensión de nombre de archivo a un nombre
proporcionado.
.DESCRIPTION
Agrega una extensión de nombre de archivo a un nombre
proporcionado. Toma las cadenas para el nombre o la
extensión de archivo.
.PARAMETER Name
Especifica el nombre del archivo.
.PARAMETER Extension
Especifica la extensión. El valor predeterminado es "Txt".
.INPUTS
Ninguna. No se pueden canalizar objetos a Add-Extension.
.OUTPUTS
System.String. Add-Extension devuelve una cadena con la
extensión o el nombre del archivo.
.EXAMPLE
C:\PS> extension -name "Archivo"
Archivo.txt
.EXAMPLE
C:\PS> extension -name "Archivo" -extension "doc"
Archivo.doc
.EXAMPLE
C:\PS> extension "Archivo" "doc"
Archivo.doc
.LINK
Versión en pantalla: http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
Los resultados son:
C:\PS> get-help add-extension -full
NOMBRE
Add-Extension
SINOPSIS
Agrega una extensión de nombre de archivo a un nombre
proporcionado.
SINTAXIS
Add-Extension [[-Name] <Cadena>] [[-Extension] <Cadena>]
[<CommonParameters>]
DESCRIPCIÓN
Agrega una extensión de nombre de archivo a un nombre
proporcionado. Toma las cadenas para el nombre o la
extensión de archivo.
PARÁMETROS
-Name
Especifica el nombre del archivo.
¿Requerido? false
¿Posición? 0
Valor predeterminado
¿Aceptar canalización? false
¿Aceptar caracteres comodín?
-Extension
Especifica la extensión. El valor predeterminado es "Txt".
¿Requerido? false
¿Posición? 1
Valor predeterminado
¿Aceptar canalización? false
¿Aceptar caracteres comodín?
<CommonParameters>
Este cmdlet admite los parámetros comunes: -Verbose,
-Debug, ErrorAction, -ErrorVariable, -WarningAction,
-WarningVariable, OutBuffer y -OutVariable. Para obtener
más información, escriba "get-help about_commonparameters".
TIPO DE ENTRADA
Ninguna. No se pueden canalizar objetos a Add-Extension.
SALIDA
System.String. Add-Extension devuelve una cadena con la
extensión o el nombre del archivo.
-------------------------- EJEMPLO 1 --------------------------
C:\PS> extension -name "Archivo"
Archivo.txt
-------------------------- EJEMPLO 2 --------------------------
C:\PS> extension -name "Archivo" -extension "doc"
Archivo.doc
-------------------------- EJEMPLO 3 --------------------------
C:\PS> extension "Archivo" "doc"
Archivo.doc
VÍNCULOS RELACIONADOS
Versión en pantalla: http://www.fabrikam.com/extension.htm
l Set-Item
Ejemplo 2: Descripciones de parámetros en la sintaxis de funciones
Este ejemplo es igual que el anterior, excepto porque las
descripciones de los parámetros se insertan en la sintaxis de
la función. Este formato resulta más útil cuando las
descripciones son breves.
function Add-Extension
{
param
(
[cadena]
# Especifica el nombre de archivo.
$name,
[cadena]
# Especifica la extensión del nombre de archivo. El valor
predeterminado es "Txt".
$extension = "txt"
)
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Agrega una extensión de nombre de archivo a un nombre proporcionado.
.DESCRIPTION
Agrega una extensión de nombre de archivo a un nombre
proporcionado. Toma las cadenas para el nombre o la
extensión de archivo.
.INPUTS
Ninguna. No se pueden canalizar objetos a Add-Extension.
.OUTPUTS
System.String. Add-Extension devuelve una cadena con la
extensión o el nombre del archivo.
.EXAMPLE
C:\PS> extension -name "Archivo"
Archivo.txt
.EXAMPLE
C:\PS> extension -name "Archivo" -extension "doc"
Archivo.doc
.EXAMPLE
C:\PS> extension "Archivo" "doc"
Archivo.doc
.LINK
Versión en pantalla: http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
Ejemplo 3: Ayuda basada en comentarios para los scripts
En el script de ejemplo siguiente se incluye Ayuda basada en comentarios.
Observe las líneas en blanco entre los símbolos de cierre "#>
" y la instrucción Param. En un script que no tenga una
instrucción Param, deberá haber por lo menos dos líneas en
blanco entre el comentario final del tema de Ayuda y la
primera declaración de función. Sin estas líneas en blanco,
Get-Help asociará el tema de Ayuda a la función y no al script.
<#
.SYNOPSIS
Realiza actualizaciones mensuales de datos.
.DESCRIPTION
El script Update-Month.ps1 actualiza el Registro con nuevos datos
generados durante el mes anterior y genera un informe.
.PARAMETER InputPath
Especifica la ruta de acceso al archivo de entrada basado en CSV.
.PARAMETER OutputPath
Especifica el nombre y la ruta de acceso del archivo de
salida basado en CSV. De forma predeterminada, MonthlyUpdates.ps1
genera un nombre a partir de la fecha y hora en que se ejecuta y
guarda la salida en el directorio local.
.INPUTS
Ninguna. No se pueden canalizar objetos a Update-Month.ps1.
.OUTPUTS
Ninguna. Update-Month.ps1 no genera ninguna salida.
.EXAMPLE
C:\PS> .\Update-Month.ps1
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\Enero.csv
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\Enero.csv
-outputPath C:\Reports\2009\Enero.csv
#>
param ([cadena]$InputPath, [cadena]$OutPutPath)
function Get-Data { }
...
El comando siguiente permite ver la Ayuda del script. Dado
que el script no se encuentra en un directorio que figure en
la lista de la variable de entorno Path, el comando Get-Help
que permite ver la Ayuda del script debe especificar la ruta
de acceso del script.
PS C:\ps-test> get-help .\update-month.ps1 -full
NOMBRE
C:\ps-test\Update-Month.ps1
SINOPSIS
Realiza actualizaciones mensuales de datos.
SINTAXIS
C:\ps-test\Update-Month.ps1 [-InputPath] <Cadena>
[[-OutputPath] ]<Cadena>] [<CommonParameters>]
DESCRIPCIÓN
El script Update-Month.ps1 actualiza el Registro con
nuevos datos generados durante el mes anterior y
genera un informe.
PARÁMETROS
-InputPath
Especifica la ruta de acceso al archivo de entrada
basado en CSV.
¿Requerido? true
¿Posición? 0
Valor predeterminado
¿Aceptar canalización? false
¿Aceptar caracteres comodín?
-OutputPath
Especifica el nombre y la ruta de acceso del
archivo de salida basado en CSV. De forma
predeterminada, MonthlyUpdates.ps1 genera un
nombre a partir de la fecha y hora en que se
ejecuta y guarda la salida en el directorio local.
¿Requerido? false
¿Posición? 1
Valor predeterminado
¿Aceptar canalización? false
¿Aceptar caracteres comodín?
<CommonParameters>
Este cmdlet admite los parámetros comunes:
-Verbose, -Debug, ErrorAction, -ErrorVariable,
-WarningAction, -WarningVariable, OutBuffer y
-OutVariable. Para obtener más información,
escriba "get-help about_commonparameters".
TIPO DE ENTRADA
Ninguna. No se pueden canalizar objetos a
Update-Month.ps1.
SALIDA
Ninguna. Update-Month.ps1 no genera ninguna salida.
-------------------------- EJEMPLO 1 --------------------------
C:\PS> .\Update-Month.ps1
-------------------------- EJEMPLO 2 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\Enero.csv
-------------------------- EJEMPLO 3 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\Enero.csv -outputPath
C:\Reports\2009\Enero.csv
VÍNCULOS RELACIONADOS
Ejemplo 4: Redirigir a un archivo XML
Es posible escribir temas de Ayuda basada en XML para las
funciones y los scripts. Aunque la Ayuda basada en
comentarios es más fácil de implementar, es necesario
recurrir a la Ayuda basada en XML si se desea controlar con
mayor precisión el contenido de la Ayuda o si los temas de la
Ayuda se van a traducir a varios idiomas.
En el ejemplo siguiente se muestran las primeras líneas del
script Update-Month.ps1. En el script se utiliza la palabra
clave ExternalHelp para especificar la ruta de acceso a un
tema de Ayuda basada en XML para el script.
# .ExternalHelp C:\MisScripts\Update-Month-Help.xml
param ([cadena]$InputPath, [cadena]$OutPutPath)
function Get-Data { }
...
En el ejemplo siguiente se muestra el uso de la palabra clave
ExternalHelp en una función.
function Add-Extension
{
param ([cadena] $name, [cadena]$extension = "txt")
$name = $name + "." + $extension
$name
# .ExternalHelp C:\ps-test\Add-Extension.xml }
}
Ejemplo 5: Redirigir a un tema de Ayuda diferente
El código siguiente es un extracto del principio de la
función Help integrada en Windows PowerShell, que muestra una
pantalla de texto de Ayuda cada vez. Dado que el tema de
Ayuda correspondiente al cmdlet Get-Help describe la función
Help, la función Help utiliza las palabras clave
ForwardHelpCategory y ForwardHelpTargetName para redirigir al
usuario al tema de Ayuda del cmdlet Get-Help.
function help
{
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
[System.String]
${Name},
...
El comando siguiente utiliza esta característica:
C:\PS> get-help help
NOMBRE
Get-Help
SINOPSIS
Muestra información acerca de cmdlets y conceptos de
Windows PowerShell.
...
VEA TAMBIÉN
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
"Cómo escribir la Ayuda de los cmdlets"
(https://go.microsoft.com/fwlink/?LinkID=123415)