Delen via

Help voor PowerShell-modules schrijven

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

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

Help-typen modules

Een module kan de volgende typen Help bevatten.

  • Help op basis van XML

    • Help voor cmdlets. De Help-onderwerpen waarin cmdlets in een module worden beschreven, zijn XML-bestanden die gebruikmaken van het Help-opdrachtschema
    • Help voor provider. De Help-onderwerpen waarin providers in een module worden beschreven, zijn XML-bestanden die gebruikmaken van het Help-schema van de provider.
    • Functie-Help. De Help-onderwerpen die functies in een module beschrijven, kunnen XML-bestanden zijn die gebruikmaken van het Help-opdrachtschema of op opmerkingen gebaseerde Help-onderwerpen in de functie, of het script of de scriptmodule
    • Help voor scripts. De Help-onderwerpen die scripts in een module beschrijven, kunnen XML-bestanden zijn die gebruikmaken van het Help-opdrachtschema of op opmerkingen gebaseerde Help-onderwerpen in de script- of scriptmodule.
    • De $PSHOME\Schemas\PSMaml map bevat de schemabestanden die de XML-indeling definiëren.

  • Conceptueel ('Info') helpen tekstbestanden

    U kunt een conceptueel Help-onderwerp ('about') gebruiken om de module en de bijbehorende leden te beschrijven en uit te leggen hoe de leden samen kunnen worden gebruikt om taken uit te voeren. PowerShell bevat standaard meer dan 100 van deze conceptuele Help-onderwerpen. De bestandsnaam moet de about_<name>.help.txt indeling gebruiken, zoals about_MyModule.help.txt.

    Opmerking

    De TOPIC sectiekop moet beginnen in de eerste kolom van de eerste regel van het bestand. De sectie-inhoud op de tweede regel moet overeenkomen met de bestandsnaam, zonder het .help.txt achtervoegsel. U moet de inhoud exact vier spaties laten inspringen. De derde regel moet leeg zijn. De SYNOPSIS sectiekop moet beginnen in de eerste kolom van de vierde regel. U moet de inhoud op de vijfde regel exact 4 spaties laten inspringen. Deze vereisten zijn nodig voor de Get-Help cmdlet om de inhoud correct te herkennen.

    TOPIC
    about_<subject or module name>

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

    U kunt de volgende voorbeeldsjabloon gebruiken als uitgangspunt voor het schrijven van conceptuele Help-onderwerpen. Met uitzondering van de eerste twee secties is de structuur van conceptuele Help-onderwerpen willekeurig. De resterende sectietitels kunnen alles zijn wat geschikt is voor uw inhoud.

    TOPIC
    about_<subject or module name>

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

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

    U kunt elke gewenste stijl en markeringen gebruiken, maar PowerShell ziet deze als tekst zonder opmaak en er is geen speciale weergave van de tekst in de PowerShell-console. De volgende suggesties zorgen voor de beste weergaveresultaten en leesbaarheid.

    • Gebruik UTF-8 met bomcodering om ervoor te zorgen dat speciale (multi-byte) tekens correct worden weergegeven.
    • Sectiekoppen onderstrepen of alle hoofdletters gebruiken om ze te laten opvallen. Hierdoor is de inhoud gemakkelijker te scannen.
    • Beperk de lengte van elke regel tot 80 tekens.
    • Codeblokken en voorbeelduitvoer laten inspringen om deze te scheiden van de omringende proza.

Plaatsing van module-Help

De Get-Help cmdlet zoekt naar module-Help-onderwerpbestanden in taalspecifieke submappen van de modulemap.

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

<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

Opmerking

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

Help voor module downloaden

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

U kunt help-onderwerpen voor modules in verschillende talen opgeven. De Get-Help cmdlet geeft automatisch module Help-onderwerpen weer in de taal die is opgegeven voor de huidige gebruiker in het item Landinstellingen in het Configuratiescherm. In Windows Vista en latere versies van Windows zoekt Get-Help u naar de Help-onderwerpen in taalspecifieke submappen van de modulemap in overeenstemming met de taalterugvalstandaarden die zijn ingesteld voor Windows.

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

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, Get-Help wordt automatisch gegenereerde Help weergegeven. De automatisch gegenereerde Help bevat de syntaxis van de opdracht, parameters en invoer- en uitvoertypen, maar bevat geen beschrijvingen. De automatisch gegenereerde Help bevat tekst waarmee de gebruiker de cmdlet probeert te gebruiken Update-Help om help voor de opdracht van internet of een bestandsshare te downloaden. U wordt ook aangeraden de parameter Online van de Get-Help cmdlet te gebruiken om de onlineversie van het Help-onderwerp op te halen.

Ondersteuning voor ondersteuning voor ondersteuning voor help-updatable

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

Gebruikers achter firewalls en gebruikers zonder internettoegang kunnen ook gebruikmaken van Updatable Help. Beheerders met internettoegang gebruiken de Save-Help cmdlet om de nieuwste Help-bestanden naar een bestandsshare te downloaden en te installeren. Vervolgens gebruiken gebruikers de parameter Path van de Update-Help cmdlet om de nieuwste Help-bestanden op te halen uit de bestandsshare.

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

Zie Ondersteunende Help-voor meer informatie over Help-ondersteuning die kan worden bijgewerkt.

Ondersteuning voor online-Help

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

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

Vanaf PowerShell 3.0 kunt u gebruikers helpen bij het vinden van de onlineversie van cmdlets en functie-Help-onderwerpen door het Kenmerk HelpUri te definiëren in 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

  • Last updated on