Så här lägger du till syntax i ett cmdlet-hjälpavsnitt

2025-03-25

Anmärkning

Manuell redigering av XML-baserad hjälp är mycket svårt. Med modulen PlatyPS kan du skriva hjälp i Markdown och sedan konvertera den till XML-baserad hjälp. Detta gör det mycket enklare att skriva och underhålla hjälp. PlatyPS kan också skapa uppdateringsbara hjälppaket åt dig. Mer information finns i Skapa XML-baserad hjälp med PlatyPS.

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 parameterattributen och hur dessa data visas i syntaxdiagrammet..

Parameterattribut

Obligatoriskt
- Om det är sant måste parametern visas i alla kommandon som använder parameteruppsättningen.
- Om det är falskt är parametern valfri i alla kommandon som använder parameteruppsättningen.
Position
- Om namnet namnges krävs parameternamnet.
- Om det är positionellt är parameternamnet valfritt. När det utelämnas måste parametervärdet vara i 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.
Pipelineindata
- Om sant (ByValue) kan du skicka indata till parametern. Indata är associerade 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 med kommandot när typen inte kan konverteras. Endast en parameter i en parameteruppsättning kan associeras med värdet.
- Om sant (ByPropertyName) kan du skicka indata till parametern. Indata associeras dock endast med parametern när parameternamnet matchar namnet på en egenskap för indataobjektet. Om parameternamnet till exempel är Pathassocieras objekt som skickas till cmdleten endast med den parametern när objektet har en egenskap med namnet path.
- Om true (ByValue, ByPropertyName) kan du skicka indata till parametern antingen efter egenskapsnamn eller efter värde. Endast en parameter i en parameteruppsättning kan associeras med värdet.
- Om det är falskt kan du inte skicka indata till den här parametern.
Globbning
- Om det är sant kan texten som användaren skriver för parametervärdet innehålla jokertecken.
- Om det är falskt kan texten som användaren skriver för parametervärdet inte innehålla jokertecken.

Parametervärdeattribut

Obligatoriskt
- Om det är sant måste det angivna värdet användas när du använder parametern i ett kommando.
- Om värdet är falskt är parametervärdet valfritt. Vanligtvis är ett värde endast valfritt 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 Obligatoriskt för en parameter.

Det obligatoriska attributet för en parameter anger om parametern (och dess värde) måste inkluderas när cmdleten anropas. Däremot används det obligatoriska attributet för ett parametervärde endast när parametern ingår i kommandot . Den 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 literala, eftersom de är ett av flera värden som kan användas med parametern.

Samla in syntaxinformation

Börja med cmdletens namn.
```
SYNTAX
    Get-Tech
```
Visa en lista över alla parametrar för cmdleten. Skriv ett bindestreck (-) före varje parameternamn. Avgränsa parametrarna i parameteruppsättningar (vissa cmdletar kan bara ha en parameteruppsättning). I det här exemplet har cmdleten Get-Tech två parameteruppsättningar.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Starta varje parameteruppsättning med cmdletens namn.

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

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

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

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

Visa inte de vanliga parametrarna (till exempel Utförlig, Felsökning och ErrorAction) i syntaxdiagrammet. Cmdleten Get-Help lägger till den informationen när den visar hjälpavsnittet.
Lägg till parametervärdena. I PowerShell representeras parametervärdena av deras .NET-typ. Typnamnet kan dock förkortas, till exempel "sträng" för System.String.
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
Förkorta typer så länge deras betydelse är tydlig, till exempel sträng för System.String och int för System.Int32.

Visa en lista över alla värden för uppräkningar, till exempel parametern -Type i föregående exempel, som kan anges till grundläggande eller avancerade.

Växla parametrar, till exempel -List i föregående exempel, har inga värden.
Lägg till vinkelparenteser i parametrar 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
```

Omslut valfria parametrar och deras valar inom hakparenteser.

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

Omslut valfria parameternamn (för positionsparametrar) inom hakparenteser. Namnet på parametrar som är positionella, till exempel parametern Namn i följande exempel, behöver inte ingå 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 parametern Typ, omsluter du valen inom klammerparenteser och separerar 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

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

Lägga till en syntaxnod

Syntaxdiagrammet som visas i cmdleten Hjälp genereras från data i xml-syntaxnoden. Syntaxnoden omges av ett par <command:syntax> taggar. Med varje parameteruppsättning av cmdleten omgiven i ett par <command:syntaxitem> taggar. Det finns ingen gräns för antalet <command:syntaxitem> taggar 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 syntaxobjektnod börjar med ett par <maml:name> taggar som innehåller namnet på cmdleten.

I följande exempel ingår 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 <command:parameter> taggar för varje parameter som ingår i parameteruppsättningen, med undantag för de 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.

Anmärkning

Taggen <command:parameter> stöder ett underordnat element <maml:description> vars innehåll aldrig visas. Parameterbeskrivningarna anges i parameternoden i XML:en. Om du vill undvika inkonsekvenser mellan informationen i syntaxobjektets bodes och parameternoden utelämnar du (<maml:description> eller lämnar den tom.

I följande exempel ingår 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>

Feedback

Var den här sidan till hjälp?