Naamgeving van Help-bestanden

  • Artikel

In dit onderwerp wordt uitgelegd hoe u een helpbestand op basis van XML kunt noemen, zodat de cmdlet Get-Help het kan vinden. De naamvereisten verschillen voor elk opdrachttype.

Help-bestanden voor cmdlet

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

<AssemblyName>.dll-help.xml

De assemblynaamindeling 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 zoekt alleen in het bestand in de modulemap naar een Help-onderwerp voor de Get-Help Get-WinEvent Microsoft.PowerShell.Diagnostics.dll-help.xml cmdlet.

Help-bestanden voor provider

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

<AssemblyName>.dll-help.xml

De assemblynaamindeling is vereist, zelfs wanneer de assembly een geneste module is.

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

Help-bestanden voor functies

Functies kunnen worden gedocumenteerd met behulp van help op basis van opmerkingen of worden beschreven in een XML Help-bestand. Wanneer de functie is gedocumenteerd in een XML-bestand, moet de functie een trefwoord opmerking hebben dat de functie koppelt .ExternalHelp 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 Help-bestand voor functies. Het is echter best practice het helpbestand een naam te geven voor de scriptmodule waarin de functie is gedefinieerd. De volgende functie wordt bijvoorbeeld gedefinieerd in het MyModule.psm1 bestand .

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

Help-bestanden voor CIM-opdrachten

Het Help-bestand voor een CIM-opdracht moet de naam hebben van 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 als geneste modules in modules kunnen worden opgenomen. Wanneer de CIM-opdracht als een functie in de sessie wordt geïmporteerd, voegt PowerShell een trefwoord opmerking toe aan de functiedefinitie die de functie koppelt aan een XML-helpbestand met de naam voor het CDXML-bestand waarin de .ExternalHelp CIM-opdracht is gedefinieerd.

Help-bestanden voor scriptwerkstroom

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. Een van de best practice is echter om het Help-bestand een naam te geven voor de scriptmodule waarin de scriptwerkstroom is gedefinieerd. Bijvoorbeeld:

<ScriptModule>.psm1-help.xml

In tegenstelling tot andere scriptopdrachten is voor scriptwerkstromen geen trefwoord voor opmerkingen vereist om .ExternalHelp ze te koppelen aan een Help-bestand. In plaats daarvan zoekt PowerShell in de UI-Culture-specifieke subdirectory's van de modulemap naar HELP-bestanden op basis van XML en zoekt naar hulp voor de scriptwerkstroom in alle bestanden. .ExternalHelp trefwoord opmerking worden genegeerd.

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