Supporto della Guida in linea

A partire da PowerShell 3.0, esistono due modi per supportare la Get-Help funzionalità Online per i comandi di PowerShell. Questo argomento illustra come implementare questa funzionalità per tipi di comando diversi.

Informazioni sulla Guida online

La Guida online è sempre stata una parte essenziale di PowerShell. Anche se il cmdlet visualizza gli argomenti della Guida al prompt dei comandi, molti utenti preferiscono l'esperienza di lettura online, tra cui codifica a colori, collegamenti ipertestuali e condivisione di idee in contenuto Community e documenti basati su Get-Help wiki. Soprattutto, prima dell'avvento della Guida aggiornabile, la Guida online ha fornito la versione più aggiornata dei file della Guida.

Con l'avvento della Guida aggiornabile in PowerShell 3.0, la Guida online svolge ancora un ruolo fondamentale. Oltre all'esperienza utente flessibile, la Guida online fornisce assistenza agli utenti che non usano o non possono usare la Guida aggiornabile per scaricare gli argomenti della Guida.

Funzionamento Get-Help -Online

Per consentire agli utenti di trovare gli argomenti della Guida online per i comandi, il comando ha un parametro Online che apre la versione online dell'argomento della Guida per un comando nel Get-Help browser Internet predefinito dell'utente.

Ad esempio, il comando seguente apre l'argomento della Guida online per il Invoke-Command cmdlet .

Get-Help Invoke-Command -Online

Per Get-Help -Online implementare , Get-Help il cmdlet cerca un UNIFORM RESOURCE IDENTIFIER (URI) per l'argomento della Guida sulla versione online nei percorsi seguenti.

Il primo collegamento nella sezione Collegamenti correlati dell'argomento della Guida per il comando . L'argomento della Guida deve essere installato nel computer dell'utente. Questa funzionalità è stata introdotta in PowerShell 2.0.
Proprietà HelpUri di qualsiasi comando. La proprietà HelpUri è accessibile anche quando l'argomento della Guida per il comando non è installato nel computer dell'utente. Questa funzionalità è stata introdotta in PowerShell 3.0.

Get-Helpcerca un URI nella prima voce della sezione Collegamenti correlati prima di ottenere il valore della proprietà HelpUri. Se il valore della proprietà non è corretto o è stato modificato, è possibile eseguirne l'override immettendo un valore diverso nel primo collegamento correlato. Tuttavia, il primo collegamento correlato funziona solo quando gli argomenti della Guida sono installati nel computer dell'utente.

È possibile supportare qualsiasi comando aggiungendo un URI valido alla prima voce nella sezione Collegamenti correlati dell'argomento della Guida basato su Get-Help -Online XML per il comando. Questa opzione è valida solo negli argomenti della Guida basati su XML e funziona solo quando l'argomento della Guida è installato nel computer dell'utente. Quando l'argomento della Guida viene installato e l'URI viene popolato, questo valore ha la precedenza sulla proprietà HelpUri del comando.

Per supportare questa funzionalità, l'URI deve essere visualizzato maml:uri nell'elemento sotto il primo elemento maml:relatedLinks/maml:navigationLink maml:relatedLinks nell'elemento .

Il codice XML seguente mostra la posizione corretta dell'URI. Il Online version: testo maml:linkText nell'elemento è una procedura consigliata, ma non è obbligatorio.

<maml:relatedLinks>
    <maml:navigationLink>
        <maml:linkText>Online version:</maml:linkText>
        <maml:uri>https://go.microsoft.com/fwlink/?LinkID=113279</maml:uri>
    </maml:navigationLink>
    <maml:navigationLink>
        <maml:linkText>about_History</maml:linkText>
        <maml:uri/>
    </maml:navigationLink>
</maml:relatedLinks>

Aggiunta della proprietà HelpUri a un comando

Questa sezione illustra come aggiungere la proprietà HelpUri a comandi di tipi diversi.

Aggiunta di una proprietà HelpUri a un cmdlet

Per i cmdlet scritti in C#, aggiungere un attributo HelpUri alla classe Cmdlet. Il valore dell'attributo deve essere un URI che inizia con http o https .

Il codice seguente illustra l'attributo HelpUri della classe Get-History cmdlet.

[Cmdlet(VerbsCommon.Get, "History", HelpUri = "https://go.microsoft.com/fwlink/?LinkID=001122")]

Aggiunta di una proprietà HelpUri a una funzione avanzata

Per le funzioni avanzate, aggiungere una proprietà HelpUri all'attributo CmdletBinding. Il valore della proprietà deve essere un URI che inizia con "http" o "https".

Il codice seguente illustra l'attributo HelpUri della New-Calendar funzione

function New-Calendar {
    [CmdletBinding(SupportsShouldProcess=$true,
    HelpURI="https://go.microsoft.com/fwlink/?LinkID=01122")]

Aggiunta di un attributo HelpUri a un comando CIM

Per i comandi CIM, aggiungere un attributo HelpUri all'elemento CmdletMetadata nel file CDXML. Il valore dell'attributo deve essere un URI che inizia con http o https .

Il codice seguente illustra l'attributo HelpUri del Start-Debug comando CIM

<CmdletMetadata Verb="Debug" HelpUri="https://go.microsoft.com/fwlink/?LinkID=001122"/>

Aggiunta di un attributo HelpUri a un flusso di lavoro

Per i flussi di lavoro scritti nel linguaggio PowerShell, aggiungere un oggetto . Direttiva di commento ExternalHelp per il codice del flusso di lavoro. Il valore della direttiva deve essere un URI che inizia con http o https .

Nota

La proprietà HelpUri non è supportata per i flussi di lavoro basati su XAML in PowerShell.

Il codice seguente illustra . Direttiva ExternalHelp in un file del flusso di lavoro.

# .ExternalHelp "https://go.microsoft.com/fwlink/?LinkID=138338"

Last updated on 2021-09-25