about_Comment_Based_Help
Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0
Insertar la introducción aquí.
TEMA
about_Comment_Based_Help
DESCRIPCIÓN BREVE
Describe cómo escribir temas de ayuda basada en comentarios para funciones scripts.
DESCRIPCIÓN LARGA
Puede escribir temas de ayuda basada en comentarios para funciones y scripts mediante palabras clave de ayuda especiales.
El cmdlet Get-Help muestra ayuda basada en comentarios en el mismo formato en el que muestra los temas de ayuda de cmdlets que se generan a partir de archivos XML. Los usuarios pueden utilizar todos los parámetros de Get-Help, como Detailed, Full, Example y Online, para mostrar el contenido de la ayuda basada en comentarios.
También puede escribir archivos de ayuda basados en XML para las funciones y los scripts. Para habilitar el cmdlet Get-Help para buscar el archivo de ayuda basado en XML de una función o un script, utilice la palabra clave ExternalHelp. Sin esta palabra clave, Get-Help no puede encontrar temas de ayuda basados en XML de funciones o scripts.
En este tema se explica cómo escribir temas de ayuda de funciones y scripts. Para obtener información sobre cómo mostrar temas de ayuda para funciones y scripts, vea Get-Help.
NOTA:
Los cmdlets Update-Help y Save-Help solo funcionan en archivos XML. La ayuda actualizable no admite temas de ayuda basada en comentarios.
NOTA PARA LA SOLUCIÓN DE PROBLEMAS:
Los valores predeterminados y un valor de "Accept Wildcard characters" no aparecen en la tabla de atributos de parámetros, incluso aunque se definan en la función o el script. Para ayudar a los usuarios, ofrezca esta información en la descripción del parámetro.
SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS
La sintaxis de la ayuda basada en comentarios se muestra a continuación:
# .< help keyword>
# <help content>
-or -
<#
.< help keyword>
< help content>
#>
La ayuda basada en comentarios se escribe como una serie de comentarios. Puede escribir un símbolo de comentario (#) antes de cada línea de comentarios o puede utilizar los símbolos "<#" y "#>" para crear un bloque de comentario. Todas las líneas dentro del bloque de comentarios 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 aparece a continuación de un comentario que no forma parte del tema de ayuda, debe haber al menos una línea en blanco entre la última línea de comentarios que no son 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 de la ayuda basada en comentarios está precedida de un punto (.). Las palabras clave pueden aparecer en cualquier orden. Los nombres de palabras clave no distinguen mayúsculas de minúsculas.
Por ejemplo, la palabra clave Description precede una descripción de una función o un script.
<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>
El bloque de comentario debe contener al menos una palabra clave. Algunas de las palabras clave, como EXAMPLE, pueden aparecer varias veces en el mismo bloque de comentario. El contenido de la ayuda de cada palabra clave comienza en la línea después de la palabra clave y puede abarcar varias líneas.
SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS EN FUNCIONES
La ayuda basada en comentarios de una función puede aparecer en una de estas tres ubicaciones:
-- At the beginning of the function body.
-- At the end of the function body.
-- Before the Function keyword. There cannot be more than one blank
line between the last line of the function help and the Function
keyword.
Por ejemplo:
function Get-Function
{
<#
.< help keyword>
< help content>
#>
<function commands>
}
-or -
function Get-Function
{
<function commands>
<#
.< help keyword>
< help content>
#>
}
-or -
<#
.< help keyword>
< help content>
#>
function Get-Function { }
SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS EN SCRIPTS
La ayuda basada en comentarios de un script puede aparecer en una de las dos ubicaciones siguientes del script.
-- At the beginning of the script file. Script help can be preceded in the
script only by comments and blank lines.
-- If the first item in the script body (after the help) is a function
declaration, there must be at least two blank lines between the end of the
script help and the function declaration. Otherwise, the help is
interpreted as being help for the function, not help for the script.
-- At the end of the script file. However, if the script is signed, place
Comment-based help at the beginning of the script file. The end of the
script is occupied by the signature block.
Por ejemplo:
<#
.< help keyword>
< help content>
#>
function Get-Function { }
-or-
function Get-Function { }
<#
.< help keyword>
< help content>
#>
SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS EN MÓDULOS DE SCRIPTS
En un módulo de script (.psm1), la ayuda basada en comentarios usa la sintaxis de funciones, no la sintaxis de scripts. No puede utilizar la sintaxis de scripts para ofrecer ayuda para todas las funciones definidas en un módulo de script.
Por ejemplo, si está utilizando la palabra clave ExternalHelp para identificar los archivos de ayuda basados en XML para las funciones en un módulo de script, debe agregar un comentario ExternalHelp a cada función.
# .ExternalHelp <XML-file-name>
function <function-name>
{
...
}
PALABRAS CLAVE DE LA AYUDA BASADA EN COMENTARIOS
A continuación se muestran las palabras clave válidas de la ayuda basada en comentarios. Se muestran en el orden en que normalmente aparecen 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 mayúsculas de minúsculas.
.SYNOPSIS
Una breve descripción de la función o el script. Esta palabra clave solo se puede utilizar una vez en cada tema.
.DESCRIPTION
Una descripción detallada de la función o el script. Esta palabra clave solo se puede utilizar una vez en cada tema.
.PARAMETER <Nombre-parámetro>
La descripción de un parámetro. Agregue una palabra clave .PARAMETER por cada parámetro de la sintaxis del script o la función.
Escriba el nombre del parámetro en la misma línea que la palabra clave .PARAMETER. Escriba la descripción del parámetro en las líneas que aparecen a continuación de la palabra clave .PARAMETER. Windows PowerShell interpreta todo el texto entre la línea .PARAMETER y la siguiente palabra clave o el final del bloque de comentario como parte de la descripción del parámetro. La descripción puede incluir saltos de párrafo.
Las palabras clave Parameter pueden aparecer en cualquier orden en el bloque de comentario, pero la sintaxis del script o la función determina el orden en que los parámetros (y sus descripciones) aparecen en el tema de ayuda. Para cambiar el orden, cambie la sintaxis.
También puede especificar una descripción del parámetro colocando un comentario en la sintaxis de la función o el script inmediatamente antes del nombre de la variable del parámetro. Si utiliza un comentario de sintaxis y una palabra clave Parameter, se usará la descripción asociada a la palabra clave Parameter y se omitirá el comentario de la sintaxis.
.EXAMPLE
Un comando de ejemplo que utiliza la función o el script, que opcionalmente puede ir acompañado de una salida de ejemplo y una descripción. Repita esta palabra clave para cada ejemplo.
.INPUTS
Los tipos de objetos de Microsoft .NET Framework que pueden canalizarse a la función o el script. También puede incluir una descripción de los objetos de entrada.
.OUTPUTS
El tipo de objetos de .NET Framework que devuelve el cmdlet. También puede incluir una descripción de los objetos devueltos.
.NOTES
Información adicional sobre la función o el script.
.LINK
El nombre de un tema relacionado. El valor aparece en la línea, debajo de la palabra clave .LINE, y debe estar precedido de un símbolo de comentario (#) o incluirse en el bloque de comentario.
Repita la palabra clave .LINK para 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) para una versión en línea del mismo tema de ayuda. La versión en línea se abre cuando utiliza el parámetro Online de Get-Help. El URI debe comenzar por "http" o "https".
.COMPONENT
La tecnología o la característica que utiliza la función o el script, o aquella con la que está relacionada. Este contenido aparece si el comando Get-Help incluye el parámetro Component de Get-Help.
.ROLE
El rol de usuario del tema de ayuda. Este contenido aparece si el comando Get-Help incluye el parámetro Role de Get-Help.
.FUNCTIONALITY
El uso previsto de la función. Este contenido aparece si el comando Get-Help incluye el parámetro Functionality de Get-Help.
.FORWARDHELPTARGETNAME <Nombre-comando>
Redirige al tema de ayuda del comando especificado. Es posible redirigir a los usuarios a cualquier tema de ayuda, incluidos los temas de ayuda de 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 haya comandos con el mismo nombre.
.REMOTEHELPRUNSPACE <Variable-PSSession>
Especifica una sesión que contiene el tema de ayuda. Escriba una variable que contenga una PSSession. El cmdlet Export-PSSession usa esta palabra clave para buscar los temas de ayuda de los comandos exportados.
.EXTERNALHELP <Archivo de ayuda XML>
Especifica un archivo de ayuda basado en XML del script o la función.
La palabra clave ExternalHelp es necesaria si se documenta una función o un script en archivos XML. Sin esta palabra clave, Get-Help no encuentra el archivo de ayuda basado en XML de la función o el script.
La palabra clave ExternalHelp tiene prioridad sobre otras palabras clave de ayuda basada en comentarios. Si aparece ExternalHelp, Get-Help no muestra ayuda basada en comentarios, incluso aunque no puede encontrar un tema de ayuda que coincida con el valor de la palabra clave ExternalHelp.
Si un módulo exporta la función, establezca el valor de la palabra clave ExternalHelp a un nombre de archivo sin una ruta de acceso. Get-Help busca el nombre de archivo especificado en un subdirectorio específico del idioma del directorio de módulo. No existen requisitos relativos al nombre del archivo de ayuda basado en XML de una función, pero como práctica recomendada, se recomienda utilizar el siguiente formato:
<ScriptModule.psm1>-help.xml
Si la función no se incluye en un módulo, incluya una ruta de acceso al archivo de ayuda basado en XML. Si el valor incluye una ruta de acceso y la ruta de acceso contiene subdirectorios específicos del idioma de interfaz de usuario, Get-Help busca en las subdirectorios de forma recursiva para intentar encontrar un archivo XML con el nombre del script o la función, de acuerdo con los estándares de reserva de idioma establecidos para Windows, como lo hace en el directorio de un módulo.
Para más información sobre el formato de archivo de ayuda basado en XML de cmdlets, consulte "Cómo crear ayuda de cmdlets" en MSDN (Microsoft Developer Network) Library, en el vínculo https://go.microsoft.com/fwlink/?LinkID=123415.
CONTENIDO GENERADO AUTOMÁTICAMENTE
El nombre, la sintaxis, la lista de parámetros, la tabla de atributos de parámetros, los parámetros comunes y las notas se generan automáticamente mediante el cmdlet Get-Help.
Nombre:
La sección Nombre del tema de ayuda de una función se toma del nombre de la función de la sintaxis de la función. El valor Nombre del tema de ayuda de un script se toma del nombre del archivo de script. Para cambiar el nombre o el uso de mayúsculas, cambie la sintaxis de la función o el nombre del archivo de script.
Sintaxis:
La sección Sintaxis del tema de ayuda se genera a partir de la sintaxis de la función o el script. Para agregar detalles a la sintaxis del tema de ayuda, como el tipo de .NET Framework de un parámetro, agregue los detalles 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 el script y de las descripciones que se agregan con la palabra clave Parameters. Los parámetros de la función se muestran en la sección "Parámetros" del tema de ayuda en el mismo orden en que aparecen en la sintaxis de la función o el script. La escritura y el uso de mayúsculas de los nombres de parámetros también se toman de la sintaxis; el nombre de parámetro que especifica la palabra clave Parameter no afecta.
Parámetros comunes:
Los parámetros comunes se agregan a la lista de parámetros y a la sintaxis del tema de ayuda, incluso aunque no tengan ningún efecto. Para más información sobre los parámetros comunes, consulte about_CommonParameters.
Tabla de atributos de parámetros:
Get-Help genera la tabla de atributos de parámetros que aparece cuando se utilizan los parámetros Full o Parameter de Get-help. El valor de los atributos Required, Position y Default proceden de la sintaxis de la función o el script.
NOTA PARA LA SOLUCIÓN DE PROBLEMAS:
Los valores predeterminados no aparecen en la tabla de atributos de parámetros, incluso aunque se definan en la función o el script. Para ayudar a los usuarios, especifique el valor predeterminado en la descripción del parámetro.
Notas:
La sección de notas del tema de ayuda se genera automáticamente a partir del nombre de la función o el script. No puede cambiar ni alterar su contenido.
DESHABILITACIÓN DE LA AYUDA BASADA EN COMENTARIOS
[Esta técnica fue una sugerencia de Rich Prescott, un ingeniero de Windows de Nueva York, NY].
Puede deshabilitar la ayuda basada en comentarios. Esto hace que la ayuda basada en comentarios no esté en vigor sin eliminarla.
Para deshabilitar la ayuda basada en comentarios, escriba los comentarios en una cadena de tipo here-string. Para ocultar la cadena here-string, asígnela a una variable o canalícela al cmdlet Out-Null.
Mientras está deshabilitada, la ayuda basada en comentarios no tiene ningún efecto.
Por ejemplo, la siguiente función tiene ayuda basada en comentarios.
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
#>
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
...
}
Para deshabilitar la ayuda basada en comentarios, especifíquela en una cadena here-string, tal y como se muestra en el ejemplo siguiente.
@"
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
#>
"@
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
...
}
Para ocultar la ayuda basada en comentarios deshabilitada, asigne la cadena here-string a una variable local que no se use de otra forma en la función, como se muestra en el ejemplo siguiente. También puede canalizarla al cmdlet Out-Null.
$x = @"
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
#>
"@
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
...
}
Para más información sobre las cadenas here-string, consulte about_Quoting_Rules (https://go.microsoft.com/fwlink/?LinkID=113253).
EJEMPLOS
Ejemplo 1: ayuda basada en comentarios de una función
La siguiente función de ejemplo incluye ayuda basada en comentarios:
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.
.PARAMETER Name
Specifies the file name.
.PARAMETER Extension
Specifies the extension. "Txt" is the default.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
Los resultados son los siguientes:
C:\PS> get-help add-extension -full
NAME
Add-Extension
SYNOPSIS
Adds a file name extension to a supplied name.
SYNTAX
Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>]
DESCRIPTION
Adds a file name extension to a supplied name. Takes any strings for the file name or extension.
PARAMETERS
-Name
Specifies the file name.
Required? false
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters?
-Extension
Specifies the extension. "Txt" is the default.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".
INPUTs
None. You cannot pipe objects to Add-Extension.
OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
-------------------------- EXAMPLE 1 --------------------------
C:\PS> extension -name "File"
File.txt
-------------------------- EXAMPLE 2 --------------------------
C:\PS> extension -name "File" -extension "doc"
File.doc
-------------------------- EXAMPLE 3 --------------------------
C:\PS> extension "File" "doc"
File.doc
RELATED LINKS
http://www.fabrikam.com/extension.html
Set-Item
Ejemplo 2: descripciones de parámetros en la sintaxis de la función
Este ejemplo es el mismo que el anterior, pero se diferencia en que las descripciones de los parámetros se insertan en la sintaxis de la función. Este formato es más útil cuando las descripciones son breves.
function Add-Extension
{
param
(
[string]
# Specifies the file name.
$name,
[string]
# Specifies the file name extension. \"Txt\" is the default.
$extension = "txt"
)
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name. Takes any strings for the file name or extension.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
Ejemplo 3: ayuda basada en comentarios de un script.
El siguiente script de ejemplo incluye ayuda basada en comentarios.
Observe las líneas en blanco entre el elemento "#>" de cierre y la instrucción Param. En un script que no tiene una instrucción Param, debe haber al menos dos líneas en blanco entre el comentario final del tema de ayuda y la primera declaración de una función. Sin esas líneas en blanco, Get-Help asocia el tema de ayuda a la función, no al script.
<#
.SYNOPSIS
Performs monthly data updates.
.DESCRIPTION
The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.
.PARAMETER InputPath
Specifies the path to the CSV-based input file.
.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.
.INPUTS
None. You cannot pipe objects to Update-Month.ps1.
.OUTPUTS
None. Update-Month.ps1 does not generate any output.
.EXAMPLE
C:\PS> .\Update-Month.ps1
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv
#>
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
El siguiente comando obtiene la ayuda del script. Como el script no está en un directorio que se muestre en la variable de entorno Path, el comando Get-Help que obtiene la ayuda del script debe especificar la ruta de acceso del script.
PS C:\ps-test> get-help .\update-month.ps1 -full
NAME
C:\ps-test\Update-Month.ps1
SYNOPSIS
Performs monthly data updates.
SYNTAX
C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]
DESCRIPTION
The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.
PARAMETERS
-InputPath
Specifies the path to the CSV-based input file.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters?
-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
None. You cannot pipe objects to Update-Month.ps1.
OUTPUTS
None. Update-Month.ps1 does not generate any output.
-------------------------- EXAMPLE 1 --------------------------
C:\PS> .\Update-Month.ps1
-------------------------- EXAMPLE 2 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-------------------------- EXAMPLE 3 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv
RELATED LINKS
Ejemplo 4: redirección a un archivo XML
Puede escribir temas de ayuda basados en XML para funciones y scripts. Aunque la ayuda basada en comentarios es más fácil de implementar, la ayuda basada en XML es necesaria para la ayuda actualizable y para ofrecer temas de ayuda en varios idiomas.
En el ejemplo siguiente se muestran las primeras líneas del script Update-Month.ps1. El script utiliza la palabra clave ExternalHelp para especificar la ruta de acceso a un tema de ayuda basado en XML del script.
Tenga en cuenta que el valor de la palabra clave ExternalHelp aparece en la misma línea que la palabra clave. Cualquier otra ubicación no es eficaz.
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
En el ejemplo siguiente se muestran tres posiciones válidas de la palabra clave ExternalHelp en una función.
function Add-Extension
{
# .ExternalHelp C:\ps-test\Add-Extension.xml
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
# .ExternalHelp C:\ps-test\Add-Extension.xml
}
# .ExternalHelp C:\ps-test\Add-Extension.xml
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}
Ejemplo 5: redirección a otro tema de ayuda
El código siguiente es un fragmento del principio de la función de ayuda integrada en Windows PowerShell, que muestra las pantallas de texto de ayuda de una en una. Como el tema de ayuda del cmdlet Get-Help describe la función de ayuda, esta función utiliza las palabras clave ForwardHelpTargetName y ForwardHelpCategory 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 siguiente comando utiliza esta característica:
C:\PS> get-help help
NAME
Get-Help
SYNOPSIS
Displays information about Windows PowerShell cmdlets and concepts.
...
PALABRAS CLAVE
about_Comment-Based_Help
VEA TAMBIÉN
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
"Cómo escribir ayuda de cmdlets" (https://go.microsoft.com/fwlink/?LinkID=123415)