La ayuda de PowerShell

Es interesante conocer qué tipo de ayuda ofrece PowerShell para darnos cuenta de cómo debemos implementarla en nuestros comandos. vamos a ver unos ejemplos a través del commando Get-Help.

Cómo usar la ayuda de un comando

Podemos obtener ayuda de un comando de varias formas. Vamos a usar el comando Get-Help como ejemplo para ver las diferentes opciones de ayuda disponibles. EL comando Get-Help obtiene ayuda de un comando y, sí, es posible obtener ayuda de Get-Help de las siguientes maneras:

Get-Help Get-Help

Get-Help –?

ambos comandos provocan como salida:

NOMBRE
    Get-Help
SINTAXIS
    Get-Help [[-Name] <string>]  [...] [<CommonParameters>]
[...]
ALIAS
    Ninguno

NOTAS
    Get-Help no encuentra los archivos de Ayuda para este cmdlet en el equipo. Mostrará solo una parte de la Ayuda.
        -- Para descargar e instalar los archivos de Ayuda para el módulo que incluye este cmdlet, use Update-Help.
        -- Para ver en línea el tema de Ayuda de este cmdlet, escriba "Get-Help Get-Help -Online" o
           vaya a http://go.microsoft.com/fwlink/?LinkID=113316.

El propio comando posiblemente nos indique en las notas que no encuentra la ayuda y debemos descargarla o bien consultarla online.

Es interesante leer la opción –online. Muchos de los comandos tienen su ayuda documentada en Internet y es posible acceder a ella a través del comando Get-Help [commando] –online.
En este caso nos abrirá en el navegador el siguiente enlace:

https://msdn.microsoft.com/powershell/reference/5.1/microsoft.powershell.core/Get-Help

En realidad el comando apenas nos ha dado información. Esto es porque cada módulo tiene un fichero XML asociado con la documentación de cada uno de los comandos. Es por ello conveniente descargar la documentación. podemos hacerlo usando el comando Update-Help. Una vez actualizada podemos repetir el comando. Veremos que tiene más información y con más sentido que lo anterior. Esto es una parte resumida del contenido mostrado:

PS C:\WINDOWS\system32> get-help get-Help
NOMBRE
    Get-Help
SINOPSIS
    Displays information about Windows PowerShell commands and concepts.

SINTAXIS
    Get-Help [[-Name] <String>] [-Category {Alias | Cmdlet | Provider | General | FAQ | Glossary | HelpFile | ScriptCommand | Function | Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource | Class | Configuration}] [-Component <String[]>] -Detailed
    [-Functionality <String[]>] [-Path <String>] [-Role <String[]>] [<CommonParameters>]
…
DESCRIPCIÓN
    The Get-Help cmdlet displays information about Windows PowerShell concepts and commands, including cmdlets, functions, CIM commands, workflows, providers, aliases and scripts.
    To get help for a Windows PowerShell command, type `Get-Help` followed by the command name, such as: `Get-Help Get-Process`. To get a list of all help topics on your system, type `Get-Help *`. You can display the whole help topic or use the parameters of the
    Get-Help cmdlet to get selected parts of the topic, such as the syntax, parameters, or examples.
…
VÍNCULOS RELACIONADOS
    Online Version: http://go.microsoft.com/fwlink/?LinkId=821483
    Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007) http://go.microsoft.com/fwlink/?LinkID=270007
    about_Command_Syntax
    Get-Command
NOTAS
    Para ver los ejemplos, escriba: "get-help Get-Help -examples".
    Para obtener más información, escriba: "get-help Get-Help -detailed".
    Para obtener información técnica, escriba: "get-help Get-Help -full".
    Para obtener ayuda disponible en línea, escriba: "get-help Get-Help -online"

Como se puede ver muestra varias secciones:

• Nombre
• Sinopsis
• Sintaxis
• Descripción
• Vínculos relacionados
• Notas

Además el propio comando nos indica que hay más contenido que mostrar si indicamos opciones como –Detailed,

–Full o –examples, que veremos en la siguiente sección.

Opciones de ayuda

Veamos qué más podemos exprimir de la ayuda. Si consultamos el enlace de la ayuda online de Get-Help podemos ver que hay varias formas de obtener ayuda de un comando a través de los siguientes parámetros:

• -ShowWindow
• -Online
• -Detailed y –Full
• -Parameter
• -Examples

El parámetro  -ShowWindow quizá sea poco utilizado pero es uno de mis preferidos. Permite mostrar la ayuda en una ventana aparte. Por ejemplo, si queremos la ayuda del comando “Get-Module” con el parámetro showWindow de la siguiente manera: 

PS C:\WINDOWS\system32> get-help get-module –ShowWindow

se abrirá una ventana como esta:

El contenido de la ventana es equivalente a poner el parámetro –Full pero en lugar de usar la salida estándar de PowerShell se usa una ventana al estilo Windows. Esta ventana no solo nos permite buscar dentro del contenido sino que además podemos hacer zoom, copiar contenido o modificar las opciones de salida en la ventana a través del botón Configuración. Y sobre todo hay que contemplar que esta opción nos permite seguir trabajando en nuestra sesión de PowerShell sin necesidad de llenar el búfer de línea de comandos con la información de la ayuda.

Es interesante leer la opción –online. Muchos de los comandos tienen su ayuda documentada en Internet y es posible acceder a ella a través del comando Get-Help [commando] –online.
En este caso nos abrirá en el navegador el siguiente enlace:

https://msdn.microsoft.com/powershell/reference/5.1/microsoft.powershell.core/Get-Help

El parámetro –Detailed proporciona, además del contenido anterior, el siguiente contenido:

Parámetros: la lista de parámetros.

Notas: Si el comando contiene notas éstas aparecerán en esta sección. Ejemplos: Si el comando contiene ejemplos aparecerán en esta sección de forma enumerada.
El comando del ejemplo siguiente proporciona la salida con el parámetro –Detailed:

C:\> get-help get-module -Detailed
NOMBRE
    Get-Module
SINTAXIS
    Get-Module [[-Name] <string[]>]  [<CommonParameters>]
   
PARÁMETROS
    -All
    -CimNamespace <string>
    -CimResourceUri <uri>
    -CimSession <CimSession>
    -FullyQualifiedName <ModuleSpecification[]>
    -ListAvailable
    -Name <string[]>
    -PSEdition <string>
    -PSSession <PSSession>
    -Refresh
    <CommonParameters>
        Este cmdlet admite los parámetros comunes Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable y OutVariable. Para obtener más información, consulte
        about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

ALIAS
    gmo

NOTAS
    Get-Help no encuentra los archivos de Ayuda para este cmdlet en el equipo. Mostrará solo una parte de la Ayuda.
        -- Para descargar e instalar los archivos de Ayuda para el módulo que incluye este cmdlet, use Update-Help.
        -- Para ver en línea el tema de Ayuda de este cmdlet, escriba "Get-Help Get-Module -Online" o
           vaya a http://go.microsoft.com/fwlink/?LinkID=141552.

La opción –Parameter seguida de un nombre de parámetro nos proporciona la información detallada de dicho parámetro. Por ejemplo, el comando get-help get-module -Parameter name tiene la siguiente salida:

C:\> get-help get-module -Parameter name
-Name <string[]>
    ¿Requerido?                  false
    ¿Posición?                   0
    ¿Aceptar canalización?       true (ByValue)
    Nombre de conjunto de parámetros           Loaded, Available, PsSession, CimSession
    Alias                      Ninguno
    ¿Dinámico?                     false

Me he saltado la opción –Full a propósito. La diferencia entre –detailed y –full es que la opción full muestra cada parámetro como si se hubiese especificado el parámetro parameter para cada uno de ellos. Por tanto, especificando la opción –full  tendremos para cada parámetro su detalle (requerido, posición, canalización, etc.).