Syntaxis toevoegen aan een Help-onderwerp voor cmdlets

Artikel
09/26/2021
6 minuten om te lezen

Voordat u begint met het codeeren van de XML voor het syntaxisdiagram in het Help-bestand van de cmdlet, leest u deze sectie voor een duidelijk beeld van het soort gegevens dat u moet opgeven, zoals de parameterkenmerken en hoe die gegevens worden weergegeven in het syntaxisdiagram.

Parameterkenmerken

Vereist
- Indien waar, moet de parameter worden weergegeven in alle opdrachten die gebruikmaken van de parameterset.
- Indien onwaar, is de parameter optioneel in alle opdrachten die gebruikmaken van de parameterset.
Positie
- Als u een naam opgeeft, is de parameternaam vereist.
- Indien positioneel, is de parameternaam optioneel. Wanneer deze wordt weggelaten, moet de parameterwaarde zich in de opgegeven positie in de opdracht. Als de waarde bijvoorbeeld position="1" is, moet de parameterwaarde de eerste of enige naamloze parameterwaarde in de opdracht zijn.
Pijplijninvoer
- Indien waar (ByValue), kunt u invoer doorspijpen naar de parameter . De invoer is gekoppeld aan de parameter ('gebonden aan'), zelfs als de naam van de eigenschap en het objecttype niet overeenkomen met het verwachte type. De PowerShell-parameterbindingsonderdelen proberen de invoer te converteren naar het juiste type en mislukken de opdracht alleen wanneer het type niet kan worden geconverteerd. Er kan slechts één parameter in een parameterset worden gekoppeld op waarde.
- Indien waar (ByPropertyName), kunt u invoer doorspijpen naar de parameter . De invoer is echter alleen gekoppeld aan de parameter wanneer de parameternaam overeenkomt met de naam van een eigenschap van het invoerobject. Als de parameternaam bijvoorbeeld is, worden objecten die worden doorspijpt naar de cmdlet alleen aan die parameter gekoppeld wanneer het object een eigenschap met Path de naam path heeft.
- Als true (ByValue, ByPropertyName) is, kunt u invoer doorspijpen naar de parameter op eigenschapsnaam of op waarde. Er kan slechts één parameter in een parameterset worden gekoppeld op waarde.
- Indien onwaar, kunt u geen invoer doorspijpen naar deze parameter.
Globbing
- Indien waar, kan de tekst die de gebruiker voor de parameterwaarde opgeeft jokertekens bevatten.
- Indien onwaar, kan de tekst die de gebruiker voor de parameterwaarde opgeeft geen jokertekens bevatten.

Parameterwaardekenmerken

Vereist
- Indien waar, moet de opgegeven waarde worden gebruikt wanneer u de parameter in een opdracht.
- Indien onwaar, is de parameterwaarde optioneel. Normaal gesproken is een waarde alleen optioneel als het een van de geldige waarden voor een parameter is, zoals in een geïndeereerd type.

Het kenmerk Vereist van een parameterwaarde verschilt van het kenmerk Vereist van een parameter.

Het vereiste kenmerk van een parameter geeft aan of de parameter (en de waarde ervan) moet worden opgenomen bij het aanroepen van de cmdlet. Het vereiste kenmerk van een parameterwaarde wordt daarentegen alleen gebruikt wanneer de parameter is opgenomen in de opdracht . Hiermee wordt aangegeven of die specifieke waarde moet worden gebruikt met de parameter .

Parameterwaarden die tijdelijke aanduidingen zijn, zijn doorgaans vereist en parameterwaarden die letterlijk zijn, zijn niet vereist, omdat ze een van de verschillende waarden zijn die kunnen worden gebruikt met de parameter .

Informatie over het verzamelen van syntaxis

Begin met de naam van de cmdlet.
```
SYNTAX
    Get-Tech
```
Alle parameters van de cmdlet. Typ een koppelteken ( - ) (ASCII 45) vóór elke parameternaam. Scheid de parameters in parametersets (sommige cmdlets hebben mogelijk slechts één parameterset). In dit voorbeeld heeft Get-Tech cmdlet twee parametersets.
```
SYNTAX
    Get-Tech -name -type
    Get-Tech -ID -list -type
```
Start elke parameterset met de naam van de cmdlet.

Vermeld eerst de standaardparameterset. De standaardparameter wordt opgegeven door de cmdlet-klasse.

Vermeld voor elke parameterset eerst de unieke parameter, tenzij er positionele parameters zijn die eerst moeten worden weergegeven. In het vorige voorbeeld zijn de parameters Naam en Id unieke parameters voor de twee parametersets (elke parameterset moet één parameter hebben die uniek is voor die parameterset). Hierdoor kunnen gebruikers gemakkelijker bepalen welke parameter ze nodig hebben voor de parameterset.

Vermeld de parameters in de volgorde waarin ze moeten worden weergegeven in de opdracht . Als de volgorde niet van belang is, vermeldt u gerelateerde parameters samen of vermeldt u eerst de meest gebruikte parameters.

Zorg ervoor dat u de parameters WhatIf en Confirm vermeldt als de cmdlet ShouldProcess ondersteunt.

Vermeld de algemene parameters (zoals Uitgebreid, Foutopsporing en ErrorAction) niet in het syntaxisdiagram. De Get-Help cmdlet voegt die informatie voor u toe wanneer het Help-onderwerp wordt weergegeven.
Voeg de parameterwaarden toe. In PowerShell worden parameterwaarden vertegenwoordigd door hun .NET-type. De typenaam kan echter worden afgekort, zoals 'tekenreeks' voor System.String.
```
SYNTAX
    Get-Tech -name string -type basic advanced
    Get-Tech -ID int -list -type basic advanced
```
Verkort typen zolang hun betekenis duidelijk is, zoals tekenreeks voor System.String en int voor System.Int32.

Vermeld alle waarden van opsommingen, zoals de parameter in het vorige voorbeeld, die -type kan worden ingesteld op basic of advanced.

Schakelparameters, zoals -list in het vorige voorbeeld, hebben geen waarden.
Voeg vierkante haken toe aan parameterwaarden die een tijdelijke aanduiding zijn, in vergelijking met parameterwaarden die letterlijke waarden zijn.
```
SYNTAX
    Get-Tech -name <string> -type basic advanced
    Get-Tech -ID <int> -list -type basic advanced
```

Optionele parameters en hun waarden tussen vierkante haken omsluiten.

SYNTAX
    Get-Tech -name <string> [-type basic advanced]
    Get-Tech -ID <int> [-list] [-type basic advanced]

Optionele parametersnamen (voor positionele parameters) tussen vierkante haken plaatsen. De naam voor parameters die positioneel zijn, zoals de parameter Name in het volgende voorbeeld, hoeft niet te worden opgenomen in de opdracht .
```
SYNTAX
    Get-Tech [-name] <string> [-type basic advanced]
    Get-Tech -ID <int> [-list] [-type basic advanced]
```
Als een parameterwaarde meerdere waarden kan bevatten, zoals een lijst met namen in de parameter Name, voegt u een paar vierkante haken toe direct na de parameterwaarde.
```
SYNTAX
    Get-Tech [-name] <string[]> [-type basic advanced]
    Get-Tech -ID <int[]> [-list] [-type basic advanced]
```
Als de gebruiker kan kiezen uit parameters of parameterwaarden, zoals de parameter Type, sluit u de opties tussen vierkante haken en scheidt u deze met het exclusieve OF-symbool (;).
```
SYNTAX
    Get-Tech [-name] <string[]> [-type {basic | advanced}]
    Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
```
Als de parameterwaarde specifieke opmaak moet gebruiken, zoals aanhalingstekens of haakjes, geeft u de notatie weer in de syntaxis.
```
SYNTAX
    Get-Tech [-name] <"string[]"> [-type {basic | advanced}]
    Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
```

De syntaxisdiagram-XML coderen

Het syntaxis-knooppunt van de XML begint direct na het beschrijvings-knooppunt, dat eindigt met de </maml:description> tag . Zie Verzamelen van syntaxisinformatie voor informatie over het verzamelen van de gegevens die worden gebruikt in het syntaxisdiagram.

Een syntaxis-knooppunt toevoegen

Het syntaxisdiagram dat wordt weergegeven in het Help-onderwerp van de cmdlet wordt gegenereerd op basis van de gegevens in het syntaxis-knooppunt van de XML. Het syntaxis-knooppunt wordt tussen twee <command:syntax> tags ingesloten. Met elke parameterset van de cmdlet ingesloten in een paar <command:syntaxitem> tags. Er is geen limiet voor het aantal <command:syntaxitem> tags dat u kunt toevoegen.

In het volgende voorbeeld ziet u een syntaxisknooppunt met syntaxisitemknooppunten voor twee parametersets.

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

De cmdlet-naam toevoegen aan de parametersetgegevens

Elke parameterset van de cmdlet wordt opgegeven in een syntaxisitem-knooppunt. Elk syntaxisitem-knooppunt begint met een paar <maml:name> tags die de naam van de cmdlet bevatten.

Het volgende voorbeeld bevat een syntaxisknooppunt met syntaxisitemknooppunten voor twee parametersets.

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

Parameters toevoegen

Elke parameter die wordt toegevoegd aan het syntaxisitem-knooppunt wordt opgegeven binnen een paar <command:parameter> tags. U hebt een paar tags nodig voor elke parameter die is opgenomen in de parameterset, met uitzondering van de algemene <command:parameter> parameters die worden geleverd door PowerShell.

De kenmerken van de openingstag <command:parameter> bepalen hoe de parameter wordt weergegeven in het syntaxisdiagram. Zie Parameterkenmerken voor meer informatie over parameterkenmerken.

Notitie

De <command:parameter> tag ondersteunt een onderliggend element waarvan de inhoud nooit wordt <maml:description> weergegeven. De parameterbeschrijvingen worden opgegeven in het parameter-knooppunt van de XML. Om inconsistenties tussen de informatie in het syntaxisitem en het parameter-knooppunt te voorkomen, laat u de weg ( of <maml:description> laat u deze leeg.

Het volgende voorbeeld bevat een syntaxisitem-knooppunt voor een parameterset met twee parameters.

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>