about_Updatable_Help
Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0
TEMA
About_Updatable_Help
DESCRIPCIÓN BREVE
Describe el sistema de Ayuda actualizable en Windows PowerShell®.
DESCRIPCIÓN LARGA
Windows PowerShell proporciona varias maneras de obtener acceso a los temas de ayuda más actualizados para cmdlets y conceptos de Windows PowerShell.
El sistema de Ayuda actualizable, introducido en Windows PowerShell 3.0, está diseñado para garantizar que siempre se tengan los temas de ayuda más recientes en el equipo local, de modo que se puedan leer en la línea de comandos. Facilita la descarga y la instalación de los archivos de ayuda, así como su actualización cuando están disponibles archivos de ayuda más recientes.
Para proporcionar ayuda actualizada a varios equipos de una empresa y a equipos sin acceso a Internet, Ayuda actualizable permite descargar los archivos de ayuda en un recurso compartido de archivos o directorio del sistema de archivos y, a continuación, instalar los archivos de ayuda desde el recurso compartido de archivos.
En Windows PowerShell 4.0, la propiedad HelpInfoUri se conserva en el acceso remoto a Windows PowerShell, lo que permite que Save-Help funcione para los módulos que están instalados en un equipo remoto, pero que no están instalados necesariamente en el equipo local. Puede guardar un objeto PSModuleInfo en un disco o medio extraíble, como una unidad USB. Para ello, ejecute Export-CliXml en un equipo que no tenga acceso a Internet, importe el objeto PSModuleInfo en un equipo que tenga acceso a Internet y, a continuación, ejecute Save-Help en el objeto PSModuleInfo. La ayuda guardada puede copiarse en el equipo remoto desconectado a través de medios extraíbles y, a continuación, instalarse ejecutando Update-Help. Estas mejoras en la funcionalidad de Save-Help permiten instalar la ayuda en equipos que no tienen ningún tipo de acceso a la red. Para ver un ejemplo de cómo usar la nueva funcionalidad Save-Help, consulte "CÓMO ACTUALIZAR LA AYUDA DESDE UN RECURSO COMPARTIDO DE ARCHIVOS: SAVE-HELP" en este tema.
Ayuda actualizable también permite el acceso en línea a los temas de ayuda más recientes y a la ayuda básica para los cmdlets, incluso si no hay ningún archivo de ayuda en el equipo.
Windows 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 Windows PowerShell y para todos los módulos de Windows.
CMDLETS DE AYUDA ACTUALIZABLE
Update-Help:
Descarga los archivos de ayuda más recientes de Internet o de un recurso compartido de archivos y los instala en el equipo local.
Save-Help:
Descarga los archivos de ayuda más recientes de Internet y los guarda en un recurso compartido de archivos o directorio del sistema de archivos. Para instalar los archivos de ayuda en los equipos, use Update-Help.
Get-Help:
Muestra temas de ayuda en la línea de comandos.
Obtiene ayuda a partir de los archivos de ayuda del equipo.
Muestra ayuda generada automáticamente para los cmdlets y las funciones que no tienen archivos de ayuda.
Abre temas de ayuda en pantalla para cmdlets, funciones, scripts y flujos de trabajo en el explorador de Internet predeterminado.
ACTUALIZAR LA AYUDA EN WINDOWS POWERSHELL ISE
También puede actualizar la ayuda usando el elemento "Actualizar la ayuda de Windows PowerShell" del menú Ayuda del Entorno de scripting integrado (ISE) de Windows PowerShell.
El elemento "Actualizar la ayuda de Windows 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, función o flujo de trabajo en el equipo, el cmdlet Get-Help muestra ayuda generada automáticamente y le indica que descargue los archivos de ayuda o que 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 actualizable y cómo acceder a los temas de ayuda en pantalla.
Por ejemplo, el comando siguiente obtiene ayuda básica para el cmdlet Get-Culture. La salida muestra la pantalla de Get-Help cuando no hay ningún archivo de ayuda en el equipo.
PS C:\> Get-Help Get-Culture
NOMBRE
Get-Culture
SINTAXIS
Get-Culture [<CommonParameters>]
ALIAS
Ninguno
COMENTARIOS
Para obtener el contenido de ayuda más reciente, incluidos ejemplos y descripciones, escriba Update-Help.
ARCHIVOS DE AYUDA DE MÓDULOS
La unidad más pequeña de Ayuda actualizable es la ayuda de módulo. La ayuda de 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 un módulo entero, pero no puede actualizar la ayuda de cmdlets individuales.
Para encontrar el módulo que contiene un cmdlet en concreto, use el formato de comando siguiente:
(Get-Command <cmdlet-name>).ModuleName
Por ejemplo, para encontrar 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 De AYUDA ACTUALIZABLE
Para actualizar la ayuda de los módulos del directorio $pshome\Modules, debe pertenecer al grupo Administradores del equipo.
Si no pertenece al grupo Administradores, no puede actualizar la ayuda de estos módulos. Sin embargo, si tiene acceso a Internet, puede ver ayuda en línea en la biblioteca de TechNet.
No hacen falta permisos especiales para actualizar la ayuda de los módulos del directorio $home\Documents\WindowsPowerShell\Modules o de los módulos de otros subdirectorios del directorio $home.
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 tener acceso 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.
CÓMO INSTALAR Y ACTUALIZAR LOS ARCHIVOS DE AYUDA
Para descargar e instalar los archivos de ayuda por primera vez o para actualizar los archivos de ayuda del equipo, use el cmdlet Update-Help.
El cmdlet Update-Help lo hace todo automáticamente, incluidas las tareas siguientes.
Determina qué módulos son compatibles con Ayuda actualizable.
Busca la ubicación de Internet donde cada módulo almacena los archivos de Ayuda actualizable.
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 de Internet los archivos nuevos.
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 temas de ayuda nuevos, use el cmdlet Get-Help. No es necesario reiniciar Windows PowerShell.
Para instalar o actualizar la ayuda de todos los módulos del equipo que admitan Ayuda actualizable, escriba:
Update-Help
Para actualizar la ayuda de módulos determinados, agregue el parámetro Module de Update-Help. Se permiten caracteres comodín en el nombre del módulo.
Update-Help -Module ServerManager
NOTAS
Sin parámetros, Update-Help actualiza la ayuda de todos los módulos de la sesión y de todos los módulos instalados que admiten Ayuda actualizable. Para que se incluyan, los módulos deben estar instalados en los directorios que se indican en el valor de la variable de entorno PSModulePath. También hay módulos que se devuelven mediante el comando "Get-Help -ListAvailable".
Si el valor del parámetro Module es * (todo), Update-Help intenta actualizar la ayuda de todos los módulos instalados, incluidos los módulos que no son compatibles con Ayuda actualizable. Este comando suele generar numerosos errores cuando el cmdlet detecta módulos que no admiten Ayuda actualizable.
CÓMO ACTUALIZAR LA AYUDA DESDE UN RECURSO COMPARTIDO DE ARCHIVOS: SAVE-HELP
Use el cmdlet Save-Help para admitir equipos que no están conectados a Internet, o bien para controlar u optimizar la actualización de la ayuda en una empresa. El cmdlet Save-Help descarga de Internet los archivos de ayuda y los guarda en el directorio del sistema de archivos que se 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 ningún archivo de ayuda o si hay disponibles archivos de ayuda más recientes para el módulo, el cmdlet Save-Help descarga de Internet los archivos nuevos. Sin embargo, no desencapsula ni instala los archivos de ayuda.
Para instalar o actualizar los archivos de ayuda de un equipo a partir de los archivos de ayuda que se guardaron 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, los desencapsula, los valida y los instala en los subdirectorios específicos del idioma 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 desde el directorio \\Server\Share, escriba:
Update-Help -SourcePath \\Server\Share
Los ejemplos siguientes muestran 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 ni el rol de servidor DHCP en el equipo local.
Opción 1:
ejecute Invoke-Command para obtener el objeto PSModuleInfo del 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 sesión de PowerShell (PSSession) dirigida al equipo que ejecuta el módulo de servidor DHCP para obtener el objeto PSModuleInfo del módulo, guárdelo en una variable $m y ejecute Save-Help en el objeto que se guardó 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 de servidor DHCP para obtener el objeto PSModuleInfo del módulo, guárdelo en una variable $m y ejecute Save-Help en el objeto que se guardó 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 del módulo de servidor DHCP en un equipo que no tiene acceso a la red.
# En primer lugar, ejecute Export-CliXml para exportar el objeto PSModuleInfo en una carpeta compartida o en 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 e 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:\UsbFlashDrive\DhcpModule.xml
Save-Help -Module $deserialized_m –DestinationPath
E:\UsbFlashDrive\SavedHelp
# Por último, transporte los medios extraíbles al equipo que no tiene acceso a la red e instale la ayuda ejecutando Update-Help.
Update-Help –Module DhcpServer –SourcePath
E:\UsbFlashDrive\SavedHelp
NOTAS:
Sin parámetros, Save-Help descarga la ayuda de todos los módulos de la sesión y de todos los módulos instalados que admiten Ayuda actualizable. Para que se incluyan, los módulos deben estar instalados en los directorios que se indican en el valor de la variable de entorno PSModulePath, ya sea en el equipo local o en un equipo remoto para el que desea guardar ayuda. Algunos módulos también se devuelven al ejecutar el comando "Get-Help -ListAvailable".
CÓMO ACTUALIZAR ARCHIVOS DE AYUDA EN IDIOMAS DIFERENTES
De forma predeterminada, los cmdlets Update-Help y Save-Help descargan la ayuda en el idioma y la referencia cultural de la interfaz de usuario que están establecidos para Windows en el equipo local. Si no hay disponibles archivos de ayuda para los módulos especificados en la referencia cultural de la interfaz de usuario local, Update-Help y Save-Help usan las reglas de reserva de idioma de Windows para buscar el mejor idioma compatible.
Sin embargo, puede usar los parámetros UICulture de los cmdlets Update-Help y Save-Help para descargar e instalar los archivos de ayuda en todas las referencias culturales de interfaz de usuario en las que están disponibles.
Por ejemplo, para guardar los archivos de ayuda más recientes de 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 Save-Help y Update-Help muestran un mensaje de error que enumera los idiomas en los que está disponible la ayuda de cada módulo, de modo que pueda elegir la opción que mejor se adapte a sus necesidades.
CÓMO ACTUALIZAR LA AYUDA AUTOMÁTICAMENTE
Para asegurarse de que dispone siempre de los archivos de ayuda más recientes, puede agregar un comando Update-Help a su perfil de Windows PowerShell.
Una cuota interna impide que el comando Update-Help se ejecute más de una vez al día. Para invalidar el límite máximo de una vez al día, use el parámetro Force.
Use un comando como el siguiente en su perfil. Este comando actualiza la ayuda de todos los módulos instalados en un trabajo en segundo plano, para que no interrumpa el trabajo. Usa un comando Out-Null para suprimir el trabajo que se devuelve y los mensajes de error que aparecerían si se usase 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 comando siguiente crea un trabajo programado que ejecuta un comando de ayuda Update-Help todos los viernes a las 5:00. Para ejecutar este comando, inicie Windows 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")
Para más información sobre los trabajos programados, consulte about_Scheduled_Jobs.
CÓMO USAR LA AYUDA EN PANTALLA
Si no puede actualizar los archivos de ayuda en el equipo local o si decide no hacerlo, puede obtener en línea los archivos de ayuda más recientes.
Para abrir el tema de ayuda en pantalla de un cmdlet o una función, use el parámetro Online del cmdlet Get-Help.
Por ejemplo, el comando siguiente abre el tema de ayuda en pantalla del cmdlet Get-Job en el explorador de Internet predeterminado:
Get-Help Get-Job -Online
O bien,
Get-Help -on Get-Job
Para obtener ayuda en pantalla de un script, use el parámetro Online y la ruta de acceso completa del script.
El parámetro Online no funciona con temas About. Para ver los temas About de Windows PowerShell Core, incluidos los temas de ayuda sobre el lenguaje de Windows PowerShell, consulte "Temas About del módulo de Windows PowerShell Core" en https://go.microsoft.com/fwlink/?LinkID=113206.
CÓMO MINIMIZAR O IMPEDIR LAS 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 Ayuda actualizable de Internet, use la configuración de directiva de grupo "Establecer la ruta de acceso de origen predeterminada de Update-Help".
Esta configuración de directiva de grupo agrega implícitamente el parámetro SourcePath, con la ubicación en el sistema de archivos que especifique para los comandos Update-Help de todos los equipos afectados. Los usuarios pueden usar el parámetro SourcePath explícitamente para especificar una ubicación en el 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 de Update-Help" aparece en Configuración del equipo y Configuración de usuario. Sin embargo, solo es efectiva la configuración de directiva que se indica en Configuración del equipo. Se omite la configuración de directiva incluida en Configuración de usuario.
Para más información, consulte about_Group_Policy_Settings.
CÓMO ACTUALIZAR LA AYUDA DE MÓDULOS NO ESTÁNDAR
Para actualizar o guardar la ayuda de un módulo que no se devuelve mediante el parámetro ListAvailable del cmdlet Get-Module, importe el módulo en la sesión actual antes de ejecutar el comando Update-Help o Save-Help. En un equipo remoto, antes de ejecutar el comando Save-Help, importe el módulo en la sesión CIM o PSSession actual (o bloque de script Invoke-Command) que está conectada al equipo remoto.
Cuando el módulo está 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 de un archivo de módulo.
Use esta técnica para actualizar o guardar la ayuda de todos los módulos que no se devuelvan mediante el parámetro ListAvailable del cmdlet Get-Module, por ejemplo, un módulo que está instalado en una ubicación que no aparece en la variable de entorno PSModulePath, o bien un módulo que no es correcto (el directorio del módulo no contiene al menos un archivo cuyo nombre base es igual que el nombre del directorio).
CÓMO ADMITIR AYUDA ACTUALIZABLE
Si crea un módulo, puede permitir ayuda en pantalla y Ayuda actualizable en los módulos. Para obtener más información, consulte "Compatibilidad con Ayuda actualizable" y "Compatibilidad con ayuda en pantalla" en MSDN Library.
Ayuda actualizable no está disponible para complementos de Windows PowerShell ni ayuda basada en comentarios.
PALABRAS CLAVE
About_Updateable_Help
COMENTARIOS
Los cmdlets Update-Help y Save-Help no se admiten en el Entorno de preinstalación de Windows (Windows PE).
VEA TAMBIÉN
Get-Help
Save-Help
Update-Help
Tabla de estado de Ayuda actualizable