Testar arquivos de ajuda do Markdown

PlatyPS espera que os arquivos Markdown sigam uma estrutura específica. Se a estrutura não estiver correta, a conversão para o formato MAML pode falhar ou o conteúdo MAML pode estar incompleto. Depois de concluir a edição dos arquivos Markdown, você deve testá-los para garantir que a estrutura esteja correta.

A melhor maneira de testar o arquivo de Ajuda do Comando Markdown é importar o arquivo e inspecionar o objeto resultante. O exemplo a seguir importa o arquivo Markdown para o Measure-PlatyPSMarkdown comando e armazena o objeto resultante na $cmdHelp variável. O Format-List * comando exibe todas as propriedades do objeto. Inspecione as propriedades para garantir que elas contenham o conteúdo esperado.

$cmdFilePath = '.\Microsoft.PowerShell.PlatyPS\Measure-PlatyPSMarkdown.md'
$cmdHelp = Import-MarkdownCommandHelp -Path $cmdFilePath
$cmdHelp | Format-List *

Metadata                    : {[document type, cmdlet], [external help file, WidgetModule-Help.xml],
                              [HelpUri, ], [Locale, en-US]…}
Locale                      : en-US
ModuleGuid                  :
ExternalHelpFile            : WidgetModule-Help.xml
OnlineVersionUrl            :
SchemaVersion               : 2024-05-01
ModuleName                  : WidgetModule
Title                       : Get-Widget
Synopsis                    : Gets one or more widgets based on specified criteria.
Syntax                      : {Get-Widget [-Name] <string> [-Color <ConsoleColor>] [-Size <int>]
                              [-Detailed] [<CommonParameters>]}
AliasHeaderFound            : True
Aliases                     :
Description                 : Gets one or more widgets from the system. You can filter the results
                              by specifying the widget's name, color, or size. Use the -Detailed
                              switch to retrieve additional information about each widget.
                              each widget.
Examples                    : {Microsoft.PowerShell.PlatyPS.Model.Example}
Parameters                  : {Color, Detailed, Name, Size}
Inputs                      : {System.String}
Outputs                     : {Widget}
Notes                       :
RelatedLinks                : {Microsoft.PowerShell.PlatyPS.Model.Links}
HasCmdletBinding            : True
HasWorkflowCommonParameters : False
Diagnostics                 : Microsoft.PowerShell.PlatyPS.Model.Diagnostics

O $cmdHelp também contém uma propriedade Diagnostics que contém informações sobre quaisquer problemas estruturais com o arquivo Markdown. Revise as informações de diagnóstico e corrija quaisquer problemas no arquivo Markdown.

$cmdHelp.Diagnostics.Messages

A coluna Severidade indica a gravidade do problema. Avisos e erros devem ser investigados e corrigidos.

Source      Severity    Message                                           Identifier
------      --------    -------                                           ----------
Metadata    Information {Metadata}                                        found 'external help …
Metadata    Information {Metadata}                                        found 'Locale'
Metadata    Information {Metadata}                                        found 'Module Name'
Metadata    Information {Metadata}                                        found 'ms.date'
Metadata    Information {Metadata}                                        found 'HelpUri'
Metadata    Information {Metadata}                                        found 'PlatyPS schema…
Metadata    Information {Metadata}                                        found 'title'
General     Information {CmdletBinding is present}                        GetCmdletBindingState
General     Information {Workflow parameters not present}                 GetWorkflowCommonPara…
Synopsis    Information {SYNOPSIS found}
Syntax      Information {Syntax found}                                    Get-Widget [-Name] <s…
Alias       Information {ALIASES header found}                            alias header is AST 8
Alias       Information {Alias string length}                             alias string length: 0
Description Information {DESCRIPTION header found}                        DESCRIPTION
Example     Information {EXAMPLES header found}                           1 examples found
Parameter   Information {Parameters}                                      4 parameters found
Parameter   Information {Color found}                                     Version 2 metadata fo…
Parameter   Information {Detailed found}                                  Version 2 metadata fo…
Parameter   Information {Name found}                                      Version 2 metadata fo…
Parameter   Information {Size found}                                      Version 2 metadata fo…
Parameter   Information {CommonParameters found}                          GetParameters
Inputs      Information {GetInput}                                        1 items found
Outputs     Information {GetOutput}                                       1 items found
Notes       Warning     {Notes content not found}                         GetNotes
Links       Information {Links found}                                     GetRelatedLinks
Links       Information {Found related links as unordered list.}
Links       Information {adding link [All about widgets](https://docs…
Links       Information {Links found}                                     1 links found

Para obter mais informações sobre a estrutura esperada dos arquivos Markdown, consulte Editar arquivos de ajuda Markdown.

Você pode testar os arquivos Markdown do módulo de maneira semelhante usando o Import-MarkdownModuleFile comando. Por exemplo:

$modFilePath = '.\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md'
$mod = Import-MarkdownModuleFile -Path $modFilePath
$mod.Diagnostics.Messages

Source                Severity    Message                        Identifier
------                --------    -------                        ----------
ModuleFileTitle       Information {Title WidgetModule Module…    GetModuleFileTitle…
Metadata              Information {found guid 8bc631f3-e82e-…    GetMetadata
Metadata              Information {found module name WidgetM…    GetMetadata
Metadata              Information {locale set to en-US}          GetMetadata
ModuleFileDescription Information {Module description found}     GetModuleFileDescr…
ModuleFileCommand     Information {command Get-Widget found}     GetModuleFileComma…

Próximas Etapas

• Converter e publicar os arquivos de ajuda