Fix ShowWindow not displaying all example Introduction items (#26676)#26860
Fix ShowWindow not displaying all example Introduction items (#26676)#26860kdt523 wants to merge 4 commits intoPowerShell:masterfrom
Conversation
…ell#26676) AddExamples() was calling GetTextFromArray() which only returned Introduction[0].text, silently dropping all subsequent array elements when new PlatyPS stores example introduction as string[]. Fix: replace the single GetTextFromArray call with an inline foreach over the raw PSObject[], rendering each element via AddText in order. Null-safe: null array and null element text are both guarded. No other sections or callers are changed. Test: regression test added to HelpSystem.Tests.ps1 (CI tag).
@microsoft-github-policy-service agree |
There was a problem hiding this comment.
Pull request overview
This pull request fixes a bug in the Get-Help -ShowWindow feature where only the first element of an example's introduction array was displayed. With new PlatyPS, help examples store introduction content as a PSObject[] array, but the rendering code in HelpParagraphBuilder.AddExamples() only extracted the first element using GetTextFromArray(), which by design returns only introductionObjects[0].text.
Changes:
- Replaced
GetTextFromArray()call with inline foreach loop to iterate all introduction array elements - Removed introduction text from code format string since it's now added separately
- Added regression test to validate introduction array accessibility
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| src/Microsoft.Management.UI.Internal/HelpWindow/HelpParagraphBuilder.cs | Fixed AddExamples() to iterate all introduction elements instead of only [0] |
| test/powershell/engine/Help/HelpSystem.Tests.ps1 | Added regression test for introduction array structure |
| string introText = GetPropertyString(intro, "text"); | ||
| if (introText != null) | ||
| { | ||
| this.AddText(HelpParagraphBuilder.AddIndent(introText), false); |
There was a problem hiding this comment.
Missing line break after each introduction text element. The current code adds introduction text without a line break between elements, which will cause multiple introduction lines to run together without spacing.
Following the pattern used in AddDescription (lines 467-472) and the remarks section (lines 552-562), each introduction element should be followed by a line break. After line 534, add:
this.AddText("\r\n", false);
This ensures proper spacing between introduction array elements, matching the formatting used elsewhere in the codebase for similar array-based text rendering.
| this.AddText(HelpParagraphBuilder.AddIndent(introText), false); | |
| this.AddText(HelpParagraphBuilder.AddIndent(introText), false); | |
| this.AddText("\r\n", false); |
| It 'example introduction elements are all accessible as an array' { | ||
| $help = Get-Help -Name Get-HelpExampleIntroTest -Full | ||
| $help.examples | Should -Not -BeNullOrEmpty | ||
| $example = $help.examples.example[0] | ||
| $example | Should -Not -BeNullOrEmpty | ||
|
|
||
| # introduction is a PSObject[] - every element must have a non-null text value | ||
| # so that AddExamples' foreach loop can render all of them without data loss | ||
| if ($null -ne $example.introduction) { | ||
| foreach ($intro in $example.introduction) { | ||
| $intro | Should -Not -BeNullOrEmpty | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
The test doesn't validate that multiple introduction elements exist or are rendered correctly. The example in the test function only has a single-line example with "PS C:> Get-HelpExampleIntroTest" followed by "Runs the test function." This may not produce multiple introduction array elements.
Consider adding a test that:
- Verifies that example.introduction is actually an array with multiple elements (e.g.,
$example.introduction.Count | Should -BeGreaterThan 1) - Or uses an example that is known to produce multiple introduction elements
- Validates the actual text content of multiple introduction elements
This would better ensure the fix correctly handles the multi-element scenario described in the PR.
- HelpParagraphBuilder.cs: add \r\n after each introduction text element, matching the pattern in AddDescription and the remarks loop. - HelpSystem.Tests.ps1: replace weak comment-based-help test with a test that loads a real MAML XML file (MultiIntroExample-help.xml) containing two <maml:para> introduction elements and asserts Count -gt 1 plus validates the text of each element.
|
This pull request has been automatically marked as Review Needed because it has been there has not been any activity for 7 days. |
Fixes #26676
Get-Help <cmdlet> -ShowWindowwas silently truncating example content.Only the first element of the
Introductionarray was rendered in the ShowWindow UI, causing examples to appear incomplete or missing entirely.PR Summary
New PlatyPS stores each example's introduction as a
PSObject[](an array of text nodes).The ShowWindow rendering path in
HelpParagraphBuilder.AddExamples()was callingGetTextFromArray(example, "introduction"), which only ever returnsintroductionObjects[0].text, silently dropping every subsequent element in the array.Root cause:
Fix — inline foreach that renders every element in order:
All introduction elements are now rendered through the same existing
AddTextpipeline, in the correct order, before the code block.PR Context
GetTextFromArray()is intentionally left unchanged — it correctly serves description, notes/alert, and parameter description sections which are all single-text-node scenarios..text→ skippedAddExamples()inHelpParagraphBuilder.csis modified.Files Changed
src/Microsoft.Management.UI.Internal/HelpWindow/HelpParagraphBuilder.csAddExamples()test/powershell/engine/Help/HelpSystem.Tests.ps1PR Checklist
.h,.cpp,.cs,.ps1, and.psm1files have the correct copyright headerBreaking changes
None
User-facing changes
Documentation needed
Issue filed: #26676
Testing - New and feature
Added regression test to
test/powershell/engine/Help/HelpSystem.Tests.ps1, tagged for CI.The test defines a helper function with a
.EXAMPLEblock in comment-based help, retrieves it viaGet-Help -Full, and asserts that all elements ofexample.introductionare non-null — validating the data structure that the fixedforeachloop reads.The ShowWindow WPF window cannot be launched in headless CI; the test validates the
PSObject[]data layer thatAddExamples()consumes.