Parametergegevens toevoegen

Artikel
12/09/2021
5 minuten om te lezen

In deze sectie wordt beschreven hoe u inhoud toevoegt die wordt weergegeven in de sectie PARAMETERS van het Help-onderwerp van de cmdlet. In de sectie PARAMETERS van het Help-onderwerp worden alle parameters van de cmdlet vermeld en vindt u een gedetailleerde beschrijving van elke parameter.

De inhoud van de sectie PARAMETERS moet consistent zijn met de inhoud van de syntaxissectie van het Help-onderwerp. Het is de verantwoordelijkheid van de Help-auteur om ervoor te zorgen dat het knooppunt Syntaxis en Parameters vergelijkbare XML-elementen bevatten.

Notitie

Voor een volledige weergave van een Help-bestand opent u een van dll-Help.xml de bestanden in de PowerShell-installatiemap. Het bestand bevat Microsoft.PowerShell.Commands.Management.dll-Help.xml bijvoorbeeld inhoud voor verschillende PowerShell-cmdlets.

Parameters toevoegen

Open het Help-bestand van de cmdlet en zoek het knooppunt Opdracht voor de cmdlet die u documenteert. Als u een nieuwe cmdlet toevoegt, moet u een nieuw opdracht-knooppunt maken. Uw Help-bestand bevat een opdracht-knooppunt voor elke cmdlet die u Help-inhoud geeft. Hier is een voorbeeld van een leeg opdracht-knooppunt.
```
<command:command>
</command:command>
```
Zoek in het knooppunt Opdracht het knooppunt Beschrijving en voeg een knooppunt Parameters toe, zoals hieronder wordt weergegeven. Er is slechts één knooppunt Parameters toegestaan en dit moet onmiddellijk het knooppunt Syntaxis volgen.
```
<command:command>
  <command:details></command:details>
  <maml:description></maml:description>
  <command:syntax></command:syntax>
  <command:parameters>
  </command:parameters>
</command:command>
```
Voeg in het knooppunt Parameters een parameter-knooppunt toe voor elke parameter van de cmdlet, zoals hieronder wordt weergegeven.

In dit voorbeeld wordt een parameter-knooppunt toegevoegd voor drie parameters.
```
<command:parameters>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
</command:parameters>
```
Omdat dit dezelfde XML-tags zijn die worden gebruikt in het knooppunt Syntaxis en omdat de parameters die hier worden opgegeven, moeten overeenkomen met de parameters die zijn opgegeven door het knooppunt Syntaxis, kunt u de parameterknooppunten kopiëren van het knooppunt Syntaxis en deze in het knooppunt Parameters plakken. Zorg er echter voor dat u slechts één exemplaar van een parameter-knooppunt kopieert, zelfs als de parameter is opgegeven in meerdere parametersets in de syntaxis.

Stel voor elk parameter-knooppunt de kenmerkwaarden in die de kenmerken van elke parameter definiëren. Deze kenmerken omvatten het volgende: required, globbing, pipelineinput en position.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
  </command:parameter>
  <command:parameter required="false" globbing="false"
           pipelineInput="false" position="named">
  </command:parameter>
  <command:parameter required="false" globbing="false"
           pipelineInput="false" position="named" ></command:parameter>
</command:parameters>

Voeg voor elk parameter-knooppunt de naam van de parameter toe. Hier is een voorbeeld van de parameternaam die is toegevoegd aan het knooppunt Parameter.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
  </command:parameter>
</command:parameters>

Voeg voor elk parameter-knooppunt de beschrijving van de parameter toe. Hier is een voorbeeld van de parameterbeschrijving die is toegevoegd aan het knooppunt Parameter.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
  </command:parameter>
</command:parameters>

Voeg voor elk parameter-knooppunt het .NET-type van de parameter toe. Het parametertype wordt samen met de parameternaam weergegeven.

Hier is een voorbeeld van de parameter .NET-type toegevoegd aan het knooppunt Parameter.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
    <dev:type> Add .NET Framework type... </dev:type>
  </command:parameter>
</command:parameters>

Voeg voor elk parameter-knooppunt de standaardwaarde van de parameter toe. De volgende zin wordt toegevoegd aan de beschrijving van de parameter wanneer de inhoud wordt weergegeven: DefaultValue is de standaardwaarde.

Hier is een voorbeeld van de standaardwaarde van de parameter wordt toegevoegd aan het knooppunt Parameter.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
    <dev:type> Add .NET Framework type... </dev:type>
    <dev:defaultvalue> Add default value...</dev:defaultvalue>
  </command:parameter>
</command:parameters>

Voeg voor elke parameter met meerdere waarden een possibleValues-knooppunt toe.

Hier is een voorbeeld van het van een possibleValues-knooppunt dat twee mogelijke waarden voor de parameter definieert

<dev:possibleValues>
  <dev:possibleValue>
    <dev:value>Unknown</dev:value>
    <maml:description>
      <maml:para></maml:para>
    </maml:description>
  </dev:possibleValue>
  <dev:possibleValue>
    <dev:value>String</dev:value>
    <maml:description>
      <maml:para></maml:para>
    </maml:description>
  </dev:possibleValue>
</dev:possibleValues>

Hier zijn enkele dingen die u moet onthouden bij het toevoegen van parameters.

De kenmerken van de parameter worden niet weergegeven in alle weergaven van het Help-onderwerp van de cmdlet. Ze worden echter weergegeven in een tabel die de parameterbeschrijving volgt wanneer de gebruiker om de weergave Full ( Get-Help <cmdletname> -Full ) of Parameter ( ) van het Get-Help <cmdletname> -Parameter onderwerp vraagt.
De beschrijving van de parameter is een van de belangrijkste onderdelen van een Help-onderwerp voor cmdlet. De beschrijving moet kort en grondig zijn. Vergeet ook niet dat als de parameterbeschrijving te lang wordt, bijvoorbeeld wanneer twee parameters met elkaar communiceren, u meer inhoud kunt toevoegen in de sectie NOTITIES van het Help-onderwerp van de cmdlet.

De beschrijving van de parameter bevat twee soorten informatie.
Wat de cmdlet doet wanneer de parameter wordt gebruikt.
Wat een juridische waarde is voor de parameter .
Omdat de parameterwaarden worden uitgedrukt als .NET-objecten, hebben gebruikers meer informatie over deze waarden nodig dan in een traditionele Help-opdrachtregel. Vertel de gebruiker welk type gegevens de parameter moet accepteren en neem voorbeelden op.

De standaardwaarde van de parameter is de waarde die wordt gebruikt als de parameter niet is opgegeven op de opdrachtregel. Houd er rekening mee dat de standaardwaarde optioneel is en niet nodig is voor bepaalde parameters, zoals vereiste parameters. U moet echter een standaardwaarde opgeven voor de meeste optionele parameters.

De standaardwaarde helpt de gebruiker om inzicht te krijgen in het effect van het niet gebruiken van de parameter . Beschrijf de standaardwaarde heel specifiek, zoals de 'Huidige map' of 'PowerShell-installatiemap ( $PSHOME )' voor een optioneel pad. U kunt ook een zin schrijven die de standaardwaarde beschrijft, zoals de volgende zin die wordt gebruikt voor de parameter PassThru: "Als PassThru niet is opgegeven, geeft de cmdlet geen objecten door in de pijplijn." Omdat de waarde wordt weergegeven tegenover de veldnaam Standaardwaarde, hoeft u de term 'standaardwaarde' niet op te nemen in de vermelding.

De standaardwaarde van de parameter wordt niet weergegeven in alle weergaven van het Help-onderwerp van de cmdlet. Deze wordt echter weergegeven in een tabel (samen met de parameterkenmerken) na de beschrijving van de parameter wanneer de gebruiker vraagt om de weergave Full ( Get-Help <cmdletname> -Full ) of Parameter ( ) van Get-Help <cmdletname> -Parameter het onderwerp.

De volgende XML toont een paar <dev:defaultValue> tags die zijn toegevoegd aan het <command:parameter> knooppunt. U ziet dat de standaardwaarde direct na de afsluitende tag (wanneer de parameterwaarde is opgegeven) of de afsluitende tag van de </command:parameterValue> </maml:description> parameterbeschrijving volgt. Naam.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
  </command:parameter>
</command:parameters>

Waarden toevoegen voor geïndeereerde typen

Als de parameter meerdere waarden of waarden van een geïndeereerd type heeft, kunt u een optioneel <dev:possibleValues> knooppunt gebruiken. Met dit knooppunt kunt u een naam en beschrijving opgeven voor meerdere waarden.

De beschrijvingen van de geïndeereerde waarden worden niet weergegeven in een van de standaard Help-weergaven die door de cmdlet worden weergegeven, maar andere Help-viewers kunnen deze inhoud in hun weergaven Get-Help weergeven.

De volgende XML toont een <dev:possibleValues> knooppunt met twee opgegeven waarden.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
    <dev:possibleValues>
      <dev:possibleValue>
        <dev:value> Value 1 </dev:value>
        <maml:description>
          <maml:para> Description 1 </maml:para>
        </maml:description>
      <dev:possibleValue>
      <dev:possibleValue>
        <dev:value> Value 2 </dev:value>
        <maml:description>
          <maml:para> Description 2 </maml:para>
        </maml:description>
      <dev:possibleValue>
    </dev:possibleValues>
  </command:parameter>
</command:parameters>

Parametergegevens toevoegen

Parameters toevoegen

Feedback