MSBuild server

documentation/MSBuild-Server.md

@@ -1,19 +1,24 @@
 # MSBuild Server
 
-MSBuild Server is basically an another type of node which can accept build request from clients and utilize worker nodes in current fashion to build projects. Main purpose of the server node is to avoid expensive MSBuild process start during build from tools like .NET SDK.
+MSBuild Server nodes accept build requests from clients and use worker nodes in the current fashion to build projects. The main purpose of the server node is to preserve caches between builds and avoid expensive MSBuild process start operations during build from tools like the .NET SDK.
+
+## Usage
+
+The primary ways to use MSBuild are via Visual Studio and via the CLI using the `dotnet build`/`dotnet msbuild` commands. MSBuild Server is not supported in Visual Studio because Visual Studio itself works like MSBuild Server. For the CLI, the server functionality is enabled by default and can be disabled by setting the `DOTNET_CLI_DO_NOT_USE_MSBUILD_SERVER` environment variable to value `1`.
+To re-enable MSBuild Server, remove the variable or set its value to `0`.
 
 ## Communication protocol
 
 The server node uses same IPC approach as current worker nodes - named pipes. This solution allows to reuse existing code. When process starts, pipe with deterministic name is opened and waiting for commands. Client has following worfklow:
 
 1. Try to connect to server
    - If server is not running, start new instance
-   - If server is busy, fallback to classic build 
+   - If server is busy or the connection is broken, fall back to previous build behavior
 2. Initiate handshake
-2. Issue build command with `EntryNodeCommand` packet
+2. Issue build command with `ServerNodeBuildCommand` packet
 3. Read packets from pipe
-   - When `EntryNodeConsoleWrite` packet type is recieved, write content to appropriate output stream with respected coloring
-   - When `EntryNodeResponse` packet type is recieved, build is done and client writes trace message with exit code
+   - Write content to the appropriate output stream (respecting coloring) with the `ServerNodeConsoleWrite` packet
+   - After the build completes, the `ServerNodeBuildResult` packet indicates the exit code
 
 ### Pipe name convention & handshake
 
@@ -25,7 +30,7 @@ Handshake is a procedure ensuring that client is connecting to a compatible serv
 
 Server requires to introduce new packet types for IPC.
 
-`EntryNodeCommand` contains all of the information necessary for a server to run a build.
+`ServerNodeBuildCommand` contains all of the information necessary for a server to run a build.
 
 | Property name            | Type                         | Description |
 |---|---|---|
@@ -34,21 +39,22 @@ Server requires to introduce new packet types for IPC.
 | BuildProcessEnvironment  | IDictionary<String, String>  | Environment variables for current build |
 | Culture                  | CultureInfo                  | The culture value for current build |
 | UICulture                | CultureInfo                  | The UI culture value for current build |
+| ConsoleConfiguration     | TargetConsoleConfiguration   | Console configuration of target Console at which the output will be rendered |
 
-`EntryNodeConsoleWrite` contains information for console output.
+`ServerNodeConsoleWrite` contains information for console output.
 
 | Property name            | Type          | Description |
 |---|---|---|
 | Text                     | String        | The text that is written to the output stream. It includes ANSI escape codes for formatting. |
 | OutputType               | Byte          | Identification of the output stream (1 = standard output, 2 = error output) |
 
-`EntryNodeResponse` informs about finished build.
+`ServerNodeBuildResult` indicates how the build finished.
 
 | Property name            | Type          | Description |
 |---|---|---|
 | ExitCode                 | Int32         | The exit code of the build |
 | ExitType                 | String        | The exit type of the build |
 
-`EntryNodeCancel` cancels the current build.
+`ServerNodeBuildCancel` cancels the current build.
 
 This type is intentionally empty and properties for build cancelation could be added in future.

documentation/specs/event-source.md

@@ -22,6 +22,7 @@ EventSource is primarily used to profile code. For MSBuild specifically, a major
 | GenerateResourceOverall | Uses resource APIs to transform resource files into strongly-typed resource classes. |
 | LoadDocument | Loads an XMLDocumentWithLocation from a path.
 | MSBuildExe | Executes MSBuild from the command line. |
+| MSBuildServerBuild | Executes a build from the MSBuildServer node. |
 | PacketReadSize | Reports the size of a packet sent between nodes. Note that this does not include time information. |
 | Parse | Parses an XML document into a ProjectRootElement. |
 | ProjectGraphConstruction | Constructs a dependency graph among projects. |

documentation/wiki/ChangeWaves.md

@@ -27,6 +27,7 @@ A wave of features is set to "rotate out" (i.e. become standard functionality) t
 - [Respect deps.json when loading assemblies](https://github.com/dotnet/msbuild/pull/7520)
 - [Consider `Platform` as default during Platform Negotiation](https://github.com/dotnet/msbuild/pull/7511)
 - [Adding accepted SDK name match pattern to SDK manifests](https://github.com/dotnet/msbuild/pull/7597)
+- [MSBuild server](https://github.com/dotnet/msbuild/pull/7634)
 
 ### 17.0
 - [Scheduler should honor BuildParameters.DisableInprocNode](https://github.com/dotnet/msbuild/pull/6400)

src/Build.OM.UnitTests/Microsoft.Build.Engine.OM.UnitTests.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <Import Project="..\Shared\FileSystemSources.proj" />
   <Import Project="..\Shared\DebuggingSources.proj" />
@@ -78,8 +78,8 @@
     <Compile Include="..\Shared\UnitTests\TestData\GlobbingTestData.cs">
       <Link>TestData\GlobbingTestData.cs</Link>
     </Compile>
+    <Compile Include="..\Shared\ProcessExtensions.cs" />
     <Compile Include="..\UnitTests.Shared\RunnerUtilities.cs" />
-
     <None Include="..\Shared\UnitTests\App.config">
       <Link>App.config</Link>
       <SubType>Designer</SubType>

src/Build.OM.UnitTests/NugetRestoreTests.cs

@@ -10,8 +10,6 @@
 #endif
 using Xunit.Abstractions;
 
-#nullable disable
-
 namespace Microsoft.Build.Engine.OM.UnitTests
 {
     public sealed class NugetRestoreTests
@@ -29,7 +27,7 @@ public NugetRestoreTests(ITestOutputHelper output)
         [Fact]
         public void TestOldNuget()
         {
-            string msbuildExePath = Path.GetDirectoryName(RunnerUtilities.PathToCurrentlyRunningMsBuildExe);
+            string msbuildExePath = Path.GetDirectoryName(RunnerUtilities.PathToCurrentlyRunningMsBuildExe)!;
             using TestEnvironment testEnvironment = TestEnvironment.Create();
             TransientTestFolder folder = testEnvironment.CreateFolder(createFolder: true);
             // The content of the solution isn't known to matter, but having a custom solution makes it easier to add requirements should they become evident.

src/Build.UnitTests/BackEnd/KnownTelemetry_Tests.cs

@@ -0,0 +1,121 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+#nullable disable
+using System;
+using System.Globalization;
+using Microsoft.Build.Framework.Telemetry;
+using Shouldly;
+using Xunit;
+
+namespace Microsoft.Build.UnitTests.Telemetry;
+
+public class KnownTelemetry_Tests
+{
+    [Fact]
+    public void BuildTelemetryCanBeSetToNull()
+    {
+        KnownTelemetry.BuildTelemetry = new BuildTelemetry();
+        KnownTelemetry.BuildTelemetry = null;
+
+        KnownTelemetry.BuildTelemetry.ShouldBeNull();
+    }
+
+    [Fact]
+    public void BuildTelemetryCanBeSet()
+    {
+        BuildTelemetry buildTelemetry = new BuildTelemetry();
+        KnownTelemetry.BuildTelemetry = buildTelemetry;
+
+        KnownTelemetry.BuildTelemetry.ShouldBeSameAs(buildTelemetry);
+    }
+
+    [Fact]
+    public void BuildTelemetryConstructedHasNoProperties()
+    {
+        BuildTelemetry buildTelemetry = new BuildTelemetry();
+
+        buildTelemetry.DisplayVersion.ShouldBeNull();
+        buildTelemetry.EventName.ShouldBe("build");
+        buildTelemetry.FinishedAt.ShouldBeNull();
+        buildTelemetry.FrameworkName.ShouldBeNull();
+        buildTelemetry.Host.ShouldBeNull();
+        buildTelemetry.InitialServerState.ShouldBeNull();
+        buildTelemetry.InnerStartAt.ShouldBeNull();
+        buildTelemetry.Project.ShouldBeNull();
+        buildTelemetry.ServerFallbackReason.ShouldBeNull();
+        buildTelemetry.StartAt.ShouldBeNull();
+        buildTelemetry.Success.ShouldBeNull();
+        buildTelemetry.Target.ShouldBeNull();
+        buildTelemetry.Version.ShouldBeNull();
+
+        buildTelemetry.UpdateEventProperties();
+        buildTelemetry.Properties.ShouldBeEmpty();
+    }
+
+    [Fact]
+    public void BuildTelemetryCreateProperProperties()
+    {
+        BuildTelemetry buildTelemetry = new BuildTelemetry();
+
+        DateTime startAt = new DateTime(2023, 01, 02, 10, 11, 22);
+        DateTime innerStartAt = new DateTime(2023, 01, 02, 10, 20, 30);
+        DateTime finishedAt = new DateTime(2023, 12, 13, 14, 15, 16);
+
+        buildTelemetry.DisplayVersion = "Some Display Version";
+        buildTelemetry.FinishedAt = finishedAt;
+        buildTelemetry.FrameworkName = "new .NET";
+        buildTelemetry.Host = "Host description";
+        buildTelemetry.InitialServerState = "hot";
+        buildTelemetry.InnerStartAt = innerStartAt;
+        buildTelemetry.Project = @"C:\\dev\\theProject";
+        buildTelemetry.ServerFallbackReason = "busy";
+        buildTelemetry.StartAt = startAt;
+        buildTelemetry.Success = true;
+        buildTelemetry.Target = "clean";
+        buildTelemetry.Version = new Version(1, 2, 3, 4);
+
+        buildTelemetry.UpdateEventProperties();
+        buildTelemetry.Properties.Count.ShouldBe(11);
+
+        buildTelemetry.Properties["BuildEngineDisplayVersion"].ShouldBe("Some Display Version");
+        buildTelemetry.Properties["BuildEngineFrameworkName"].ShouldBe("new .NET");
+        buildTelemetry.Properties["BuildEngineHost"].ShouldBe("Host description");
+        buildTelemetry.Properties["InitialMSBuildServerState"].ShouldBe("hot");
+        buildTelemetry.Properties["ProjectPath"].ShouldBe(@"C:\\dev\\theProject");
+        buildTelemetry.Properties["ServerFallbackReason"].ShouldBe("busy");
+        buildTelemetry.Properties["BuildSuccess"].ShouldBe("True");
+        buildTelemetry.Properties["BuildTarget"].ShouldBe("clean");
+        buildTelemetry.Properties["BuildEngineVersion"].ShouldBe("1.2.3.4");
+
+        // verify computed
+        buildTelemetry.Properties["BuildDurationInMilliseconds"] = (finishedAt - startAt).TotalMilliseconds.ToString(CultureInfo.InvariantCulture);
+        buildTelemetry.Properties["InnerBuildDurationInMilliseconds"] = (finishedAt - innerStartAt).TotalMilliseconds.ToString(CultureInfo.InvariantCulture);
+    }
+
+    [Fact]
+    public void BuildTelemetryHandleNullsInRecordedTimes()
+    {
+        BuildTelemetry buildTelemetry = new BuildTelemetry();
+
+        buildTelemetry.StartAt = DateTime.MinValue;
+        buildTelemetry.FinishedAt = null;
+        buildTelemetry.UpdateEventProperties();
+        buildTelemetry.Properties.ShouldBeEmpty();
+
+        buildTelemetry.StartAt = null;
+        buildTelemetry.FinishedAt = DateTime.MaxValue;
+        buildTelemetry.UpdateEventProperties();
+        buildTelemetry.Properties.ShouldBeEmpty();
+
+        buildTelemetry.InnerStartAt = DateTime.MinValue;
+        buildTelemetry.FinishedAt = null;
+        buildTelemetry.UpdateEventProperties();
+        buildTelemetry.Properties.ShouldBeEmpty();
+
+        buildTelemetry.InnerStartAt = null;
+        buildTelemetry.FinishedAt = DateTime.MaxValue;
+        buildTelemetry.UpdateEventProperties();
+        buildTelemetry.Properties.ShouldBeEmpty();
+    }
+}

src/Build.UnitTests/BackEnd/RedirectConsoleWriter_Tests.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using System;
+using System.IO;
+using System.Text;
+using System.Threading.Tasks;
+using Microsoft.Build.Experimental;
+using Shouldly;
+using Xunit;
+
+namespace Microsoft.Build.Engine.UnitTests.BackEnd
+{
+    public class RedirectConsoleWriter_Tests
+    {
+        [Fact]
+        public async Task EmitConsoleMessages()
+        {
+            StringBuilder sb = new StringBuilder();
+
+            using (TextWriter writer = OutOfProcServerNode.RedirectConsoleWriter.Create(text => sb.Append(text)))
+            {
+                writer.WriteLine("Line 1");
+                await Task.Delay(80); // should be somehow bigger than `RedirectConsoleWriter` flush period - see its constructor
+                writer.Write("Line 2");
+            }
+
+            sb.ToString().ShouldBe($"Line 1{Environment.NewLine}Line 2");
+        }
+    }
+}

src/Build/BackEnd/BuildManager/BuildManager.cs

@@ -25,6 +25,7 @@
 using Microsoft.Build.Exceptions;
 using Microsoft.Build.Experimental.ProjectCache;
 using Microsoft.Build.Framework;
+using Microsoft.Build.Framework.Telemetry;
 using Microsoft.Build.Graph;
 using Microsoft.Build.Internal;
 using Microsoft.Build.Logging;
@@ -456,7 +457,7 @@ public void BeginBuild(BuildParameters parameters)
                         _nodeManager?.ShutdownAllNodes();
                         _taskHostNodeManager?.ShutdownAllNodes();
                     }
-               }
+                }
             }
 
             _previousLowPriority = parameters.LowPriority;
@@ -470,6 +471,14 @@ public void BeginBuild(BuildParameters parameters)
 
                 MSBuildEventSource.Log.BuildStart();
 
+                // Initiate build telemetry data
+                DateTime now = DateTime.UtcNow;
+                KnownTelemetry.BuildTelemetry ??= new()
+                {
+                    StartAt = now,
+                };
+                KnownTelemetry.BuildTelemetry.InnerStartAt = now;
+
                 if (BuildParameters.DumpOpportunisticInternStats)
                 {
                     Strings.EnableDiagnostics();
@@ -796,6 +805,13 @@ public BuildSubmission PendBuildRequest(BuildRequestData requestData)
                 VerifyStateInternal(BuildManagerState.Building);
 
                 var newSubmission = new BuildSubmission(this, GetNextSubmissionId(), requestData, _buildParameters.LegacyThreadingSemantics);
+
+                if (KnownTelemetry.BuildTelemetry != null)
+                {
+                    KnownTelemetry.BuildTelemetry.Project ??= requestData.ProjectFullPath;
+                    KnownTelemetry.BuildTelemetry.Target ??= string.Join(",", requestData.TargetNames);
+                }
+
                 _buildSubmissions.Add(newSubmission.SubmissionId, newSubmission);
                 _noActiveSubmissionsEvent.Reset();
                 return newSubmission;
@@ -817,6 +833,15 @@ public GraphBuildSubmission PendBuildRequest(GraphBuildRequestData requestData)
                 VerifyStateInternal(BuildManagerState.Building);
 
                 var newSubmission = new GraphBuildSubmission(this, GetNextSubmissionId(), requestData);
+
+                if (KnownTelemetry.BuildTelemetry != null)
+                {
+                    // Project graph can have multiple entry points, for purposes of identifying event for same build project,
+                    // we believe that including only one entry point will provide enough precision.
+                    KnownTelemetry.BuildTelemetry.Project ??= requestData.ProjectGraphEntryPoints?.FirstOrDefault().ProjectFile;
+                    KnownTelemetry.BuildTelemetry.Target ??= string.Join(",", requestData.TargetNames);
+                }
+
                 _graphBuildSubmissions.Add(newSubmission.SubmissionId, newSubmission);
                 _noActiveSubmissionsEvent.Reset();
                 return newSubmission;
@@ -965,6 +990,35 @@ public void EndBuild()
                         }
 
                         loggingService.LogBuildFinished(_overallBuildSuccess);
+
+                        if (KnownTelemetry.BuildTelemetry != null)
+                        {
+                            KnownTelemetry.BuildTelemetry.FinishedAt = DateTime.UtcNow;
+                            KnownTelemetry.BuildTelemetry.Success = _overallBuildSuccess;
+                            KnownTelemetry.BuildTelemetry.Version = ProjectCollection.Version;
+                            KnownTelemetry.BuildTelemetry.DisplayVersion = ProjectCollection.DisplayVersion;
+                            KnownTelemetry.BuildTelemetry.FrameworkName = NativeMethodsShared.FrameworkName;
+
+                            string host = null;
+                            if (BuildEnvironmentState.s_runningInVisualStudio)
+                            {
+                                host = "VS";
+                            }
+                            else if (!string.IsNullOrEmpty(Environment.GetEnvironmentVariable("MSBUILD_HOST_NAME")))
+                            {
+                                host = Environment.GetEnvironmentVariable("MSBUILD_HOST_NAME");
+                            }
+                            else if (!string.IsNullOrEmpty(Environment.GetEnvironmentVariable("VSCODE_CWD")) || Environment.GetEnvironmentVariable("TERM_PROGRAM") == "vscode")
+                            {
+                                host = "VSCode";
+                            }
+                            KnownTelemetry.BuildTelemetry.Host = host;
+
+                            KnownTelemetry.BuildTelemetry.UpdateEventProperties();
+                            loggingService.LogTelemetry(buildEventContext: null, KnownTelemetry.BuildTelemetry.EventName, KnownTelemetry.BuildTelemetry.Properties);
+                            // Clean telemetry to make it ready for next build submission.
+                            KnownTelemetry.BuildTelemetry = null;
+                        }
                     }
 
                     ShutdownLoggingService(loggingService);