Lägga till parameterinformation

Artikel
12/09/2021

I det här avsnittet beskrivs hur du lägger till innehåll som visas i avsnittet PARAMETRAR i cmdlet-hjälpavsnittet. Avsnittet PARAMETERS (PARAMETRAR) i hjälpavsnittet listar var och en av parametrarna i cmdleten och innehåller en detaljerad beskrivning av varje parameter.

Innehållet i avsnittet PARAMETERS ska vara konsekvent med innehållet i syntaxavsnittet i hjälpavsnittet. Det är hjälpförfattarens ansvar att se till att noden Syntax och Parametrar innehåller liknande XML-element.

Anteckning

Om du vill ha en fullständig vy över en hjälpfil öppnar du en av dll-Help.xml filerna som finns i PowerShell-installationskatalogen. Filen innehåller till Microsoft.PowerShell.Commands.Management.dll-Help.xml exempel innehåll för flera av PowerShell-cmdletarna.

Lägga till parametrar

Öppna cmdlet-hjälpfilen och leta upp noden Kommando för den cmdlet som du dokumenterar. Om du lägger till en ny cmdlet måste du skapa en ny kommandonod. Hjälp-filen innehåller en kommandonod för varje cmdlet som du tillhandahåller hjälpinnehåll för. Här är ett exempel på en tom kommandonod.
```
<command:command>
</command:command>
```

Leta upp noden Beskrivning i noden Kommando och lägg till noden Parametrar enligt nedan. Endast en parameternod tillåts och den bör omedelbart följa syntaxnoden.

<command:command>
  <command:details></command:details>
  <maml:description></maml:description>
  <command:syntax></command:syntax>
  <command:parameters>
  </command:parameters>
</command:command>

I noden Parametrar lägger du till en parameternod för varje parameter i cmdleten enligt nedan.

I det här exemplet läggs en parameternod till för tre parametrar.
```
<command:parameters>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
</command:parameters>
```
Eftersom det här är samma XML-taggar som används i syntaxnoden, och eftersom parametrarna som anges här måste matcha parametrarna som anges av noden Syntax, kan du kopiera parameternoderna från noden Syntax och klistra in dem i noden Parametrar. Se dock till att endast kopiera en instans av en parameternod, även om parametern anges i flera parameteruppsättningar i syntaxen.

För varje parameternod anger du de attributvärden som definierar egenskaperna för varje parameter. Dessa attribut omfattar följande: obligatoriskt, globning, pipelineinput och 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>

Lägg till namnet på parametern för varje parameternod. Här är ett exempel på parameternamnet som lagts till i parameternoden.

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

Lägg till en beskrivning av parametern för varje parameternod. Här är ett exempel på parameterbeskrivningen som lagts till i parameternoden.

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

Lägg till .NET-typen för parametern för varje parameternod. Parametertypen visas tillsammans med parameternamnet.

Här är ett exempel på parameterns .NET-typ som lagts till i parameternoden.

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

Lägg till standardvärdet för parametern för varje parameternod. Följande mening läggs till i parameterbeskrivningen när innehållet visas: DefaultValue är standardvärdet.

Här är ett exempel på parameterns standardvärde som läggs till i parameternoden.

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

Lägg till en possibleValues-nod för varje parameter som har flera värden.

Här är ett exempel på en possibleValues-nod som definierar två möjliga värden för parametern

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

Här är några saker att komma ihåg när du lägger till parametrar.

Attributen för parametern visas inte i alla vyer i cmdlet-hjälpavsnittet. De visas dock i en tabell som följer parameterbeskrivningen när användaren frågar efter vyn Fullständig ( ) eller Get-Help <cmdletname> -Full Parameter ( ) Get-Help <cmdletname> -Parameter för ämnet.
Parameterbeskrivningen är en av de viktigaste delarna i ett cmdlet-hjälpavsnitt. Beskrivningen bör vara kort och grundlig. Kom också ihåg att om parameterbeskrivningen blir för lång, till exempel när två parametrar interagerar med varandra, kan du lägga till mer innehåll i avsnittet ANTECKNINGAR i cmdlet-hjälpavsnittet.

Parameterbeskrivningen innehåller två typer av information.
Vad cmdleten gör när parametern används.
Vad ett juridiskt värde är för parametern.
Eftersom parametervärdena uttrycks som .NET-objekt behöver användarna mer information om dessa värden än i en traditionell kommandoradshjälp. Berätta för användaren vilken typ av data parametern är utformad för att acceptera och ta med exempel.

Standardvärdet för parametern är det värde som används om parametern inte har angetts på kommandoraden. Observera att standardvärdet är valfritt och inte behövs för vissa parametrar, till exempel obligatoriska parametrar. Du bör dock ange ett standardvärde för de flesta valfria parametrar.

Standardvärdet hjälper användaren att förstå effekten av att inte använda parametern . Beskriv standardvärdet mycket specifikt, till exempel "Aktuell katalog" eller "PowerShell-installationskatalogen ( $PSHOME )" för en valfri sökväg. Du kan också skriva en mening som beskriver standardvärdet, till exempel följande mening som används för parametern PassThru: "Om PassThru inte har angetts skickar cmdleten inte objekt nedåt i pipelinen." Eftersom värdet visas mitt emot fältnamnet Standardvärde behöver du inte inkludera termen "standardvärde" i posten.

Standardvärdet för parametern visas inte i alla vyer i cmdlet-hjälpavsnittet. Den visas dock i en tabell (tillsammans med parameterattributen) efter parameterbeskrivningen när användaren frågar efter vyn Fullständig ( ) eller Get-Help <cmdletname> -Full Parameter ( ) Get-Help <cmdletname> -Parameter för ämnet.

Följande XML visar ett par taggar som <dev:defaultValue> lagts till i <command:parameter> noden. Observera att standardvärdet följer omedelbart efter den avslutande </command:parameterValue> taggen (när parametervärdet anges) eller </maml:description> sluttaggen för parameterbeskrivningen. Namn.

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

Lägga till värden för uppräknade typer

Om parametern har flera värden eller värden av en uppräknad typ kan du använda en valfri <dev:possibleValues> nod. Med den här noden kan du ange ett namn och en beskrivning för flera värden.

Tänk på att beskrivningarna av de uppräknade värdena inte visas i någon av de standardhjälpvyer som visas av cmdleten, men andra hjälpvisningsprogram kan visa det här innehållet i sina Get-Help vyer.

Följande XML visar en <dev:possibleValues> nod med två angivna värden.

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

Lägga till parameterinformation

Lägga till parametrar

Feedback

Ytterligare resurser