about_Updatable_Help

Articolo
10/20/2023

Descrizione breve

Descrive il sistema della Guida aggiornabile in PowerShell.

Descrizione lunga

PowerShell offre diversi modi per accedere agli argomenti della Guida più aggiornati per i cmdlet e i concetti di PowerShell.

Il sistema della Guida aggiornabile, introdotto in PowerShell 3.0, è progettato per garantire che siano sempre disponibili gli argomenti della Guida più recenti nel computer locale in modo da poterli leggere dalla riga di comando. Semplifica il download e l'installazione dei file della Guida e l'aggiornamento ogni volta che i file della Guida più recenti diventano disponibili.

Per fornire assistenza aggiornata per più computer in un'organizzazione e per i computer che non hanno accesso a Internet, la Guida aggiornabile consente di scaricare i file della Guida in una directory o una condivisione file system del file system e quindi installare i file della Guida dalla condivisione file.

In PowerShell 4.0 la proprietà HelpInfoUri viene mantenuta tramite la comunicazione remota di Windows PowerShell, che consente di Save-Help lavorare per i moduli installati in un computer remoto, ma non sono necessariamente installati nel computer locale. È possibile salvare un oggetto PSModuleInfo su disco o supporti rimovibili (ad esempio un'unità USB) eseguendo Export-Clixml in un computer che non ha accesso a Internet, importando l'oggetto PSModuleInfo in un computer che dispone di accesso a Internet e quindi in esecuzione Save-Help nell'oggetto PSModuleInfo . La Guida salvata può essere copiata nel computer remoto, disconnesso tramite supporti rimovibili e quindi installata eseguendo Update-Help. Questi miglioramenti apportati alla Save-Help funzionalità consentono di installare la Guida nei computer senza alcun tipo di accesso alla rete. Per un esempio di come usare la nuova Save-Help funzionalità, vedere Come aggiornare la Guida da una condivisione file in questo argomento.

La Guida aggiornabile supporta anche l'accesso online agli argomenti della Guida più recenti e alla Guida di base per i cmdlet, anche quando non sono presenti file della Guida nel computer.

PowerShell non include file della Guida. È possibile usare la funzionalità Guida aggiornabile per installare i file della Guida per tutti i comandi inclusi per impostazione predefinita in PowerShell e per tutti i moduli di Windows.

Cmdlet della Guida aggiornabili

Update-Help: scarica i file della Guida più recenti da Internet o da una condivisione file e li installa nel computer locale.
Save-Help: scarica i file della Guida più recenti da Internet e li salva in una directory o in una condivisione file system. Per installare i file della Guida nei computer, usare Update-Help.
Get-Help: visualizza gli argomenti della Guida nella riga di comando. Ottiene la Guida dai file della Guida nel computer. Visualizza la Guida generata automaticamente per cmdlet e funzioni che non dispongono di file della Guida. Apre gli argomenti della Guida online per cmdlet, funzioni, script e flussi di lavoro nel browser Internet predefinito.

Aggiornare la Guida in PowerShell I edizione Standard

È anche possibile aggiornare la Guida usando la voce Aggiorna guida di PowerShell nel menu ? in PowerShell Integrated Scripting Environment (I edizione Standard).

L'elemento della Guida di PowerShell aggiorna esegue un Update-Help comando senza parametri.

Guida generata automaticamente: Guida senza file della Guida

Se nel computer non è disponibile il file della Guida per un cmdlet, una funzione o un flusso di lavoro, il Get-Help cmdlet visualizza la Guida generata automaticamente e richiede di scaricare i file della Guida o leggerli online.

La Guida generata automaticamente include sintassi e alias e osservazioni che spiegano come usare i cmdlet della Guida aggiornabili e per accedere agli argomenti della Guida online.

Ad esempio, il comando seguente ottiene la Guida di base per il Get-Culture cmdlet . L'output mostra la Get-Help visualizzazione quando non sono presenti file della Guida nel computer.

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.

File della Guida per i moduli

L'unità più piccola della Guida aggiornabile è la Guida per un modulo. La Guida del modulo include la Guida per tutti i cmdlet, le funzioni, i flussi di lavoro, i provider, gli script e i concetti in un modulo. È possibile aggiornare la Guida per tutti i moduli installati nel computer, anche se non vengono importati nella sessione corrente.

È possibile aggiornare la Guida per l'intero modulo, ma non è possibile aggiornare la Guida per singoli cmdlet.

Per trovare il modulo che contiene un cmdlet specifico, usare il formato di comando seguente:

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

Ad esempio, per trovare il modulo che contiene il Set-ExecutionPolicy cmdlet, digitare:

(Get-Command Set-ExecutionPolicy).ModuleName

Per aggiornare la Guida per un modulo specifico, digitare:

Update-Help -Module <ModuleName>

Ad esempio, per aggiornare la Guida per il modulo che contiene il cmdlet Set-ExecutionPolicy, digitare:

Update-Help -Module Microsoft.PowerShell.Security

Autorizzazioni per la Guida aggiornabile

Per aggiornare la Guida per i moduli nella directory $pshome/Modules, è necessario essere membri del gruppo Amministrazione istrators nel computer.

Se non si è membri del gruppo Amministrazione istrators, non è possibile aggiornare la Guida per questi moduli, ma se si ha accesso a Internet, è possibile visualizzare la Guida online.

L'aggiornamento della Guida per i moduli nella directory $HOME/Documents/PowerShell/Modules o nei moduli in altre sottodirectory della $HOME directory non richiede autorizzazioni speciali.

I Update-Help cmdlet e Save-Help hanno un parametro UseDefaultCredentials che fornisce le credenziali esplicite dell'utente corrente. Questo parametro è progettato per accedere a percorsi Internet sicuri.

I Update-Help cmdlet e Save-Help hanno anche un parametro Credential che consente di eseguire il comando in un computer remoto e di accedere a una condivisione file in un terzo computer. Il parametro Credential è valido solo quando si usano i parametri SourcePath o LiteralPath di Update-Help e i parametri DestinationPath o LiteralPath di Save-Help.

Come installare e aggiornare i file della Guida

Per scaricare e installare i file della Guida per la prima volta o per aggiornare i file della Guida nel computer, usare il Update-Help cmdlet .

Il Update-Help cmdlet esegue tutte le attività più complesse, incluse le attività seguenti.

Determina quali moduli supportano la Guida aggiornabile.
Trova il percorso Internet in cui ogni modulo archivia i file della Guida aggiornabili.
Confronta i file della Guida per ogni modulo nel computer con i file della Guida più recenti disponibili per ogni modulo.
Scarica i nuovi file da Internet.
Annulla il wrapping del pacchetto del file della Guida.
Verifica che i file siano file della Guida validi.
Installa i file della Guida nella sottodirectory specifica del linguaggio della directory del modulo.

Per accedere ai nuovi argomenti della Guida, usare il Get-Help cmdlet . Non è necessario riavviare Windows PowerShell.

Per installare o aggiornare la Guida per tutti i moduli nel computer che supporta la Guida aggiornabile, digitare:

Update-Help

Per aggiornare la Guida per moduli specifici, aggiungere il parametro Module di Update-Help. I caratteri jolly sono consentiti nel nome del modulo.

Ad esempio, per aggiornare la Guida per il modulo ServerManager, digitare:

Update-Help -Module ServerManager

Senza parametri, Update-Help gli aggiornamenti della Guida per tutti i moduli della sessione e per tutti i moduli installati che supportano la Guida aggiornabile. Per essere inclusi, i moduli devono essere installati nelle directory elencate nel valore della variabile di ambiente PSModulePath. Si tratta anche di moduli restituiti da un Get-Module -ListAvailable comando.

Se il valore del parametro Module è * (tutto), Update-Help tenta di aggiornare la Guida per tutti i moduli installati, inclusi i moduli che non supportano la Guida aggiornabile. Questo comando genera in genere molti errori perché il cmdlet rileva moduli che non supportano la Guida aggiornabile.

Per supportare i computer che non sono connessi a Internet o per controllare o semplificare l'aggiornamento in un'organizzazione, usare il Save-Help cmdlet . Il Save-Help cmdlet scarica i file della Guida da Internet e li salva in una directory del file system specificata.

Save-Help confronta i file della Guida nella directory specificata con i file della Guida più recenti disponibili per ogni modulo. Se per il modulo non sono disponibili file della Guida o file della Guida più recenti, il Save-Help cmdlet scarica i nuovi file da Internet. Tuttavia, non annulla il wrapping o installa i file della Guida.

Per installare o aggiornare i file della Guida in un computer da file della Guida salvati in una directory del file system, usare il parametro SourcePath del Update-Help cmdlet . Il Update-Help cmdlet identifica i file della Guida più recenti, annulla il wrapping e li convalida e li installa nelle sottodirectory specifiche della lingua delle directory del modulo.

Ad esempio, per salvare la Guida per tutti i moduli installati nella \\Server\Share directory, digitare:

Save-Help -DestinationPath \\Server\Share

Quindi, per aggiornare la Guida dalla \\Server\Share directory, digitare:

Update-Help -SourcePath \\Server\Share

Negli esempi seguenti viene illustrato l'uso di Save-Help per salvare la Guida per i moduli non installati nel computer locale. In questo esempio l'amministratore esegue Save-Help per salvare la Guida per il modulo DhcpServer da un computer client connesso a Internet, senza installare il modulo DhcpServer o il ruolo Server DHCP nel computer locale.

Opzione 1: eseguire Invoke-Command per ottenere l'oggetto PSModuleInfo per il modulo remoto, salvarlo in una variabile, $me quindi eseguire Save-Help nell'oggetto PSModuleInfo specificando la variabile $m come nome del modulo.

$invokeCommandSplat = @{
    ComputerName = 'RemoteServer'
    ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable }
}
$m = Invoke-Command @invokeCommandSplat
Save-Help -Module $m -DestinationPath C:\SavedHelp

Opzione 2: aprire una sessione PSSession destinata al computer che esegue il modulo Server DHCP per ottenere l'oggetto PSModuleInfo per il modulo, salvarlo in una variabile $me quindi eseguirlo Save-Help sull'oggetto salvato nella $m variabile.

$s = New-PSSession -ComputerName RemoteServer
$m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

Opzione 3: aprire una sessione CIM, destinata al computer che esegue il modulo Server DHCP, per ottenere l'oggetto PSModuleInfo per il modulo, salvarlo in una variabile $me quindi eseguire Save-Help sull'oggetto salvato nella $m variabile.

$c = New-CimSession -ComputerName RemoteServer
$m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

Nell'esempio seguente l'amministratore installa la Guida per il modulo Server DHCP in un computer che non dispone dell'accesso alla rete.

Export-Clixml Eseguire prima di tutto per esportare l'oggetto PSModuleInfo in una cartella condivisa o in supporti rimovibili.

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

Successivamente, trasportare il supporto rimovibile in un computer con accesso a Internet e quindi importare l'oggetto PSModuleInfo con Import-Clixml. Eseguire Save-Help per salvare la Guida per l'oggetto PSModuleInfo del modulo DhcpServer importato.

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

Infine, trasportare nuovamente il supporto rimovibile nel computer che non dispone dell'accesso alla rete e quindi installare la Guida eseguendo Update-Help.

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

Senza parametri, Save-Help scarica la Guida per tutti i moduli nella sessione e per tutti i moduli installati che supportano la Guida aggiornabile. Per essere inclusi, i moduli devono essere installati nelle directory elencate nel valore della $env:PSModulePath variabile di ambiente, nel computer locale o in un computer remoto per cui si desidera salvare la Guida. Si tratta anche di moduli restituiti eseguendo un Get-Help -ListAvailable comando .

Come aggiornare i file della Guida in lingue diverse

Per impostazione predefinita, i cmdlet e Save-Help scaricano la Update-Help Guida nelle impostazioni cultura e nella lingua dell'interfaccia utente impostate per Windows nel computer locale. Se i file della Guida per i moduli specificati non sono disponibili nelle impostazioni cultura Update-Help dell'interfaccia utente locale e Save-Help usano le regole di fallback della lingua di Windows per trovare la lingua supportata migliore.

È tuttavia possibile usare i parametri UICulture dei Update-Help cmdlet e Save-Help per scaricare e installare i file della Guida in tutte le impostazioni cultura dell'interfaccia utente in cui sono disponibili.

Ad esempio, per salvare i file della Guida più recenti per tutti i moduli nella sessione in giapponese (ja-Jp) e francese (fr-FR), digitare:

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

Se i file della Guida per i moduli non sono disponibili nelle lingue specificate, i Update-Help cmdlet e Save-Help restituiscono un messaggio di errore che elenca le lingue in cui è disponibile la Guida per ogni modulo in modo da poter scegliere l'alternativa più adatta alle proprie esigenze.

Nota

Attualmente, il contenuto della Guida aggiornabile è pubblicato solo in inglese (en-US).

Come usare la Guida online

Se non è possibile o non si sceglie di aggiornare i file della Guida nel computer locale, è comunque possibile ottenere i file della Guida più recenti online.

Per aprire l'argomento della Guida online per qualsiasi cmdlet o funzione, usare il parametro Online del Get-Help cmdlet .

Ad esempio, il comando seguente apre l'argomento della Guida online per il Get-Job cmdlet nel browser Internet predefinito:

Get-Help Get-Job -Online

Per ottenere la Guida online per uno script, usare il parametro Online e il percorso completo dello script.

Il parametro Online non funziona con gli argomenti About. Per visualizzare gli argomenti relativi a PowerShell, inclusi gli argomenti della Guida sul linguaggio di PowerShell, vedere Argomenti relativi a PowerShell.

Come ridurre al minimo o impedire i download Internet

Per ridurre al minimo i download Internet e fornire la Guida aggiornabile agli utenti che non sono connessi a Internet, usare il Save-Help cmdlet . Scaricare la Guida da Internet e salvarla in una condivisione di rete. Creare quindi un'impostazione di Criteri di gruppo o un processo pianificato che esegue un Update-Help comando in tutti i computer. Impostare il valore del parametro SourcePath del Update-Help cmdlet sulla condivisione di rete.

Per impedire agli utenti che hanno accesso a Internet di scaricare la Guida aggiornabile da Internet, usare l'impostazione Imposta il percorso di origine predefinito per i Criteri di gruppo Update-Help .

Questa impostazione di Criteri di gruppo aggiunge in modo implicito il parametro SourcePath , con il percorso del file system specificato, a ogni Update-Help comando in ogni computer interessato. Gli utenti possono usare il parametro SourcePath in modo esplicito per specificare un percorso del file system diverso, ma non possono escludere il parametro SourcePath e scaricare la Guida da Internet.

Nota

L'impostazione imposta il percorso di origine predefinito per i criteri di gruppo Update-Help viene visualizzata in Configurazione computer e Configurazione utente. Tuttavia, solo l'impostazione dei criteri in Configurazione computer è efficace. L'impostazione dei criteri in Configurazione utente viene ignorata.

Per altre informazioni, vedere Informazioni sulle impostazioni di Criteri di gruppo.

Come aggiornare la Guida per i moduli non standard

Per aggiornare o salvare la Guida per un modulo non restituito dal parametro ListAvailable del cmdlet, importare il modulo nella sessione corrente prima di Get-Module eseguire un Update-Help comando o Save-Help . In un computer remoto, prima di eseguire il Save-Help comando, importare il modulo nel blocco di script o Invoke-Command sessione corrente connesso al computer remoto.

Quando il modulo si trova nella sessione corrente, eseguire i Update-Help cmdlet o Save-Help senza parametri oppure usare il parametro Module per specificare il nome del modulo.

I parametri Module dei Update-Help cmdlet e Save-Help accettano solo un nome di modulo. Non accettano il percorso di un file di modulo.

Usare questa tecnica per aggiornare o salvare la Guida per qualsiasi modulo non restituito dal parametro ListAvailable del Get-Module cmdlet, ad esempio un modulo installato in un percorso non elencato nella $env:PSModulePath variabile di ambiente o un modulo non ben formato (la directory del modulo non contiene almeno un file il cui nome di base è uguale al nome della directory).

Come supportare la Guida aggiornabile

Se si crea un modulo, è possibile supportare la Guida online e la Guida aggiornabile per i moduli. Per altre informazioni, vedere Supporto della Guida aggiornabile e supporto della Guida online.

Guida aggiornabile non disponibile per gli snap-in di PowerShell o la Guida basata su commenti.

Osservazioni:

I Update-Help cmdlet e Save-Help non sono supportati in Windows Preinstallation Environment (Windows PE).