Converter e publicar os arquivos de ajuda

Neste ponto, você deve ter terminado de criar, editar e testar os arquivos de ajuda do Markdown. O próximo passo é converter os arquivos de origem Markdown em arquivos de ajuda MAML e publicar para o seu módulo.

Converter os arquivos Markdown para MAML

O exemplo a seguir importa os arquivos de ajuda Markdown no diretório e, em .\WidgetModule seguida, exporta o comando help para o formato MAML no .\maml diretório.

Measure-PlatyPSMarkdown -Path .\WidgetModule\*.md |
    Where-Object Filetype -match 'CommandHelp' |
    Import-MarkdownCommandHelp -Path {$_.FilePath} |
    Export-MamlCommandHelp -OutputFolder .\maml

Publicar os ficheiros de ajuda

Existem duas opções de publicação:

• Incluir os ficheiros de ajuda no módulo
• Empacotar os arquivos de ajuda para a Ajuda atualizável

Opção 1: Incluir os ficheiros de ajuda no módulo

O Get-Help cmdlet procura arquivos de tópico da Ajuda do módulo em subdiretórios específicos do idioma do diretório do módulo. Copie os arquivos de ajuda MAML e quaisquer about_*.help.txt arquivos para uma pasta específica do idioma no diretório do módulo. O nome da pasta deve usar o formato de código de cultura, como en-US. Por exemplo, o diagrama de estrutura de diretórios a seguir mostra o local dos tópicos da Ajuda para o módulo WidgetModule.

<PSModulePath>/
└── WidgetModule/
    └── en-US/
        ├── about_WidgetModule.help.txt
        ├── WidgetModule-Help.xml
        └── NestedWidgetModule.dll-Help.xml

Se você criou ajuda em outros idiomas, crie pastas adicionais para cada idioma.

Opção 2: Empacotar os arquivos de ajuda para a Ajuda atualizável

Para oferecer suporte à Ajuda atualizável, você precisa empacotar o arquivo de ajuda (MAML e ajuda baseada em texto) em um arquivo morto e criar um HelpInfo.xml arquivo que inclua o local de download do conteúdo da ajuda, a versão da ajuda e os idiomas disponíveis.

Você também precisa hospedar o conteúdo de ajuda em um servidor Web que suporte HTTPS. O módulo deve ter um manifesto de módulo. A propriedade HelpInfoUri no manifesto deve conter a URL para o local da pasta no servidor Web onde o HelpInfo.xml arquivo está localizado. Esse URL deve ser o local da pasta, não o caminho completo para o HelpInfo.xml arquivo, e deve terminar com um caractere de barra (/).

Para obter mais informações, consulte Criação de ajuda atualizável.

PlatyPS torna este processo mais fácil. Se o manifesto do módulo contiver a propriedade HelpInfoUri quando você criar o arquivo Markdown do módulo, PlatyPS adicionará automaticamente os metadados necessários ao arquivo Markdown. Use o exemplo a seguir para criar o pacote de Ajuda atualizável.

$params = @{
    CabinetFilesFolder = '.\maml\WidgetModule'
    MarkdownModuleFile = '.\WidgetModule\WidgetModule.md'
    OutputFolder       = '.\helppackage'
}
New-HelpCabinetFile @params

O parâmetro CabinetFilesFolder especifica a pasta que contém o MAML e os arquivos de ajuda baseados em texto a serem incluídos no pacote. O parâmetro MarkdownModuleFile especifica o arquivo Markdown do módulo que contém os metadados necessários para criar o HelpInfo.xml arquivo. O parâmetro OutputFolder especifica a pasta onde os arquivos e .cab e .zip o HelpInfo.xml arquivo são criados. Copie esses arquivos para o servidor Web no local especificado pela propriedade HelpInfoUri .

A propriedade HelpInfoUri no manifesto deve conter a URL para o local da pasta no servidor Web onde o HelpInfo.xml arquivo está localizado. O Update-Help cmdlet usa esse local para construir o caminho completo para o HelpInfo.xml arquivo. O Update-Help cmdlet usa as informações no HelpInfo.xml arquivo para construir o caminho completo para os arquivos de conteúdo da ajuda.

Para obter mais informações, consulte Como funciona a Ajuda atualizável.