TEMA about_Comment_Based_HelpDESCRIPCIN 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> # -o bien, < 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 "" 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. 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 { < contenido de ayuda> #> } -o bien, function MiFuncin { < contenido de ayuda> #> } -o bien, < 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: < contenido de ayuda> #> function MiFuncin { } -o bien, function MiFuncin { } < 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 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 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 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 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 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 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] ] [[-Extension] ] [] 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? false Posicin? 0 Valor predeterminado Aceptar canalizacin? false Aceptar caracteres comodn? -Extension Especifica la extensin. El valor predeterminado es "Txt". Requerido? false Posicin? 1 Valor predeterminado Aceptar canalizacin? false Aceptar caracteres comodn? 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 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. .\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] [[-OutputPath] ]] [] 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? true Posicin? 0 Valor predeterminado Aceptar canalizacin? false Aceptar caracteres comodn? -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? 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 { [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)