Feedback

Help voor PowerShell-modules schrijven

  • Artikel
  • 5 minuten om te lezen

PowerShell-modules kunnen Help-onderwerpen bevatten over de module en over de moduleleden, zoals cmdlets, providers, functies en scripts. De cmdlet geeft de Help-onderwerpen van de module weer in dezelfde indeling als de Help voor andere PowerShell-items en gebruikers gebruiken standaardopdrachten om de Get-Help Get-Help Help-onderwerpen op te halen.

In dit document wordt de indeling en de juiste plaatsing van Help-onderwerpen van de module uitgelegd en worden richtlijnen voor Help-inhoud van de module uitgelegd.

Typen Module-Help

Een module kan de volgende typen Help bevatten.

  • Cmdlet Help. De Help-onderwerpen waarin cmdlets in een module worden beschreven, zijn XML-bestanden die gebruikmaken van het Help-schema voor opdrachten

  • Provider Help. De Help-onderwerpen waarin providers in een module worden beschreven, zijn XML-bestanden die gebruikmaken van het Help-schema van de provider.

  • Function Help. De Help-onderwerpen waarin functies in een module worden beschreven, kunnen XML-bestanden zijn die gebruikmaken van het Help-schema voor opdrachten of Help-onderwerpen op basis van opmerkingen in de functie, of de script- of scriptmodule

  • Script Help. De Help-onderwerpen waarin scripts in een module worden beschreven, kunnen XML-bestanden zijn die gebruikmaken van het Help-schema voor opdrachten of Help-onderwerpen op basis van opmerkingen in de script- of scriptmodule.

  • Conceptueel ('Over') Help. U kunt een conceptueel Help-onderwerp (over) gebruiken om de module en de leden ervan te beschrijven en uit te leggen hoe de leden samen kunnen worden gebruikt om taken uit te voeren. Conceptuele Help-onderwerpen zijn tekstbestanden met Unicode-codering (UTF-8). De bestandsnaam moet de indeling about_<name>.help.txt gebruiken, zoals about_MyModule.help.txt . PowerShell bevat standaard meer dan 100 van deze conceptuele Onderwerpen over Help en zijn opgemaakt zoals in het volgende voorbeeld.

    TOPIC
    about_<subject or module name>

SHORT DESCRIPTION
    A short, one-line description of the topic contents.

LONG DESCRIPTION
    A detailed, full description of the subject or purpose of the module.

EXAMPLES
    Examples of how to use the module or how the subject feature works in practice.

KEYWORDS
    Terms or titles on which you might expect your users to search for the information in this topic.

SEE ALSO
    Text-only references for further reading. Hyperlinks cannot work in the PowerShell console.

Alle schemabestanden vindt u in de $PSHOME\Schemas\PSMaml map .

Plaatsing van module-Help

De Get-Help cmdlet zoekt naar Help-onderwerpbestanden van de module in taalspecifieke subdirectory's van de modulemap.

In het volgende mapstructuurdiagram ziet u bijvoorbeeld de locatie van de Help-onderwerpen voor de module SampleModule.

<ModulePath>
         \SampleModule
               \<en-US>
                     \about_SampleModule.help.txt
                     \SampleModule.dll-help.xml
                     \SampleNestedModule.dll-help.xml
               \<fr-FR>
                     \about_SampleModule.help.txt
                     \SampleModule.dll-help.xml
                     \SampleNestedModule.dll-help.xml

Notitie

In het voorbeeld vertegenwoordigt de tijdelijke aanduiding een van de paden in de omgevingsvariabele, zoals , of een aangepast pad dat <ModulePath> door de gebruiker wordt PSModulePath $HOME\Documents\Modules $PSHOME\Modules opgegeven.

Help voor modules verkrijgen

Wanneer een gebruiker een module in een sessie importeert, worden de Help-onderwerpen voor die module samen met de module in de sessie geïmporteerd. U kunt de Help-onderwerpbestanden in de waarde van de fileList-sleutel in het modulemanifest bekijken, maar Help-onderwerpen worden niet beïnvloed door de Export-ModuleMember cmdlet .

U kunt help-onderwerpen voor de module in verschillende talen bieden. De cmdlet geeft automatisch helponderwerpen van de module weer in de taal die is opgegeven voor de huidige gebruiker in het item Regionale en Get-Help taalopties in Configuratiescherm. In Windows Vista en latere versies van Windows zoekt u naar de Help-onderwerpen in taalspecifieke subdirectory's van de modulemap in overeenstemming met de taalterugvalstandaarden die zijn vastgelegd voor Get-Help Windows.

Vanaf PowerShell 3.0 activeert het uitvoeren van een opdracht voor een cmdlet of functie het Get-Help automatisch importeren van de module. De Get-Help cmdlet geeft onmiddellijk de inhoud weer van de Help-onderwerpen in de module.

Als de module geen Help-onderwerpen bevat en er geen Help-onderwerpen zijn voor de opdrachten in de module op de computer van de gebruiker, wordt automatisch Get-Help gegenereerde Help weergegeven. De automatisch gegenereerde Help bevat de opdrachtsyntaxis, parameters en invoer- en uitvoertypen, maar bevat geen beschrijvingen. De automatisch gegenereerde Help bevat tekst die de gebruiker opdracht om te proberen de cmdlet te gebruiken om Help voor de opdracht te downloaden van internet of een Update-Help bestands share. U wordt ook aangeraden de onlineparameter van de cmdlet te gebruiken om de onlineversie van het Get-Help Help-onderwerp op te halen.

Ondersteunende help die kan worden bijgewerkt

Gebruikers van PowerShell 3.0 en latere versies van PowerShell kunnen bijgewerkte Help-bestanden voor een module downloaden en installeren via internet of via een lokale bestands share. De Update-Help Save-Help cmdlets en verbergen de beheerdetails voor de gebruiker. Gebruikers voeren de cmdlet uit en gebruiken vervolgens de cmdlet om de nieuwste Help-bestanden voor de module te lezen via Update-Help Get-Help de PowerShell-opdrachtprompt. Gebruikers hoeven niet opnieuw te Windows of PowerShell.

Gebruikers achter firewalls en gebruikers zonder internettoegang kunnen ook Help gebruiken die kan worden bijwerkbaar. Beheerders met internettoegang gebruiken de cmdlet om de nieuwste Help-bestanden te downloaden en Save-Help installeren op een bestands share. Vervolgens gebruiken gebruikers de parameter Path van de cmdlet om de nieuwste Help-bestanden op te halen Update-Help uit de bestands share.

Auteurs van modules kunnen Help-bestanden opnemen in de module en help-informatie van updatable gebruiken om de Help-bestanden bij te werken, of help-bestanden weglaten uit de module en Help gebruiken om ze zowel te installeren als bij te werken.

Zie Ondersteunende Help die kan worden bijwerkbaar voor meer informatie over Help die kan worden updatable.

Ondersteunende online help

Gebruikers die bijgewerkte Help-bestanden niet kunnen of installeren op hun computers, zijn vaak afhankelijk van de onlineversie van de Help-onderwerpen van de module. Met de parameter Online van de cmdlet wordt de onlineversie van een cmdlet of het Help-onderwerp voor geavanceerde functies voor de gebruiker geopend in Get-Help de standaardinternetbrowser.

De cmdlet gebruikt de waarde van de eigenschap HelpUri van de cmdlet of functie om de onlineversie van het Get-Help Help-onderwerp te vinden.

Vanaf PowerShell 3.0 kunt u gebruikers helpen de onlineversie van cmdlet en functie helponderwerpen te vinden door het kenmerk HelpUri te definiëren voor de cmdlet-klasse of de eigenschap HelpUri van het kenmerk CmdletBinding. De waarde van het kenmerk is de waarde van de eigenschap HelpUri van de cmdlet of functie.

Zie Ondersteunende online help voor meer informatie.

Zie ook

Een PowerShell-module schrijven

Ondersteunende help die kan worden bijgewerkt

Ondersteunende online help