Creare la Guida basata su XML con PlatyPS

  • Articolo

Quando si crea un modulo di PowerShell, è sempre consigliabile includere informazioni dettagliate per i cmdlet creati. Se i cmdlet sono implementati in codice compilato, è necessario usare la Guida basata su XML. Questo formato XML è noto come Microsoft Assistance Markup Language (MAML).

La documentazione legacy di PowerShell SDK contiene informazioni dettagliate sulla creazione della Guida per i cmdlet di PowerShell inclusi in moduli. Tuttavia, PowerShell non fornisce strumenti per la creazione della Guida basata su XML. La documentazione dell'SDK illustra la struttura della Guida MAML, ma lascia agli utenti il compito di creare manualmente il contenuto MAML complesso e profondamente annidato.

Questa è l'attività per cui può essere utile il modulo PlatyPS.

Che cos'è PlatyPS?

PlatyPS è uno strumento open source iniziato come progetto hackathon per semplificare la creazione e la manutenzione di MAML. PlatyPS documenta la sintassi dei set di parametri e i singoli parametri per ogni cmdlet nel modulo. PlatyPS crea file markdown strutturati che contengono informazioni sulla sintassi. Non consente di creare descrizioni o fornire esempi.

PlatyPS crea segnaposto per le descrizioni e gli esempi. Dopo aver aggiunto le informazioni necessarie, PlatyPS compila i file markdown in file MAML. Il sistema di Guida di PowerShell supporta anche file della Guida concettuali in formato testo normale (argomenti "about"). PlatyPS offre un cmdlet per creare un modello Markdown strutturato per un nuovo file about, ma questi file about_*.help.txt devono essere gestiti manualmente.

È possibile includere i file della Guida MAML e di testo con il modulo. PlatyPS può anche essere usato per compilare i file della Guida in un pacchetto CAB che può essere ospitato per la Guida aggiornabile.

Introduzione all'uso di PlatyPS

Per prima cosa, è necessario installare PlatyPS da PowerShell Gallery.

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

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

Dopo aver installato PlatyPS, importare il modulo nella sessione.

Import-Module platyps

Il diagramma di flusso seguente illustra il processo di creazione o aggiornamento del contenuto di riferimento di PowerShell.

Flusso di lavoro per la creazione della Guida basata su XML mediante PlatyPS

Creare contenuto Markdown per un modulo di PowerShell

  1. Importare il nuovo modulo nella sessione. Ripetere questo passaggio per ogni modulo che è necessario documentare.

    Eseguire il comando seguente per importare i moduli:

    Import-Module <your module name>

  2. Usare PlatyPS per generare file markdown per la pagina del modulo e tutti i cmdlet associati all'interno del modulo. Ripetere questo passaggio per ogni modulo che è necessario documentare.

    $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 la cartella di output non esiste, New-MarkdownHelp la crea. In questo esempio New-MarkdownHelp crea un file markdown per ogni cmdlet nel modulo. Crea anche la pagina del modulo in un file denominato <ModuleName>.md. Questa pagina del modulo contiene un elenco dei cmdlet contenuti nel modulo e i segnaposto per la descrizione della sezione Riepilogo. I metadati nella pagina del modulo provengono dal manifesto del modulo e vengono usati da PlatyPS per creare il file XML HelpInfo (come illustrato di seguito).

    New-MarkdownAboutHelp crea una nuovo file about denominato about_topic_name.md.

    Per altre informazioni, vedere New-MarkdownHelp e New-MarkdownAboutHelp.

Aggiornare il contenuto Markdown esistente quando il modulo viene modificato

PlatyPS può anche aggiornare i file markdown esistenti per un modulo. Usare questo passaggio per aggiornare i moduli esistenti con nuovi cmdlet, nuovi parametri o parametri modificati.

  1. Importare il nuovo modulo nella sessione. Ripetere questo passaggio per ogni modulo che è necessario documentare.

    Eseguire il comando seguente per importare i moduli:

    Import-Module <your module name>

  2. Usare PlatyPS per aggiornare i file markdown per la pagina di destinazione del modulo e tutti i cmdlet associati all'interno del modulo. Ripetere questo passaggio per ogni modulo che è necessario documentare.

    $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 aggiorna il cmdlet e i file markdown del modulo nella cartella specificata. Non aggiorna i about_*.md file. Il file del modulo (ModuleName.md) riceve l'eventuale nuovo testo della sezione Riepilogo aggiunto ai file del cmdlet. Gli aggiornamenti ai file dei cmdlet includono le modifiche seguenti:

    • Nuovi set di parametri
    • Nuovi parametri
    • Metadati dei parametri aggiornati
    • Informazioni sui tipi di input e output aggiornati

    Per altre informazioni, vedere Update-MarkdownHelpModule.

Modificare i file markdown nuovi o aggiornati

PlatyPS documenta la sintassi dei set di parametri e dei singoli parametri. Non consente di creare descrizioni o fornire esempi. Le aree specifiche in cui è necessario il contenuto sono racchiuse tra parentesi graffe. ad esempio {{ Fill in the Description }}

Modello di Markdown che mostra i segnaposto in VS Code

È necessario aggiungere un riepilogo, una descrizione del cmdlet, le descrizioni per ogni parametro e almeno un esempio.

Per informazioni dettagliate sulla scrittura di contenuto di PowerShell, vedere gli articoli seguenti:

Nota

PlatyPS ha uno schema specifico usato per i riferimenti ai cmdlet. Questo schema consente solo determinati blocchi Markdown in sezioni specifiche del documento. Se si inserisce contenuto nella posizione sbagliata, il passaggio di compilazione di PlatyPS ha esito negativo. Per altre informazioni, vedere la documentazione relativa allo schema nel repository di PlatyPS. Per un esempio completo di informazioni di riferimento sui cmdlet ben formate, vedere Get-Item.

Dopo aver fornito il contenuto richiesto per ogni cmdlet, è necessario assicurarsi di aggiornare la pagina di destinazione del modulo. Verificare che il modulo includa i valori Module Guid e Download Help Link corretti nei metadati YAML del file <module-name>.md. Aggiungere eventuali metadati mancanti.

Inoltre, è possibile notare che alcuni cmdlet non hanno una sezione Riepilogo (breve descrizione). Il comando seguente aggiorna la pagina di destinazione del modulo con il testo della descrizione del Riepilogo. Aprire la pagina di destinazione del modulo per verificare le descrizioni.

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

Ora che è stato immesso tutto il contenuto, è possibile creare i file della Guida MAML visualizzati da Get-Help nella console di PowerShell.

Creare i file della Guida esterni

Questo passaggio consente di creare i file della Guida MAML visualizzati da Get-Help nella console di PowerShell.

Per compilare i file MAML, eseguire il comando seguente:

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

New-ExternalHelp converte tutti i file Markdown del cmdlet in uno o più file MAML. I file about vengono convertiti in file di testo normale con il formato seguente per il nome: about_topic_name.help.txt. Il contenuto di Markdown deve soddisfare il requisito dello schema PlatyPS. New-ExternalHelp termina con errori quando il contenuto non segue lo schema. Per correggere le violazioni dello schema, è necessario modificare i file.

Attenzione

PlatyPS offre scarsi risultati per la conversione dei file about_*.md in testo normale. Per ottenere risultati accettabili, è necessario usare codice Markdown molto semplice. Potrebbe essere preferibile mantenere i file about_topic_name.help.txt in formato testo normale, anziché consentire a PlatyPS di convertirli.

Al termine di questo passaggio, i file *-help.xml e about_*.help.txt saranno disponibili nella cartella di output di destinazione.

Per altre informazioni, vedere New-ExternalHelp

Testare i file della Guida compilati

È possibile verificare il contenuto con il cmdlet Get-HelpPreview:

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

Il cmdlet legge il file MAML compilato e restituisce il contenuto nello stesso formato ricevuto da Get-Help. In questo modo è possibile esaminare i risultati per verificare che i file markdown siano stati compilati correttamente e producano i risultati desiderati. Se si rileva un errore, modificare nuovamente i file markdown e ricompilare il file MAML.

A questo punto i file della Guida sono pronti per la pubblicazione.

Pubblicazione della Guida

Ora che i file markdown sono stati compilati come file della Guida di PowerShell, si è pronti per renderli disponibili agli utenti. Sono disponibili due opzioni per fornire informazioni della Guida nella console di PowerShell.

  • Includere i file della Guida nel pacchetto del modulo
  • Creare un pacchetto della Guida aggiornabile che gli utenti installano con il cmdlet Update-Help

Includere i file della Guida nel pacchetto del modulo

I file della Guida possono essere inclusi nel pacchetto del modulo. Vedere Scrittura della Guida per i moduli per informazioni dettagliate sulla struttura di cartelle. È necessario includere l'elenco dei file della Guida nel valore della chiave FileList nel manifesto del modulo.

Creare un pacchetto della Guida aggiornabile

I passaggi generali per creare la Guida aggiornabile includono:

  1. Trovare un sito Internet per ospitare i file della Guida
  2. Aggiungere una chiave HelpInfoURI al manifesto del modulo
  3. Creare un file XML HelpInfo
  4. Creare i file CAB
  5. Caricare i file

Per altre informazioni, vedere Supporto per la Guida aggiornabile: procedura dettagliata.

PlatyPS ti assiste con alcuni di questi passaggi.

HelpInfoURI è un URL che punta alla posizione in cui sono ospitati i file della Guida in Internet. Questo valore viene configurato nel manifesto del modulo. Update-Help legge il manifesto del modulo per ottenere questo URL e scaricare il contenuto della Guida aggiornabile. Questo URL deve puntare solo al percorso della cartella e non ai singoli file. Update-Help costruisce i nomi di file da scaricare in base ad altre informazioni dal manifesto del modulo e dal file XML HelpInfo.

Importante

HelpInfoURI deve terminare con un carattere barra rovesciata (/). Senza tale carattere, Update-Help non è possibile costruire i percorsi di file corretti per scaricare il contenuto. Inoltre, la maggior parte dei servizi file basati su HTTP distingue tra maiuscole e minuscole. È importante che i metadati del modulo nel file XML HelpInfo contengano la lettera maiuscola corretta.

Il cmdlet New-ExternalHelp crea il file XML HelpInfo nella cartella di output. Il file XML HelpInfo viene compilato usando i metadati YAML contenuti nei file markdown del modulo (ModuleName.md).

Il cmdlet New-ExternalHelpCab crea file ZIP e CAB contenenti i file MAML e about_*.help.txt compilati. I file CAB sono compatibili con tutte le versioni di PowerShell. PowerShell 6 e versioni successive possono usare file ZIP.

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

Dopo aver creato i file ZIP e CAB, caricare i file ZIP, CAB e XML HelpInfo nel file server HTTP. Posizionare i file nel percorso indicato da HelpInfoURI.

Per altre informazioni, vedere New-ExternalHelpCab.

Altre opzioni di pubblicazione

Markdown è un formato versatile che è facile da trasformare in altri formati per la pubblicazione. Usando uno strumento come Pandoc, è possibile convertire i file della Guida Markdown in molti formati diversi di documenti, inclusi i formati testo normale, HTML, PDF e Office.

Inoltre, i cmdlet ConvertFrom-Markdown e Show-Markdown in PowerShell 6 e versioni successive possono essere usati per convertire codice Markdown in HTML o creare una visualizzazione colorata nella console di PowerShell.

Problemi noti

PlatyPS è molto rigoroso nel rispettare lo schema per la struttura dei file markdown creati e compilati. È molto facile scrivere markdown valido che viola questo schema. Per altre informazioni, vedere la guida di stile di PowerShell e gli articoli di riferimento sulla modifica.