about_Updatable_Help
Aggiornamento: maggio 2014
Si applica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
ARGOMENTO
About_Updatable_Help
DESCRIZIONE BREVE
Descrive il sistema della Guida aggiornabile di Windows PowerShell®.
DESCRIZIONE LUNGA
Windows PowerShell offre diversi modi per accedere agli argomenti della Guida più aggiornati relativi a cmdlet e concetti di Windows PowerShell.
Il sistema di Guida aggiornabile, introdotto in Windows PowerShell 3.0, è progettato per garantire che gli argomenti della Guida più recenti siano sempre disponibili nel computer locale in modo che sia possibile leggerli dalla riga di comando. Semplifica inoltre il download e l'installazione dei file della Guida e il relativo aggiornamento ogni volta che diventano disponibili file della Guida più recenti.
Per fornire informazioni aggiornate per più computer di un'organizzazione e per i computer senza accesso a Internet, la Guida aggiornabile consente di scaricare i file della Guida in una directory del file system o in una condivisione di file e installarli quindi dalla condivisione di file.
In Windows PowerShell 4.0, la proprietà HelpInfoUri viene mantenuta tramite la comunicazione remota di Windows PowerShell, consentendo a Save-Help di funzionare per i moduli che vengono installati in un computer remoto ma non necessariamente nel computer locale. È possibile salvare un oggetto PSModuleInfo su disco o supporto rimovibile (ad esempio un'unità USB) eseguendo Export-CliXml su un computer senza accesso a Internet, importando l'oggetto PSModuleInfo su un computer con accesso a Internet ed eseguendo quindi Save-Help per l'oggetto PSModuleInfo. La Guida salvata può essere copiata nel computer remoto e disconnesso usando supporti rimovibili e quindi eseguendo Update-Help. Questi miglioramenti della funzionalità Save-Help consentono di installare la Guida in computer privi di qualsiasi tipo di accesso alla rete. Per un esempio di come usare la nuova funzionalità Save-Help, vedere "COME AGGIORNARE LA GUIDA DA CONDIVISIONE FILE: SAVE-HELP" in questo argomento.
La Guida aggiornabile supporta anche l'accesso online agli argomenti della Guida più recenti e la Guida di base per i cmdlet, anche quando non sono presenti file della Guida nel computer.
Windows PowerShell 3.0 non contiene file della Guida. È possibile usare la funzionalità Guida aggiornabile per installare i file della Guida per tutti i comandi inclusi per impostazione predefinita in Windows PowerShell e per tutti i moduli di Windows.
CMDLET DI GUIDA AGGIORNABILE
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 condivisione file o directory del file system. Per installare i file della Guida nel computer, usare Update-Help.
Get-Help:
Visualizza gli argomenti della guida nella riga di comando.
Ottiene assistenza dai file della Guida sul computer.
Visualizza la guida generata automaticamente per i cmdlet e le funzioni che non dispongono di file della Guida.
Apre gli argomenti della Guida in linea per cmdlet, funzioni, script e flussi di lavoro nel browser Internet predefinito.
AGGIORNARE LA GUIDA DI WINDOWS POWERSHELL ISE
È anche possibile aggiornare la Guida mediante la voce "Aggiornamento Guida Windows PowerShell" nel menu della Guida in Windows PowerShell Integrated Scripting Environment (ISE).
La voce "Aggiorna Guida di Windows PowerShell" esegue un comando Update-Help senza parametri.
GUIDA GENERATA AUTOMATICAMENTE: GUIDA SENZA FILE DELLA GUIDA
Se non si dispone del file della Guida per un cmdlet, funzione o flusso di lavoro nel computer, il cmdlet Get-Help visualizza la Guida generata automaticamente e chiede di scaricare i file della Guida o leggerli in linea.
La guida generata automaticamente include sintassi, alias e commenti che spiegano come usare i cmdlet della Guida aggiornabile e come accedere alla Guida in linea.
Ad esempio, il comando seguente ottiene informazioni di base per il cmdlet Get-Culture. L'output mostra la visualizzazione di Get-Help quando non sono presenti file della Guida nel computer.
PS C:\> Get-Help Get-Culture
NOME
Get-Culture
SINTASSI
Get-Culture [<ParametriComuni>]
ALIAS
Nessuno
OSSERVAZIONI
Per ottenere il contenuto della Guida più recente con descrizioni ed esempi, digitare: Update-Help.
FILE DELLA GUIDA PER MODULI
L'unità più piccola della Guida aggiornabile è la Guida per un modulo. Nella Guida del modulo sono disponibili informazioni 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 sul computer, anche se non vengono importati nella sessione corrente.
È possibile aggiornare la Guida per l'intero modulo, ma non è possibile aggiornare la Guida per i singoli cmdlet.
Per trovare il modulo che contiene un particolare cmdlet, usare il comando nel formato seguente:
(Get-Command <cmdlet-name>).ModuleName
Ad esempio, per trovare il modulo che contiene il cmdlet Set-ExecutionPolicy, digitare:
(Get-Command Set-ExecutionPolicy).ModuleName
Per aggiornare la Guida per un particolare modulo, 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 membro del gruppo Administrators nel computer.
Se non si è un membro del gruppo Administrators, non è possibile aggiornare la Guida di questi moduli. Se si dispone di accesso a Internet, tuttavia, è possibile visualizzare la Guida online nella libreria TechNet.
Aggiornamento della Guida per i moduli nella directory $home\Documents\WindowsPowerShell\Modules o nei moduli in altre sottodirectory della directory $home che non richiedono autorizzazioni speciali.
I cmdlet Update-Help e Save-Help hanno un parametro UseDefaultCredentials che fornisce le credenziali esplicite dell'utente corrente. Questo parametro è progettato per l'accesso a percorsi Internet sicuri.
I cmdlet Update-Help e Save-Help hanno anche un parametro Credential che consente di eseguire il comando su un computer remoto e accedere a una condivisione di file in un terzo computer. Il parametro Credential è valido solo quando si usano i parametri SourcePath o LiteralPath della Guida di aggiornamento 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 in uso, usare il cmdlet Update-Help.
Il cmdlet Update-Help esegue tutte le operazioni di disco rigido per l'utente, incluse le attività seguenti.
Determina quali moduli supportano la Guida aggiornabile.
Trova il percorso Internet in cui ogni modulo archivia i file della Guida aggiornabile.
Confronta i file della Guida per ciascun modulo sul computer con i file della Guida più recenti disponibili per ciascun modulo.
Scarica i nuovi file da Internet.
Apre il pacchetto di file della Guida.
Verifica che i file siano file della Guida validi.
Installa i file della Guida nella sottodirectory specifica della lingua della directory del modulo.
Per accedere ai nuovi argomenti della Guida, usare il cmdlet Get-Help. Non è necessario riavviare Windows PowerShell.
Per installare o aggiornare la Guida per tutti i moduli sul computer che supporta la Guida aggiornabile, digitare:
Update-Help
Per aggiornare la Guida per moduli specifici, aggiungere il parametro Module di Update-Help. Nel nome del modulo sono consentiti i caratteri jolly.
Update-Help -Module ServerManager
NOTE
Senza parametri, Update-Help aggiorna 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 variabile di ambiente PSModulePath. Questi sono anche i moduli restituiti da un comando "Get-Help -ListAvailable".
Se il valore del parametro Module è * (tutto), Update-Help tenta di aggiornare la Guida per tutti i moduli installati, inclusi quelli che non supportano la Guida aggiornabile. Questo comando solitamente genera molti errori poiché il cmdlet rileva moduli che non supportano la Guida aggiornabile.
COME AGGIORNARE LA GUIDA DA UNA CONDIVISIONE FILE: SAVE-HELP
Per supportare i computer non connessi a Internet oppure per controllare o semplificare l'aggiornamento della Guida in un'organizzazione, usare il cmdlet Save-Help. Il cmdlet Save-Help scarica i file della Guida da Internet e li salva nella directory del file system specificata dall'utente.
Save-Help confronta i file della Guida nella directory specificata con i file della Guida più recenti disponibili per ciascun modulo. Se nella directory non sono presenti file della Guida o se per il modulo sono disponibili file della Guida più recenti, il cmdlet Save-Help scarica i nuovi file da Internet. Tuttavia, non estrae dal pacchetto né installa i file della Guida.
Per installare o aggiornare i file della Guida su un computer dai file della Guida salvati in una directory del file system, usare il parametro SourcePath del cmdlet Update-Help. Il cmdlet Update-Help identifica i file della Guida più recenti, li estrae dal pacchetto e li convalida, quindi li installa nelle sottodirectory specifiche delle lingue delle directory dei moduli.
Ad esempio, per salvare la Guida per tutti i moduli installati nella directory \\Server\Share, digitare:
Save-Help -DestinationPath \\Server\Share
Quindi, per aggiornare la Guida dalla directory \\Server\Share, digitare:
Update-Help -SourcePath \\Server\Share
Negli esempi seguenti viene illustrano l'utilizzo di Save-Help per salvare la Guida per i moduli che non sono 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 sul computer locale.
Opzione 1:
Eseguire Invoke-Command per ottenere l'oggetto PSModuleInfo per il modulo remoto, salvarlo in una variabile, $m, quindi eseguire Save-Help per l'oggetto PSModuleInfo specificando la variabile $m come nome del modulo.
$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock
{ Get-Module -Name DhcpServer -ListAvailable }
Save-Help -Module $m -DestinationPath C:\SavedHelp
Opzione 2:
Aprire una sessione PSSession, assegnata al computer che esegue il modulo di Server DHCP, per ottenere l'oggetto PSModuleInfo per il modulo, salvarlo in una variabile $m e quindi eseguire Save-Help sull'oggetto salvato nella variabile $m.
$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, assegnata al computer che esegue il modulo di Server DHCP, per ottenere l'oggetto PSModuleInfo per il modulo, salvarlo in una variabile $m e quindi eseguire Save-Help sull'oggetto salvato nella variabile $m.
$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 di Server DHCP su un computer senza accesso alla rete.
# Eseguire prima Export-CliXml per esportare l'oggetto PSModuleInfo in una cartella condivisa o su supporti rimovibili.
$m = Get-Module -Name DhcpServer –ListAvailable
Export-CliXml –Path E:\UsbFlashDrive\DhcpModule.xml –InputObject $m
# Trasportare poi il supporto rimovibile in un computer con accesso a Internet e importare l'oggetto PSModuleInfo con Import-CliXml. Eseguire Save-Help per salvare la Guida per l'oggetto PSModuleInfo modulo DhcpServer importato.
$deserialized_m = Import-CliXml E:\UsbFlashDrive\DhcpModule.xml
Save-Help -Module $deserialized_m –DestinationPath
E:\UsbFlashDrive\SavedHelp
# Riportare, infine, il supporto rimovibile sul computer senza accesso alla rete e quindi installare la Guida eseguendo Update-Help.
Update-Help –Module DhcpServer –SourcePath
E:\UsbFlashDrive\SavedHelp
NOTE:
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 variabile di ambiente PSModulePath, nel computer locale o in un computer remoto per il quale si desidera salvare la Guida. Sono compresi i moduli che vengono restituiti eseguendo un comando "Get-Help -ListAvailable".
COME AGGIORNARE I FILE DELLA GUIDA IN LINGUE DIVERSE
Per impostazione predefinita, i cmdlet Update-Help e Save-Help scaricano la Guida nella lingua e cultura dell'interfaccia utente impostata per Windows nel computer locale. Se i file della Guida per i moduli specificati non sono disponibili nella lingua dell'interfaccia utente locale, Update-Help e Save-Help usano le regole di fallback della lingua di Windows per trovare la migliore lingua supportata.
Tuttavia, è possibile usare i parametri di UICulture dei cmdlet Update-Help e Save-Help per scaricare e installare i file della Guida nelle lingue dell'interfaccia utente in cui sono disponibili.
Ad esempio, per salvare i file della Guida più recenti per tutti i moduli della 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 cmdlet Update-Help e Save-Help restituiscono un messaggio di errore che elenca le lingue in cui la Guida è disponibile per ciascun modulo in modo che sia possibile scegliere l'alternativa che meglio soddisfa le proprie esigenze.
COME AGGIORNARE AUTOMATICAMENTE LA GUIDA
Per garantire che i file della Guida siano sempre aggiornati, è possibile aggiungere un comando Update-Help al proprio profilo Windows PowerShell.
Una quota interna impedisce l'esecuzione del comando Update-Help più di una volta al giorno. Per ignorare il limite di una volta al giorno, usare il parametro Force.
Usare un comando simile al seguente nel proprio profilo. Questo comando aggiorna la Guida per tutti i moduli installati in un processo in background in modo da non disturbare il lavoro. Viene usato un comando Out-Null per eliminare il processo restituito ed eventuali messaggi di errore che vengono visualizzati quando il comando viene eseguito più di una volta al giorno.
Start-Job {Update-Help} | Out-Null
È anche possibile creare un processo pianificato che esegue il cmdlet Update-Help o Save-Help a qualunque intervallo.
Ad esempio, il comando seguente crea un processo pianificato che esegue un comando della guida Update-Help ogni venerdì alle 5:00. Per eseguire questo comando, avviare Windows PowerShell con l'opzione "Esegui come amministratore".
Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
-Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")
Per altre informazioni sui processi pianificati, vedere about_Scheduled_Jobs.
COME USARE LA GUIDA IN LINEA
Se non è possibile o non si desidera aggiornare i file della Guida nel computer locale, è comunque possibile ottenere i file più recenti in linea.
Per aprire l'argomento della Guida in linea per un cmdlet o una funzione, usare il parametro Online del cmdlet Get-Help.
Ad esempio, il comando seguente consente di aprire l'argomento della Guida in linea per il cmdlet Get-Job nel browser Internet predefinito:
Get-Help Get-Job -Online
- oppure -
Get-Help -on Get-Job
Per ottenere la Guida in linea per uno script, usare il parametro Online e il percorso completo dello script.
Il parametro Online non funziona con gli argomenti di informazioni. Per visualizzare gli argomenti informativi per Windows PowerShell di base, inclusi gli argomenti della Guida sulla lingua di Windows PowerShell, vedere "Argomenti di informazioni sui componenti di sistema di Windows PowerShell" in https://go.microsoft.com/fwlink/?LinkID=113206.
COME RIDURRE O EVITARE DOWNLOAD DA INTERNET
Per ridurre al minimo i download da Internet e fornire una Guida aggiornabile agli utenti che non sono connessi a Internet, usare il cmdlet Save-Help. Scaricare la Guida da Internet e salvarla in una condivisione di rete. Quindi, creare un'impostazione di criteri di gruppo o un processo pianificato che esegue un comando Update-Help in tutti i computer. Impostare la condivisione di rete come valore del parametro SourcePath del cmdlet Update-Help.
Per evitare che gli utenti con accesso a Internet eseguano il download della Guida aggiornabile da Internet, usare l'impostazione di criteri di gruppo "Impostare il percorso di origine predefinito per Update-Help".
Questa impostazione di criteri di gruppo aggiunge in modo implicito il parametro SourcePath, con il percorso del file system specificato, a ogni comando Update-Help in tutti i computer interessati. Gli utenti possono usare in modo esplicito il parametro SourcePath per specificare un percorso del file system diverso, ma non possono escludere il parametro SourcePath e il download della Guida da Internet.
NOTA:
Verrà visualizzata l'impostazione di criteri di gruppo "Impostare il percorso di origine predefinito per Update-Help" in configurazione Computer e configurazione utente. Tuttavia, solo l'impostazione di criteri di gruppo in Configurazione computer è effettiva. L'impostazione dei criteri in Configurazione utente viene ignorata.
Per altre informazioni, vedere about_Group_Policy_Settings.
COME AGGIORNARE LA GUIDA PER I MODULI NON STANDARD
Per aggiornare o salvare la Guida per un modulo che non viene restituito dal parametro ListAvailable del cmdlet Get-Module, importare il modulo nella sessione corrente prima di eseguire un comando Save-Help o Update-Help. In un computer remoto, prima di eseguire il comando Save-Help, importare il modulo in CIM o PSSession corrente, o il blocco di script Invoke-Command, connesso al computer remoto.
Quando il modulo si trova nella sessione corrente, eseguire il cmdlet Update-Help o Save-Help senza parametri oppure usare il parametro Module per specificare il nome del modulo.
I parametri Module dei cmdlet Update-Help 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 di qualsiasi modulo non restituito dal parametro ListAvailable del cmdlet Get-Module, ad esempio un modulo installato in un percorso non elencato nella variabile di ambiente PSModulePath o un modulo con un formato non corretto (la directory del modulo non contiene almeno un file il cui nome di base corrisponde al nome della directory).
COME SUPPORTARE LA GUIDA AGGIORNABILE
Se si crea un modulo, è possibile supportare la Guida in linea e la Guida aggiornabile per i moduli. Per altre informazioni, vedere "Supporto Guida aggiornabile" e "Supporto Guida in linea" in MSDN Library.
Guida aggiornabile non disponibile per snap-in Windows PowerShell o Guide basate su commento.
PAROLE CHIAVE
About_Updateable_Help
OSSERVAZIONI
I cmdlet Update-Help e Save-Help non sono supportati in Ambiente preinstallazione di Windows (Windows PE).
VEDERE ANCHE
Get-Help
Save-Help
Update-Help
Tabella di stato Guida aggiornabile