Como adicionar sinopse/resumo de um cmdlet em C#?

Question

Suponha que você esteja escrevendo algum PSCmdLet em C#:

/// <summary>
/// Get a stack overflow exception.
/// </summary>
[Cmdlet(VerbsCommon.Join, "StackOverflow")]
[OutputType(typeof(OverflowException))]
public class JoinStackOverflow : PSCmdlet {
  protected override void ProcessRecord() {
    throw new OverflowException("stack");
  }
}

Se o módulo que define o acima for carregado no PowerShell, o comando help Join-StackOverflow retornará o seguinte:

NAME
  Join-StackOverflow

SYNTAX
  Join-StackOverflow  [<CommonParameters>]

ALIASES
  None

REMARKS
  None

Como posso adicionar uma sinopse/resumo para este cmdlet, por ex.o mesmo que para Get-Process:

NAME
  Get-Process

SYNOPSIS
  Gets the processes that are running on the local computer or a remote computer.

...

Answer 1

A ajuda do cmdlet normalmente está no arquivo XML satélite.Supondo que o cmdlet esteja no módulo MeuModule.dll, o arquivo de ajuda normalmente está em MyModule\en-US\MyModule.dll-help.xml

Help XML é o chamado formato MAML.Para evitar compor cada vez manualmente criei uma ferramenta (biblioteca de scripts) Ajuda.Ele gera um modelo de script de ajuda para um cmdlet que se parece um pouco com help.Aqui está um exemplo.Então, após preencher os espaços em branco (exemplo), outro comando do Helps é chamado para converter esse script em MAML XML.

P.S.Existem outras ferramentas auxiliares na web.Experimentei alguns deles e decidi criar o meu próprio.

Answer 2

Aqui está a estrutura básica do arquivo MyModule.dll-Help.xml, que pode estar no mesmo diretório que a própria DLL do módulo ou em um subdiretório de cultura (como en-US):

<!-- For a complete treatment of this format for PowerShell cmdlets, 
     see https://msdn.microsoft.com/en-us/library/bb525433.aspx -->
<command:command 
  xmlns:maml="http://schemas.microsoft.com/maml/2004/10"
  xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" 
  xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
  <command:details>
    <command:name>Verb-Noun</command:name>
    <command:verb></command:verb>
    <command:noun></command:noun>
    <maml:description><maml:para>Synopsis</maml:para></maml:description>
  </command:details>
  <maml:description><maml:para>Description</maml:para></maml:description>
  <command:syntax>
    <command:syntaxItem>
      <maml:name>Verb-Noun</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>
      <!-- Additional parameter elements for each additional parameter. -->
    </command:syntaxItem>
    <!-- Additional syntaxItem elements for each additional parameter set. -->
  </command:syntax>
  <command:parameters>
    <command:parameter required="true" globbing="true" pipelineInput="true (ByValue)" position="1">
      <maml:name>ParameterName1</maml:name>
      <command:parameterValue required="true">string[]</command:parameterValue>
      <maml:description><maml:para>Parameter description</maml:para></maml:description>
      <dev:type>string[]</dev:type>
      <dev:defaultvalue>defaultvalue</dev:defaultvalue>
      <dev:possiblevalues>
        <dev:possiblevalue>
          <dev:value>value1</dev:value>
          <maml:description><maml:para>value description</maml:para></maml:description>
        </dev:possiblevalue>
        <dev:possiblevalue>
          <dev:value>value2</dev:value>
          <maml:description><maml:para>value description</maml:para></maml:description>
        </dev:possiblevalue>
      </dev:possiblevalues>
    </command:parameter>
    <command:parameter required="true" globbing="true" pipelineInput="true (ByPropertyName)">
      <maml:name>ParameterName2</maml:name>
      <maml:description><maml:para>Parameter description</maml:para></maml:description>
      <dev:type>int32[]</dev:type>
      <dev:defaultvalue>defaultvalue</dev:defaultvalue>
    </command:parameter>
    <!-- Additional parameter elements for each additional parameter. -->
  </command:parameters>
  <command:inputTypes>
    <command:inputType>
      <dev:type>
        <maml:name>System.String</maml:name>
        <maml:uri></maml:uri>
        <maml:description><maml:para></maml:para></maml:description>
      </dev:type>
      <maml:description><maml:para>You can pipe names …</maml:para></maml:description>
    </command:inputType>
    <!-- Additional inputType elements for each additional input type. -->
  </command:inputTypes>
  <command:returnValues>
    <command:returnValue>
      <dev:type>
        <maml:name>System.Object</maml:name>
        <maml:uri></maml:uri>
        <maml:description><maml:para></maml:para></maml:description>
      </dev:type>
      <maml:description><maml:para>When you …</maml:para></maml:description>
    </command:returnValue>
  </command:returnValues>
  <maml:alertSet>
    <maml:title>Note Title</maml:title>
    <maml:alert>
      <maml:para></maml:para>
    </maml:alert>
  </maml:alertSet>
  <command:examples>
    <command:example>
      <maml:title>----------  EXAMPLE 1  ----------</maml:title>
      <!-- The documentation (and SQLPS) suggests the PS C:\&gt; should go in the intro,
           but the dll-Help.xml files that come with PowerShell all seem to add it to the dev:code line. -->
      <maml:Introduction><maml:para>PS C:\&gt;</maml:para></maml:Introduction>
      <dev:code>Verb-Noun</dev:code>
      <dev:remarks>
        <maml:para> command description </maml:para>
        <!-- Two empty para elements signify the beginning of the output. -->
        <maml:para/>
        <maml:para/>
        <maml:para>output</maml:para>
      </dev:remarks>
    </command:example>
  </command:examples>
  <maml:relatedLinks>
    <maml:navigationLink><maml:linkText>Topic-name</maml:linkText><maml:uri></maml:uri></maml:navigationLink>
    <maml:navigationLink><maml:linkText>Topic-name</maml:linkText><maml:uri></maml:uri></maml:navigationLink>
  </maml:relatedLinks>
</command:command>