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 di 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. Consente di scaricare e installare facilmente i file della guida e di aggiornarli ogni volta che i file della guida più recenti diventano disponibili.
Per fornire la guida 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 file system o in una condivisione file e quindi di 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 il funzionamento di Save-Help per i moduli installati in un computer remoto, ma che non sono necessariamente installati nel computer locale. È possibile salvare un oggetto PSModuleInfo su disco o su un supporto rimovibile, 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 che dispone di accesso a Internet e quindi eseguendo Save-Help sull'oggetto PSModuleInfo. La guida salvata può essere copiata nel computer remoto scollegato usando supporti rimovibili e quindi installata eseguendo Update-Help. I miglioramenti apportati alla 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 una condivisione FILE: SAVE-HELP" in questo argomento.
La guida aggiornabile supporta inoltre l'accesso online ai più recenti argomenti della guida e alla guida di base per i cmdlet di, anche quando non sono presenti file della guida nel computer.
PowerShell 3,0 non viene con i 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 file system directory 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 i cmdlet e le 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
Per aggiornare la guida, è anche possibile usare l'elemento "Aggiorna guida di PowerShell" nel menu? in PowerShell Integrated Scripting Environment (ISE).
L'elemento "aggiornare la 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 chiede di scaricare i file della guida o di leggerli online.
La guida generata automaticamente include sintassi e alias e commenti 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 la visualizzazione Get-Help 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 i singoli cmdlet.
Per trovare il modulo che contiene un cmdlet specifico, usare il formato di comando seguente:
(Get-Command <cmdlet-name>).ModuleName
Per trovare, ad esempio, 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 membri del gruppo Administrators nel computer.
Se non si è un membro del gruppo Administrators, non è possibile aggiornare la guida per questi moduli. Tuttavia, se si dispone di accesso a Internet, è possibile visualizzare la guida online nella libreria TechNet.
Aggiornamento della Guida per i moduli $ nella \ Directory Home Documents \ WindowsPowerShell \ Modules o moduli in altre sottodirectory della $ Home Directory non sono necessarie 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 in un computer remoto e 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 operazioni più impegnative, 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 del computer con i file della guida più recenti disponibili per ogni modulo.
- Scarica i nuovi file da Internet.
- Consente di annullare 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 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 i 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 aggiorna la guida per tutti i moduli della sessione e per tutti i moduli installati che supportano la guida aggiornabile. Per includere i moduli, è necessario che siano 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 è * (tutti), 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 quando 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 dell'assistenza 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 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 la directory non contiene file della guida o sono disponibili file della guida più recenti per il modulo, 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 da file della Guida salvati in una directory file system, usare il parametro SourcePath del cmdlet Update-Help. Il cmdlet Update-Help identifica i file della guida più recenti, li annulla e li convalida e li installa nelle sottodirectory specifiche del linguaggio delle directory dei moduli.
Ad esempio, per salvare la guida per tutti i moduli installati nella \ \ \ directory della condivisione server, digitare:
Save-Help -DestinationPath \\Server\Share
Quindi, per aggiornare la guida dalla \ \ \ directory della condivisione server, digitare:
Update-Help -SourcePath \\Server\Share
Negli esempi seguenti viene illustrato 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 nel 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 sull'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, 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 server DHCP in un computer che non dispone di accesso alla rete.
Eseguire innanzitutto Export-Clixml per esportare l'oggetto PSModuleInfo in una cartella condivisa o in un supporto rimovibile.
$m = Get-Module -Name DhcpServer -ListAvailable
Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m
Quindi, trasportare il supporto rimovibile in un computer dotato di 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 i supporti rimovibili nel computer che non dispone di accesso alla rete, 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 della sessione e per tutti i moduli installati che supportano la guida aggiornabile. Per includere i moduli, è necessario che siano 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 dell'interfaccia utente e nella lingua impostate 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 utilizzano le regole di fallback della lingua di Windows per trovare la lingua più supportata.
Tuttavia, è possibile usare i parametri UICulture dei cmdlet Update-Help e Save-Help per scaricare e installare i file della Guida in qualsiasi impostazioni cultura 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 in cui sono elencate 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ù di una volta al giorno. Per eseguire l'override del valore massimo di una volta al giorno, usare il parametro Force.
Usare un comando come quello riportato di seguito nel profilo. Questo comando Aggiorna la guida per tutti i moduli installati in un processo in background in modo da non infastidire il lavoro. Usa un comando out-null per disattivare il processo restituito e tutti i messaggi di errore che altrimenti verrebbero 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 a qualsiasi intervallo.
Ad esempio, il comando seguente consente di creare un processo pianificato che esegue un comando Update-Help ogni venerdì alle 5:00 AM. 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 si sceglie di non 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 consente di aprire l'argomento della Guida in linea 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 informazioni sugli argomenti. Per informazioni sugli argomenti relativi a PowerShell core, inclusi gli argomenti della guida sul linguaggio PowerShell, vedere l'argomento relativo ai moduli di PowerShell Core.
COME RIDURRE O IMPEDIRE IL DOWNLOAD DI INTERNET
Per ridurre al minimo i download per Internet e fornire una guida aggiornabile agli utenti non connessi a Internet, usare il cmdlet Save-Help. Scaricare la guida da Internet e salvarla in una condivisione di rete. Quindi, creare un'impostazione Criteri di gruppo o un processo pianificato per l'esecuzione di un comando Update-Help su tutti i computer. Impostare il valore del parametro SourcePath del cmdlet Update-Help sulla condivisione di rete.
Per impedire agli utenti che dispongono di accesso a Internet di scaricare la guida aggiornabile da Internet, usare l'impostazione del 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 di 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 di file system diverso, ma non possono escludere il parametro SourcePath e scaricare la guida da Internet.
Nota: l'impostazione di criteri di gruppo "impostare 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 o Invoke-Command corrente, che è 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 del modulo dei cmdlet Update-Help e Save-Help accettano solo un nome di modulo. Non accettano il percorso di un file del modulo.
Usare 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 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 ulteriori informazioni, vedere "supporto della Guida aggiornabile" e supporto della Guida in linea nel Microsoft docs.
La 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).