[FIXED] Die .Xml-Hilfe zeigt keine Parameterplatzhalter im SYNTAX-Abschnitt an

Ausgabe

Ich habe eine PowerShell – Funktion in einer .ps1Datei. Die Funktion hat zwei Parametersätze mit je einem Parameter. Der param()Block in der Funktionsdeklaration lautet:

Function Restore-ExplorerWindow
{
    param(
        [Parameter(ParameterSetName = 'ByPath',
            Mandatory,
            Position=0,
            ValueFromPipeline)]
        [ValidateScript({Test-Path $_ -PathType 'Leaf'})]
        [String[]]
        $Path,
        [Parameter(ParameterSetName = 'ByObject',
            Mandatory,
            Position=0,
            ValueFromPipeline)]
        [System.Object[]]
        $ExplorerState
    )

Ohne definierte Hilfe generiert PowerShell Folgendes:

SYNTAX
    Restore-ExplorerWindow [-Path] <string[]>  [<CommonParameters>]

    Restore-ExplorerWindow [-ExplorerState] <Object[]>  [<CommonParameters>]


PARAMETERS
    -ExplorerState <Object[]>

        Required?                    true
        Position?                    0
        Accept pipeline input?       true (ByValue)
        Parameter set name           ByObject
        Aliases                      None
        Dynamic?                     false

    -Path <string[]>

        Required?                    true
        Position?                    0
        Accept pipeline input?       true (ByValue)
        Parameter set name           ByPath
        Aliases                      None
        Dynamic?                     false

Aber wenn ich eine scheinbar funktionierende .xml-Hilfedatei spezifiziere, die Folgendes SYNTAXund PARAMETERSKnoten enthält:

    <command:syntax>
      <command:syntaxItem>
        <maml:name>Restore-ExplorerWindow</maml:name>
        <command:parameter
         required="true"
         variableLength="true"
         globbing="false"
         pipelineInput="true"
         position="0"
         aliases="none">
          <maml:name>Path</maml:name>
          <dev:type>
            <maml:name>System.String[]</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>none</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>Restore-ExplorerWindow</maml:name>
        <command:parameter
         required="true"
         variableLength="true"
         globbing="false"
         pipelineInput="true"
         position="0"
         aliases="none">
          <maml:name>ExplorerState</maml:name>
          <dev:type>
            <maml:name>System.Object[]</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>none</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
     </command:syntax>
    <command:parameters>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true" position="0" aliases="none">
        <maml:name>Path</maml:name>
        <maml:description>
          <maml:para>Path to previously exported .xml file.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.String[]</command:parameterValue>
        <dev:type>
          <maml:name>System.String[]</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>none</dev:defaultValue>
      </command:parameter>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true" position="0" aliases="none">
        <maml:name>ExplorerState</maml:name>
        <maml:description>
          <maml:para>Custom object created by `Get-ExplorerWindow`.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Object[]</command:parameterValue>
        <dev:type>
          <maml:name>System.Object[]</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>none</dev:defaultValue>
      </command:parameter>
    </command:parameters>

Get-Helpzeigt folgendes an:

SYNTAX
    Restore-ExplorerWindow [-Path] [<CommonParameters>]

    Restore-ExplorerWindow [-ExplorerState] [<CommonParameters>]


DESCRIPTION
    Opens an Explorer window using the information saved by `Get-ExplorerWindow`.


PARAMETERS
    -Path <System.String[]>
        Path to previously exported .xml file.

        Required?                    true
        Position?                    0
        Default value                none
        Accept pipeline input?       true
        Accept wildcard characters?  false

    -ExplorerState <Object[]>
        Custom object created by `Get-ExplorerWindow`.

        Required?                    true
        Position?                    0
        Default value                none
        Accept pipeline input?       true
        Accept wildcard characters?  false

Ich kann nicht herausfinden, warum ich nicht sehe:

SYNTAX
    Restore-ExplorerWindow [-Path] <string[]>  [<CommonParameters>]

    Restore-ExplorerWindow [-ExplorerState] <Object[]>  [<CommonParameters>]

mit der XML-Hilfe.

Lösung

Ihren <command:syntaxItem>Elementen fehlt jeweils ein <command:parameterValue>untergeordnetes Element.

Duplizieren Sie einfach die Elemente dieses Namens, die später bereits als <command:parameter>untergeordnete Elemente definiert wurden.

The documentation of the XML-based MAML format PowerShell help files use is How to Create the Cmdlet Help File

You can avoid the problem you encountered – notably the need to duplicate information across elements – by authoring your help files with the help of the PlatyPS module (install with Install-Module PlatyPS), which auto-generates the MAML XML from Markdown files that it scaffolds from a given module’s implementation.

Note:

• The PlatyPs module only works with PowerShell modules, not stand-alone PowerShell scripts (.ps1 files).

• Für Skriptdateien ( .ps1) / Funktionen, die in Skriptdateien enthalten sind, besteht der einfachste Ansatz darin, kommentarbasierte Hilfedefinitionen anstelle externer MAML-Dateien ( .help-xml) zu verwenden.

Beantwortet von – mklement0

Antwort geprüft von – David Marino (FixError Volunteer)