TEMA

about_Comment_Based_Help
DESCRIPCIN BREVE
Describe cmo escribir temas de Ayuda basada en comentarios para funciones
y scripts.
DESCRIPCIN 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 parmetros de Get-Help, tales como Detailed,
Full, Example y Online, a fin de mostrar la Ayuda de funciones y scripts.
Tambin 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 cmo escribir temas de Ayuda para
funciones y scripts. Para obtener informacin sobre cmo 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 smbolo de comentario (#) delante de cada lnea de
comentarios, o bien utilizar los smbolos "<#" y "#>" para crear un
bloque de comentario. Todas las lneas contenidas en el bloque de
comentario se interpretan como comentarios.
Todas las lneas 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 lnea en blanco entre la
ltima lnea de comentario que no es de Ayuda y el principio de
la Ayuda basada en comentarios.
Las palabras clave definen cada seccin 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 maysculas y minsculas.
Por ejemplo, la palabra clave Description precede a una
descripcin de una funcin o un script.

<#
.Description
Get-Function muestra el nombre y la sintaxis de todas las
funciones de la sesin.
#>
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 lnea que figura despus de la palabra clave y puede
abarcar varias lneas.

SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS EN LAS FUNCIONES

La Ayuda basada en comentarios de una funcin puede aparecer en
una de las tres ubicaciones siguientes:
-- Al principio del cuerpo de la funcin.
-- Al final del cuerpo de la funcin.
-- Antes de la palabra clave Function. No puede haber ms de
una lnea en blanco entre ltima lnea de la Ayuda la de
funcin y la palabra clave Function.

Por ejemplo:
function MiFuncin
{
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>
<comandos de funcin>
}
-o bien,
function MiFuncin
{
<comandos de funcin>
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>
}
-o bien,
<#
.< palabra clave de ayuda>

< contenido de ayuda>

#>
function MiFuncin { }

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
lneas en blanco.
-- Si el primer elemento del cuerpo del script (despus de la
Ayuda) es una declaracin de funcin, debe haber por lo menos
dos lneas en blanco entre el fin de la Ayuda del script y la
declaracin de funcin. De lo contrario, la Ayuda se
interpretar como si correspondiese a la funcin y no al script.
-- Al final del archivo de script.

Por ejemplo:
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>
function MiFuncin { }
-o bien,
function MiFuncin { }
<#
.< palabra clave de ayuda>
< contenido de ayuda>
#>

PALABRAS CLAVE DE LA AYUDA BASADA EN COMENTARIOS

A continuacin se enumeran las palabras clave vlidas 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 maysculas y
minsculas.
.SYNOPSIS
Descripcin breve de la funcin o el script. Esta palabra
clave solo se puede utilizar una vez en cada tema.

.DESCRIPTION
Descripcin detallada de la funcin o el script. Esta palabra
clave solo se puede utilizar una vez en cada tema.
.PARAMETER <Nombre-del-parmetro>
Descripcin de un parmetro. Se puede incluir una palabra
clave Parameter por cada parmetro que haya en la sintaxis de
la funcin o el script.
Las palabras clave Parameter pueden aparecer en cualquier
orden dentro el bloque de comentario; sin embargo, la sintaxis
de la funcin o el script determina en qu orden aparecern los
parmetros (y sus descripciones respectivas) en el tema de Ayuda.
Para cambiar el orden, deber cambiar la sintaxis.
Tambin se puede especificar la descripcin de un parmetro
incluyendo un comentario en la sintaxis de la funcin o del
script inmediatamente antes del nombre de variable del parmetro.
Si utiliza un comentario de sintaxis y una palabra clave
Parameter, se utilizar la descripcin asociada a la palabra
clave Parameter y se omitir el comentario de sintaxis.
.EXAMPLE
Comando de ejemplo que utiliza la funcin o el script, y que
puede ir seguido, opcionalmente, por un ejemplo de resultado
y una descripcin. Repita esta palabra clave por cada ejemplo.
.INPUTS
Los tipos de Microsoft .NET Framework de los objetos que se pueden
canalizar a la funcin o al script. Tambin se puede incluir una
descripcin de los objetos de entrada.
.OUTPUTS
El tipo de .NET Framework de los objetos que el cmdlet devuelve.
Tambin se puede incluir una descripcin de los objetos devueltos.
.NOTES
Informacin adicional sobre la funcin o el script.
.LINK
Nombre de un tema relacionado. Repita esta palabra clave por
cada tema relacionado.
Este contenido aparece en la seccin Vnculos relacionados
del tema de Ayuda.
El contenido de la palabra clave Link tambin puede incluir
un identificador uniforme de recursos (URI)a una versin en pantalla
del mismo tema de Ayuda. La versin en pantalla se abre cuando se
utiliza el parmetro Online de Get-Help. El identificador URI debe
comenzar con "http" o "https".
.COMPONENT
Tecnologa o caracterstica que la funcin o el script utiliza,
o con la que est relacionado. Este contenido aparece cuando el
comando Get-Help incluye el parmetro Component de Get-Help.
.ROLE
Rol de usuario correspondiente al tema de Ayuda. Este
contenido aparece cuando el comando Get-Help incluye el

parmetro Role de Get-Help.

.FUNCTIONALITY
Uso previsto de la funcin. Este contenido aparece cuando el
comando Get-Help incluye el parmetro 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 funcin, un script,
un cmdlet o un proveedor.
.FORWARDHELPCATEGORY <Categora>
Especifica la categora de Ayuda del elemento en ForwardHelpTargetName.
Los valores vlidos 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 sesin que contiene el tema de Ayuda. Escriba
una variable que contenga una sesin 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 funcin.
En Windows Vista y en las versiones de Windows posteriores,
si la ruta especificada contiene subdirectorios especficos
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 funcin, 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 ms informacin sobre el formato de los archivos de Ayuda
basada en XML para los cmdlet, vea el tema acerca de cmo crear Ayuda
de cmdlets en MSDN Library (Microsoft Developer Network)en
http://go.microsoft.com/fwlink/?LinkID=123415
CONTENIDO AUTOGENERADO
El cmdlet Get-Help genera automticamente el nombre, la sintaxis,
la lista de parmetros, la tabla de atributos del parmetro, los
parmetros comunes y las notas.
Nombre:
La seccin de nombre de un tema de Ayuda de una funcin
se toma del nombre de la funcin que figura en la
sintaxis de la funcin. 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 maysculas, cambie la
sintaxis de la funcin o el nombre del archivo de script.
Sintaxis:
La seccin de sintaxis del tema de Ayuda se genera a
partir de la sintaxis de la funcin o del script. Para

agregar detalles a la sintaxis del tema de Ayuda, como el

tipo de .NET Framework de un parmetro, adalos a la sintaxis.
Si no especifica un tipo de parmetro, el tipo "Object" se
inserta como valor predeterminado.
Lista de parmetros:
La lista de parmetros del tema de Ayuda se genera a
partir de la sintaxis de la funcin o del script y de las
descripciones que se agregan mediante la palabra clave
Parameters. Los parmetros de funcin aparecen en seccin
"Parmetros" del tema de Ayuda en el mismo orden en que
aparecen en la sintaxis de la funcin o del script. La
ortografa y el uso de maysculas de los nombres de los
parmetros tambin se toman de la sintaxis; el nombre de
parmetro especificado por la palabra clave Parameter no
tiene efecto en ello.
Parmetros comunes:
Los parmetros comunes se agregan a la sintaxis y a la
lista de parmetros del tema de Ayuda, aunque no tengan
ningn efecto. Para obtener ms informacin sobre los
parmetros comunes, vea about_CommonParameters.
Tabla de atributos del parmetro:
Get-Help genera la tabla de atributos del parmetro que
aparece cuando se utilizan l os parmetros Full o
Parameter de Get-Help. El valor de los atributos
Requerido, Posicin y Valor predeterminado se toma de la
sintaxis de la funcin o del script.
Notas:
La seccin de notas del tema de Ayuda se genera
automticamente a partir del nombre de la funcin o del
script. Su contenido no se puede modificar ni verse afectado.

EJEMPLOS
Ejemplo 1: Ayuda basada en comentarios de una funcin
En la funcin 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 extensin de nombre de archivo a un nombre
proporcionado.
.DESCRIPTION
Agrega una extensin de nombre de archivo a un nombre
proporcionado. Toma las cadenas para el nombre o la
extensin de archivo.

.PARAMETER Name
Especifica el nombre del archivo.
.PARAMETER Extension
Especifica la extensin. 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
extensin 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
Versin 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 extensin de nombre de archivo a un nombre
proporcionado.
SINTAXIS
Add-Extension [[-Name] <Cadena>] [[-Extension] <Cadena>]
[<CommonParameters>]
DESCRIPCIN
Agrega una extensin de nombre de archivo a un nombre
proporcionado. Toma las cadenas para el nombre o la
extensin de archivo.
PARMETROS
-Name
Especifica el nombre del archivo.
Requerido?
Posicin?

false
0

Valor predeterminado
Aceptar canalizacin?
Aceptar caracteres comodn?

false

-Extension
Especifica la extensin. El valor predeterminado es "Txt".
Requerido?
Posicin?
Valor predeterminado
Aceptar canalizacin?
Aceptar caracteres comodn?

false
1
false

<CommonParameters>
Este cmdlet admite los parmetros comunes: -Verbose,
-Debug, ErrorAction, -ErrorVariable, -WarningAction,
-WarningVariable, OutBuffer y -OutVariable. Para obtener
ms informacin, 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
extensin 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
VNCULOS RELACIONADOS
Versin en pantalla: http://www.fabrikam.com/extension.htm
l Set-Item

Ejemplo 2: Descripciones de parmetros en la sintaxis de funciones

Este ejemplo es igual que el anterior, excepto porque las
descripciones de los parmetros se insertan en la sintaxis de
la funcin. Este formato resulta ms til cuando las
descripciones son breves.
function Add-Extension
{
param
(

[cadena]
# Especifica el nombre de archivo.
$name,
[cadena]
# Especifica la extensin del nombre de archivo. El valor
predeterminado es "Txt".
$extension = "txt"
)
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Agrega una extensin de nombre de archivo a un nombre proporcionado.
.DESCRIPTION
Agrega una extensin de nombre de archivo a un nombre
proporcionado. Toma las cadenas para el nombre o la
extensin de archivo.
.INPUTS
Ninguna. No se pueden canalizar objetos a Add-Extension.
.OUTPUTS
System.String. Add-Extension devuelve una cadena con la
extensin 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
Versin 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 lneas en blanco entre los smbolos de cierre "#>
" y la instruccin Param. En un script que no tenga una
instruccin Param, deber haber por lo menos dos lneas en
blanco entre el comentario final del tema de Ayuda y la

primera declaracin de funcin. Sin estas lneas en blanco,

Get-Help asociar el tema de Ayuda a la funcin 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>]

DESCRIPCIN
El script Update-Month.ps1 actualiza el Registro con
nuevos datos generados durante el mes anterior y
genera un informe.
PARMETROS
-InputPath
Especifica la ruta de acceso al archivo de entrada
basado en CSV.
Requerido?
Posicin?
Valor predeterminado
Aceptar canalizacin?
Aceptar caracteres comodn?

true
0
false

-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
Posicin?
1
Valor predeterminado
Aceptar canalizacin?
false
Aceptar caracteres comodn?
<CommonParameters>
Este cmdlet admite los parmetros comunes:
-Verbose, -Debug, ErrorAction, -ErrorVariable,
-WarningAction, -WarningVariable, OutBuffer y
-OutVariable. Para obtener ms informacin,
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
VNCULOS 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 ms fcil de implementar, es necesario
recurrir a la Ayuda basada en XML si se desea controlar con
mayor precisin 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 lneas 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 funcin.
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 cdigo siguiente es un extracto del principio de la
funcin 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 funcin
Help, la funcin 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 caracterstica:
C:\PS> get-help help
NOMBRE
Get-Help
SINOPSIS
Muestra informacin acerca de cmdlets y conceptos de
Windows PowerShell.
...
VEA TAMBIN
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
"Cmo escribir la Ayuda de los cmdlets"
(http://go.microsoft.com/fwlink/?LinkID=123415)