about_Updatable_Help

Artículo
10/20/2023

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 la actualización de los archivos de ayuda 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 o recurso compartido de archivos del sistema 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 la comunicación remota de Windows PowerShell, que permite Save-Help trabajar con módulos instalados en un equipo remoto, pero no están instalados necesariamente en el equipo local. Puede guardar un objeto PSModuleInfo en disco o medios extraíbles (por ejemplo, una unidad USB) ejecutando Export-Clixml en un equipo que no tiene acceso a Internet, importando el objeto PSModuleInfo en un equipo que tiene acceso a Internet y, a continuación, ejecutándose 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, instalar mediante la ejecución Update-Helpde . Estas mejoras en Save-Help la 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 Save-Help funcionalidad, vea Cómo actualizar la ayuda de un recurso compartido de archivos 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 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 de sistema de archivos o un recurso compartido de archivos. Para instalar los archivos de ayuda en equipos, use Update-Help.
Get-Help: muestra 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 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 Get-Help cmdlet muestra la 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, y comentarios que explican cómo usar los cmdlets de Ayuda actualizables y acceder a los temas de ayuda en línea.

Por ejemplo, el siguiente comando obtiene ayuda básica para el Get-Culture cmdlet . La salida muestra la Get-Help pantalla 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 la ayuda de 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 Set-ExecutionPolicy cmdlet , 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 ayuda en línea.

La actualización de la ayuda de los módulos en el directorio $HOME/Documents/PowerShell/Modules o los módulos de otros subdirectorios del $HOME directorio no requiere permisos especiales.

Los Update-Help cmdlets 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 Update-Help cmdlets 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 Update-Help cmdlet .

El Update-Help cmdlet 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 desde Internet.
Desencapsula el paquete del archivo de ayuda.
Comprueba que los archivos son archivos de ayuda válidos.
Instala los archivos de ayuda en el subdirectorio específico del lenguaje del directorio del módulo.

Para acceder a los nuevos temas de ayuda, use el Get-Help cmdlet . No es necesario reiniciar PowerShell.

Para instalar o actualizar la ayuda de todos los módulos del equipo que admite la 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 actualiza la ayuda para todos los módulos de la sesión y para todos los módulos instalados que admiten la Ayuda actualizable. Para incluirlos, los módulos deben instalarse en directorios que aparecen en el valor de la variable de entorno PSModulePath. También son módulos devueltos por un Get-Module -ListAvailable comando.

Si el valor del parámetro Module es * (all), Update-Help intenta actualizar la ayuda de todos los módulos instalados, incluidos los módulos que no admiten la Ayuda actualizable. Este comando suele generar muchos errores, ya que el cmdlet encuentra módulos que no admiten ayuda actualizable.

Para admitir equipos que no están conectados a Internet o para controlar o simplificar la actualización en una empresa, use el Save-Help cmdlet . El Save-Help cmdlet 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 Save-Help cmdlet descarga los nuevos archivos desde Internet. Sin embargo, no desencapsula ni instala los archivos de ayuda.

Para instalar o actualizar los archivos de ayuda en un equipo de archivos de ayuda que se guardaron en un directorio del sistema de archivos, use el parámetro SourcePath del Update-Help cmdlet . El Update-Help cmdlet identifica los archivos de ayuda más recientes, desencapsula y los valida e 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 \\Server\Share directorio, escriba:

Save-Help -DestinationPath \\Server\Share

A continuación, para actualizar la ayuda del \\Server\Share directorio, 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 se 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, y, a continuación, $mejecute Save-Help en el objeto PSModuleInfo especificando la variable $m como nombre del módulo.

$invokeCommandSplat = @{
    ComputerName = 'RemoteServer'
    ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable }
}
$m = Invoke-Command @invokeCommandSplat
Save-Help -Module $m -DestinationPath C:\SavedHelp

Opción 2: abra una PSSession dirigida al equipo que ejecuta el módulo servidor DHCP para obtener el objeto PSModuleInfo para el módulo, guárdelo en una variable $my, a continuación, ejecútelo Save-Help en el objeto que se guarda en la $m variable.

$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 del servidor DHCP, para obtener el objeto PSModuleInfo del módulo, guárdelo en una variable $my, a continuación, ejecútelo Save-Help en el objeto que se guarda en la $m variable.

$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:\UsbDrive\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 del objeto PSModuleInfo del módulo DhcpServer importado.

$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp

Por último, vuelva a transportar el medio extraíble al equipo que no tenga acceso a la red y, a continuación, instale la ayuda mediante la ejecución Update-Helpde .

Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\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 aparecen en el valor de la $env:PSModulePath variable de entorno, 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 Get-Help -ListAvailable comando .

Actualización de archivos de ayuda en diferentes idiomas

De forma predeterminada, los Update-Help cmdlets 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 Update-Help cultural de la interfaz de usuario local y Save-Help usan las reglas de reserva de idioma de Windows para encontrar el mejor idioma compatible.

Sin embargo, puede usar los parámetros UICulture de los Update-Help cmdlets 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 Update-Help cmdlets y Save-Help devuelven un mensaje de error que muestra los idiomas en los que está disponible la ayuda de cada módulo para que pueda elegir la alternativa que mejor satisfaga sus necesidades.

Nota:

Actualmente, el contenido de la Ayuda actualizable solo se publica en inglés (en-US).

Uso de la ayuda en línea

Si no puede o no actualizar los archivos de ayuda en el equipo local, 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 Get-Help cmdlet.

Por ejemplo, el siguiente comando abre el tema de ayuda en línea del cmdlet en el Get-Job 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, incluidos los temas de ayuda sobre el lenguaje de PowerShell, consulte Temas sobre PowerShell.

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 Save-Help cmdlet . 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 Update-Help comando en todos los equipos. Establezca el valor del parámetro SourcePath del Update-Help cmdlet en el recurso compartido de red.

Para evitar que los usuarios que tengan acceso a Internet descarguen la Ayuda actualizable desde Internet, use la opción Establecer la ruta de acceso de origen predeterminada para la configuración de directiva de grupo Update-Help .

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 todos los Update-Help comandos de cada equipo afectado. Los usuarios pueden usar el parámetro SourcePath explícitamente para especificar una ubicación diferente del sistema de archivos, pero no pueden excluir el parámetro SourcePath y descargar ayuda de Internet.

Nota:

La opción Establecer la ruta de acceso de origen predeterminada para la configuración de directiva de grupo 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 Get-Module cmdlet, importe el módulo a la sesión actual antes de ejecutar un Update-Help comando o Save-Help . En un equipo remoto, antes de ejecutar el Save-Help comando, importe el módulo en el bloque de script o Invoke-Command sesión actual, que está conectado al equipo remoto.

Cuando el módulo se encuentra en la sesión actual, ejecute los Update-Help cmdlets 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 Update-Help cmdlets 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 Get-Module cmdlet, como un módulo instalado en una ubicación que no aparece en la $env:PSModulePath variable de entorno o un módulo que no esté bien formado (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 la ayuda actualizable

Si crea un módulo, puede admitir ayuda en línea y Ayuda actualizable para los módulos. Para obtener más información, consulte Compatibilidad con ayuda actualizable y ayuda en línea de soporte técnico.

Ayuda actualizable que no está disponible para complementos de PowerShell o ayuda basada en comentarios.

Comentarios

Los Update-Help cmdlets y Save-Help no se admiten en el entorno de preinstalación de Windows (Windows PE).

Compartir a través de