Partilhar via

sobre_Ajuda_Atualizável

Breve descrição

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 up-toatuais 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 sempre que arquivos de ajuda mais recentes ficam 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 ou compartilhamento de arquivos do sistema 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, que permite que Save-Help trabalhe 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, em seguida, executando Save-Help no objeto PSModuleInfo. A ajuda salva pode ser copiada para o computador remoto desconectado usando mídia removível e, em seguida, instalada executando Update-Help. Estas melhorias na funcionalidade Save-Help permitem-lhe instalar ajuda em computadores que não têm qualquer tipo de acesso à rede. Para obter um exemplo de como usar a nova funcionalidade Save-Help, consulte Como atualizar a ajuda de um de 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 da Ajuda atualizáveis

  • Update-Help: Transfere os ficheiros de ajuda mais recentes da Internet ou de uma partilha de ficheiros e instala-os no computador local.

  • Save-Help: Baixa os ficheiros de ajuda mais recentes da internet e guarda-os num diretório do sistema de ficheiros ou num partilhamento de ficheiros. Para instalar os ficheiros de ajuda nos computadores, utilize Update-Help.

  • Get-Help: Exibe tópicos de ajuda na linha de comando. Obtém ajuda dos ficheiros 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 ficheiros 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 exibirá 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, além de 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 cmdlet Get-Culture. A saída mostra o ecrã Get-Help quando não há ficheiros 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.

Ficheiros de ajuda para módulos

A menor unidade de ajuda atualizável é a ajuda para um módulo. A ajuda do módulo inclui ajuda sobre todos os cmdlets, funções, fluxos de trabalho, provedores, scripts e conceitos num 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 cmdlet Set-ExecutionPolicy, digite:

(Get-Command Set-ExecutionPolicy).ModuleName

Para atualizar a ajuda para 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 membro do grupo Administradores, não poderá atualizar a ajuda para esses módulos; Mas se tiver acesso à Internet, pode ver a ajuda online.

A atualização da ajuda para módulos no diretório $HOME/Documents/PowerShell/Modules ou 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 UseDefaultCredentials que fornece as credenciais explícitas do utilizador atual. Este parâmetro foi concebido para aceder a localizações seguras na Internet.

Os cmdlets Update-Help 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 parâmetros de Save-Help.

Como instalar e atualizar arquivos de ajuda

Para baixar e instalar 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 duro para você, incluindo as tarefas a seguir.

  • Determina quais módulos suportam a Ajuda Atualizável.
  • Localiza o local da Internet onde cada módulo armazena seus arquivos de Ajuda atualizáveis.
  • Compara os ficheiros de ajuda de cada módulo no computador com os ficheiros de ajuda mais recentes disponíveis para cada módulo.
  • Descarrega os novos ficheiros da Internet.
  • Desembrulha o pacote do ficheiro 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 da Ajuda, use o cmdlet Get-Help. Não é necessário reiniciar o PowerShell.

Para instalar ou atualizar a ajuda para todos os módulos no computador que suporta a Ajuda Atualizável, digite:

Update-Help

Para atualizar a ajuda para módulos específicos, adicione o parâmetro do módulo 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

A Update-Help, sem parâmetros, atualiza a ajuda para todos os módulos da 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. Estes também são módulos que são retornados por um comando Get-Module -ListAvailable.

Se o valor do parâmetro Module for * (todos), Update-Help tentará atualizar a ajuda para todos os módulos instalados, incluindo módulos que não suportam a 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 dar suporte a computadores que não estão conectados à Internet ou para controlar ou simplificar a atualização de ajuda em uma empresa, use o cmdlet Save-Help. O cmdlet Save-Help baixa arquivos de ajuda da Internet e os salva em um diretório do 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 cmdlet Save-Help 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 cmdlet Update-Help. O cmdlet Update-Help identifica os arquivos de ajuda mais recentes, desempacota-os e valida-os e instala-os nos subdiretórios específicos do idioma dos diretórios do módulo.

Por exemplo, para guardar a documentação de apoio de todos os módulos instalados no diretório \\Server\Share, insira:

Save-Help -DestinationPath \\Server\Share

Em seguida, 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 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 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, $me, em seguida, execute 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 uma PSSession direcionada para o computador que está a executar o módulo do Servidor DHCP, para obter o objeto PSModuleInfo para o módulo, salve-o numa $mvariável e execute Save-Help no objeto 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, direcionada para o computador que está a executar o módulo do DHCP Server, para obter o objeto PSModuleInfo para o módulo, salve-o numa variável $me depois execute Save-Help no objeto que está 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 a ajuda para o módulo 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 o comando Save-Help para guardar 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.

Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp

Sem parâmetros, Save-Help faz o download da ajuda para todos os módulos da 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 $Env:PSModulePath, 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 executando um comando Get-Help -ListAvailable.

Como atualizar arquivos de ajuda em idiomas diferentes

Por padrão, os cmdlets Update-Help 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 ficheiros de ajuda para os módulos especificados não estiverem disponíveis no idioma da interface de utilizador local, Update-Help e Save-Help usam as regras de fallback de idioma do Windows para encontrar o idioma suportado mais adequado.

No entanto, você pode usar os parâmetros UICulture dos cmdlets Update-Help e Save-Help para baixar e instalar arquivos de ajuda em qualquer cultura de interface do usuário em que estejam disponíveis.

Por exemplo, para salvar os arquivos de ajuda mais recentes para todos os módulos da 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 cmdlets Update-Help e Save-Help retornarão uma mensagem de erro que lista os idiomas em que 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 só é publicado em inglês (en-US).

Como usar a ajuda on-line

Se não conseguir ou optar por não atualizar os ficheiros de ajuda no computador local, ainda pode obter os ficheiros de ajuda mais recentes online.

Para abrir o tópico da 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 em seu navegador de internet padrão:

Get-Help Get-Job -Online

Para obter ajuda online para um script, utilize o parâmetro Online juntamente com o caminho completo para o script.

O parâmetro Online não funciona com os tópicos Acerca de. Para ver os tópicos sobre o PowerShell, incluindo tópicos de ajuda sobre a linguagem do PowerShell, consulte a secção Tópicos Sobre o PowerShell.

Como minimizar ou impedir downloads da Internet

Para minimizar os downloads da Internet e fornecer Ajuda Atualizável aos usuários que não estão conectados à Internet, use o cmdlet Save-Help. Transfira ajuda da Internet e guarde-a numa partilha 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 utilizadores com acesso à Internet transfiram a Ajuda Atualizável da Internet, utilize a definição de Política de Grupo Definir o caminho de origem predefinido para a Ajuda de Atualização.

Essa configuração de Diretiva de Grupo adiciona implicitamente o parâmetro SourcePath, com o local do sistema de arquivos especificado, a cada comando Update-Help 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 Update-Help aparece em Configuração do Computador e em Configuração do Usuário. No entanto, apenas a definição de política na Configuração do Computador é eficaz. A definição de política sob Configuração do Utilizador é ignorada.

Para obter mais informações, consulte 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 Get-Module, importe o módulo para a sessão atual antes de executar um comando Update-Help ou Save-Help. Num computador remoto, antes de executar o Save-Help comando, importa o módulo para a Sessão atual, ou Invoke-Command bloco de script, que está ligado ao computador remoto.

Quando o módulo estiver na sessão atual, execute os cmdlets Update-Help ou Save-Help sem parâmetros ou use o parâmetro Module para especificar o nome do módulo.

Os parâmetros do Módulo dos cmdlets Update-Help 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 para qualquer módulo que não seja retornado pelo parâmetro ListAvailable do cmdlet Get-Module, como um módulo instalado em um local que não esteja listado na variável de ambiente $Env: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 à 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 Ajuda Atualizável Suportada e Ajuda Online Suportada.

A ajuda atualizável não está disponível para snap-ins do PowerShell ou ajuda baseada em comentários.

Observações

Os cmdlets Update-Help e Save-Help não são suportados no Ambiente de Pré-instalação do Windows (Windows PE).

Consulte também

  • Last updated on