add support for /tl:[auto|on|off] msbuild flag (#2768)

* add support for /tl:[auto|on|off] msbuild flag
* adjust link to PR
* wrap help text in <para/> tags for better rendering in IDE

---------

Co-authored-by: Andrii Chebukin <XperiAndri@Outlook.com>

Author: smoothdeveloper

RELEASE_NOTES.md

@@ -3,6 +3,7 @@
 ## 6.0.1 - 2024-07-11
 * BUGFIX: MSBuild.build adds a bad string at the end of properties, thanks @0x53A - https://github.com/fsprojects/FAKE/issues/2738
 * ENHANCEMENT: Added shorthash to git functions, thanks @voronoipotato - https://github.com/fsprojects/FAKE/pull/2752
+* ENHANCEMENT: Support for `/tl:[auto:on:off]` msbuild flag, thanks @smoothdeveloper - https://github.com/fsprojects/FAKE/pull/2768
 * ENHANCEMENT: Fixes for usage in .NET 8.0 enviroment projects.
 
 ## 6.0.0 - 2023-02-20

src/app/Fake.DotNet.MSBuild/MSBuild.fs

@@ -33,6 +33,26 @@ type MSBuildVerbosity =
     | Detailed
     | Diagnostic
 
+/// <summary>
+/// <para>Specifies whether the terminal logger should be used for the build output. The default is auto, which first verifies the environment before enabling terminal logging. The environment check verifies that the terminal is capable of using modern output features and isn't using a redirected standard output before enabling the new logger. on skips the environment check and enables terminal logging. off skips the environment check and uses the default console logger.</para>
+/// <para>The terminal logger shows you the restore phase followed by the build phase. During each phase, the currently building projects appear at the bottom of the terminal. Each project that's building outputs both the MSBuild target currently being built and the amount of time spent on that target. You can search this information to learn more about the build. When a project is finished building, a single "build completed" section is written that captures:</para>
+/// <para>
+/// <ul>
+/// <li>The name of the built project.</li>
+/// <li>The target framework (if multi-targeted).</li>
+/// <li>The status of that build.</li>
+/// <li>The primary output of that build (which is hyperlinked).</li>
+/// <li>Any diagnostics generated for that project.</li>
+/// </ul>
+/// </para>
+/// </summary>
+/// <remarks>This option is available starting in .NET 8.</remarks>
+[<RequireQualifiedAccess>]
+type MSBuildTerminalLoggerOption =
+    | On
+    | Off
+    | Auto
+
 /// <summary>
 /// MSBuild log option
 /// See <a href="https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-command-line-reference?view=vs-2015">
@@ -414,6 +434,9 @@ type MSBuildParams =
         /// Disable the default console logger, and don't log events to the console.
         NoConsoleLogger: bool
 
+        /// --tl[auto|on|off]
+        TerminalLogger: MSBuildTerminalLoggerOption
+
         /// The list of warnings to treat as errors
         WarnAsError: string list option
 
@@ -455,6 +478,7 @@ type MSBuildParams =
           ToolsVersion = None
           Verbosity = None
           NoConsoleLogger = false
+          TerminalLogger = MSBuildTerminalLoggerOption.Auto
           WarnAsError = None
           NoWarn = None
           RestorePackagesFlag = false
@@ -529,6 +553,9 @@ module MSBuild =
             /// Disable the default console logger, and don't log events to the console.
             NoConsoleLogger: bool
 
+            /// --tl:[auto|on|off]
+            TerminalLogger: MSBuildTerminalLoggerOption
+
             /// The list of warnings to treat as errors
             WarnAsError: string list option
 
@@ -565,6 +592,7 @@ module MSBuild =
               ToolsVersion = None
               Verbosity = None
               NoConsoleLogger = false
+              TerminalLogger = MSBuildTerminalLoggerOption.Auto
               WarnAsError = None
               NoWarn = None
               DisableInternalBinLog = false
@@ -588,6 +616,7 @@ module MSBuild =
           ToolsVersion = x.ToolsVersion
           Verbosity = x.Verbosity
           NoConsoleLogger = x.NoConsoleLogger
+          TerminalLogger = x.TerminalLogger
           WarnAsError = x.WarnAsError
           NoWarn = x.NoWarn
           DisableInternalBinLog = x.DisableInternalBinLog
@@ -614,6 +643,7 @@ module MSBuild =
             ToolsVersion = x.ToolsVersion
             Verbosity = x.Verbosity
             NoConsoleLogger = x.NoConsoleLogger
+            TerminalLogger = x.TerminalLogger
             WarnAsError = x.WarnAsError
             NoWarn = x.NoWarn
             Loggers = x.Loggers
@@ -859,6 +889,11 @@ module MSBuild =
               yield maxCpu
               yield noLogo
               yield nodeReuse
+          yield
+              (match p.TerminalLogger with
+               | MSBuildTerminalLoggerOption.Off -> Some("tl", "off")
+               | MSBuildTerminalLoggerOption.On -> Some("tl", "on")
+               | MSBuildTerminalLoggerOption.Auto -> None)
           yield tools
           yield verbosity
           yield noConsoleLogger

src/test/Fake.Core.UnitTests/Fake.DotNet.MSBuild.fs

@@ -6,6 +6,25 @@ open Expecto
 
 [<Tests>]
 let tests =
+    let flagsTestCase name changeBuildArgs expected =
+        testCase name
+        <| fun _ ->
+            let _, cmdLine = MSBuild.buildArgs changeBuildArgs
+
+            let expected =
+                if BuildServer.ansiColorSupport then
+                    $"%s{expected} /clp:ForceConsoleColor".Trim()
+                else
+                    expected.Trim()
+
+            let expected =
+                if Environment.isUnix then
+                    $"{expected} /p:RestorePackages=False".Trim()
+                else
+                    $"/m /nodeReuse:False {expected} /p:RestorePackages=False".Trim()
+
+            Expect.equal cmdLine expected $"Expected a given cmdLine '{expected}', but got '{cmdLine}'."
+
     testList
         "Fake.DotNet.MSBuild.Tests"
         [ testCase "Test that we can create simple msbuild cmdline"
@@ -37,4 +56,18 @@ let tests =
                   else
                       "/restore /m /nodeReuse:False /p:RestorePackages=False"
 
-              Expect.equal cmdLine expected "Expected a given cmdline." ]
+              Expect.equal cmdLine expected "Expected a given cmdline."
+
+          flagsTestCase "/tl:auto doesn't ouput anything (1)" id ""
+          flagsTestCase
+              "/tl:auto doesn't ouput anything (2)"
+              (fun args -> { args with TerminalLogger = MSBuildTerminalLoggerOption.Auto })
+              ""
+          flagsTestCase
+              "/tl:on does ouput"
+              (fun args -> { args with TerminalLogger = MSBuildTerminalLoggerOption.On })
+              "/tl:on"
+          flagsTestCase
+              "/tl:off does ouput"
+              (fun args -> { args with TerminalLogger = MSBuildTerminalLoggerOption.Off })
+              "/tl:off" ]