Freigeben über

Unterstützung einer Onlinehilfe

  • Artikel

Hinweis

Die manuelle Erstellung von XML-basierten Hilfen ist sehr schwierig. Mit dem PlatyPS Modul können Sie Hilfe in Markdown schreiben und dann in XML-basierte Hilfe konvertieren. Dies erleichtert das Schreiben und Verwalten von Hilfe. PlatyPS- können auch die aktualisierbaren Hilfepakete für Sie erstellen. Weitere Informationen finden Sie unter Erstellen einer XML-basierten Hilfe mithilfe von PlatyPS-.

Ab PowerShell 3.0 gibt es zwei Möglichkeiten, das Get-Help Online-Feature für PowerShell-Befehle zu unterstützen. In diesem Thema wird erläutert, wie Sie dieses Feature für verschiedene Befehlstypen implementieren.

Informationen zur Onlinehilfe

Onlinehilfe war immer ein wichtiger Bestandteil von PowerShell. Obwohl das cmdlet Get-Help Hilfethemen an der Eingabeaufforderung anzeigt, bevorzugen viele Benutzer das Lesen online, einschließlich Farbcodierung, Links und Teilen von Ideen in Communityinhalten und wiki-basierten Dokumenten. Vor dem Aufkommen der aktualisierbaren Hilfe haben Onlinehilfen die am häufigsten up-to-date-Version der Hilfedateien bereitgestellt.

Mit der Einführung der aktualisierbaren Hilfe in PowerShell 3.0 spielt die Onlinehilfe immer noch eine wichtige Rolle. Neben der flexiblen Benutzeroberfläche bietet die Onlinehilfe Hilfe für Benutzer, die keine aktualisierbare Hilfe zum Herunterladen von Hilfethemen verwenden oder nicht verwenden können.

Funktionsweise von Get-Help -Online

Damit Benutzer die Onlinehilfethemen für Befehle finden können, verfügt der Befehl Get-Help über einen Onlineparameter, der die Onlineversion des Hilfethemas für einen Befehl im Standard-Internetbrowser des Benutzers öffnet.

Mit dem folgenden Befehl wird beispielsweise das Onlinehilfethema für das Cmdlet Invoke-Command geöffnet.

Get-Help Invoke-Command -Online

Um Get-Help -Onlinezu implementieren, sucht das Cmdlet Get-Help nach einem URI (Uniform Resource Identifier) für das Hilfethema der Onlineversion an den folgenden Speicherorten.

  • Der erste Link im Abschnitt Verwandte Links Abschnitt des Hilfethemas für den Befehl. Das Hilfethema muss auf dem Computer des Benutzers installiert sein. Dieses Feature wurde in PowerShell 2.0 eingeführt.

  • Die HelpUri- Eigenschaft eines beliebigen Befehls. Auf die HelpUri-Eigenschaft kann zugegriffen werden, auch wenn das Hilfethema für den Befehl nicht auf dem Computer des Benutzers installiert ist. Dieses Feature wurde in PowerShell 3.0 eingeführt.

    Get-Help sucht im ersten Eintrag im Abschnitt Verwandte Links nach einem URI, bevor der Wert der HelpUri-Eigenschaft abgerufen wird. Wenn der Eigenschaftswert falsch ist oder geändert wurde, können Sie ihn überschreiben, indem Sie einen anderen Wert in den ersten verknüpften Link eingeben. Der erste verwandte Link funktioniert jedoch nur, wenn die Hilfethemen auf dem Computer des Benutzers installiert sind.

Sie können Get-Help -Online für jeden Befehl unterstützen, indem Sie dem ersten Eintrag im Abschnitt Verwandte Links Abschnitt des XML-basierten Hilfethemas für den Befehl einen gültigen URI hinzufügen. Diese Option ist nur in XML-basierten Hilfethemen gültig und funktioniert nur, wenn das Hilfethema auf dem Computer des Benutzers installiert ist. Wenn das Hilfethema installiert und der URI aufgefüllt wird, hat dieser Wert Vorrang vor der HelpUri- Eigenschaft des Befehls.

Zur Unterstützung dieses Features muss der URI im maml:uri-Element unter dem ersten maml:relatedLinks/maml:navigationLink Element im maml:relatedLinks-Element angezeigt werden.

Der folgende XML-Code zeigt die richtige Platzierung des URI. Der Online version: Text im maml:linkText-Element ist eine bewährte Methode, ist jedoch nicht erforderlich.

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

Hinzufügen der HelpUri-Eigenschaft zu einem Befehl

In diesem Abschnitt wird gezeigt, wie Sie die HelpUri--Eigenschaft zu Befehlen unterschiedlicher Typen hinzufügen.

Hinzufügen einer HelpUri-Eigenschaft zu einem Cmdlet

Fügen Sie für in C# geschriebene Cmdlets ein HelpUri-attribut zur Cmdlet- klasse hinzu. Der Wert des Attributs muss ein URI sein, der mit http oder httpsbeginnt.

Der folgende Code zeigt das HelpUri--Attribut der Get-History Cmdlet-Klasse.

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

Hinzufügen einer HelpUri-Eigenschaft zu einer erweiterten Funktion

Fügen Sie für erweiterte Funktionen eine HelpUri-eigenschaft zum attribut CmdletBinding hinzu. Der Wert der Eigenschaft muss ein URI sein, der mit "http" oder "https" beginnt.

Der folgende Code zeigt das attribut HelpUri der funktion New-Calendar

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

Hinzufügen eines HelpUri-Attributs zu einem Cim-Befehl

Fügen Sie für CIM-Befehle dem CmdletMetadata--Element in der CDXML-Datei ein HelpUri- attribut hinzu. Der Wert des Attributs muss ein URI sein, der mit http oder httpsbeginnt.

Der folgende Code zeigt das HelpUri-Attribut des Befehls Start-Debug CIM

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

Hinzufügen eines HelpUri-Attributs zu einem Workflow

Fügen Sie für Workflows, die in der PowerShell-Sprache geschrieben sind, dem Workflowcode ein .EXTERNALHELP Kommentarschlüsselwort hinzu. Der Wert des Schlüsselworts muss ein URI sein, der mit http oder httpsbeginnt.

Hinweis

Die HelpUri-Eigenschaft wird für XAML-basierte Workflows in PowerShell nicht unterstützt.

Der folgende Code zeigt das schlüsselwort .EXTERNALHELP in einer Workflowdatei.

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