La ayuda de PowerShell

PowerShell

Este es uno de los capítulos del tutorial PowerShell. Encontrarás los enlaces a todos los de capítulos, al final de este artículo.

En el tutorial de scripts en Bash dejé la ayuda para uno de los capítulos finales del tutorial, concretamente el capítulo sobre una ayuda para tus scripts. Sin embargo, preparando este tutorial, y mientras me documentaba sobre PowerShell, he visto, que en muchos tutoriales, el capítulo de ayuda de PowerShell se encuentra de los primeros, y creo que es lo mas acertado, sobre todo en el caso de PowerShell.

Como habrás oído en mas de una ocasión, a programar se aprende programando. De la misma manera, creo que la mejor de aprender a utilizar un shell es utilizándolo, y en este sentido, que mejor forma que desde la ayuda.

Si estás acostumbrado a utilizar otros shell en Linux, verás que PowerShell es peculiar, no es como los que has utilizando hasta el momento, con lo que te tienes que habituar a su sintaxis y funcionamiento. Y ¿que mejor forma de hacerlo que con la ayuda?.

La ayuda de PowerShell

La ayuda de PowerShell

En el caso de PowerShell, no es necesario que memorices decenas o cientos de comandos e instrucciones. Lo que necesitas es saber utilizar la ayuda de PowerShell a las mil maravillas. Si sabes como utilizar la ayuda de PowerShell, ya tienes mucho camino recorrido.

¿Donde conseguir la ayuda?

La ayuda de PowerShell la tienes en PowerShell. Puedes conseguir ayuda de un comando con Get-Help <comando>, pero no solo esto, sino que también puedes consultarlo en línea, ejecutando Get-Help <comando> -Online.

Lo mejor es consultarlo directamente en tu equipo y para ello, necesitas descargar e instalar los archivos de ayuda. Y es que PowerShell no incluye la ayuda por defecto, como te digo, tienes que instalarla o consultarla en línea como has visto antes. Para instalar la ayuda en tu equipo, tan solo tienes que ejecutar la siguiente instrucción,

Update-Help

A partir de aquí ya tienes toda la información en tu equipo y puedes consultarla cuando quieras. Desde PowerShell, puedes consultar la ayuda utilizando los comandos help y Get-Help.

Sobre los cmdlets de ayuda

En el capítulo de introducción escribí sobre los comandos de PowerShell, los cmdlets. Los comandos de PowerShell tienen una forma verbo-sustantivo, como por ejemplo, el primero que abordarás en este tutorial Get-Help. PowerShell, tiene tres cmdlets principales,

  • Get-Help
  • Get-Command
  • Get-Member

Con estos tres cmdlets tenemos que ser capaces de desenvolvernos con soltura en PowerShell, y por esta razón, es necesario conocerlos en profundidad. Así, para averiguar que hace un cmdlet tienes que utilizar estas herramientas.

Get-Help

El primero de los cmdlet con el que tienes que lidiar es Get-Help. Este cmdlet te muestra información sobre cmdlets, funciones, scripts, módulos, y mucho mas.

Como te indiqué anteriormente, PowerShell no incluye los archivos de ayuda, pero puedes obtener información en línea o utilizando el cmdlet Update-Help para descargar los archivos de ayuda a tu ordenador, y de esta forma tener toda la ayuda directamente desde la línea de comandos.

Para obtener ayuda en línea, tendrías que utilizar la opción -Online, como te muestro a continuación,

Get-Help -Online Get-Help

También puedes obtener ayuda de cualquier cmdlet utilizando la opción -?, como a continuación Get-Help -?. Pero no solo esto, tienes las siguientes opciones para obtener ayuda de un cmdlet,

  • Get-Help Get-Help
  • Get-Help -Name Get-Help
  • Get-Help -?
  • help Get-Help

Pero, si quieres obtener información mas detallada, tienes dos opciones adicionales,

  • Get-Help Get-Help -Detailed
  • Get-Help Get-Help -Full

Por ejemplo, para el caso de Get-Help Get-Help -Full además de la descripción y sintáxis, se muestran los diferentes parámetros que puedes utilizar, entre ellos, por ejemplo, -Full. De este te da la siguiente descripción,

-Full

Required?                    false
Position?                    Named
Accept pipeline input?       false
Parameter set name           AllUsersView
Aliases                      None
Dynamic?                     false
Accept wildcard characters?  false

Esta descripción te informa sobre la utilización del parámetro. Así, por ejemplo, en el caso anterior, te indica que no es un parámetro requerido, que es independiente de la posición, que no se puede utilizar encadenado a otros comandos, es decir, no se puede utilizar con pipes o tuberías.

Por el contrario, por ejemplo, el parámetro -Name te muestra la siguiente información,

-Name <string>

Required?                    false
Position?                    0
Accept pipeline input?       true (ByPropertyName)
Parameter set name           (All)
Aliases                      None
Dynamic?                     false
Accept wildcard characters?  false

Como ves, en este caso si que permite el uso por posición, en este caso 0, esto indica que es completamente equivalente Get-Help Get-ChildItem, por ejemplo, a Get-Help -Name Get-ChildItem.

Por otro lado también admite el uso de pipes, por ejemplo,

Get-Comman Get-ChildItem | Get-Help

De cualquier forma, el encadenamiento de comandos o tuberías o pipes, será un tema que abordaremos mas adelante y con mas profundidad. Ahora simplemente que sepas lo que significan las características que te muestra la ayuda.

Tampoco necesitas mostrar toda la ayuda para un determinado cmdlet. Tienes la opción de mostrar solo una sección de la ayuda. Por ejemplo, en el caso de que solo quisieras mostrar los ejemplos, en el caso de que los tuviera, puedes hacerlo con la opción -Examples como te muestro a continuación,

Get-Help Get-Help -Examples

O si quisieras ver solo la sección correspondiente a los parámetros, lo podrías hacer utilizando Get-Help Get-Help -Parameter *.

Indicarte que la ayuda que se muestra es sensiblemente diferente dependiendo de la plataforma en la que la estés ejecutando. De hecho, la misma instrucción ejecutada en Microsoft Windows, da mucha mas información, incluso para el caso de Get-Help.

Algunos aspectos interesantes
  • Get-Help tal cual, es decir, sin parámetros adicionales, te mostrará información sobre el sistema de ayuda de PowerShell. Es decir, básicamente, lo que puedes leer en este capítulo.
  • Get-Help * mostrará por pantalla un litado de todos los artículos de ayuda que tienes disponibles en tu equipo.
  • Get-Help about_*, con este obtendrás todos los artículos conceptuales incluidos con la ayuda. De nuevo, aquí indicarte que, dependiendo de en que plataforma lo ejecutes, obtendrás una ayuda u otra. Por ejemplo, en mi equipo Linux, no me muestra ayuda alguna.
  • Get-Help -Name <palabra> muestra un listado de artículos que tengan que ver con esa palabra, siempre que no haya coincidencia exacta, en cuyo caso te mostrará la ayuda en cuestión. Es decir, si ejecutas Get-Help -Name help te mostrará la ayuda de Get-Help. Sin embargo, si ejecutas Get-Help -Name hel te mostrará el siguiente listado de artículos,
Name      Category  Module                     Synopis
----      --------  ------                     -------
help      Function  Microsoft.PowerShell.Core  ...
Get-Help  Cmdlet    Microsoft.PowerShell.Core  ...
Save-Help Cmdlet    Microsoft.PowerShell.Core  ...
...
  • Get-Help -Name ejemplo.ps1 te mostrará la ayuda del script ejemplo.ps1. Evidentemente este script tiene que tener su ayuda o de otra forma no se mostrará nada. En el capítulo sobre scripts con powershell abordaré este tema, para que sea mas sencillo utilizar nuestros propios scripts.

Get-Command

Este cmdlet te muestra un listado de todos los cmdlet, alias, funciones, filtros, scripts y aplicaciones, que tienes instalado en tu equipo. Get-Command * trae todo tipo de comandos, incluyendo todos los archivos que se encuentren en el Path.

Si ejecutas Get-Command con el nombre exacto de un cmdlet, sin comodines, automáticamente importa el módulo que contiene el comando, en el caso de que no esté disponible, de forma que puedes utilizar el comando de inmediato. Si por el contrario está disponible te mostrará un resultado como el que ves a continuación para Get-Command Get-Help,

CommandType     Name      Version    Source
-----------     ----      -------    ------
Cmdlet          Get-Help  7.1.1.0    Microsoft.P…
  • Get-Command -ListImported lista todos los comandos que están disponibles en la sesión en curso. En el caso de que haya alguno que necesites, y no está disponible lo puedes importar como te he indicado anteriormente.
  • Get-Command -Type Cmdlet lista todos los cmdlet, si quieres puedes listar Alias, Application, Configuration, Filter, Script, ExternaScript, Function. O en el caso de que quieras listar todos utiliza All. Si, además los quieres listados ordenados por nombre lo puedes hacer de la siguiente forma,
Get-Command -Type Cmdlet | Sort-Object -Property Noun
  • También puedes listar los comandos que se encuentran en un módulo puedes utilizar la opción -Module, como por ejemplo en Get-Command -Module Microsoft.PowerShell.Utility. Si quieres saber todos los módulos disponibles puedes utilizar el comando Get-Module -ListAvailable.
  • Si quieres saber información de un determinado comando puedes ejecutar Get-Command <comando> -ShowCommandInfo, como por ejemplo en Get-Command Get-ChildItem -ShowCommandInfo. O si quieres obtener el módulo en el que se encuentra un determinado comando, por ejemplo Get-Help, puedes hacerlo de la siguiente forma (Get-Command Get-Help).ModuleName
  • También puedes listar todos los cmdlet que tengan un determinado parámetro, como por ejemplo Get-Command -ParameterName Hidden, que te devolverá lo siguiente,
CommandType     Name           Version    Source
-----------     ----           -------    ------
Cmdlet          Get-ChildItem  7.0.0.0    Microsoft.P…

De la misma manera también puedes conseguir información relativa a un alias. Por ejemplo, si quieres conseguir información relativa al alias dir, puedes ejecutar Get-Command dir que te devolverá lo siguiente,

CommandType     Name                 Version    Source
-----------     ----                 -------    ------
Alias           dir -> Get-ChildItem

Get-Member

El tercero de los cmdlet con los que conseguir ayuda es Get-Member. Este cmdlet te muestra los miembros de un objeto, es decir, te da información sobre las propiedades* y métodos.

Por ejemplo, si quieres obtener tanto propiedades como métodos del cmdlet Get-Help, tienes que ejecutar la siguiente instrucción,

Get-Command Get-Help | Get-Member

Esto te devolverá lo siguiente,

   TypeName: System.Management.Automation.CmdletInfo

Name                MemberType     Definition
----                ----------     ----------
Equals              Method         bool Equals(System.Object obj)
GetHashCode         Method         int GetHashCode()
GetType             Method         type GetType()
ResolveParameter    Method         System.Management.Automation.ParameterMet...
ToString            Method         string ToString()
CommandType         Property       System.Management.Automation.CommandTypes CommandType …
DefaultParameterSet Property       string DefaultParameterSet {get;}
Definition          Property       string Definition {get;}
HelpFile            Property       string HelpFile {get;}
ImplementingType    Property       type ImplementingType {get;}
Module              Property       psmoduleinfo Module {get;}
ModuleName          Property       string ModuleName {get;}
Name                Property       string Name {get;}
Noun                Property       string Noun {get;}
Options             Property       System.Management.Automation.ScopedItemOp...
OutputType          Property       System.Collections.ObjectModel.ReadOnlyCo...
Parameters          Property       System.Collections.Generic.Dictionary[str...
ParameterSets       Property       System.Collections.ObjectModel.ReadOnlyCollection[Syst…
PSSnapIn            Property       System.Management.Automation.PSSnapInInfo...
RemotingCapability  Property       System.Management.Automation.RemotingCapa...
Source              Property       string Source {get;}
Verb                Property       string Verb {get;}
Version             Property       version Version {get;}
Visibility          Property       System.Management.Automation.SessionState...
DLL                 ScriptProperty System.Object DLL {get=$this.Implementing...
HelpUri             ScriptProperty System.Object HelpUri {get=$oldProgressPr...

Esto mas o menos ya lo has intuido de lo que has visto antes. Por ejemplo, puedes conocer el nombre del módulo al que pertenece con (Get-Command Get-Help).ModuleName.

Desde luego que este cmdlet tiene muchas mas posibilidades, pero esto lo podrás ver en los siguientes capítulos del tutorial, conforme vayas profundizando en PowerShell.

Conclusión

Como ves, una de las características interesantes de PowerShell es precisamente su potente ayuda. Sin embargo, inicialmente solo tienes que recordar tres cmdlet, Get-Help, Get-Command y Get-Member. A partir de estos tres, tienes que conseguir obtener el resto de información que necesites.


Imagen de portada de nikko macaspac en Unsplash

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *