Acerca de la Ayuda actualizable
DESCRIPCIÓN BREVE
Describe el sistema de ayuda actualizable en PowerShell.
DESCRIPCIÓN LARGA
PowerShell proporciona varias maneras diferentes de acceder a los temas de ayuda más actualizados para los cmdlets y conceptos de PowerShell.
El sistema de Ayuda actualizable, introducido en PowerShell 3.0, está diseñado para asegurarse de que siempre tiene los temas de ayuda más recientes en el equipo local para que pueda leerlos en la línea de comandos. Facilita la descarga e instalación de archivos de ayuda y su actualización cada vez que los archivos de ayuda más recientes estén disponibles.
Para proporcionar ayuda actualizada para varios equipos de una empresa y para equipos que no tienen acceso a Internet, la Ayuda actualizable le permite descargar archivos de ayuda en un directorio del sistema de archivos o un recurso compartido de archivos y, a continuación, instalar los archivos de ayuda desde el recurso compartido de archivos.
En PowerShell 4.0, la propiedad HelpInfoUri se conserva a través de Windows PowerShell comunicación remota, lo que permite que Save-Help funcionen para los módulos instalados en un equipo remoto, pero no se instalan necesariamente en el equipo local. Puede guardar un objeto PSModuleInfo en disco o medios extraíbles (como una unidad USB) ejecutando Export-Clixml en un equipo que no tenga acceso a Internet, importando el objeto PSModuleInfo en un equipo que tenga acceso a Internet y, a continuación, ejecutando Save-Help en el objeto PSModuleInfo. La ayuda guardada se puede copiar en el equipo remoto, desconectado mediante medios extraíbles y, a continuación, instalarse mediante la ejecución de Update-Help. Estas mejoras en Save-Help funcionalidad le permiten instalar ayuda en equipos sin ningún tipo de acceso a la red. Para obtener un ejemplo de cómo usar la nueva funcionalidad de Save-Help, vea "HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP" en este tema.
La Ayuda actualizable también admite el acceso en línea a los temas de ayuda más recientes y la ayuda básica para cmdlets, incluso cuando no hay archivos de ayuda en el equipo.
PowerShell 3.0 no incluye archivos de Ayuda. Puede usar la característica Ayuda actualizable para instalar los archivos de ayuda para todos los comandos que se incluyen de forma predeterminada en PowerShell y para todos los módulos de Windows.
CMDLETS DE AYUDA ACTUALIZABLES
Update-Help: descarga los archivos de ayuda más recientes de Internet o un recurso compartido de archivos, e los instala en el equipo local.
Save-Help: descarga los archivos de ayuda más recientes de Internet y los guarda en un directorio del sistema de archivos o en un recurso compartido de archivos. Para instalar los archivos de ayuda en equipos, use Update-Help.
Get-Help: muestra los temas de ayuda en la línea de comandos. Obtiene ayuda de los archivos de ayuda del equipo. Muestra la ayuda generada automáticamente para cmdlets y funciones que no tienen archivos de ayuda. Abre temas de ayuda en línea para cmdlets, funciones, scripts y flujos de trabajo en el explorador de Internet predeterminado.
AYUDA DE ACTUALIZACIÓN EN PowerShell ISE
También puede actualizar la ayuda mediante el elemento "Actualizar ayuda de PowerShell" en el menú Ayuda del entorno de scripting integrado (ISE) de PowerShell.
El elemento "Actualizar ayuda de PowerShell" ejecuta un comando Update-Help sin parámetros.
AYUDA GENERADA AUTOMÁTICAMENTE: AYUDA SIN ARCHIVOS DE AYUDA
Si no tiene el archivo de ayuda de un cmdlet, una función o un flujo de trabajo en el equipo, el cmdlet Get-Help muestra ayuda generada automáticamente y le pide que descargue los archivos de ayuda o los lea en línea.
La ayuda generada automáticamente incluye sintaxis y alias, así como comentarios que explican cómo usar los cmdlets de Ayuda actualizables y para acceder a los temas de ayuda en línea.
Por ejemplo, el siguiente comando obtiene ayuda básica para el cmdlet Get-Culture. La salida muestra el Get-Help mostrar cuando no hay archivos de ayuda en el equipo.
Get-Help Get-Culture
NAME
Get-Culture
SYNTAX
Get-Culture [<CommonParameters>]
ALIASES
None
REMARKS
To get the latest Help content including descriptions and examples
type: Update-Help.
ARCHIVOS DE AYUDA PARA MÓDULOS
La unidad más pequeña de Ayuda actualizable es ayuda para un módulo. La ayuda del módulo incluye ayuda para todos los cmdlets, funciones, flujos de trabajo, proveedores, scripts y conceptos de un módulo. Puede actualizar la ayuda de todos los módulos instalados en el equipo, incluso si no se importan en la sesión actual.
Puede actualizar la ayuda de todo el módulo, pero no puede actualizar la ayuda de cmdlets individuales.
Para buscar el módulo que contiene un cmdlet determinado, use el siguiente formato de comando:
(Get-Command <cmdlet-name>).ModuleName
Por ejemplo, para buscar el módulo que contiene el cmdlet Set-ExecutionPolicy, escriba:
(Get-Command Set-ExecutionPolicy).ModuleName
Para actualizar la ayuda de un módulo determinado, escriba:
Update-Help -Module <ModuleName>
Por ejemplo, para actualizar la ayuda del módulo que contiene el cmdlet Set-ExecutionPolicy, escriba:
Update-Help -Module Microsoft.PowerShell.Security
PERMISOS PARA OBTENER AYUDA ACTUALIZABLE
Para actualizar la ayuda de los módulos del directorio $pshome\Modules, debe ser miembro del grupo Administradores del equipo.
Si no es miembro del grupo Administradores, no puede actualizar la ayuda de estos módulos; pero si tiene acceso a Internet, puede ver la ayuda en línea en la biblioteca de TechNet.
La actualización de la ayuda para los módulos del directorio $home\Documents\WindowsPowerShell\Modules o módulos de otros subdirectorios del directorio $home no requieren permisos especiales.
Los cmdlets Update-Help y Save-Help tienen un parámetro UseDefaultCredentials que proporciona las credenciales explícitas del usuario actual. Este parámetro está diseñado para acceder a ubicaciones seguras de Internet.
Los cmdlets Update-Help y Save-Help también tienen un parámetro Credential que permite ejecutar el comando en un equipo remoto y acceder a un recurso compartido de archivos en un tercer equipo. El parámetro Credential solo es válido cuando se usan los parámetros SourcePath o LiteralPath de Update-Help y los parámetros DestinationPath o LiteralPath de Save-Help.
INSTALACIÓN Y ACTUALIZACIÓN DE ARCHIVOS DE AYUDA
Para descargar e instalar archivos de ayuda por primera vez, o para actualizar los archivos de ayuda en el equipo, use el cmdlet Update-Help.
El cmdlet Update-Help realiza todo el trabajo duro para usted, incluidas las siguientes tareas.
- Determina qué módulos admiten ayuda actualizable.
- Busca la ubicación de Internet donde cada módulo almacena sus archivos de Ayuda actualizables.
- Compara los archivos de ayuda de cada módulo del equipo con los archivos de ayuda más recientes que están disponibles para cada módulo.
- Descarga los nuevos archivos de Internet.
- Desencapsula el paquete de archivos de ayuda.
- Comprueba que los archivos son archivos de ayuda válidos.
- Instala los archivos de ayuda en el subdirectorio específico del idioma del directorio del módulo.
Para acceder a los nuevos temas de ayuda, use el cmdlet Get-Help. No es necesario reiniciar PowerShell.
Para instalar o actualizar la ayuda de todos los módulos del equipo que admiten ayuda actualizable, escriba:
Update-Help
Para actualizar la ayuda de determinados módulos, agregue el parámetro Module de Update-Help. Se permiten caracteres comodín en el nombre del módulo.
Por ejemplo, para actualizar la ayuda del módulo ServerManager, escriba:
Update-Help -Module ServerManager
Sin parámetros, Update-Help ayuda para todos los módulos de la sesión y para todos los módulos instalados que admiten ayuda actualizable. Para incluirse, los módulos deben instalarse en directorios que se enumeran en el valor de la variable de entorno PSModulePath. También son módulos devueltos por un comando "Get-Help -ListAvailable".
Si el valor del parámetro Module es * (todos), Update-Help intenta actualizar la ayuda de todos los módulos instalados, incluidos los módulos que no admiten ayuda actualizable. Este comando suele generar muchos errores, ya que el cmdlet encuentra módulos que no admiten ayuda actualizable.
CÓMO ACTUALIZAR LA AYUDA DE UN RECURSO COMPARTIDO DE ARCHIVOS: SAVE-HELP
Para admitir equipos que no están conectados a Internet o para controlar o simplificar la actualización en una empresa, use el cmdlet Save-Help. El cmdlet Save-Help descarga archivos de ayuda de Internet y los guarda en un directorio del sistema de archivos que especifique.
Save-Help compara los archivos de ayuda del directorio especificado con los archivos de ayuda más recientes que están disponibles para cada módulo. Si el directorio no tiene archivos de ayuda o archivos de ayuda más recientes están disponibles para el módulo, el cmdlet Save-Help descarga los nuevos archivos de Internet. Sin embargo, no desencapsula ni instala los archivos de ayuda.
Para instalar o actualizar los archivos de ayuda en un equipo a partir de archivos de ayuda guardados en un directorio del sistema de archivos, use el parámetro SourcePath del cmdlet Update-Help. El cmdlet Update-Help identifica los archivos de ayuda más recientes, desencapsula y los valida, e los instala en los subdirectorios específicos del lenguaje de los directorios del módulo.
Por ejemplo, para guardar la ayuda de todos los módulos instalados en el directorio \\Server\Share, escriba:
Save-Help -DestinationPath \\Server\Share
A continuación, para actualizar la ayuda del directorio \\Server\Share, escriba:
Update-Help -SourcePath \\Server\Share
En los ejemplos siguientes se muestra el uso de Save-Help para guardar la ayuda de los módulos que no están instalados en el equipo local. En este ejemplo, el administrador ejecuta Save-Help para guardar la ayuda del módulo DhcpServer desde un equipo cliente conectado a Internet, sin instalar el módulo DhcpServer o el rol servidor DHCP en el equipo local.
Opción 1: Ejecute Invoke-Command para obtener el objeto PSModuleInfo para el módulo remoto, guárdelo en una variable, $m y, a continuación, ejecute Save-Help en el objeto PSModuleInfo especificando la variable $m como nombre del módulo.
$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock
{ Get-Module -Name DhcpServer -ListAvailable }
Save-Help -Module $m -DestinationPath C:\SavedHelp
Opción 2: Abra una PSSession, destinada al equipo que ejecuta el módulo servidor DHCP, para obtener el objeto PSModuleInfo del módulo, guárdelo en una variable $m y, a continuación, ejecute Save-Help en el objeto que se guarda en la variable $m.
$s = New-PSSession -ComputerName RemoteServer
$m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp
Opción 3: Abra una sesión CIM, dirigida al equipo que ejecuta el módulo servidor DHCP, para obtener el objeto PSModuleInfo del módulo, guárdelo en una variable $m y, a continuación, ejecute Save-Help en el objeto que se guarda en la variable $m.
$c = New-CimSession -ComputerName RemoteServer
$m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp
En el ejemplo siguiente, el administrador instala la ayuda para el módulo Servidor DHCP en un equipo que no tiene acceso a la red.
En primer lugar, ejecute Export-Clixml para exportar el objeto PSModuleInfo a una carpeta compartida o a medios extraíbles.
$m = Get-Module -Name DhcpServer -ListAvailable
Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m
A continuación, transporte los medios extraíbles a un equipo que tenga acceso a Internet y, a continuación, importe el objeto PSModuleInfo con Import-Clixml. Ejecute Save-Help para guardar la Ayuda para el objeto PSModuleInfo del módulo DhcpServer importado.
$deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath `
E:\UsbFlashDrive\SavedHelp
Por último, vuelva a transportar los medios extraíbles al equipo que no tiene acceso a la red y, a continuación, instale la ayuda mediante la ejecución de Update-Help.
Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp
Sin parámetros, Save-Help descarga ayuda para todos los módulos de la sesión y para todos los módulos instalados que admiten ayuda actualizable. Para incluirse, los módulos deben instalarse en directorios que se muestran en el valor de la variable de entorno PSModulePath, en el equipo local o en un equipo remoto para el que desea guardar ayuda. También son módulos que se devuelven mediante la ejecución de un comando "Get-Help -ListAvailable".
ACTUALIZACIÓN DE ARCHIVOS DE AYUDA EN DISTINTOS IDIOMAS
De forma predeterminada, los cmdlets Update-Help y Save-Help descargan ayuda en la referencia cultural y el idioma de la interfaz de usuario que se establece para Windows en el equipo local. Si los archivos de ayuda de los módulos especificados no están disponibles en la referencia cultural de la interfaz de usuario local, Update-Help y Save-Help usar las reglas de reserva de idioma de Windows para encontrar el mejor idioma admitido.
Sin embargo, puede usar los parámetros UICulture de los cmdlets Update-Help y Save-Help para descargar e instalar archivos de ayuda en las referencias culturales de la interfaz de usuario en las que están disponibles.
Por ejemplo, para guardar los archivos de ayuda más recientes para todos los módulos de la sesión en japonés (Ja-jp) y francés (fr-FR), escriba:
Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr
Si los archivos de ayuda de los módulos no están disponibles en los idiomas especificados, los cmdlets Update-Help y Save-Help devuelven un mensaje de error que enumera los idiomas en los que la ayuda de cada módulo está disponible para que pueda elegir la alternativa que mejor se adapte a sus necesidades.
CÓMO ACTUALIZAR LA AYUDA AUTOMÁTICAMENTE
Para asegurarse de que siempre tiene los archivos de ayuda más recientes, puede agregar un comando Update-Help al perfil de PowerShell.
Una cuota interna impide que el comando Update-Help se ejecute más de una vez al día. Para invalidar el máximo de una vez por día, use el parámetro Force.
Use un comando como el siguiente en el perfil. Este comando actualiza la ayuda de todos los módulos instalados en un trabajo en segundo plano para que no moleste el trabajo. Usa un comando Out-Null para suprimir el trabajo que se devuelve y los mensajes de error que, de lo contrario, aparecerían al usar el comando más de una vez al día.
Start-Job {Update-Help} | Out-Null
También puede crear un trabajo programado que ejecute el cmdlet Update-Help o Save-Help en cualquier intervalo.
Por ejemplo, el siguiente comando crea un trabajo programado que ejecuta un comando de ayuda Update-Help todos los viernes a las 5:00 a. m. Para ejecutar este comando, inicie PowerShell con la opción "Ejecutar como administrador".
Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
-Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")
USO DE LA AYUDA EN LÍNEA
Si no puede actualizar o no actualizar los archivos de ayuda en el equipo local, todavía puede obtener los archivos de ayuda más recientes en línea.
Para abrir el tema de ayuda en línea para cualquier cmdlet o función, use el parámetro Online del cmdlet Get-Help.
Por ejemplo, el siguiente comando abre el tema de ayuda en línea para el cmdlet Get-Job en el explorador de Internet predeterminado:
Get-Help Get-Job -Online
Para obtener ayuda en línea para un script, use el parámetro Online y la ruta de acceso completa al script.
El parámetro Online no funciona con temas acerca de. Para ver los temas sobre PowerShell Core, incluidos los temas de ayuda sobre el lenguaje de PowerShell, consulte Módulo de PowerShell Core Acerca de Topics.
CÓMO MINIMIZAR O EVITAR DESCARGAS DE INTERNET
Para minimizar las descargas de Internet y proporcionar ayuda actualizable a los usuarios que no están conectados a Internet, use el cmdlet Save-Help. Descargue la ayuda de Internet y guárdela en un recurso compartido de red. A continuación, cree una configuración de directiva de grupo o un trabajo programado que ejecute un comando Update-Help en todos los equipos. Establezca el valor del parámetro SourcePath del cmdlet Update-Help en el recurso compartido de red.
Para evitar que los usuarios que tienen acceso a Internet descarguen la Ayuda actualizable desde Internet, use la opción "Establecer la ruta de acceso de origen predeterminada para Update-Help" directiva de grupo.
Esta configuración de directiva de grupo agrega implícitamente el parámetro SourcePath, con la ubicación del sistema de archivos que especifique, a cada comando Update-Help de cada equipo afectado. Los usuarios pueden usar el parámetro SourcePath explícitamente para especificar una ubicación del sistema de archivos diferente, pero no pueden excluir el parámetro SourcePath y descargar ayuda de Internet.
NOTA: La configuración de directiva de grupo "Establecer la ruta de acceso de origen predeterminada para Update-Help" aparece en Configuración del equipo y Configuración de usuario. Sin embargo, solo la configuración de directiva en Configuración del equipo es efectiva. La configuración de directiva en Configuración de usuario se omite.
Para más información, consulte about_Group_Policy_Settings.
ACTUALIZACIÓN DE LA AYUDA PARA MÓDULOS NO ESTÁNDAR
Para actualizar o guardar la ayuda de un módulo que no devuelve el parámetro ListAvailable del cmdlet Get-Module, importe el módulo en la sesión actual antes de ejecutar un comando Update-Help o Save-Help. En un equipo remoto, antes de ejecutar el comando Save-Help, importe el módulo en el bloque de script CIM o PSSession actual, o Invoke-Command bloque de script, que está conectado al equipo remoto.
Cuando el módulo se encuentra en la sesión actual, ejecute los cmdlets Update-Help o Save-Help sin parámetros o use el parámetro Module para especificar el nombre del módulo.
Los parámetros Module de los cmdlets Update-Help y Save-Help solo aceptan un nombre de módulo. No aceptan la ruta de acceso a un archivo de módulo.
Use esta técnica para actualizar o guardar la ayuda de cualquier módulo que no devuelva el parámetro ListAvailable del cmdlet Get-Module, como un módulo instalado en una ubicación que no aparece en la variable de entorno PSModulePath o un módulo que no tenga el formato correcto (el directorio del módulo no contiene al menos un archivo cuyo nombre base sea el mismo que el nombre del directorio).
CÓMO ADMITIR AYUDA ACTUALIZABLE
Si crea un módulo, puede admitir la ayuda en línea y la Ayuda actualizable para los módulos. Para obtener más información, vea "Ayuda actualizable" y Ayuda en línea de soporte técnico en la Microsoft Docs.
Ayuda actualizable no disponible para complementos de PowerShell o ayuda basada en comentarios.
COMENTARIOS
Los cmdlets Update-Help y Save-Help no son compatibles en el entorno de preinstalación de Windows (Windows PE).