about_Updatable_Help
Descrição breve
Descreve o sistema de ajuda atualizável no PowerShell.
Descrição longa
O PowerShell fornece várias maneiras diferentes de acessar os tópicos de ajuda mais atualizados para cmdlets e conceitos do PowerShell.
O sistema de Ajuda atualizável, introduzido no PowerShell 3.0, foi projetado para garantir que você sempre tenha os tópicos de ajuda mais recentes em seu computador local para que possa lê-los na linha de comando. Ele facilita o download e a instalação de arquivos de ajuda e a atualização deles sempre que arquivos de ajuda mais recentes estiverem disponíveis.
Para fornecer ajuda atualizada para vários computadores em uma empresa e para computadores que não têm acesso à Internet, a Ajuda atualizável permite baixar arquivos de ajuda para um diretório de sistema de arquivos ou compartilhamento de arquivos e, em seguida, instalar os arquivos de ajuda do compartilhamento de arquivos.
No PowerShell 4.0, a propriedade HelpInfoUri é preservada sobre a comunicação remota do Windows PowerShell, o que permite Save-Help
trabalhar para módulos instalados em um computador remoto, mas não necessariamente instalados no computador local. Você pode salvar um objeto PSModuleInfo em disco ou mídia removível (como uma unidade USB) executando Export-Clixml
em um computador que não tenha acesso à Internet, importando o objeto PSModuleInfo em um computador que tenha acesso à Internet e executando Save-Help
no objeto PSModuleInfo . A ajuda salva pode ser copiada para o computador remoto e desconectado usando mídia removível e, em seguida, instalada executando Update-Help
o . Essas melhorias na Save-Help
funcionalidade permitem que você instale a ajuda em computadores que estão sem qualquer tipo de acesso à rede. Para obter um exemplo de como usar a nova Save-Help
funcionalidade, consulte Como atualizar a ajuda de um compartilhamento de arquivos neste tópico.
A Ajuda atualizável também oferece suporte ao acesso on-line aos tópicos de ajuda mais recentes e à ajuda básica para cmdlets, mesmo quando não há arquivos de ajuda no computador.
O PowerShell não vem com arquivos de Ajuda. Você pode usar o recurso Ajuda Atualizável para instalar os arquivos de ajuda para todos os comandos incluídos por padrão no PowerShell e para todos os módulos do Windows.
Cmdlets de ajuda atualizáveis
Update-Help
: Baixa os arquivos de ajuda mais recentes da Internet ou de um compartilhamento de arquivos e os instala no computador local.Save-Help
: Baixa os arquivos de ajuda mais recentes da Internet e os salva em um diretório de sistema de arquivos ou compartilhamento de arquivos. Para instalar os arquivos de ajuda em computadores, useUpdate-Help
.Get-Help
: Exibe tópicos de ajuda na linha de comando. Obtém ajuda dos arquivos de ajuda no computador. Exibe a ajuda gerada automaticamente para cmdlets e funções que não têm arquivos de ajuda. Abre tópicos de ajuda online para cmdlets, funções, scripts e fluxos de trabalho no navegador da Internet padrão.
Ajuda gerada automaticamente: ajuda sem arquivos de ajuda
Se você não tiver o arquivo de ajuda para um cmdlet, função ou fluxo de trabalho no computador, o cmdlet exibirá Get-Help
a ajuda gerada automaticamente e solicitará que você baixe os arquivos de ajuda ou os leia online.
A ajuda gerada automaticamente inclui sintaxe e aliases e comentários que explicam como usar os cmdlets da Ajuda Atualizável e acessar os tópicos da Ajuda online.
Por exemplo, o comando a seguir obtém ajuda básica para o Get-Culture
cmdlet. A saída mostra a Get-Help
exibição quando não há arquivos de ajuda no computador.
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.
Arquivos de ajuda para módulos
A menor unidade da Ajuda atualizável é a ajuda para um módulo. A ajuda do módulo inclui ajuda para todos os cmdlets, funções, fluxos de trabalho, provedores, scripts e conceitos em um módulo. Você pode atualizar a ajuda para todos os módulos instalados no computador, mesmo que eles não sejam importados para a sessão atual.
Você pode atualizar a ajuda para todo o módulo, mas não pode atualizar a ajuda para cmdlets individuais.
Para localizar o módulo que contém um cmdlet específico, use o seguinte formato de comando:
(Get-Command <cmdlet-name>).ModuleName
Por exemplo, para localizar o módulo que contém o Set-ExecutionPolicy
cmdlet, digite:
(Get-Command Set-ExecutionPolicy).ModuleName
Para atualizar a ajuda de um módulo específico, digite:
Update-Help -Module <ModuleName>
Por exemplo, para atualizar a ajuda do módulo que contém o cmdlet Set-ExecutionPolicy, digite:
Update-Help -Module Microsoft.PowerShell.Security
Permissões para ajuda atualizável
Para atualizar a ajuda para os módulos no diretório $pshome/Modules
, você deve ser membro do grupo Administradores no computador.
Se você não for membro do grupo Administradores, não poderá atualizar a ajuda para esses módulos; Mas se você tiver acesso à Internet, você pode ver a ajuda on-line.
A atualização da ajuda para módulos no diretório $HOME/Documents/PowerShell/Modules
ou módulos em outros subdiretórios do $HOME
diretório não requer permissões especiais.
Os Update-Help
cmdlets e Save-Help
têm um parâmetro UseDefaultCredentials que fornece as credenciais explícitas do usuário atual. Esse parâmetro foi projetado para acessar locais seguros da Internet.
Os Update-Help
cmdlets e Save-Help
também têm um parâmetro Credential que permite executar o comando em um computador remoto e acessar um compartilhamento de arquivos em um terceiro computador. O parâmetro Credential é válido somente quando você usa os parâmetros SourcePath ou LiteralPath de Update-Help
e os parâmetros DestinationPath ou LiteralPath de Save-Help
.
Como instalar e atualizar arquivos de ajuda
Para baixar e instalar arquivos de ajuda pela primeira vez ou atualizar os arquivos de ajuda em seu computador, use o Update-Help
cmdlet.
O Update-Help
cmdlet faz todo o trabalho duro para você, incluindo as tarefas a seguir.
- Determina quais módulos oferecem suporte à Ajuda Atualizável.
- Localiza o local da Internet onde cada módulo armazena seus arquivos de Ajuda atualizáveis.
- Compara os arquivos de ajuda de cada módulo no computador com os arquivos de ajuda mais recentes disponíveis para cada módulo.
- Baixa os novos arquivos da internet.
- Desencapsula o pacote de arquivo de ajuda.
- Verifica se os arquivos são arquivos de ajuda válidos.
- Instala os arquivos de ajuda no subdiretório específico do idioma do diretório do módulo.
Para acessar os novos tópicos de ajuda, use o Get-Help
cmdlet. Você não precisa reiniciar o PowerShell.
Para instalar ou atualizar a ajuda para todos os módulos no computador que oferece suporte à Ajuda Atualizável, digite:
Update-Help
Para atualizar a ajuda para módulos específicos, adicione o parâmetro Module de Update-Help
. Caracteres curinga são permitidos no nome do módulo.
Por exemplo, para atualizar a ajuda para o módulo ServerManager, digite:
Update-Help -Module ServerManager
Sem parâmetros, Update-Help
as atualizações ajudam para todos os módulos na sessão e para todos os módulos instalados que suportam a Ajuda atualizável. Para serem incluídos, os módulos devem ser instalados em diretórios listados no valor da variável de ambiente PSModulePath. Esses também são módulos que são retornados por um Get-Module -ListAvailable
comando.
Se o valor do parâmetro Module for *
(all), Update-Help
tentará atualizar a ajuda para todos os módulos instalados, incluindo módulos que não oferecem suporte à Ajuda Atualizável. Esse comando normalmente gera muitos erros à medida que o cmdlet encontra módulos que não oferecem suporte à Ajuda Atualizável.
Como atualizar a ajuda de um compartilhamento de arquivos
Para oferecer suporte a computadores que não estão conectados à Internet ou para controlar ou simplificar a atualização da ajuda em uma empresa, use o Save-Help
cmdlet. O Save-Help
cmdlet baixa arquivos de ajuda da Internet e os salva em um diretório de sistema de arquivos que você especificar.
Save-Help
Compara os arquivos de Ajuda no diretório especificado com os arquivos de Ajuda mais recentes disponíveis para cada módulo. Se o diretório não tiver arquivos de ajuda ou se arquivos de ajuda mais recentes estiverem disponíveis para o módulo, o Save-Help
cmdlet baixará os novos arquivos da Internet. No entanto, ele não desempacota ou instala os arquivos de ajuda.
Para instalar ou atualizar os arquivos de ajuda em um computador a partir de arquivos de ajuda que foram salvos em um diretório do sistema de arquivos, use o parâmetro SourcePath do Update-Help
cmdlet. O Update-Help
cmdlet identifica os arquivos de ajuda mais recentes, os desencapsula e valida e os instala nos subdiretórios específicos do idioma dos diretórios do módulo.
Por exemplo, para salvar a ajuda de todos os módulos instalados no \\Server\Share
diretório, digite:
Save-Help -DestinationPath \\Server\Share
Em seguida, para atualizar a ajuda do \\Server\Share
diretório, digite:
Update-Help -SourcePath \\Server\Share
Os exemplos a seguir mostram o uso de para salvar a ajuda de Save-Help
módulos que não estão instalados no computador local. Neste exemplo, o administrador é executado Save-Help
para salvar a ajuda para o módulo DhcpServer de um computador cliente conectado à Internet, sem instalar o módulo DhcpServer ou a função Servidor DHCP no computador local.
Opção 1: Executar Invoke-Command
para obter o objeto PSModuleInfo para o módulo remoto, salvá-lo em uma variável e, em seguida, $m
executar Save-Help
no objeto PSModuleInfo especificando a variável $m
como o nome do módulo.
$invokeCommandSplat = @{
ComputerName = 'RemoteServer'
ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable }
}
$m = Invoke-Command @invokeCommandSplat
Save-Help -Module $m -DestinationPath C:\SavedHelp
Opção 2: Abra um PSSession direcionado ao computador que está executando o módulo do servidor DHCP, para obter o objeto PSModuleInfo para o módulo, salve-o em uma variável $m
e execute Save-Help
no objeto salvo na $m
variável.
$s = New-PSSession -ComputerName RemoteServer
$m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp
Opção 3: Abra uma sessão CIM, direcionada ao computador que está executando o módulo do servidor DHCP, para obter o objeto PSModuleInfo para o módulo, salvá-lo em uma variável $m
e executá-lo Save-Help
no objeto salvo na $m
variável.
$c = New-CimSession -ComputerName RemoteServer
$m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp
No exemplo a seguir, o administrador instala a ajuda para o módulo do servidor DHCP em um computador que não tem acesso à rede.
Primeiro, execute Export-Clixml
para exportar o objeto PSModuleInfo para uma pasta compartilhada ou para uma mídia removível.
$m = Get-Module -Name DhcpServer -ListAvailable
Export-Clixml -Path E:\UsbDrive\DhcpModule.xml -InputObject $m
Em seguida, transporte a mídia removível para um computador que tenha acesso à Internet e, em seguida, importe o objeto PSModuleInfo com Import-Clixml
. Execute Save-Help
para salvar a Ajuda para o módulo DhcpServer importado objeto PSModuleInfo .
$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp
Finalmente, transporte a mídia removível de volta para o computador que não tem acesso à rede e, em seguida, instale a ajuda executando Update-Help
o .
Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp
Sem parâmetros, Save-Help
baixa a ajuda para todos os módulos na sessão e para todos os módulos instalados que suportam a Ajuda atualizável. Para serem incluídos, os módulos devem ser instalados em diretórios listados no valor da variável de $env:PSModulePath
ambiente, no computador local ou em um computador remoto para o qual você deseja salvar a ajuda. Esses também são módulos que são retornados pela execução de um Get-Help -ListAvailable
comando.
Como atualizar arquivos de ajuda em diferentes idiomas
Por padrão, os Update-Help
cmdlets e Save-Help
baixam a ajuda na cultura e no idioma da interface do usuário definidos para o Windows no computador local. Se os arquivos de ajuda para os módulos especificados não estiverem disponíveis na cultura da interface do usuário local, Update-Help
use Save-Help
as regras de fallback de idioma do Windows para encontrar o melhor idioma com suporte.
No entanto, você pode usar os parâmetros UICulture dos cmdlets e Save-Help
para baixar e instalar arquivos de ajuda em qualquer cultura de Update-Help
interface do usuário na qual eles estejam disponíveis.
Por exemplo, para salvar os arquivos de ajuda mais recentes para todos os módulos na sessão em japonês (ja-Jp) e francês (fr-FR), digite:
Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr
Se os arquivos de ajuda para os módulos não estiverem disponíveis nos idiomas especificados, os Update-Help
cmdlets e Save-Help
retornarão uma mensagem de erro que lista os idiomas nos quais a ajuda para cada módulo está disponível para que você possa escolher a alternativa que melhor atenda às suas necessidades.
Observação
Atualmente, o conteúdo da Ajuda atualizável é publicado apenas em inglês (en-US).
Como usar a ajuda on-line
Se você não puder ou optar por não atualizar os arquivos de ajuda no computador local, ainda poderá obter os arquivos de ajuda mais recentes online.
Para abrir o tópico de ajuda online para qualquer cmdlet ou função, use o parâmetro Online do Get-Help
cmdlet.
Por exemplo, o comando a seguir abre o tópico de ajuda online para o Get-Job
cmdlet no navegador da Internet padrão:
Get-Help Get-Job -Online
Para obter ajuda online para um script, use o parâmetro Online e o caminho completo para o script.
O parâmetro Online não funciona com tópicos Sobre. Para ver os tópicos sobre o PowerShell, incluindo tópicos de ajuda sobre a linguagem do PowerShell, consulte PowerShell Sobre tópicos.
Como minimizar ou impedir downloads na internet
Para minimizar os downloads da Internet e fornecer Ajuda Atualizável aos usuários que não estão conectados à Internet, use o Save-Help
cmdlet. Baixe a ajuda da Internet e salve-a em um compartilhamento de rede. Em seguida, crie uma configuração de Diretiva de Grupo ou um trabalho agendado que execute um Update-Help
comando em todos os computadores. Defina o valor do parâmetro SourcePath do cmdlet para o compartilhamento de Update-Help
rede.
Para impedir que os usuários com acesso à Internet baixem a Ajuda Atualizável da Internet, use a configuração Definir o caminho de origem padrão para a Diretiva de Grupo Update-Help .
Essa configuração de Diretiva de Grupo adiciona implicitamente o parâmetro SourcePath , com o local do sistema de arquivos especificado, a cada Update-Help
comando em cada computador afetado. Os usuários podem usar o parâmetro SourcePath explicitamente para especificar um local diferente do sistema de arquivos, mas não podem excluir o parâmetro SourcePath e baixar a ajuda da Internet.
Observação
A configuração de diretiva de grupo Definir o caminho de origem padrão para a Ajuda de Atualização é exibida em Configuração do Computador e Configuração do Usuário. No entanto, apenas a definição de política em Configuração do Computador é eficaz. A definição de política em Configuração do Utilizador é ignorada.
Confira mais informações em about_Group_Policy_Settings.
Como atualizar a ajuda para módulos não padrão
Para atualizar ou salvar a ajuda de um módulo que não é retornado pelo parâmetro ListAvailable do cmdlet, importe o módulo para a sessão atual antes de Get-Module
executar um Update-Help
comando ou Save-Help
. Em um computador remoto, antes de executar o Save-Help
comando, importe o módulo para a Sessão atual, ou Invoke-Command
bloco de script, que está conectado ao computador remoto.
Quando o módulo estiver na sessão atual, execute os Update-Help
cmdlets ou Save-Help
sem parâmetros ou use o parâmetro Module para especificar o nome do módulo.
Os parâmetros Module dos Update-Help
cmdlets e Save-Help
aceitam apenas um nome de módulo. Eles não aceitam o caminho para um arquivo de módulo.
Use essa técnica para atualizar ou salvar a ajuda de qualquer módulo que não seja retornado pelo parâmetro ListAvailable do Get-Module
cmdlet, como um módulo instalado em um local que não esteja listado $env:PSModulePath
na variável de ambiente ou um módulo que não esteja bem formado (o diretório do módulo não contém pelo menos um arquivo cujo nome base seja o mesmo que o nome do diretório).
Como oferecer suporte à ajuda atualizável
Se você criar um módulo, poderá oferecer suporte à ajuda on-line e à Ajuda atualizável para seus módulos. Para obter mais informações, consulte Suporte à Ajuda Atualizável e Suporte à Ajuda Online.
Ajuda atualizável não disponível para snap-ins do PowerShell ou ajuda baseada em comentários.
Comentários
Os Update-Help
cmdlets e Save-Help
não têm suporte no Ambiente de Pré-instalação do Windows (Windows PE).