Lägga till syntax till ett cmdlet-hjälpavsnitt

Artikel
09/25/2021

Innan du börjar koda XML-koden för syntaxdiagrammet i cmdlet-hjälpfilen läser du det här avsnittet för att få en tydlig bild av vilken typ av data du behöver ange, till exempel parameterattribut och hur dessa data visas i syntaxdiagrammet..

Parameterattribut

Obligatorisk
- Om sant måste parametern visas i alla kommandon som använder parameteruppsättningen.
- Om det är false är parametern valfri i alla kommandon som använder parameteruppsättningen.
Position
- Om parameternamnet namnges krävs det.
- Om det är positionellt är parameternamnet valfritt. När det utelämnas måste parametervärdet finnas på den angivna positionen i kommandot. Om värdet till exempel är position="1" måste parametervärdet vara det första eller enda namnlösa parametervärdet i kommandot.
Pipeline-indata
- Om värdet är true (ByValue) kan du skicka indata till parametern . Indata associeras med parametern ("bound to") även om egenskapsnamnet och objekttypen inte matchar den förväntade typen. PowerShell-parameterbindningskomponenterna försöker konvertera indata till rätt typ och misslyckas bara kommandot när typen inte kan konverteras. Endast en parameter i en parameteruppsättning kan associeras med ett värde.
- Om sant (ByPropertyName) kan du skicka indata till parametern . Indata associeras dock bara med parametern när parameternamnet matchar namnet på en egenskap för indataobjektet. Om parameternamnet till exempel är , associeras objekt som piped till cmdleten med den parametern endast när objektet har en Path egenskap med namnet path.
- Om värdet är true (ByValue, ByPropertyName) kan du skicka indata till parametern antingen med egenskapsnamn eller värde. Endast en parameter i en parameteruppsättning kan associeras med ett värde.
- Om det är falskt kan du inte skicka indata till den här parametern.
Globbing
- Om värdet är true kan den text som användaren skriver för parametervärdet innehålla jokertecken.
- Om värdet är falskt får den text som användaren skriver för parametervärdet inte innehålla jokertecken.

Parametervärdeattribut

Obligatorisk
- Om värdet är true måste det angivna värdet användas när du använder parametern i ett kommando.
- Om värdet är false är parametervärdet valfritt. Vanligtvis är ett värde valfritt endast när det är ett av flera giltiga värden för en parameter, till exempel i en uppräknad typ.

Attributet Obligatoriskt för ett parametervärde skiljer sig från attributet Obligatorisk för en parameter.

Attributet som krävs för en parameter anger om parametern (och dess värde) måste inkluderas vid anrop av cmdleten. Det obligatoriska attributet för ett parametervärde används däremot bara när parametern ingår i kommandot. Det anger om det specifika värdet måste användas med parametern .

Normalt krävs parametervärden som är platshållare och parametervärden som är literaler, eftersom de är ett av flera värden som kan användas med parametern .

Samla in syntaxinformation

Börja med cmdlet-namnet.
```
SYNTAX
    Get-Tech
```
Lista alla parametrar för cmdleten . Skriv ett bindestreck ( - ) (ASCII 45) före varje parameternamn. Separera parametrarna i parameteruppsättningar (vissa cmdlets kan bara ha en parameteruppsättning). I det här exemplet Get-Tech cmdleten två parameteruppsättningar.
```
SYNTAX
    Get-Tech -name -type
    Get-Tech -ID -list -type
```
Starta varje parameteruppsättning med cmdlet-namnet.

Lista standardparameteruppsättningen först. Standardparametern anges av cmdlet-klassen.

För varje parameteruppsättning listar du först dess unika parameter, såvida det inte finns positionsparametrar som måste visas först. I föregående exempel är namn- och ID-parametrarna unika parametrar för de två parameteruppsättningarna (varje parameteruppsättning måste ha en parameter som är unik för den parameteruppsättningen). Det gör det enklare för användarna att identifiera vilken parameter de behöver ange för parameteruppsättningen.

Visa en lista med parametrarna i den ordning som de ska visas i kommandot. Om ordningen inte spelar någon roll listar du relaterade parametrar tillsammans eller listar de mest använda parametrarna först.

Se till att ange parametrarna WhatIf och Confirm om cmdleten stöder ShouldProcess.

Visa inte de vanliga parametrarna (till exempel Verbose, Debug och ErrorAction) i syntaxdiagrammet. Get-HelpCmdleten lägger till den informationen åt dig när den visar hjälpavsnittet.
Lägg till parametervärdena. I PowerShell representeras parametervärden av deras .NET-typ. Typnamnet kan dock förkortas, till exempel "string" för System.String.
```
SYNTAX
    Get-Tech -name string -type basic advanced
    Get-Tech -ID int -list -type basic advanced
```
Förkorta typerna så länge deras innebörd är tydlig, till exempel sträng för System.String och int för System.Int32.

Lista alla värden för uppräkningar, till exempel parametern i föregående -type exempel, som kan ställas in på grundläggande eller avancerat.

Växelparametrar, till -list exempel i föregående exempel, har inga värden.
Lägg till vinkelparenteser till parametervärden som är platshållare, jämfört med parametervärden som är literaler.
```
SYNTAX
    Get-Tech -name <string> -type basic advanced
    Get-Tech -ID <int> -list -type basic advanced
```

Omge valfria parametrar och deras val inom hakparenteser.

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

Omge valfria parameternamn (för positionsparametrar) inom hakparenteser. Namnet på parametrar som är positionella, till exempel parametern Name i följande exempel, behöver inte inkluderas i kommandot.
```
SYNTAX
    Get-Tech [-name] <string> [-type basic advanced]
    Get-Tech -ID <int> [-list] [-type basic advanced]
```
Om ett parametervärde kan innehålla flera värden, till exempel en lista med namn i parametern Namn, lägger du till ett par hakparenteser direkt efter parametervärdet.
```
SYNTAX
    Get-Tech [-name] <string[]> [-type basic advanced]
    Get-Tech -ID <int[]> [-list] [-type basic advanced]
```
Om användaren kan välja mellan parametrar eller parametervärden, till exempel type-parametern, omsluter du alternativen inom klammerparenteser och avgränsar dem med den exklusiva OR-symbolen(;).
```
SYNTAX
    Get-Tech [-name] <string[]> [-type {basic | advanced}]
    Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
```
Om parametervärdet måste använda specifik formatering, till exempel citattecken eller parenteser, visar du formatet i syntaxen.
```
SYNTAX
    Get-Tech [-name] <"string[]"> [-type {basic | advanced}]
    Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
```

Koda XML-syntaxdiagrammet

Syntaxnoden i XML-filen börjar omedelbart efter beskrivningsnoden, som slutar med </maml:description> taggen . Information om hur du samlar in de data som används i syntaxdiagrammet finns i Samla in syntaxinformation.

Lägga till en syntaxnod

Syntaxdiagrammet som visas i hjälpavsnittet för cmdleten genereras från data i syntaxnoden i XML-filen. Syntaxnoden omges av ett par <command:syntax> taggar. Med varje parameteruppsättning för cmdleten som omges av ett par <command:syntaxitem> taggar. Det finns ingen gräns för hur många taggar <command:syntaxitem> som du kan lägga till.

I följande exempel visas en syntaxnod som har syntaxobjektnoder för två parameteruppsättningar.

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

Lägga till cmdlet-namnet i parameteruppsättningsdata

Varje parameteruppsättning för cmdleten anges i en syntaxobjektnod. Varje syntaxobjektsnod börjar med ett <maml:name> par taggar som innehåller namnet på cmdleten.

Följande exempel innehåller en syntaxnod som har syntaxobjektnoder för två parameteruppsättningar.

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

Lägga till parametrar

Varje parameter som läggs till i syntaxobjektnoden anges inom ett par <command:parameter> taggar. Du behöver ett par taggar för varje parameter som ingår i parameteruppsättningen, med undantag för de <command:parameter> vanliga parametrar som tillhandahålls av PowerShell.

Attributen för den inledande <command:parameter> taggen avgör hur parametern visas i syntaxdiagrammet. Information om parameterattribut finns i Parameterattribut.

Anteckning

Taggen <command:parameter> stöder ett under element vars innehåll aldrig <maml:description> visas. Parameterbeskrivningarna anges i parameternoden i XML-filen. Undvik inkonsekvenser mellan informationen i syntaxobjektet och parameternoden genom att utelämna ( eller <maml:description> lämna den tom.

Följande exempel innehåller en syntaxobjektnod för en parameteruppsättning med två parametrar.

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