Add the parameter -Paged to Get-Help to support paging (PowerShell#13374)

Author: adityapatwardhan

assets/files.wxs

@@ -3108,6 +3108,9 @@
       <Component Id="cmpF65478926051451688800150DBAEE4BC">
         <File Id="fil99692697F55D4B1B9D28FDBD439A11BA" KeyPath="yes" Source="$(var.ProductSourcePath)\mscordaccore_$(var.FileArchitecture)_$(var.FileArchitecture)_5.0.20.36411.dll" />
       </Component>
+      <Component Id="cmp5485813EC16244898CB9A944AC2BC5E9">
+        <File Id="fil6EA784763CF94299BC6E75DF068F05A3" KeyPath="yes" Source="$(var.ProductSourcePath)\Microsoft.PowerShell.Pager.dll" />
+      </Component>
     </DirectoryRef>
   </Fragment>
   <Fragment>
@@ -4110,6 +4113,7 @@
       <ComponentRef Id="cmp0BD7D15E0377407FA4C43BFE89F0C12E" />
       <ComponentRef Id="cmpC0FFB3F4FB30438082D2DC0F4E4BF12D" />
       <ComponentRef Id="cmpF65478926051451688800150DBAEE4BC" />
+      <ComponentRef Id="cmp5485813EC16244898CB9A944AC2BC5E9" />
     </ComponentGroup>
   </Fragment>
 </Wix>

src/System.Management.Automation/System.Management.Automation.csproj

@@ -29,6 +29,7 @@
     <!-- the following package(s) are from the powershell org -->
     <PackageReference Include="Microsoft.Management.Infrastructure" Version="2.0.0" />
     <PackageReference Include="Microsoft.PowerShell.Native" Version="7.0.0" />
+    <PackageReference Include="Microsoft.PowerShell.Pager" Version="1.0.0-preview.2" />
   </ItemGroup>
 
   <PropertyGroup>

src/System.Management.Automation/help/HelpCommands.cs

@@ -14,6 +14,8 @@
 using System.Management.Automation.Internal;
 using System.Management.Automation.Runspaces;
 using System.Runtime.InteropServices;
+using System.Text;
+using Microsoft.PowerShell;
 #if !UNIX
 using Microsoft.Win32;
 #endif
@@ -115,15 +117,21 @@ public SwitchParameter Detailed
         [Parameter(ParameterSetName = "AllUsersView")]
         public SwitchParameter Full
         {
+            private get => _full;
+
             set
             {
-                if (value.ToBool())
+                _full = value.ToBool();
+
+                if (_full)
                 {
                     _viewTokenToAdd = HelpView.FullView;
                 }
             }
         }
 
+        private bool _full;
+
         /// <summary>
         /// Changes the view of HelpObject returned.
         /// </summary>
@@ -141,15 +149,24 @@ public SwitchParameter Full
         [Parameter(ParameterSetName = "Examples", Mandatory = true)]
         public SwitchParameter Examples
         {
+            private get
+            {
+                return _examples;
+            }
+
             set
             {
-                if (value.ToBool())
+                _examples = value.ToBool();
+
+                if (_examples)
                 {
                     _viewTokenToAdd = HelpView.ExamplesView;
                 }
             }
         }
 
+        private bool _examples;
+
         /// <summary>
         /// Parameter name.
         /// </summary>
@@ -202,6 +219,23 @@ public SwitchParameter Online
 
         private bool _showOnlineHelp;
 
+        /// <summary>
+        /// This parameter, if true, will direct get-help cmdlet to
+        /// display the help content using Microsoft.PowerShell.Pager on alternate screen buffer.
+        /// </summary>
+        [Parameter]
+        public SwitchParameter Paged
+        {
+            get;
+            set;
+        }
+
+        private Microsoft.PowerShell.Pager Pager => _pager ??= new Microsoft.PowerShell.Pager();
+
+        private Pager _pager;
+
+        private string _multiItemPagerBuffer;
+
 #if !UNIX
         private GraphicalHostReflectionWrapper graphicalHostReflectionWrapper;
         private bool showWindow;
@@ -336,6 +370,10 @@ protected override void ProcessRecord()
                 {
                     throw PSTraceSource.NewInvalidOperationException(HelpErrors.MultipleOnlineTopicsNotSupported, "Online");
                 }
+                else if (Paged && countOfHelpInfos > 1)
+                {
+                    Pager.Write(_multiItemPagerBuffer);
+                }
 
                 // show errors only if there is no wildcard search or VerboseHelpErrors is true.
                 if (((countOfHelpInfos == 0) && (!WildcardPattern.ContainsWildcardCharacters(helpRequest.Target)))
@@ -496,7 +534,7 @@ private void GetAndWriteParameterInfo(HelpInfo helpInfo)
             {
                 foreach (PSObject pInfo in pInfos)
                 {
-                    WriteObject(pInfo);
+                    WriteObjectPaged(pInfo, bufferOutputWhenPaged: false);
                 }
             }
         }
@@ -597,7 +635,7 @@ private void WriteObjectsOrShowOnlineHelp(HelpInfo helpInfo, bool showFullHelp)
                         {
                             PSObject objectToReturn = TransformView(helpInfo.FullHelp);
                             objectToReturn.IsHelpObject = true;
-                            WriteObject(objectToReturn);
+                            WriteObjectPaged(objectToReturn, bufferOutputWhenPaged: false);
                         }
                     }
                     else
@@ -612,12 +650,92 @@ private void WriteObjectsOrShowOnlineHelp(HelpInfo helpInfo, bool showFullHelp)
                             }
                         }
 
-                        WriteObject(helpInfo.ShortHelp);
+                        WriteObjectPaged(helpInfo.ShortHelp, bufferOutputWhenPaged: true);
                     }
                 }
             }
         }
 
+        private void WriteObjectPaged(object sendToPipeline, bool bufferOutputWhenPaged)
+        {
+            if (Paged)
+            {
+                var helpText = GetHelpOutput();
+
+                if (bufferOutputWhenPaged)
+                {
+                    // The output from GetHelpOutput has all the item in the output.
+                    // We just need to store it and then write to Pager later.
+                    // No need to append them.
+                    _multiItemPagerBuffer = helpText;
+                }
+                else
+                {
+                    Pager.Write(helpText);
+                }
+            }
+            else
+            {
+                WriteObject(sendToPipeline);
+            }
+        }
+
+        private string GetHelpOutput()
+        {
+            using System.Management.Automation.PowerShell ps = System.Management.Automation.PowerShell.Create(RunspaceMode.CurrentRunspace);
+
+            ps.AddCommand(@"Microsoft.PowerShell.Core\Get-Help");
+
+            if (!string.IsNullOrEmpty(this.Name))
+            {
+                ps.AddParameter(nameof(this.Name), this.Name);
+            }
+
+            if (this.Category is not null)
+            {
+                ps.AddParameter(nameof(this.Category), this.Category);
+            }
+
+            if (this.Component is not null)
+            {
+                ps.AddParameter(nameof(this.Component), this.Component);
+            }
+
+            if (this.Functionality is not null)
+            {
+                ps.AddParameter(nameof(this.Functionality), this.Functionality);
+            }
+
+            if (!string.IsNullOrEmpty(this.Path))
+            {
+                ps.AddParameter(nameof(this.Path), this.Path);
+            }
+
+            if (this.Role is not null)
+            {
+                ps.AddParameter(nameof(this.Role), this.Role);
+            }
+
+            if (this.Examples)
+            {
+                ps.AddParameter(nameof(this.Examples), this.Examples);
+            }
+
+            if (this.Full)
+            {
+                ps.AddParameter(nameof(this.Full), this.Full);
+            }
+
+            if (this.Parameter is not null)
+            {
+                ps.AddParameter(nameof(this.Parameter), this.Parameter);
+            }
+
+            ps.AddCommand(@"Microsoft.PowerShell.Utility\Out-String");
+
+            return ps.Invoke<string>().FirstOrDefault();
+        }
+
         /// <summary>
         /// Opens the Uri. System's default application will be used
         /// to show the uri.
@@ -888,4 +1006,3 @@ Uri result in
         }
     }
 }
-