Informazioni sulla Guida aggiornabile
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 assicurarsi di avere sempre gli argomenti della Guida più recenti nel computer locale in modo da poterli leggere nella riga di comando. Consente di scaricare e installare facilmente i file della Guida e di aggiornarli ogni volta che diventano disponibili file della Guida più recenti.
Per fornire assistenza aggiornata per più computer in un'organizzazione e per i computer che non hanno accesso a Internet, guida aggiornabile consente di scaricare i file della Guida in una directory o una condivisione file del file system e quindi installare i file della Guida dalla condivisione file.
In PowerShell 4.0 la proprietà HelpInfoUri viene mantenuta tramite Windows PowerShell comunicazione remota, che consente di Save-Help di funzionare 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 dispone di accesso a Internet, importando l'oggetto PSModuleInfo in un computer con accesso a Internet e quindi eseguendo Save-Help sull'oggetto PSModuleInfo. La Guida salvata può essere copiata nel computer remoto, disconnesso tramite supporti rimovibili e quindi installata eseguendo Update-Help. Questi miglioramenti nella funzionalità di Save-Help consentono di installare la Guida nei computer senza alcun tipo di accesso alla rete. Per un esempio di come usare la nuova funzionalità di Save-Help, vedere "HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP" 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 3.0 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.
Salva-Guida: scarica i file della Guida più recenti da Internet e li salva in una directory del file system o in una condivisione file. 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 ISE
È anche possibile aggiornare la Guida usando la voce "Aggiorna guida di PowerShell" nel menu Guida in PowerShell Integrated Scripting Environment (ISE).
L'elemento "Aggiorna guida di 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, una funzione o un flusso di lavoro nel computer, il cmdlet Get-Help visualizza la Guida generata automaticamente e richiede di scaricare i file della Guida o leggerli online.
La Guida generata automaticamente include la sintassi e gli alias e le 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 cmdlet Get-Culture. L'output mostra il Get-Help visualizzato 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 è utile 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 di 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 i 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 cmdlet Set-ExecutionPolicy, 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 Administrators nel computer.
Se non si è membri del gruppo Administrators, non è possibile aggiornare la Guida per questi moduli; ma se si ha accesso a Internet, è possibile visualizzare la Guida online nella libreria TechNet.
L'aggiornamento della Guida per i moduli nella directory $home\Documents\WindowsPowerShell\Modules o moduli in altre sottodirectory della directory $home 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 accedere a percorsi Internet sicuri.
I cmdlet Update-Help e Save-Help dispongono anche di 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 cmdlet Update-Help.
Il cmdlet Update-Help 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 della lingua della directory del modulo.
Per accedere ai nuovi argomenti della Guida, usare il cmdlet Get-Help. Non è necessario riavviare 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 determinati moduli, 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 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 comando "Get-Help -ListAvailable".
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.
COME AGGIORNARE LA GUIDA DA UNA CONDIVISIONE FILE: SAVE-HELP
Per supportare i computer che non sono connessi a Internet o per controllare o semplificare l'aggiornamento in un'organizzazione, usare il cmdlet Save-Help. Il cmdlet Save-Help 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 cmdlet Save-Help scarica i nuovi file da Internet. Tuttavia, non esegue il wrapping o installa i file della Guida.
Per installare o aggiornare i file della Guida in un computer dai file della Guida salvati in una directory del file system, utilizzare il parametro SourcePath del cmdlet Update-Help. Il cmdlet Update-Help 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 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 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, $m e quindi eseguire Save-Help nell'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, destinata al computer che esegue il modulo 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, destinata al computer che esegue il modulo Server DHCP, per ottenere l'oggetto PSModuleInfo per il modulo, salvarla 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 Server DHCP in un computer che non dispone dell'accesso alla rete.
Eseguire prima di tutto Export-Clixml per esportare l'oggetto PSModuleInfo in una cartella condivisa o in supporti rimovibili.
$m = Get-Module -Name DhcpServer -ListAvailable
Export-Clixml -Path E:\UsbFlashDrive\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:\UsbFlashDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath `
E:\UsbFlashDrive\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:\UsbFlashDrive\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 variabile di ambiente PSModulePath, nel computer locale o in un computer remoto per cui si desidera salvare la Guida. Si tratta anche di moduli 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 nelle impostazioni cultura e nella lingua dell'interfaccia utente impostata per Windows nel computer locale. Se i file della Guida per i moduli specificati non sono disponibili nelle impostazioni cultura dell'interfaccia utente locale, Update-Help e Save-Help usare le regole di fallback della lingua di Windows per trovare la lingua supportata migliore.
È tuttavia possibile usare i parametri UICulture dei cmdlet Update-Help 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 cmdlet Update-Help 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.
COME AGGIORNARE AUTOMATICAMENTE LA GUIDA
Per assicurarsi di avere sempre i file della Guida più recenti, è possibile aggiungere un comando Update-Help al profilo di PowerShell.
Una quota interna impedisce l'esecuzione del comando Update-Help più volte ogni giorno. Per eseguire l'override del valore massimo di una volta al giorno, usare il parametro Force.
Usare un comando simile al seguente nel profilo. Questo comando aggiorna la Guida per tutti i moduli installati in un processo in background, in modo da non disturbare il lavoro. Usa un comando Out-Null per eliminare il processo restituito e tutti i messaggi di errore che altrimenti vengono visualizzati quando si usa il comando 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 in qualsiasi intervallo.
Ad esempio, il comando seguente crea un processo pianificato che esegue un comando della Guida di Update-Help ogni venerdì alle 5:00. Per eseguire questo comando, avviare PowerShell con l'opzione "Esegui come amministratore".
Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
-Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")
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 cmdlet Get-Help.
Ad esempio, il comando seguente apre l'argomento della Guida online per il cmdlet Get-Job 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 Core, inclusi gli argomenti della Guida sul linguaggio di PowerShell, vedere PowerShell Core Module About Topics (Modulo di base di 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 cmdlet Save-Help. 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 comando Update-Help in tutti i computer. Impostare il valore del parametro SourcePath del cmdlet Update-Help 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 Update-Help" Criteri di gruppo.
Questa impostazione Criteri di gruppo aggiunge in modo implicito il parametro SourcePath, con il percorso del file system specificato, a ogni comando Update-Help in ogni computer interessato. Gli utenti possono usare il parametro SourcePath in modo esplicito per specificare un percorso diverso del file system, ma non possono escludere il parametro SourcePath e scaricare la Guida da Internet.
NOTA: l'impostazione dei criteri di gruppo "Imposta il percorso di origine predefinito per Update-Help" viene visualizzata in Configurazione computer e Configurazione utente. Tuttavia, solo l'impostazione dei criteri in Configurazione computer è valida. 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 Get-Module, importare il modulo nella sessione corrente prima di eseguire un comando Update-Help o Save-Help. In un computer remoto, prima di eseguire il comando Save-Help, importare il modulo nel blocco di script CIM o PSSession corrente o Invoke-Command connesso al computer remoto.
Quando il modulo si trova nella sessione corrente, eseguire i 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.
Utilizzare questa tecnica per aggiornare o salvare la Guida per 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 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 nel Microsoft Docs.
Guida aggiornabile non disponibile per gli snap-in di PowerShell o la Guida basata su commenti.
REMARKS
I cmdlet Update-Help e Save-Help non sono supportati in Ambiente preinstallazione di Windows (Windows PE).