Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Export-MamlCommandHelp: a module file in the batch aborts the whole export and writes nothing

Aperta
  • Qualcosa non va?
#862 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
72/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
csharp, powershell
Ambito
cli, tooling

Direzione di ricerca

Iniziare con la riproduzione usando Import-MarkdownCommandHelp e Export-MamlCommandHelp, quindi esaminare ImportMarkdownCommand.cs e il raggruppamento dell'esportazione e la logica del percorso di output descritti nell'issue. Confrontare il comportamento dell'importazione con Update-MarkdownCommandHelp e verificare che il batch contenente una pagina del modulo continui a scrivere la guida dei comandi valida senza interrompersi.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Summary

Passing a module file (the -WithModulePage output) to Import-MarkdownCommandHelp and piping the
result to Export-MamlCommandHelp throws and aborts the entire batch, so no MAML is written at
all — including for the valid command help in the same pipeline.

The failure is silent in the sense that matters: you get a created output directory containing zero
.xml files, and the only signal is a terminating error naming a directory rather than a document.

Steps to reproduce

Microsoft.PowerShell.PlatyPS 1.0.3, PowerShell 7.6.5, Windows.

Import-Module Microsoft.PowerShell.PlatyPS -RequiredVersion 1.0.3

# a one-function module, imported
$mi = Import-Module .\DemoMod\DemoMod.psd1 -Force -PassThru

New-MarkdownCommandHelp -ModuleInfo $mi -OutputFolder .\docs -WithModulePage -Force
# => docs\DemoMod\DemoMod.md, docs\DemoMod\Get-DemoThing.md

Import-MarkdownCommandHelp -Path (Get-ChildItem .\docs\DemoMod -Filter *.md).FullName |
    Export-MamlCommandHelp -OutputFolder .\maml -Force
Actual
imported objects: 2
  Title='DemoMod'        ExternalHelpFile=''
  Title='Get-DemoThing'  ExternalHelpFile='DemoMod-Help.xml'

EXPORT THREW: UnauthorizedAccessException :: Access to the path '...\maml\DemoMod' is denied.
xml files written: 0

Get-DemoThing's help is valid and was lost.

Expected

Either Import-MarkdownCommandHelp rejects a module file the way Update-MarkdownCommandHelp
already does, or Export-MamlCommandHelp skips the record with a non-terminating error and still
writes the command help it can.

Analysis

Two things combine.

Import-MarkdownCommandHelp does no document-type probing. Update-MarkdownCommandHelp does:

var identity = MarkdownProbe.Identify(path);
if (! identity.IsCommandHelp())
{
    WriteError(new ErrorRecord(new ArgumentException($"'{path}' is not a CommandHelp file."), ...));
    continue;
}

ImportMarkdownCommand.cs has no equivalent check and calls
MarkdownConverter.GetCommandHelpFromMarkdownFile(path) directly, so a module file returns a
CommandHelp with ExternalHelpFile set to the empty string rather than null.

That empty string then defeats both null-coalescing fallbacks in the export path:

GroupBy(c => c?.ExternalHelpFile ?? c?.ModuleName)
helpFileName = group.First().ExternalHelpFile ?? $"{moduleName}-Help.xml"

"" is not null, so neither falls through, and Path.Combine(moduleMamlBasePath, "") resolves to
the directory itself. Writing it throws UnauthorizedAccessException. Because OrderBy(g => g.Key)
sorts the empty key first and the exception is unhandled in EndProcessing, the batch stops before
reaching any real document.

Suggested fix

A string.IsNullOrEmpty check in place of the ?? in the export path would turn a total-loss abort
into a single skipped record. Probing document type in Import-MarkdownCommandHelp, matching
Update-MarkdownCommandHelp, would stop it earlier and give a clearer message.

Notes

The documented idiom does filter module files out, and every example I found uses it:

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

So this is avoidable, and we do avoid it. It is reported because the failure mode is
disproportionate — a caller who forgets the filter, or who points at a docs tree that happens to
contain a module page, loses the whole export rather than one file, and the error message names a
directory with no indication that a module page was the cause.

Lingua principale
C#
Stelle
870
Fork
166
Merge medio
21h 17m
PR unite (30g)
1

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di PowerShell/platyPS

Tutte le issue di PowerShell/platyPS

Issue simili

Altre issue su C#

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.