about_Updatable_Help
Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
TÓPICO
About_Updatable_Help
DESCRIÇÃO BREVE
Descreve o sistema de ajuda atualizável no Windows PowerShell®.
DESCRIÇÃO LONGA
Windows PowerShell fornece várias maneiras diferentes para acessar os tópicos da Ajuda mais atualizados para Windows PowerShell cmdlets e conceitos.
O sistema de ajuda atualizável, introduzido no Windows PowerShell 3.0, foi projetado para garantir que você sempre tenha os tópicos da Ajuda mais recentes em seu computador local para que possa lê-los na linha de comando. Ele torna mais fácil fazer download e instalar arquivos de Ajuda e atualizá-los sempre que arquivos mais recentes são disponibilizados.
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 fazer o download de arquivos de Ajuda em um diretório de sistema de arquivos ou compartilhamento de arquivo e, em seguida, instalar os arquivos de Ajuda a partir do compartilhamento de arquivos.
Em Windows PowerShell 4.0, a propriedade HelpInfoUri é mantida por Windows PowerShell remotamente, permitindo que Save-Help trabalhe com módulos que são instalados em um computador remoto, mas não necessariamente estão 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, em seguida, executando Save-Help no objeto PSModuleInfo. A ajuda salva pode ser copiada para o computador remoto, desconectado, utilizando mídias removíveis e, em seguida, executando Update-Help. Esses aperfeiçoamentos na funcionalidade Save-Help permitem que você instale ajuda em computadores que estão sem nenhum tipo de acesso à rede. Para obter um exemplo de como usar a nova funcionalidade Save-Help, consulte "COMO ATUALIZAR AJUDA EM UM COMPARTILHAMENTO DE ARQUIVOS: SAVE-HELP" neste tópico.
Ajuda atualizável também oferece suporte a acesso on-line para os tópicos de ajuda mais recentes e ajuda básica para cmdlets, mesmo quando não há nenhum arquivo de Ajuda no computador.
Windows PowerShell 3.0 não é disponibilizado com arquivos de Ajuda. Você pode usar o recurso Ajuda Atualizável para instalar os arquivos de ajuda para todos os comandos que são incluídos por padrão em Windows PowerShell e para todos os módulos do Windows.
CMDLETS DE AJUDA ATUALIZÁVEL
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 compartilhamento de arquivo ou diretório de sistema do arquivo. Para instalar os arquivos de Ajuda em computadores, use Update-Help.
Get-Gelp:
Exibe os tópicos da Ajuda na linha de comando.
Obtém ajuda dos arquivos de Ajuda no computador.
Exibe ajuda auto-gerada para cmdlets e funções que não têm arquivos de Ajuda.
Abre os tópicos da Ajuda online para funções, cmdlets, scripts e fluxos de trabalho no navegador de Internet padrão.
ATUALIZAR A AJUDA NO WINDOWS POWERSHELL ISE
Você também pode atualizar a Ajuda usando o item "Update Windows PowerShell Help" no menu Ajuda do Windows PowerShell ambiente de script integrado (ISE).
O item "Update Windows PowerShell Help" executa um comando Update-Help sem parâmetros.
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 Get-Help exibe ajuda gerada automaticamente e solicita que você baixe os arquivos de Ajuda ou os leia online.
A ajuda gerada automaticamente inclui comentários que explicam como usar os cmdlets de ajuda atualizável e acessar os tópicos da Ajuda on-line, sintaxe e aliases.
Por exemplo, o comando a seguir obtém ajuda básica para o cmdlet Get-Culture. A saída mostra a exibição de Get-Help quando não houver nenhum arquivo de Ajuda no computador.
PS C:\> Get-Help Get-Culture
NOME
Get-culture
SINTAXE
Get-Culture [<CommonParameters>]
ALIASES
Não
COMENTÁRIOS
Para obter o conteúdo de ajuda mais recente, incluindo descrições e tipo de exemplos: Update-Help.
ARQUIVOS DE AJUDA PARA OS MÓDULOS
A menor unidade de ajuda atualizável é 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 o módulo inteiro, mas não pode atualizar a Ajuda para os cmdlets individuais.
Para localizar o módulo que contém um determinado cmdlet, use o seguinte formato de comando:
(Get-Command <cmdlet-name>).ModuleName
Por exemplo, para localizar o módulo que contém o cmdlet Set-ExecutionPolicy, 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 para o 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 um membro do grupo Administradores, não poderá atualizar a Ajuda para esses módulos; mas se tiver acesso à Internet, poderá exibir a Ajuda online na TechNet Library.
Atualizando a ajuda para os módulos no diretório $home\Documents\WindowsPowerShell\Modules ou para módulos em outros subdiretórios do diretório $home não requer permissões especiais.
Os cmdlets Update-Help e Save-Help têm um parâmetro de UseDefaultCredentials que fornece as credenciais explícitas do usuário atual. Este parâmetro destina-se a acessar locais na Internet seguros.
Os cmdlets Update-Help e Save-Help também tem um parâmetro de credencial que permite que você execute o comando em um computador remoto e acesse um compartilhamento de arquivos em um terceiro computador. O parâmetro Credential é válido somente quando você usa os parâmetros SourcePath ou LiteralPath da Ajuda de atualização e os parâmetros DestinationPath ou LiteralPath de Save-Help.
COMO INSTALAR E ATUALIZAR ARQUIVOS DE AJUDA
Para baixar e instalar os arquivos de ajuda pela primeira vez, ou para atualizar os arquivos de Ajuda em seu computador, use o cmdlet Update-Help.
O cmdlet Update-Help faz todo o trabalho pesado para você, incluindo as seguintes tarefas.
Determina quais módulos suportam a ajuda atualizável.
Encontra o local da Internet onde cada módulo armazena seus arquivos de ajuda atualizável.
Compara os arquivos de ajuda para cada módulo no seu computador aos arquivos de ajuda mais recentes disponíveis para cada módulo.
Baixa os novos arquivos da Internet.
Desencapsula o pacote de arquivos de Ajuda.
Verifica se os arquivos são arquivos de ajuda válidos.
Instala os arquivos de Ajuda no subdiretório do idioma específico do diretório do módulo.
Para acessar os novos tópicos da Ajuda, use o cmdlet Get-Help. Você não precisa reiniciar Windows 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 os módulos específicos, adicione o parâmetro de módulo de Update-Help. Caracteres curinga são permitidos no nome do módulo.
Update-Help -Module ServerManager
OBSERVAÇÕES
Sem parâmetros, Update-Help atualiza a ajuda para todos os módulos na sessão em todos os módulos instalados que dão suporte à Ajuda Atualizável. Para serem incluídos, os módulos devem ser instalados em diretórios que estão listados no valor da variável de ambiente PSModulePath. Eles também são módulos que são retornados por um comando "Get-Help - ListAvailable".
Se o valor do parâmetro de módulo é * (todos), Update-Help tenta atualizar a Ajuda para todos os módulos instalados, incluindo os módulos que não dão suporte à ajuda atualizável. Esse comando normalmente gera muitos erros quando o o cmdlet encontra módulos que dão suporte a Ajuda atualizável.
COMO ATUALIZAR A AJUDA DE UM COMPARTILHAMENTO DE ARQUIVO: SAVE-HELP
Para oferecer suporte a computadores que não estão conectados à Internet, ou para controlar e otimizar a atualização de Ajuda em uma empresa, use o cmdlet Save-Help. O cmdlet Save-Help baixa os arquivos de Ajuda da Internet e os salva em um diretório de sistema de arquivos que você especificar.
Save-Help compara os arquivos da Ajuda no diretório especificado com os arquivos de ajuda mais recentes disponíveis para cada módulo. Se o diretório não tem nenhum arquivo de Ajuda ou arquivos de ajuda mais recentes estão disponíveis para o módulo, o cmdlet Save-Help baixa os novos arquivos da Internet. No entanto, ele não desencapsula 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 de sistema de arquivos, use o parâmetro SourcePath do cmdlet Update-Help. O cmdlet Update-Help identifica os arquivos de ajuda mais recentes, ou não valida e as instala nos subdiretórios específicos do idioma dos diretórios de módulo.
Por exemplo, para salvar a Ajuda para todos os módulos instalados no diretório \\Server\Share, digite:
Save-Help -DestinationPath \\Server\Share
Para atualizar a Ajuda do diretório \\Server\Share, digite:
Update-Help -SourcePath \\Server\Share
Os exemplos a seguir mostram o uso do Save-Help para salvar a ajuda para os módulos que não estão instalados no computador local. Neste exemplo, o administrador executa Save-Help para salvar a Ajuda para o módulo DhcpServer de um computador cliente conectado à Internet, sem instalar o módulo de DhcpServer ou a função de servidor DHCP no computador local.
Opção 1:
Execute Invoke-Command para obter o objeto PSModuleInfo para o módulo remoto, salve-o em uma variável, $m e execute Save-Help no objeto PSModuleInfo especificando a variável $m como o nome do módulo.
$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock
{ Get-Module -Name DhcpServer -ListAvailable }
Save-Help -Module $m -DestinationPath C:\SavedHelp
Opção 2:
Abra um PSSession, voltada para o computador que está executando o módulo de servidor DHCP, para obter o objeto PSModuleInfo para o módulo, salve-o em uma variável $m e execute Save-Help no objeto que é salvo na variável $m.
$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, voltada para o computador que está executando o módulo de servidor DHCP, para obter o objeto PSModuleInfo para o módulo, salve-oo em uma variável $m e execute Save-Help no objeto que é salvo na variável $m.
$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 ajuda para o módulo de servidor DHCP em um computador que não tem acesso à rede.
# Em primeiro lugar, execute Export-CliXml para exportar o objeto PSModuleInfo para uma pasta compartilhada ou mídia removível.
$m = Get-Module -Name DhcpServer –ListAvailable
Export-CliXml –Path E:\UsbFlashDrive\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 objeto de PSModuleInfo de módulo DhcpServer importado.
$deserialized_m = Import-CliXml E:\UsbFlashDrive\DhcpModule.xml
Save-Help -Module $deserialized_m –DestinationPath
E:\UsbFlashDrive\SavedHelp
# Finalmente, transporte a mídia removível para o computador que não tem acesso à rede e, em seguida, instale a Ajuda executando Update-Help.
Update-Help –Module DhcpServer –SourcePath
E:\UsbFlashDrive\SavedHelp
OBSERVAÇÕES:
Sem parâmetros, o Save-Help baixa ajuda para todos os módulos na sessão em todos os módulos instalados que dão suporte a Ajuda atualizável. A serem incluídos, os módulos devem ser instalados em diretórios que estão listados no valor da variável de ambiente PSModulePath, no computador local ou em um computador remoto para o qual você deseja salvar a Ajuda. Eles também são módulos que são retornados ao executar um comando "Get-Help - ListAvailable".
COMO ATUALIZAR OS ARQUIVOS DE AJUDA EM DIFERENTES IDIOMAS
Por padrão, os cmdlets Update-Help e Save-Help baixam a ajuda na cultura da interface do usuário e o idioma definido para o Windows no computador local. Se os arquivos de ajuda para os módulos especificados não estão disponíveis na cultura da interface do usuário local, Update-Help e Save-Help usam as regras de fallback de idioma do Windows para localizar o melhor suporte para o idioma.
No entanto, você pode usar os parâmetros UICulture dos cmdlets Update-Help e Save-Help para baixar e instalar os arquivos de Ajuda em qualquer cultura da interface do usuário no qual eles estão 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 são disponíveis nos idiomas que você especificou, o cmdlets Update-Help e Save-Help retorna 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.
COMO ATUALIZAR AUTOMATICAMENTE A AJUDA
Para garantir que você sempre tenha os arquivos de ajuda mais recentes, você pode adicionar um comando Update-Help para seu Windows PowerShell perfil.
Uma cota interna impede que o comando Update-Help execute mais de uma vez por dia. Para substituir o máximo de uma vez por dia, use o parâmetro Force.
Use um comando como a seguir em seu perfil. Este comando atualiza a Ajuda para todos os módulos instalados em um trabalho em segundo plano para que ele não incomode o seu trabalho. Ele usa um comando Out-Null para suprimir o trabalho que é retornado e quaisquer mensagens de erro que normalmente seriam exibidas quando você usa o comando mais de uma vez por dia.
Start-Job {Update-Help} | Out-Null
Você também pode criar um trabalho agendado que executa o cmdlet Update-Help ou Save-Help em qualquer intervalo.
Por exemplo, o comando a seguir cria um trabalho programado que executa um comando de ajuda Update-Help todas as sextas-feiras, às 5h. Para executar este comando, inicie Windows PowerShell com a opção "Executar como administrador".
Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
-Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")
Para obter mais informações sobre os trabalhos agendados, consulte about_Scheduled_Jobs.
COMO USAR A AJUDA ON-LINE
Se você não pode ou não deseja atualizar os arquivos de Ajuda no computador local, ainda pode obter os mais recentes arquivos de Ajuda online.
Para abrir o tópico de ajuda online para qualquer cmdlet ou função, use o parâmetro Online do cmdlet Get-Help.
Por exemplo, o comando a seguir abre o tópico da ajuda online para o cmdlet Get-Job no navegador de Internet padrão:
Get-Help Get-Job -Online
- ou -
Get-Help -on Get-Job
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 os tópicos About. Para ver o sobre tópicos para Windows PowerShell Core, incluindo tópicos da Ajuda sobre o Windows PowerShell language, consulte "Módulo do Windows PowerShell Core sobre tópicos" em https://go.microsoft.com/fwlink/?LinkID=113206.
COMO MINIMIZAR OU EVITAR DOWNLOADS DA INTERNET
Para minimizar os downloads da Internet e fornecer ajuda atualizável para usuários que não estão conectados à Internet, use o cmdlet Save-Help. 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 comando Update-Help em todos os computadores. Defina o valor do parâmetro SourcePath do cmdlet Update-Help para o compartilhamento de rede.
Para impedir que os usuários que têm acesso á Internet de fazer download da Ajuda Atualizável da Internet, use a configuração de diretiva de grupo "Definir o caminho de origem padrão para Update-Help".
Essa configuração de diretiva de grupo adiciona implicitamente o parâmetro SourcePath, com o local do sistema de arquivos que você especificar, para cada comando Update-Help em todos os computadores afetados. Os usuários podem usar o parâmetro SourcePath explicitamente para especificar um local de sistema de arquivos diferente, mas não podem excluir o parâmetro SourcePath e baixar a Ajuda da Internet.
OBSERVAÇÃO:
A configuração de política de grupo "Definir o caminho de origem padrão para Update-Help" aparece em configuração do Computador e Configuração do Usuário. No entanto, apenas a configuração de diretiva em configuração do computador é eficaz. A configuração de diretiva em configuração do usuário é ignorada.
Para obter mais informações, consulte about_Group_Policy_Settings.
COMO ATUALIZAR A AJUDA PARA OS MÓDULOS NÃO PADRÃO
Para atualizar ou salvar a Ajuda para um módulo que não é retornado pelo parâmetro ListAvailable do cmdlet Get-Module, importe o módulo para a sessão atual antes de executar um comando Uldate-Help ou Save-Help. Em um computador remoto, antes de executar o comando Save-Help, importe o módulo atual CIM ou PSSession – ou o bloco de script Invoke-Command, que está conectado ao computador remoto.
Quando o módulo está na sessão atual, execute os cmdlets Update-Help ou Save-Help sem parâmetros, ou use o parâmetro de módulo para especificar o nome do módulo.
Os parâmetros do módulo de cmdlets do Update-Help e Save-Help aceitam 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 cmdlet Get-Module, como um módulo que é instalado em um local que não esteja listado na variável de ambiente PSModulePath 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 é o mesmo que o nome do diretório).
COMO DAR SUPORTE A AJUDA ATUALIZÁVEL
Se você criar um módulo, pode suportar ajuda on-line e ajuda atualizável para seus módulos. Para obter mais informações, consulte "Suporte à Ajuda Atualizável" e "Ajuda de Suporte Online" em biblioteca MSDN.
Ajuda atualizável não está disponível para Windows PowerShell ajuda snap-ins ou com base em comentários.
PALAVRAS-CHAVE
About_Updateable_Help
COMENTÁRIOS
Não há suporte para os cmdlets Update-Help e Save-Help Windows Preinstallation Environment (Windows PE).
CONSULTE TAMBÉM
Get-Help
Save-Help
Update-Help
Tabela de status de ajuda atualizável