Help-bestanden een naam geven

Notitie

Handmatig schrijven van hulp op basis van XML is erg moeilijk. Met de module PlatyPS kunt u hulp schrijven in Markdown en deze vervolgens converteren naar op XML gebaseerde help. Hierdoor is het veel eenvoudiger om hulp te schrijven en te onderhouden. PlatyPS- kunt ook de Updateable Help-pakketten voor u maken. Zie Hulp op basis van XML maken met PlatyPS-voor meer informatie.

In dit onderwerp wordt uitgelegd hoe u een op XML gebaseerd Help-bestand een naam kunt geven, zodat de cmdlet Get-Help- deze kan vinden. De naamvereisten verschillen voor elk opdrachttype.

Help-bestanden voor cmdlets

Het Help-bestand voor een C#-cmdlet moet een naam hebben voor de assembly waarin de cmdlet is gedefinieerd. Gebruik de volgende bestandsnaamindeling:

<AssemblyName>.dll-help.xml

De indeling van de assemblynaam is vereist, zelfs wanneer de assembly een geneste module is.

De cmdlet Get-WinEvent wordt bijvoorbeeld gedefinieerd in de Microsoft.PowerShell.Diagnostics.dll assembly. De cmdlet Get-Help zoekt alleen naar een Help-onderwerp voor de Get-WinEvent-cmdlet in het Microsoft.PowerShell.Diagnostics.dll-help.xml-bestand in de modulemap.

Help-bestanden van provider

Het Help-bestand voor een PowerShell-provider moet een naam hebben voor de assembly waarin de provider is gedefinieerd. Gebruik de volgende bestandsnaamindeling:

<AssemblyName>.dll-help.xml

De indeling van de assemblynaam is vereist, zelfs wanneer de assembly een geneste module is.

De certificaatprovider wordt bijvoorbeeld gedefinieerd in de Microsoft.PowerShell.Security.dll assembly. De cmdlet Get-Help zoekt alleen naar een Help-onderwerp voor de certificaatprovider in het Microsoft.PowerShell.Security.dll-help.xml-bestand in de modulemap.

Help-bestanden voor functies

Functies kunnen worden gedocumenteerd met behulp van hulp op basis van opmerkingen of gedocumenteerd in een XML-helpbestand. Wanneer de functie wordt gedocumenteerd in een XML-bestand, moet de functie een .EXTERNALHELP trefwoord voor opmerkingen hebben waarmee de functie wordt gekoppeld aan het XML-bestand. Anders kan de Get-Help cmdlet het Help-bestand niet vinden.

Er zijn geen technische vereisten voor de naam van een functie-Help-bestand. Het is echter een best practice om het Help-bestand een naam te geven voor de scriptmodule waarin de functie is gedefinieerd. De volgende functie wordt bijvoorbeeld gedefinieerd in het bestand MyModule.psm1.

#.EXTERNALHELP MyModule.psm1-help.xml
function Test-Function { ... }

Vanaf PowerShell 5.0 kunnen functies die door een module worden geëxporteerd, worden gedocumenteerd in een Help-bestand met de naam van de module. U hoeft geen trefwoord voor opmerkingen te gebruiken .EXTERNALHELP . Als de Test-Function functie bijvoorbeeld door de MyModule module wordt geëxporteerd, kunt u het Help-bestand MyModule-help.xmleen naam opgeven. De Get-Help cmdlet zoekt naar help voor de Test-Function functie in het MyModule-help.xml bestand in de modulemap.

Help-bestanden voor CIM-opdrachten

Het Help-bestand voor een CIM-opdracht moet een naam hebben voor het CDXML-bestand waarin de CIM-opdracht is gedefinieerd. Gebruik de volgende bestandsnaamindeling:

<FileName>.cdxml-help.xml

CIM-opdrachten worden gedefinieerd in CDXML-bestanden die kunnen worden opgenomen in modules als geneste modules. Wanneer de CIM-opdracht als een functie in de sessie wordt geïmporteerd, voegt PowerShell een .EXTERNALHELP trefwoord voor opmerkingen toe aan de functiedefinitie die de functie koppelt aan een XML-Help-bestand met de naam voor het CDXML-bestand waarin de CIM-opdracht is gedefinieerd.

Help-bestanden voor scriptwerkstromen

Scriptwerkstromen die zijn opgenomen in modules, kunnen worden gedocumenteerd in HELP-bestanden op basis van XML. Er zijn geen technische vereisten voor de naam van het Help-bestand. Het is echter een best practice om het Help-bestand een naam te geven voor de scriptmodule waarin de scriptwerkstroom is gedefinieerd. Voorbeeld:

<ScriptModule>.psm1-help.xml

In tegenstelling tot andere scriptopdrachten is voor scriptwerkstromen geen .EXTERNALHELP trefwoord voor opmerkingen vereist om deze te koppelen aan een Help-bestand. In plaats daarvan zoekt PowerShell in de gebruikersinterface-cultuurspecifieke submappen van de modulemap naar OP XML gebaseerde Help-bestanden en zoekt naar help voor de scriptwerkstroom in alle bestanden. .EXTERNALHELP trefwoord voor opmerkingen wordt genegeerd.

Omdat het trefwoord voor .EXTERNALHELP opmerking wordt genegeerd, kan de Get-Help cmdlet alleen hulp vinden voor scriptwerkstromen wanneer deze zijn opgenomen in modules.