Interpretación del contenido del archivo de ayuda y actualización del contenido de ayuda local en PowerShell

Completado

Cuando encuentre el comando que necesita para una tarea, puede usar su archivo de ayuda para aprender a usarlo. Una manera de aprender es examinar los ejemplos e intentar comprender su uso. No obstante, es raro que los ejemplos traten todas las posibles variaciones del uso del comando. Aprender a interpretar la sintaxis del archivo de ayuda puede ayudarle a identificar todas las funcionalidades de un comando determinado.

Ayuda de Get-EventLog

Use la ayuda para Get-EventLog como ejemplo. Si escribe el comando Get-Help Get-EventLog en la consola y presiona la tecla Entrar, la ayuda devuelve la sintaxis siguiente:

Get-EventLog [-LogName] <String> [[-InstanceId] <Int64[]>] [-After <DateTime>] [-AsBaseObject] [-Before <DateTime>] [-ComputerName <String[]>] [-EntryType {Error | Information | FailureAudit | SuccessAudit | Warning}] [-Index <Int32[]>] [-Message <String>] [-Newest <Int32>] [-Source <String[]>] [-UserName <String[]>] [<CommonParameters>]

Get-EventLog [-AsString] [-ComputerName <String[]>] [-List] [<CommonParameters>]

Los dos bloques de texto son conjuntos de parámetros, cada uno de los cuales representa una manera en la que puede ejecutar el comando. Observe que cada conjunto de parámetros tiene muchos parámetros y ambos tienen varios parámetros en común. No se pueden mezclar ni relacionar parámetros entre conjuntos. Es decir, si decide usar el parámetro –List , no puede usar también –LogName, ya que estos parámetros no aparecen juntos en el mismo conjunto de parámetros.

El nombre del parámetro –LogName se coloca entre corchetes, lo que significa que es un parámetro posicional. No se puede ejecutar el comando sin un nombre de registro. Sin embargo, no es necesario escribir el nombre del parámetro –LogName . Debe pasar la cadena del nombre de registro como primer parámetro, ya que esa es la posición en el archivo de ayuda donde aparece el parámetro –LogName . Por tanto, los dos comandos siguientes arrojan los mismos resultados:

Get-EventLog –LogName Application
Get-EventLog Application

Omisión de nombres de parámetros

Tenga cuidado al omitir los nombres de parámetro, por varios motivos. No se pueden omitir todos los parámetros. Por ejemplo, el parámetro -ComputerName no puede omitir el nombre del parámetro. Además, puede perder rápidamente el hilo de dónde va cada cosa. Al proporcionar nombres de parámetro, los parámetros pueden aparecer en cualquier orden, como se muestra en el siguiente comando:

Get-EventLog –ComputerName LON-DC1 –LogName Application –Newest 10

Sin embargo, al omitir los nombres de parámetro, debe asegurarse de escribir los parámetros en el orden correcto. Por ejemplo, el siguiente comando no funcionará porque el valor del nombre del registro no aparece en la posición correcta:

Get-EventLog –ComputerName LON-DC1 Application

Especificación de varios valores

Algunos parámetros aceptan más de un valor. En la sección SINTAXIS, una notación entre corchetes dobles en el tipo de valor de parámetro designa estos parámetros. Por ejemplo:

-ComputerName <string[]>

La sintaxis anterior indica que el parámetro –ComputerName puede aceptar uno o varios valores de cadena. Una manera de especificar varios valores es mediante una lista separada por comas. No es necesario incluir los valores entre comillas, a menos que los propios valores contengan una coma o un espacio en blanco, como un carácter de espacio o tabulación. Por ejemplo, use el siguiente comando para especificar varios nombres de equipo:

Get-EventLog –LogName Application –ComputerName LON-CL1,LON-DC1

Nota:

Para obtener más información sobre cada parámetro, consulte la ayuda completa del comando. Por ejemplo, ejecute Get-Help Get-EventLog –Full para consultar la ayuda completa de Get-EventLog y observe la información adicional que se muestra. Por ejemplo, puede confirmar que el parámetro –LogName es obligatorio y aparece en la primera posición.

Procedimiento recomendado: Si acaba de empezar a trabajar con Windows PowerShell, procure proporcionar nombres de parámetro completos en lugar de pasar valores de parámetro por posición. Los nombres de parámetro completos facilitan la revisión y la solución de problemas, así como la detección de errores si escribe el comando incorrectamente.

Actualización de la Ayuda

Las versión de Windows PowerShell 3.0 y posteriores no se envían con archivos de ayuda. En su lugar, los archivos de ayuda están disponibles como servicio en línea. Los comandos creados por Microsoft tienen sus archivos de ayuda hospedados en servidores web propiedad de Microsoft. Los comandos que no son de Microsoft a veces están disponibles en línea, siempre y cuando el autor o proveedor compile el módulo correctamente y proporcione una ubicación en línea para los archivos de ayuda. Con el modelo en línea, los autores que escriben comandos, incluidos los autores de Microsoft, pueden realizar correcciones y mejoras en sus archivos de ayuda a lo largo del tiempo y, a continuación, entregarlos sin tener que crear una actualización completa del producto.

Ejecute Update-Help para examinar el equipo en busca de todos los módulos instalados, recuperar las ubicaciones de ayuda en línea de cada uno e intentar descargar sus respectivos archivos de ayuda. Debe ejecutar este comando como miembro del grupo administradores local, ya que la ayuda principal de los comandos de Windows PowerShell se almacena en la carpeta %systemdir% . Aparecerán mensajes de error si la ayuda no se puede descargar. En tal caso, Windows PowerShell seguirá creando una pantalla de ayuda predeterminada para los comandos.

Windows PowerShell descarga de manera predeterminada los archivos de ayuda en el idioma configurado del sistema. Si la ayuda no está disponible en ese idioma, Windows PowerShell descarga de forma predeterminada el idioma en-US (inglés de EE. UU.). Puede invalidar este comportamiento mediante un parámetro de Update-Help para especificar la UICulture para la que desea recuperar ayuda.

De forma predeterminada, Update-Help comprobará los archivos de ayuda una vez cada 24 horas, incluso si ejecuta el comando varias veces seguidas. Para invalidar este comportamiento, incluya el parámetro –Force.

El complemento de Update-Help es Save-Help. Descarga el contenido de ayuda y lo guarda en la ubicación que especifique. Esto le permite copiar ese contenido en equipos que no están conectados a Internet. Update-Help ofrece un parámetro para especificar una ubicación de origen alternativa. Esta función permite actualizar la ayuda en equipos que no están conectados a Internet.

En versiones anteriores a Windows PowerShell 4.0, Update-Help y Save-Help descargan ayuda solo para los cmdlets instalados en el equipo local (desde donde se ejecuta el comando). En Windows PowerShell 4.0 y versiones posteriores, puede usar Save-Help para módulos instalados en equipos remotos.