make control of middleware order public (#740)

* make control of middleware order public

* unique middleware position per internally defined middleware

Author: jonsequitur

src/System.CommandLine/Builder/CommandLineBuilder.cs

@@ -12,7 +12,7 @@ namespace System.CommandLine.Builder
 {
     public class CommandLineBuilder : CommandBuilder
     {
-        private List<(InvocationMiddleware middleware, int order)> _middlewareList;
+        private readonly List<(InvocationMiddleware middleware, int order)> _middlewareList = new List<(InvocationMiddleware middleware, int order)>();
 
         public CommandLineBuilder(Command rootCommand = null)
             : base(rootCommand ?? new RootCommand())
@@ -43,30 +43,22 @@ public Parser Build()
                     responseFileHandling: ResponseFileHandling,
                     middlewarePipeline: _middlewareList?.OrderBy(m => m.order)
                                                        .Select(m => m.middleware)
-                                                       .ToArray(), 
+                                                       .ToArray(),
                     helpBuilderFactory: HelpBuilderFactory));
         }
 
         internal void AddMiddleware(
             InvocationMiddleware middleware,
-            int order)
+            MiddlewareOrder order)
         {
-            if (_middlewareList == null)
-            {
-                _middlewareList = new List<(InvocationMiddleware, int)>();
-            }
-
-            _middlewareList.Add((middleware, order));
+            _middlewareList.Add((middleware, (int) order));
         }
 
-        internal static class MiddlewareOrder
+        internal void AddMiddleware(
+            InvocationMiddleware middleware,
+            MiddlewareOrderInternal order)
         {
-            public const int ProcessExit = int.MinValue;
-            public const int ExceptionHandler = ProcessExit + 100;
-            public const int Configuration = ExceptionHandler + 100;
-            public const int Preprocessing = Configuration + 100;
-            public const int AfterPreprocessing = Preprocessing + 100;
-            public const int Middle = 0;
+            _middlewareList.Add((middleware, (int) order));
         }
     }
 }

src/System.CommandLine/Builder/CommandLineBuilderExtensions.cs

@@ -79,7 +79,7 @@ public static CommandLineBuilder UseVersionOption(
                 {
                     await next(context);
                 }
-            }, CommandLineBuilder.MiddlewareOrder.Preprocessing);
+            }, MiddlewareOrderInternal.VersionOption);
 
             return builder;
         }

src/System.CommandLine/Invocation/InvocationExtensions.cs

@@ -66,7 +66,7 @@ public static CommandLineBuilder CancelOnProcessTermination(this CommandLineBuil
                         blockProcessExit.Set();
                     }
                 }
-            }, CommandLineBuilder.MiddlewareOrder.ProcessExit);
+            }, MiddlewareOrderInternal.Startup);
 
             return builder;
         }
@@ -79,31 +79,33 @@ public static CommandLineBuilder ConfigureConsole(
             {
                 context.BindingContext.ConsoleFactory = new AnonymousConsoleFactory(createConsole);
                 await next(context);
-            }, CommandLineBuilder.MiddlewareOrder.Middle);
+            }, MiddlewareOrderInternal.ConfigureConsole);
 
             return builder;
         }
 
         public static CommandLineBuilder UseMiddleware(
             this CommandLineBuilder builder,
-            InvocationMiddleware middleware)
+            InvocationMiddleware middleware,
+            MiddlewareOrder order = MiddlewareOrder.Default)
         {
             builder.AddMiddleware(
                 middleware,
-                CommandLineBuilder.MiddlewareOrder.Middle);
+                order);
 
             return builder;
         }
 
         public static CommandLineBuilder UseMiddleware(
             this CommandLineBuilder builder,
-            Action<InvocationContext> onInvoke)
+            Action<InvocationContext> onInvoke,
+            MiddlewareOrder order = MiddlewareOrder.Default)
         {
             builder.AddMiddleware(async (context, next) =>
             {
                 onInvoke(context);
                 await next(context);
-            }, CommandLineBuilder.MiddlewareOrder.Middle);
+            }, order);
 
             return builder;
         }
@@ -128,7 +130,7 @@ public static CommandLineBuilder UseDebugDirective(
                 }
 
                 await next(context);
-            }, CommandLineBuilder.MiddlewareOrder.ExceptionHandler - 1);
+            }, MiddlewareOrderInternal.DebugDirective);
 
             return builder;
         }
@@ -147,7 +149,7 @@ public static CommandLineBuilder UseExceptionHandler(
                 {
                     (onException ?? Default)(exception, context);
                 }
-            }, order: CommandLineBuilder.MiddlewareOrder.ExceptionHandler);
+            }, MiddlewareOrderInternal.ExceptionHandler);
 
             return builder;
 
@@ -178,7 +180,7 @@ public static CommandLineBuilder UseParseDirective(
                 {
                     await next(context);
                 }
-            }, CommandLineBuilder.MiddlewareOrder.Preprocessing);
+            }, MiddlewareOrderInternal.ParseDirective);
 
             return builder;
         }
@@ -207,7 +209,7 @@ public static CommandLineBuilder UseSuggestDirective(
                 {
                     await next(context);
                 }
-            }, CommandLineBuilder.MiddlewareOrder.Preprocessing);
+            }, MiddlewareOrderInternal.SuggestDirective);
 
             return builder;
         }
@@ -225,7 +227,7 @@ public static CommandLineBuilder UseTypoCorrections(
                     typoCorrection.ProvideSuggestions(context.ParseResult, context.Console);
                 }
                 await next(context);
-            }, CommandLineBuilder.MiddlewareOrder.Preprocessing);
+            }, MiddlewareOrderInternal.TypoCorrection);
 
             return builder;
         }
@@ -336,7 +338,7 @@ public static CommandLineBuilder UseHelp(this CommandLineBuilder builder)
                 {
                     await next(context);
                 }
-            }, CommandLineBuilder.MiddlewareOrder.Preprocessing);
+            }, MiddlewareOrderInternal.HelpOption);
 
             return builder;
         }
@@ -351,7 +353,7 @@ public static CommandLineBuilder UseHelp(
                 {
                     await next(context);
                 }
-            }, CommandLineBuilder.MiddlewareOrder.Preprocessing);
+            }, MiddlewareOrderInternal.HelpOption);
             return builder;
         }
 
@@ -368,7 +370,7 @@ public static CommandLineBuilder UseParseErrorReporting(
                 {
                     await next(context);
                 }
-            }, CommandLineBuilder.MiddlewareOrder.AfterPreprocessing);
+            }, MiddlewareOrderInternal.ParseErrorReporting);
             return builder;
         }
 
@@ -406,7 +408,7 @@ await feature.EnsureRegistered(async () =>
                 });
 
                 await next(context);
-            }, CommandLineBuilder.MiddlewareOrder.Configuration);
+            }, MiddlewareOrderInternal.RegisterWithDotnetSuggest);
 
             return builder;
         }

src/System.CommandLine/Invocation/MiddlewareOrder.cs

@@ -0,0 +1,28 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace System.CommandLine.Invocation
+{
+    public enum MiddlewareOrder
+    {
+        ExceptionHandler = -2000,
+        Configuration = -1000,
+        Default = default,
+        ErrorReporting = 1000,
+    }
+
+    internal enum MiddlewareOrderInternal
+    {
+        Startup = -4000,
+        ExceptionHandler = -3000,
+        ConfigureConsole = -2500,
+        RegisterWithDotnetSuggest = -2400,
+        DebugDirective = -2300,
+        ParseDirective = -2200,
+        SuggestDirective = -2000,
+        TypoCorrection = -1900,
+        VersionOption = -1200,
+        HelpOption = -1100,
+        ParseErrorReporting = 1000,
+    }
+}