about_Updatable_Help

Artigo
04/13/2023

Breve descrição

Descreve o sistema de ajuda updatable em PowerShell.

Longa descrição

O PowerShell fornece várias formas diferentes de aceder aos tópicos de ajuda mais atualizados para os cmdlets e conceitos powerShell.

O sistema de Ajuda Updatable, introduzido no PowerShell 3.0, foi concebido para garantir que tem sempre os tópicos de ajuda mais recentes no seu computador local para que possa lê-los na linha de comando. Torna-se fácil descarregar e instalar ficheiros de ajuda e atualizá-los sempre que os ficheiros de ajuda mais recentes estiverem disponíveis.

Para fornecer ajuda atualizada para vários computadores numa empresa e para computadores que não têm acesso à internet, o Updatable Help permite-lhe descarregar ficheiros de ajuda para um diretório de ficheiros ou partilha de ficheiros e, em seguida, instalar os ficheiros de ajuda a partir da partilha de ficheiros.

No PowerShell 4.0, a propriedade HelpInfoUri é preservada ao longo de Windows PowerShell de remoting, que permite trabalhar para módulos que são instalados num computador remoto, mas não são necessariamente instalados Save-Help no computador local. Pode guardar um objeto PSModuleInfo para discos ou meios amovíveis (como uma unidade USB) executando Export-Clixml num computador que não tenha acesso à Internet, importando o objeto PSModuleInfo num computador que tenha acesso à Internet e, em seguida, funcionando Save-Help no objeto PSModuleInfo . A ajuda guardada pode ser copiada para o computador remoto e desligado utilizando suportes amovíveis e depois instalada por execução Update-Help. Estas melhorias na Save-Help funcionalidade permitem instalar ajuda em computadores que não têm qualquer tipo de acesso à rede. Para um exemplo de como utilizar a nova Save-Help funcionalidade, consulte Como atualizar a ajuda de uma partilha de ficheiros neste tópico.

A Updatable Help também suporta o acesso online aos tópicos de ajuda mais recentes e ajuda básica para os cmdlets, mesmo quando não há ficheiros de ajuda no computador.

O PowerShell 3.0 não vem com ficheiros de ajuda. Pode utilizar a função Ajuda Updatable para instalar os ficheiros de ajuda para todos os comandos incluídos por padrão no PowerShell e para todos os módulos Windows.

Updatable ajuda cmdlets

Update-Help: Descarrega os ficheiros de ajuda mais recentes da internet ou de uma partilha de ficheiros e instala-os no computador local.
Save-Help: Descarrega os ficheiros de ajuda mais recentes da internet e guarda-os num diretório de ficheiros ou partilha de ficheiros. Para instalar os ficheiros de ajuda nos computadores, utilize Update-Help-
Get-Help: Os ecrãs ajudam os tópicos na linha de comando. Obtém ajuda dos ficheiros de ajuda do computador. Exibe ajuda gerada automaticamente para cmdlets e funções que não têm ficheiros de ajuda. Abre tópicos de ajuda on-line para cmdlets, funções, scripts e fluxos de trabalho no seu navegador de Internet padrão.

Ajuda gerada automaticamente: ajuda sem ficheiros de ajuda

Se não tiver o ficheiro de ajuda para um cmdlet, função ou fluxo de trabalho no computador, o Get-Help cmdlet exibe ajuda gerada automaticamente e pede-lhe para descarregar os ficheiros de ajuda ou lê-los online.

A ajuda gerada automaticamente inclui sintaxe e pseudónimos, e comentários que explicam como usar os cmdlets de ajuda updatable e aceder aos tópicos de ajuda online.

Por exemplo, o seguinte comando recebe ajuda básica para o Get-Culture cmdlet. A saída mostra o Get-Help visor 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 unidade mais pequena de Updatable Help é a ajuda para um módulo. A ajuda do módulo inclui ajuda para todos os cmdlets, funções, fluxos de trabalho, fornecedores, scripts e conceitos num módulo. Pode atualizar a ajuda para todos os módulos instalados no computador, mesmo que não sejam importados para a sessão atual.

Pode atualizar a ajuda para todo o módulo, mas não é possível atualizar a ajuda para os cmdlets individuais.

Para encontrar o módulo que contém um cmdlet específico, utilize o seguinte formato de comando:

(Get-Command <cmdlet-name>).ModuleName

Por exemplo, para encontrar o módulo que contém o Set-ExecutionPolicy cmdlet, escreva:

(Get-Command Set-ExecutionPolicy).ModuleName

Para atualizar a ajuda para um módulo específico, escreva:

Update-Help -Module <ModuleName>

Por exemplo, para atualizar a ajuda para o módulo que contém o Set-ExecutionPolicy cmdlet, escreva:

Update-Help -Module Microsoft.PowerShell.Security

Permissões para ajuda updatable

Para atualizar a ajuda para os módulos no diretório $pshome/Modules, tem de ser membro do grupo de Administradores no computador.

Se não for membro do grupo administradores, não poderá atualizar a ajuda para estes módulos; mas se tiver acesso à internet, pode ver ajuda online.

A atualização da ajuda para módulos no diretório $HOME/Documents/PowerShell/Modules ou módulos noutras subdireções do $HOME diretório não requer permissões especiais.

Os Update-Help cmdlets e Save-Help cmdlets têm um parâmetro UseDefaultCredentials que fornece as credenciais explícitas do utilizador atual. Este parâmetro foi concebido para aceder a locais seguros da Internet.

Os Update-Help cmdlets também Save-Help têm um parâmetro credencial que permite executar o comando num computador remoto e aceder a uma partilha de ficheiros num terceiro computador. O parâmetro credencial só é válido quando utiliza os parâmetros SourcePath ou LiteralPath de Update-Help e os parâmetros DestinationPath ou LiteralPath de Save-Help.

Como instalar e atualizar ficheiros de ajuda

Para descarregar e instalar ficheiros de ajuda pela primeira vez, ou para atualizar os ficheiros de ajuda no seu computador, utilize o Update-Help cmdlet.

O Update-Help cmdlet faz todo o trabalho árduo para si, incluindo as seguintes tarefas.

Determina quais os módulos que suportam a Ajuda Updatable.
Encontra a localização da internet onde cada módulo armazena os seus ficheiros De Ajuda Updatable.
Compara os ficheiros de ajuda de cada módulo no seu computador com os mais recentes ficheiros de ajuda que estão disponíveis para cada módulo.
Descarrega os novos ficheiros da internet.
Desembrulha o pacote de ficheiros de ajuda.
Verifique se os ficheiros são ficheiros de ajuda válidos.
Instala os ficheiros de ajuda na subdiretória específica do idioma do diretório do módulo.

Para aceder aos novos tópicos de ajuda, use o Get-Help cmdlet. Não precisas de reiniciar o PowerShell.

Para instalar ou atualizar ajuda para todos os módulos do computador que suporta a Ajuda Updatable, escreva:

Update-Help

Para atualizar a ajuda para determinados módulos, adicione o parâmetro do Módulo de Update-Help. Os caracteres wildcard são permitidos no nome do módulo.

Por exemplo, para atualizar a ajuda para o módulo ServerManager, escreva:

Update-Help -Module ServerManager

Sem parâmetros, Update-Help as atualizações ajudam a todos os módulos da sessão e a todos os módulos instalados que suportam a Ajuda Updatable. Para serem incluídos, os módulos devem ser instalados em diretórios que estejam listados no valor da variável ambiente PSModulePath. Estes são também módulos que são devolvidos por um comando "Obter-Ajuda -Lista Disponível".

Se o valor do parâmetro do Módulo for * (todos), Update-Help tenta atualizar a ajuda para todos os módulos instalados, incluindo módulos que não suportam Ajuda Updatable. Este comando normalmente gera muitos erros à medida que o cmdlet encontra módulos que não suportam Ajuda Updatable.

Para suportar computadores que não estão ligados à internet, ou para controlar ou simplificar ajuda a atualizar numa empresa, utilize o Save-Help cmdlet. O Save-Help cmdlet descarrega ficheiros de ajuda da internet e guarda-os num diretório de sistema de ficheiros que especifica.

Save-Help compara os ficheiros de ajuda no diretório especificado com os mais recentes ficheiros de ajuda que estão disponíveis para cada módulo. Se o diretório não tiver ficheiros de ajuda ou ficheiros de ajuda mais recentes estiverem disponíveis para o módulo, o Save-Help cmdlet descarrega os novos ficheiros a partir da internet. No entanto, não desembrulha ou instala os ficheiros de ajuda.

Para instalar ou atualizar os ficheiros de ajuda de um computador a partir de ficheiros de ajuda que foram guardados num diretório de sistemas de ficheiros, utilize o parâmetro SourcePath do Update-Help cmdlet. O Update-Help cmdlet identifica os mais recentes ficheiros de ajuda, desembrulha-os e valida-os e instala-os nas subdisposições específicas da linguagem dos diretórios dos módulos.

Por exemplo, para guardar ajuda para todos os módulos instalados no \\Server\Share diretório, escreva:

Save-Help -DestinationPath \\Server\Share

Em seguida, para atualizar a ajuda do \\Server\Share diretório, escreva:

Update-Help -SourcePath \\Server\Share

Os exemplos a seguir mostram a utilização de Save-Help para guardar ajuda para módulos que não estão instalados no computador local. Neste exemplo, o administrador corre Save-Help para guardar a ajuda do módulo DhcpServer a partir de um computador cliente ligado à Internet, sem instalar o módulo DhcpServer ou a função do Servidor DHCP no computador local.

Opção 1: Correr Invoke-Command para obter o objeto PSModuleInfo para o módulo remoto, guardá-lo numa variável e, em seguida, $mexecutar 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 uma pssessão direcionada para o computador que está a executar o módulo DOBC Server, para obter o objeto PSModuleInfo para o módulo, guardá-lo numa variável $m, e depois executar Save-Help o objeto que é guardado 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: Abrir uma sessão CIM, direcionada para o computador que está a executar o módulo DOBS Server, para obter o objeto PSModuleInfo para o módulo, guardá-lo numa variável $m, e depois executar Save-Help o objeto que é guardado 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 seguinte, o administrador instala ajuda para o módulo do Servidor DHCP num computador que não tem acesso à rede.

Em primeiro lugar, corra Export-Clixml para exportar o objeto PSModuleInfo para uma pasta partilhada ou para meios removíveis.

$m = Get-Module -Name DhcpServer -ListAvailable
Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m

Em seguida, transporte os meios de comunicação amovíveis para um computador que tenha acesso à Internet e, em seguida, importe o objeto PSModuleInfo com Import-Clixml. Corra Save-Help para salvar a ajuda para o módulo dhcpServer importado objeto PSModuleInfo .

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

Por fim, transporte os meios de comunicação amovíveis 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:\UsbFlashDrive\SavedHelp

Sem parâmetros, Save-Help os downloads ajudam a todos os módulos da sessão e a todos os módulos instalados que suportam Ajuda Updatable. Para serem incluídos, os módulos devem ser instalados em diretórios que estejam listados no valor da $env:PSModulePath variável ambiente, quer no computador local, quer num computador remoto para o qual pretende poupar ajuda. Estes são também módulos que são devolvidos executando um Get-Help -ListAvailable comando.

Como atualizar ficheiros de ajuda em diferentes idiomas

Por padrão, o download e Save-Help os Update-Help cmdlets ajudam na cultura e linguagem ui que está definida para Windows no computador local. Se os ficheiros de ajuda para os módulos especificados não estiverem disponíveis na cultura local de UI, Update-Help e Save-Help utilizar as regras de recuo do idioma do Windows para encontrar o idioma mais bem suportado.

No entanto, pode utilizar os parâmetros UICulture dos Update-Help cmdlets e Save-Help cmdlets para descarregar e instalar ficheiros de ajuda em quaisquer culturas de UI em que estejam disponíveis.

Por exemplo, para guardar os mais recentes ficheiros de ajuda para todos os módulos da sessão em japonês (Ja-jp) e francês (fr-FR), escreva:

Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr

Se os ficheiros de ajuda para os módulos não estiverem disponíveis nos idiomas especificados, os cmdlets e Save-Help os Update-Help cmdlets devolvem uma mensagem de erro que lista os idiomas em que a ajuda para cada módulo está disponível para que possa escolher a alternativa que melhor satisfaz as suas necessidades.

Nota

Atualmente, o conteúdo de ajuda atualização só é publicado em inglês (en-US). Em alguns sistemas não Windows deve utilizar o parâmetro UICulture para solicitar explicitamente o en-US conteúdo.

Como usar a ajuda online

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

Para abrir o tópico de ajuda on-line para qualquer cmdlet ou função, utilize o parâmetro Online do Get-Help cmdlet.

Por exemplo, o seguinte comando abre o tópico de ajuda on-line para o Get-Job cmdlet no seu navegador de Internet padrão:

Get-Help Get-Job -Online

Para obter ajuda on-line 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. Para ver os tópicos sobre o PowerShell, incluindo tópicos de ajuda sobre a linguagem PowerShell, consulte PowerShell About Topics.

Como minimizar ou prevenir transferências de internet

Para minimizar os downloads de internet e fornecer Ajuda Updatable aos utilizadores que não estão ligados à internet, utilize o Save-Help cmdlet. Faça o download da ajuda da internet e guarde-a para uma partilha de rede. Em seguida, crie uma definição de Política de Grupo ou um trabalho programado que executa um Update-Help comando em todos os computadores. Desa estava o valor do parâmetro SourcePath do Update-Help cmdlet para a partilha de rede.

Para evitar que os utilizadores que tenham acesso à Internet descarreguem a Ajuda Updatable a partir da internet, utilize a definição da via de origem padrão para a definição de Política de Grupo de ajuda de atualização.

Esta definição Política de Grupo adiciona implicitamente o parâmetro SourcePath, com a localização do sistema de ficheiros que especifica, a todos os comandos Update-Help de cada computador afetado. Os utilizadores podem usar explicitamente o parâmetro SourcePath para especificar uma localização de sistema de ficheiros diferente, mas não podem excluir o parâmetro SourcePath e descarregar a ajuda da internet.

Nota

O caminho de origem padrão para a definição de política do grupo de ajuda de atualização aparece na configuração do computador e na configuração do utilizador. No entanto, apenas a definição de política na Configuração do Computador é eficaz. A definição de política na Configuração do Utilizador é ignorada.

Para mais informações, consulte about_Group_Policy_Settings.

Como atualizar a ajuda para módulos não padrão

Para atualizar ou guardar ajuda para um módulo que não seja devolvido pelo parâmetro ListAvailable do Get-Module cmdlet, importe o módulo para a sessão atual antes de executar um Update-Help ou Save-Help um comando. Num computador remoto, antes de executar o Save-Help comando, importe o módulo para a Sessão atual, ou Invoke-Command bloco de scripts, que está ligado ao computador remoto.

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

Os parâmetros do Módulo e Save-Help dos Update-Help cmdlets aceitam apenas um nome de módulo. Não aceitam o caminho para um ficheiro de módulo.

Utilize esta técnica para atualizar ou guardar ajuda para qualquer módulo que não seja devolvido pelo parâmetro ListAvailable do Get-Module cmdlet, como um módulo que esteja instalado num local que não esteja listado na $env:PSModulePath variável ambiente, ou um módulo que não esteja bem formado (o diretório do módulo não contém pelo menos um ficheiro cujo nome base seja o mesmo que o nome do diretório).

Como apoiar a ajuda updatable

Se autoria de um módulo, pode apoiar a ajuda online e a Ajuda Updatable para os seus módulos. Para obter mais informações, consulte suporte para ajudar e apoiar a ajuda online.

Ajuda updatable não disponível para snap-ins PowerShell ou ajuda baseada em comentários.

Observações

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