Obsługa pomocy online

Uwaga

Ręczne tworzenie pomocy opartej na języku XML jest bardzo trudne. Moduł PlatyPS umożliwia napisanie pomocy w języku Markdown, a następnie przekonwertowanie go na pomoc opartą na języku XML. Ułatwia to pisanie i konserwację pomocy. platyPS można również utworzyć pakiety Pomocy z możliwością aktualizacji. Aby uzyskać więcej informacji, zobacz Create XML-based help using PlatyPS.

Począwszy od programu PowerShell 3.0, istnieją dwa sposoby obsługi funkcji Get-Help Online dla poleceń programu PowerShell. W tym temacie wyjaśniono, jak zaimplementować tę funkcję dla różnych typów poleceń.

Informacje o pomocy online

Pomoc online zawsze była istotną częścią programu PowerShell. Mimo że polecenie cmdlet Get-Help wyświetla tematy pomocy w wierszu polecenia, wielu użytkowników preferuje doświadczenie czytania w trybie online, w tym kodowania kolorami, hiperlinków i udostępniania pomysłów w dokumentach dotyczących zawartości społeczności i dokumentów opartych na witrynie typu wiki. Co najważniejsze, przed pojawieniem się funkcji Updatable Help, pomoc online dostarczyła najbardziej up-to- aktualna wersja plików pomocy.

Wraz z pojawieniem się dodatku Updatable Help w programie PowerShell 3.0 pomoc online nadal odgrywa istotną rolę. Oprócz elastycznego środowiska użytkownika pomoc online zapewnia pomoc użytkownikom, którzy nie mogą korzystać z aktualizowalnej pomocy, aby pobrać tematy pomocy.

Jak działa Get-Help -Online

Aby ułatwić użytkownikom znajdowanie tematów pomocy online dla poleceń, polecenie Get-Help ma parametr Online, który otwiera wersję online tematu pomocy dla polecenia w domyślnej przeglądarce internetowej użytkownika.

Na przykład następujące polecenie otwiera temat pomocy online dla polecenia cmdlet Invoke-Command.

Get-Help Invoke-Command -Online

Aby zaimplementować Get-Help -Online, polecenie cmdlet Get-Help szuka identyfikatora URI (Uniform Resource Identifier) dla tematu pomocy dotyczącej wersji online w następujących lokalizacjach.

• Pierwszy link w sekcji linki powiązane tematu pomocy dla polecenia. Temat pomocy musi być zainstalowany na komputerze użytkownika. Ta funkcja została wprowadzona w programie PowerShell 2.0.

• Właściwość HelpUri dowolnego polecenia. Właściwość HelpUri jest dostępna nawet wtedy, gdy temat pomocy dla polecenia nie jest zainstalowany na komputerze użytkownika. Ta funkcja została wprowadzona w programie PowerShell 3.0.

  Get-Help szuka identyfikatora URI w pierwszym wpisie w sekcji Related Links przed uzyskaniem wartości właściwości HelpUri. Jeśli wartość właściwości jest niepoprawna lub została zmieniona, możesz ją zastąpić, wprowadzając inną wartość w pierwszym powiązanym linku. Jednak pierwszy powiązany link działa tylko wtedy, gdy tematy pomocy są zainstalowane na komputerze użytkownika.

Dodawanie identyfikatora URI do pierwszego powiązanego linku tematu pomocy dotyczącej poleceń

Można obsługiwać Get-Help -Online dla dowolnego polecenia, dodając prawidłowy identyfikator URI do pierwszego wpisu w sekcji Related Links w temacie pomocy opartej na xml polecenia. Ta opcja jest prawidłowa tylko w tematach pomocy opartych na formacie XML i działa tylko wtedy, gdy temat pomocy jest zainstalowany na komputerze użytkownika. Po zainstalowaniu tematu pomocy i wypełnieniu identyfikatora URI ta wartość ma pierwszeństwo przed właściwością HelpUri polecenia.

Aby obsługiwać tę funkcję, identyfikator URI musi pojawić się w elemecie maml:uri w pierwszym elemenie maml:relatedLinks/maml:navigationLink w elemecie maml:relatedLinks.

Poniższy kod XML przedstawia prawidłowe rozmieszczenie identyfikatora URI. Tekst Online version: w elemecie maml:linkText jest najlepszym rozwiązaniem, ale nie jest wymagany.

<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>

Dodawanie właściwości HelpUri do polecenia

W tej sekcji przedstawiono sposób dodawania właściwości HelpUri do poleceń różnych typów.

Dodawanie właściwości HelpUri do polecenia cmdlet

W przypadku poleceń cmdlet napisanych w języku C#dodaj atrybut HelpUri do klasy Cmdlet. Wartość atrybutu musi być identyfikatorem URI rozpoczynającym się od http lub https.

Poniższy kod przedstawia atrybut HelpUri klasy polecenia cmdlet Get-History.

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

Dodawanie właściwości HelpUri do funkcji zaawansowanej

W przypadku funkcji zaawansowanych dodaj właściwość HelpUri do atrybutu CmdletBinding. Wartość właściwości musi być identyfikatorem URI rozpoczynającym się od ciągu "http" lub "https".

Poniższy kod przedstawia atrybut HelpUri funkcji New-Calendar

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

Dodawanie atrybutu HelpUri do polecenia cim

W przypadku poleceń ciM dodaj atrybut HelpUri do elementu CmdletMetadata w pliku CDXML. Wartość atrybutu musi być identyfikatorem URI rozpoczynającym się od http lub https.

Poniższy kod przedstawia atrybut HelpUri polecenia ciM Start-Debug

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

Dodawanie atrybutu HelpUri do przepływu pracy

W przypadku przepływów pracy napisanych w języku programu PowerShell dodaj słowo kluczowe komentarza .EXTERNALHELP do kodu przepływu pracy. Wartość słowa kluczowego musi być identyfikatorem URI rozpoczynającym się od http lub https.

Uwaga

Właściwość HelpUri nie jest obsługiwana w przypadku przepływów pracy opartych na języku XAML w programie PowerShell.

Poniższy kod przedstawia słowo kluczowe .EXTERNALHELP w pliku przepływu pracy.

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