fix #2765: add RootCommand.HelpName

Author: Jon Sequeira

System.CommandLine.v3.ncrunchsolution

@@ -2,8 +2,8 @@
   <Settings>
     <AllowParallelTestExecution>True</AllowParallelTestExecution>
     <CustomBuildProperties>
-      <Value>TargetFrameworks = net8.0</Value>
-      <Value>TargetFramework = net8.0</Value>
+      <Value>TargetFrameworks = net10.0</Value>
+      <Value>TargetFramework = net10.0</Value>
     </CustomBuildProperties>
     <EnableRDI>False</EnableRDI>
     <RdiConfigured>True</RdiConfigured>

src/System.CommandLine.ApiCompatibility.Tests/ApiCompatibilityApprovalTests.System_CommandLine_api_is_not_changed.approved.txt

@@ -139,6 +139,7 @@
     public static System.String ExecutablePath { get; }
     .ctor(System.String description = )
     public System.Collections.Generic.IList<Directive> Directives { get; }
+    public System.String HelpName { get; set; }
     public System.Void Add(Directive directive)
   public abstract class Symbol
     public System.String Description { get; set; }

src/System.CommandLine.Tests/Help/HelpBuilderTests.cs

@@ -336,6 +336,61 @@ public void Usage_section_does_not_contain_hidden_argument()
             help.Should().NotContain("hidden");
         }
 
+        [Fact]
+        public void Usage_section_uses_HelpName_when_set_on_root_command()
+        {
+            var rootCommand = new RootCommand
+            {
+                HelpName = "my-custom-tool"
+            };
+            rootCommand.Options.Add(new Option<string>("--opt") { Description = "an option" });
+
+            _helpBuilder.Write(rootCommand, _console);
+
+            var expected =
+                $"Usage:{NewLine}" +
+                $"{_indentation}my-custom-tool [options]";
+
+            _console.ToString().Should().Contain(expected);
+        }
+
+        [Fact]
+        public void Usage_section_uses_HelpName_when_set_on_subcommand_parent()
+        {
+            var rootCommand = new RootCommand
+            {
+                HelpName = "my-custom-tool"
+            };
+            var subcommand = new Command("sub", "a subcommand");
+            subcommand.Options.Add(new Option<string>("--opt") { Description = "an option" });
+            rootCommand.Subcommands.Add(subcommand);
+
+            _helpBuilder.Write(subcommand, _console);
+
+            var expected =
+                $"Usage:{NewLine}" +
+                $"{_indentation}my-custom-tool sub [options]";
+
+            _console.ToString().Should().Contain(expected);
+        }
+
+        [Fact]
+        public void Usage_section_uses_Name_when_HelpName_is_not_set()
+        {
+            var command = new Command("the-command", "command help");
+            command.Options.Add(new Option<string>("--opt") { Description = "an option" });
+            var rootCommand = new RootCommand();
+            rootCommand.Subcommands.Add(command);
+
+            _helpBuilder.Write(command, _console);
+
+            var expected =
+                $"Usage:{NewLine}" +
+                $"{_indentation}{_executableName} the-command [options]";
+
+            _console.ToString().Should().Contain(expected);
+        }
+
         #endregion Usage
 
         #region Arguments

src/System.CommandLine.Tests/RootCommandTests.cs

@@ -15,5 +15,38 @@ public void Root_command_name_defaults_to_executable_name()
 
             rootCommand.Name.Should().Be(RootCommand.ExecutableName);
         }
+
+        [Fact]
+        public void HelpName_can_be_set_explicitly()
+        {
+            var rootCommand = new RootCommand
+            {
+                HelpName = "my-tool"
+            };
+
+            rootCommand.HelpName.Should().Be("my-tool");
+        }
+
+        [Fact]
+        public void HelpName_can_be_set_to_null_explicitly()
+        {
+            var rootCommand = new RootCommand
+            {
+                HelpName = null
+            };
+
+            rootCommand.HelpName.Should().BeNull();
+        }
+
+        [Fact]
+        public void Setting_HelpName_does_not_change_Name()
+        {
+            var rootCommand = new RootCommand
+            {
+                HelpName = "my-tool"
+            };
+
+            rootCommand.Name.Should().Be(RootCommand.ExecutableName);
+        }
     }
 }

src/System.CommandLine/Help/HelpBuilder.cs

@@ -135,7 +135,7 @@ IEnumerable<string> GetUsageParts()
                         displayOptionTitle = parentCommand.Options.Any(x => x.Recursive && !x.Hidden);
                     }
 
-                    yield return parentCommand.Name;
+                    yield return (parentCommand is RootCommand root ? root.HelpName : null) ?? parentCommand.Name;
 
                     if (parentCommand.Arguments.Any())
                     {

src/System.CommandLine/RootCommand.cs

@@ -5,6 +5,8 @@
 using System.CommandLine.Completions;
 using System.CommandLine.Help;
 using System.IO;
+using System.Linq;
+using System.Reflection;
 
 namespace System.CommandLine
 {
@@ -20,6 +22,10 @@ public class RootCommand : Command
     {
         private static string? _executablePath;
         private static string? _executableName;
+        private static string? _toolCommandName;
+        private static bool _toolCommandNameInitialized;
+        private string? _helpName;
+        private bool _helpNameSet;
 
         /// <param name="description">The description of the command, shown in help.</param>
         public RootCommand(string description = "") : base(ExecutableName, description)
@@ -31,6 +37,23 @@ public RootCommand(string description = "") : base(ExecutableName, description)
                 new SuggestDirective()
             };
         }
+
+        /// <summary>
+        /// Gets or sets the name used for the root command in help output.
+        /// </summary>
+        /// <remarks>
+        /// If not explicitly set, defaults to the <c>ToolCommandName</c> MSBuild property value
+        /// (when available via assembly metadata), or <c>null</c> to fall back to <see cref="Symbol.Name"/>.
+        /// </remarks>
+        public string? HelpName
+        {
+            get => _helpNameSet ? _helpName : ToolCommandName;
+            set
+            {
+                _helpName = value;
+                _helpNameSet = true;
+            }
+        }
 
         /// <summary>
         /// Represents all of the directives that are valid under the root command.
@@ -52,5 +75,21 @@ public static string ExecutableName
         /// The path to the currently running executable.
         /// </summary>
         public static string ExecutablePath => _executablePath ??= Environment.GetCommandLineArgs()[0];
+
+        private static string? ToolCommandName
+        {
+            get
+            {
+                if (!_toolCommandNameInitialized)
+                {
+                    _toolCommandName = Assembly.GetEntryAssembly()?
+                        .GetCustomAttributes<AssemblyMetadataAttribute>()
+                        .FirstOrDefault(a => a.Key == "System.CommandLine.ToolCommandName")?.Value;
+                    _toolCommandNameInitialized = true;
+                }
+
+                return _toolCommandName;
+            }
+        }
     }
 }