Syntaxis toevoegen aan een Help-onderwerp voor cmdlets

Artikel
2025-03-25

Notitie

Handmatig schrijven van hulp op basis van XML is erg moeilijk. Met de module PlatyPS kunt u hulp schrijven in Markdown en deze vervolgens converteren naar op XML gebaseerde help. Hierdoor is het veel eenvoudiger om hulp te schrijven en te onderhouden. PlatyPS- kunt ook de Updateable Help-pakketten voor u maken. Zie Hulp op basis van XML maken met PlatyPS-voor meer informatie.

Lees deze sectie voordat u begint met het codeeren van de XML voor het syntaxisdiagram in het Help-bestand van de cmdlet om een duidelijk beeld te krijgen 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.
- Als deze onwaar is, is de parameter optioneel in alle opdrachten die gebruikmaken van de parameterset.
Positie
- Als de naam is genoemd, is de parameternaam vereist.
- Als u positioneel bent, is de parameternaam optioneel. Wanneer deze wordt weggelaten, moet de parameterwaarde zich in de opgegeven positie in de opdracht bevinden. Als de waarde bijvoorbeeld position="1" is, moet de parameterwaarde de eerste of enige naamloze parameterwaarde in de opdracht zijn.
Pijplijninvoer
- Als waar (ByValue) is, kunt u invoer naar de parameter doorsluisen. De invoer is gekoppeld aan de parameter ('gebonden aan'), zelfs als de eigenschapsnaam en het objecttype niet overeenkomen met het verwachte type. De onderdelen van de PowerShell-parameterbinding 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 aan de waarde.
- Als waar (ByPropertyName), kunt u invoer naar de parameter doorsluisen. 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 Path, worden objecten die worden doorgesluisd naar de cmdlet alleen aan die parameter gekoppeld wanneer het object een eigenschap met de naam van het pad heeft.
- Als waar (ByValue, ByPropertyName), kunt u invoer naar de parameter doorsluisen op eigenschapsnaam of op waarde. Er kan slechts één parameter in een parameterset worden gekoppeld aan de waarde.
- Als dit onwaar is, kunt u geen invoer doorsluisen naar deze parameter.
Globbing
- Indien waar, kan de tekst die de gebruiker voor de parameterwaarde typt jokertekens bevatten.
- Als dit onwaar is, kan de tekst die de gebruiker voor de parameterwaarde typt, geen jokertekens bevatten.

Parameterwaardekenmerken

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

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

Het vereiste kenmerk van een parameter geeft aan of de parameter (en de bijbehorende waarde) moeten 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 bepaalde waarde moet worden gebruikt met de parameter.

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

Informatie over de syntaxis verzamelen

Begin met de naam van de cmdlet.
```
SYNTAX
    Get-Tech
```
Geef alle parameters van de cmdlet weer. Typ een afbreekstreepje (-) vóór elke parameternaam. Scheid de parameters in parametersets (sommige cmdlets hebben mogelijk slechts één parameterset). In dit voorbeeld heeft de cmdlet Get-Tech twee parametersets.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Start elke parameterset met de naam van de cmdlet.

Geef eerst de standaardparameterset weer. 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 moeten opgeven voor de parameterset.

Geef de parameters weer in de volgorde waarin ze moeten worden weergegeven in de opdracht. Als de volgorde niet van belang is, geeft u gerelateerde parameters weer of geeft u eerst de meest gebruikte parameters weer.

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

Vermeld de algemene parameters (zoals Uitgebreid, Fouten opsporen 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
```
Verkorte typen zolang hun betekenis duidelijk is, zoals tekenreeks voor System.String en int voor System.Int32.

Geef alle waarden van opsommingen weer, zoals de -Type parameter in het vorige voorbeeld, die kan worden ingesteld op basis- of geavanceerde.

Schakel tussen parameters, zoals -List in het vorige voorbeeld, hebben geen waarden.
Hoekhaken toevoegen aan parameterwaarden die tijdelijke aanduidingen zijn, vergeleken met parameterwaarden die letterlijke waarden zijn.
```
SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced
```

Plaats optionele parameters en hun vales tussen vierkante haken.

SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

Plaats optionele parametersnamen (voor positionele parameters) tussen vierkante haken. De naam voor parameters die positioneel zijn, zoals de naamparameter in het volgende voorbeeld, hoeft niet in de opdracht te worden opgenomen.
```
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 Naam, 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 uit parameters of parameterwaarden kan kiezen, zoals de parameter Type, plaatst u de opties tussen accolades 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 in de syntaxis weer.
```
SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

De XML van het syntaxisdiagram coderen

Het syntaxisknooppunt van de XML begint direct na het beschrijvingsknooppunt, dat eindigt op de </maml:description> tag. Zie Informatie over het verzamelen van syntaxisgegevensvoor informatie over het verzamelen van de gegevens die in het syntaxisdiagram worden gebruikt.

Een syntaxisknooppunt toevoegen

Het syntaxisdiagram dat wordt weergegeven in het Help-onderwerp voor cmdlets, wordt gegenereerd op basis van de gegevens in het syntaxisknooppunt van de XML. Het syntaxisknooppunt bevindt zich in een paar <command:syntax> tags. Bij elke parameterset van de cmdlet 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 naam van de cmdlet toevoegen aan de parametersetgegevens

Elke parameterset van de cmdlet wordt opgegeven in een syntaxisitemknooppunt. Elk syntaxisitemknooppunt 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 knooppunt syntaxisitem, wordt opgegeven binnen een paar <command:parameter> tags. U hebt een paar <command:parameter> tags nodig voor elke parameter die is opgenomen in de parameterset, met uitzondering van de algemene parameters die worden geleverd door PowerShell.

De kenmerken van het openen <command:parameter> tag bepalen hoe de parameter wordt weergegeven in het syntaxisdiagram. Zie parameterkenmerkenvoor meer informatie over parameterkenmerken.

Notitie

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

Het volgende voorbeeld bevat een syntaxisitemknooppunt 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>

Delen via