Criar ajuda baseada em XML com o PlatyPS

Artigo
11/10/2023

Ao criar um módulo do PowerShell, recomenda-se sempre que inclua ajuda detalhada para os cmdlets que criar. Se os cmdlets forem implementados em código compilado, tem de utilizar a ajuda baseada em XML. Este formato XML é conhecido como Linguagem de Marcação de Assistência Microsoft (MAML).

A documentação legada do SDK do PowerShell abrange os detalhes da criação de ajuda para cmdlets do PowerShell empacotados em módulos. No entanto, o PowerShell não fornece ferramentas para criar a ajuda baseada em XML. A documentação do SDK explica a estrutura da ajuda do MAML, mas deixa-lhe a tarefa de criar o conteúdo MAML complexo e profundamente aninhado manualmente.

É aqui que o módulo PlatyPS pode ajudar.

O que é o PlatyPS?

O PlatyPS é uma ferramenta open source que começou como um projeto de hackathon para facilitar a criação e manutenção da MAML. O PlatyPS documenta a sintaxe dos conjuntos de parâmetros e os parâmetros individuais para cada cmdlet no módulo. O PlatyPS cria ficheiros Markdown estruturados que contêm as informações de sintaxe. Não pode criar descrições nem fornecer exemplos.

O PlatyPS cria marcadores de posição para preencher descrições e exemplos. Depois de adicionar as informações necessárias, o PlatyPS compila os ficheiros Markdown em ficheiros MAML. O sistema de ajuda do PowerShell também permite ficheiros de ajuda conceptual em texto simples (sobre tópicos). O PlatyPS tem um cmdlet para criar um modelo de Markdown estruturado para um novo ficheiro , mas estes about_*.help.txt ficheiros têm de ser mantidos manualmente.

Pode incluir os ficheiros de ajuda MAML e Texto com o seu módulo. Também pode utilizar o PlatyPS para compilar os ficheiros de ajuda num pacote CAB que pode ser alojado para obter ajuda atualizável.

Começar a utilizar o PlatyPS

Primeiro, tem de instalar o PlatyPS a partir do Galeria do PowerShell.

# Install using PowerShellGet 2.x
Install-Module platyps -Force

# Install using PSResourceGet 1.x
Install-PSResource platyps -Force

Depois de instalar o PlatyPS, importe o módulo para a sua sessão.

Import-Module platyps

O fluxograma seguinte descreve o processo de criação ou atualização de conteúdos de referência do PowerShell.

O fluxo de trabalho para criar ajuda baseada em XML com o PlatyPS

Criar conteúdos do Markdown para um módulo do PowerShell

Importe o seu novo módulo para a sessão. Repita este passo para cada módulo que precisa de documentar.

Execute o seguinte comando para importar os módulos:
```
Import-Module <your module name>
```
Utilize o PlatyPS para gerar ficheiros Markdown para a página do módulo e todos os cmdlets associados no módulo. Repita este passo para cada módulo que precisa de documentar.
```
$OutputFolder = <output path>
$parameters = @{
    Module = <ModuleName>
    OutputFolder = $OutputFolder
    AlphabeticParamsOrder = $true
    WithModulePage = $true
    ExcludeDontShow = $true
    Encoding = [System.Text.Encoding]::UTF8
}
New-MarkdownHelp @parameters

New-MarkdownAboutHelp -OutputFolder $OutputFolder -AboutName "topic_name"
```
Se a pasta de saída não existir, New-MarkdownHelp cria-a. Neste exemplo, New-MarkdownHelp cria um ficheiro Markdown para cada cmdlet no módulo. Também cria a página do módulo num ficheiro com o nome <ModuleName>.md. Esta página de módulo contém uma lista dos cmdlets contidos no módulo e marcadores de posição para a descrição da Sinopse . Os metadados na página do módulo provêm do manifesto do módulo e são utilizados pelo PlatyPS para criar o ficheiro XML HelpInfo (conforme explicado abaixo).

New-MarkdownAboutHelp cria um novo ficheiro com o nome about_topic_name.md.

Para obter mais informações, veja New-MarkdownHelp e New-MarkdownAboutHelp.

Atualizar o conteúdo de Markdown existente quando o módulo for alterado

O PlatyPS também pode atualizar ficheiros Markdown existentes para um módulo. Utilize este passo para atualizar módulos existentes com novos cmdlets, novos parâmetros ou parâmetros que foram alterados.

Importe o seu novo módulo para a sessão. Repita este passo para cada módulo que precisa de documentar.

Execute o seguinte comando para importar os módulos:
```
Import-Module <your module name>
```
Utilize o PlatyPS para atualizar ficheiros Markdown para a página de destino do módulo e todos os cmdlets associados no módulo. Repita este passo para cada módulo que precisa de documentar.
```
$parameters = @{
    Path = <folder with Markdown>
    RefreshModulePage = $true
    AlphabeticParamsOrder = $true
    UpdateInputOutput = $true
    ExcludeDontShow = $true
    LogPath = <path to store log file>
    Encoding = [System.Text.Encoding]::UTF8
}
Update-MarkdownHelpModule @parameters
```
Update-MarkdownHelpModule atualiza os ficheiros Markdown do cmdlet e do módulo na pasta especificada. Não atualiza os about_*.md ficheiros. O ficheiro de módulo (ModuleName.md) recebe qualquer novo texto de Synopsis que tenha sido adicionado aos ficheiros de cmdlet. Atualizações aos ficheiros de cmdlets incluem a seguinte alteração:
- Novos conjuntos de parâmetros
- Parâmetros novos
- Metadados de parâmetros atualizados
- Informações atualizadas sobre o tipo de entrada e saída
Para obter mais informações, veja Update-MarkdownHelpModule.

Editar os ficheiros Markdown novos ou atualizados

O PlatyPS documenta a sintaxe dos conjuntos de parâmetros e os parâmetros individuais. Não pode criar descrições nem fornecer exemplos. As áreas específicas em que o conteúdo é necessário estão contidas em chavetas. Por exemplo: {{ Fill in the Description }}

Modelo de Markdown a mostrar os marcadores de posição no VS Code

Tem de adicionar uma sinopse, uma descrição do cmdlet, descrições para cada parâmetro e, pelo menos, um exemplo.

Para obter informações detalhadas sobre como escrever conteúdos do PowerShell, veja os seguintes artigos:

Nota

O PlatyPS tem um esquema específico que é utilizado para referência de cmdlets. Esse esquema só permite determinados blocos de Markdown em secções específicas do documento. Se colocar conteúdo na localização errada, o passo de compilação PlatyPS falhará. Para obter mais informações, veja a documentação do esquema no repositório PlatyPS. Para obter um exemplo completo de referência de cmdlet bem formado, veja Get-Item.

Depois de fornecer o conteúdo necessário para cada um dos seus cmdlets, tem de se certificar de que atualiza a página de destino do módulo. Verifique se o módulo tem os valores corretos Module Guid e Download Help Link nos metadados YAML do <module-name>.md ficheiro. Adicione quaisquer metadados em falta.

Além disso, poderá reparar que alguns cmdlets podem não ter uma Sinopse (breve descrição). O comando seguinte atualiza a página de destino do módulo com o texto de descrição da sinopse . Abra a página de destino do módulo para verificar as descrições.

Update-MarkdownHelpModule -Path <full path output folder> -RefreshModulePage

Agora que introduziu todo o conteúdo, pode criar os ficheiros de ajuda MAML que são apresentados pela Get-Help consola do PowerShell.

Criar os ficheiros de ajuda externos

Este passo cria os ficheiros de ajuda MAML que são apresentados pela Get-Help consola do PowerShell.

Para criar os ficheiros MAML, execute o seguinte comando:

New-ExternalHelp -Path <folder with MDs> -OutputPath <output help folder>

New-ExternalHelp converte todos os ficheiros Markdown do cmdlet num (ou mais) ficheiros MAML. Acerca dos ficheiros são convertidos em ficheiros de texto simples com o seguinte formato de nome: about_topic_name.help.txt. O conteúdo de Markdown tem de cumprir os requisitos do esquema PlatyPS. New-ExternalHelp sai com erros quando o conteúdo não segue o esquema. Tem de editar os ficheiros para corrigir as violações de esquema.

Atenção

O PlatyPS faz um mau trabalho ao converter os about_*.md ficheiros em texto simples. Tem de utilizar o Markdown muito simples para obter resultados aceitáveis. Poderá querer manter os ficheiros em formato de texto about_topic_name.help.txt simples, em vez de permitir que o PlatyPS os converta.

Assim que este passo estiver concluído, verá *-help.xml os ficheiros e about_*.help.txt na pasta de saída de destino.

Para obter mais informações, veja New-ExternalHelp

Testar os ficheiros de ajuda compilados

Pode verificar o conteúdo com o cmdlet Get-HelpPreview :

Get-HelpPreview -Path "<ModuleName>-Help.xml"

O cmdlet lê o ficheiro MAML compilado e produz o conteúdo no mesmo formato que receberia de Get-Help. Isto permite-lhe inspecionar os resultados para verificar se os ficheiros markdown foram compilados corretamente e produzir os resultados pretendidos. Se encontrar um erro, volte a editar os ficheiros Markdown e recompile a MAML.

Agora, está pronto para publicar os seus ficheiros de ajuda.

Publicar a sua ajuda

Agora que compilou os ficheiros Markdown nos ficheiros de ajuda do PowerShell, está pronto para disponibilizar os ficheiros aos utilizadores. Existem duas opções para fornecer ajuda na consola do PowerShell.

Empacotar os ficheiros de ajuda com o módulo
Criar um pacote de ajuda atualizável que os utilizadores instalam com o Update-Help cmdlet

Ajuda do empacotamento com o módulo

Os ficheiros de ajuda podem ser empacotados com o seu módulo. Veja Writing Help for Modules (Escrever Ajuda para Módulos ) para obter detalhes sobre a estrutura de pastas. Deve incluir a lista de ficheiros de Ajuda no valor da chave FileList no manifesto do módulo.

Criar um pacote de ajuda atualizável

A um nível elevado, os passos para criar ajuda atualizável incluem:

Localizar um site da Internet para alojar os seus ficheiros de ajuda
Adicionar uma chave HelpInfoURI ao manifesto do módulo
Criar um ficheiro XML HelpInfo
Criar ficheiros CAB
Carregar os seus ficheiros

Para obter mais informações, veja Support Updateable Help: Step-by-step (Suporte da Ajuda Atualizável: Passo a passo).

O PlatyPS ajuda-o com alguns destes passos.

O HelpInfoURI é um URL que aponta para a localização onde os seus ficheiros de ajuda estão alojados na Internet. Este valor está configurado no manifesto do módulo. Update-Help lê o manifesto do módulo para obter este URL e transferir o conteúdo de ajuda atualizável. Este URL só deve apontar para a localização da pasta e não para ficheiros individuais. Update-Help constrói os nomes de ficheiro a transferir com base noutras informações do manifesto do módulo e do ficheiro XML HelpInfo.

Importante

O HelpInfoURI tem de terminar com um caráter de barra (/). Sem esse caráter, Update-Help não é possível construir os caminhos de ficheiro corretos para transferir o conteúdo. Além disso, a maioria dos serviços de ficheiros baseados em HTTP são sensíveis a maiúsculas e minúsculas. É importante que os metadados do módulo no ficheiro XML HelpInfo contenham as letras maiúsculas e minúsculas.

O New-ExternalHelp cmdlet cria o ficheiro XML HelpInfo na pasta de saída. O ficheiro XML HelpInfo é criado com metadados YAML contidos nos ficheiros Markdown do módulo (ModuleName.md).

O New-ExternalHelpCab cmdlet cria ficheiros ZIP e CAB que contêm o MAML e about_*.help.txt os ficheiros que compilou. Os ficheiros CAB são compatíveis com todas as versões do PowerShell. O PowerShell 6 e superior podem utilizar ficheiros ZIP.

$helpCabParameters = @{
    CabFilesFolder = $MamlOutputFolder
    LandingPagePath = $LandingPage
    OutputFolder = $CabOutputFolder
}
New-ExternalHelpCab @helpCabParameters

Depois de criar os ficheiros ZIP e CAB, carregue os ficheiros ZIP, CAB e HelpInfo XML para o servidor de ficheiros HTTP. Coloque os ficheiros na localização indicada pelo HelpInfoURI.

Para obter mais informações, veja New-ExternalHelpCab.

Outras opções de publicação

O Markdown é um formato versátil que é fácil de transformar noutros formatos para publicação. Ao utilizar uma ferramenta como o Pandoc, pode converter os seus ficheiros de ajuda do Markdown em vários formatos de documento diferentes, incluindo formatos de documentos de texto simples, HTML, PDF e Office.

Além disso, os cmdlets ConvertFrom-Markdown e Show-Markdown no PowerShell 6 e superior podem ser utilizados para converter Markdown em HTML ou criar um ecrã colorido na consola do PowerShell.

Problemas conhecidos

O PlatyPS é muito sensível ao esquema da estrutura dos ficheiros Markdown que cria e compila. É muito fácil escrever Markdown válido que viola este esquema. Para obter mais informações, veja os artigos Guia de estilos do PowerShell e Referência de edição.