OutOfProcTaskHostNode.cs

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System;
using System.Collections;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Reflection;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Build.BackEnd;
using Microsoft.Build.Eventing;
using Microsoft.Build.Execution;
using Microsoft.Build.Framework;
using Microsoft.Build.Framework.Utilities;
using Microsoft.Build.Experimental.FileAccess;
using Microsoft.Build.Internal;
using Microsoft.Build.Shared;
#if FEATURE_APPDOMAIN
using System.Runtime.Remoting;
using System.Runtime.Remoting.Messaging;
#endif

#nullable disable

namespace Microsoft.Build.CommandLine
{
    /// <summary>
    /// This class represents an implementation of INode for out-of-proc node for hosting tasks.
    /// </summary>
    internal class OutOfProcTaskHostNode :
#if FEATURE_APPDOMAIN
        MarshalByRefObject,
#endif
        INodePacketFactory, INodePacketHandler, IBuildEngine10
    {
        /// <summary>
        /// Keeps a record of all environment variables that, on startup of the task host, have a different
        /// value from those that are passed to the task host in the configuration packet for the first task.
        /// These environments are assumed to be effectively identical, so the only difference between the
        /// two sets of values should be any environment variables that differ between e.g. a 32-bit and a 64-bit
        /// process.  Those are the variables that this dictionary should store.
        ///
        /// - The key into the dictionary is the name of the environment variable.
        /// - The Key of the KeyValuePair is the value of the variable in the owning worker node process -- the value that we
        ///   wish to ensure is replaced by whatever the correct value in our current process is.
        /// - The Value of the KeyValuePair is the value of the variable in the current process -- the value that
        ///   we wish to replay the Key value with in the environment that we receive from the owning worker node before
        ///   applying it to the current process.
        ///
        /// Note that either value in the KeyValuePair can be null, as it is completely possible to have an
        /// environment variable that is set in 32-bit processes but not in 64-bit, or vice versa.
        ///
        /// This dictionary must be static because otherwise, if a node is sitting around waiting for reuse, it will
        /// have inherited the environment from the previous build, and any differences between the two will be seen
        /// as "legitimate".  There is no way for us to know what the differences between the startup environment of
        /// the previous build and the environment of the first task run in the task host in this build -- so we
        /// must assume that the 4ish system environment variables that this is really meant to catch haven't
        /// somehow magically changed between two builds spaced no more than 15 minutes apart.
        /// </summary>
        private static IDictionary<string, KeyValuePair<string, string>> s_mismatchedEnvironmentValues;

        /// <summary>
        /// The endpoint used to talk to the host.
        /// </summary>
        private NodeEndpointOutOfProcTaskHost _nodeEndpoint;

        /// <summary>
        /// The packet factory.
        /// </summary>
        private NodePacketFactory _packetFactory;

        /// <summary>
        /// The event which is set when we receive packets.
        /// </summary>
        private AutoResetEvent _packetReceivedEvent;

        /// <summary>
        /// The queue of packets we have received but which have not yet been processed.
        /// </summary>
        private Queue<INodePacket> _receivedPackets;

        /// <summary>
        /// The current configuration for this task host.
        /// </summary>
        private TaskHostConfiguration _currentConfiguration;

        /// <summary>
        /// The saved environment for the process.
        /// </summary>
        private IDictionary<string, string> _savedEnvironment;

        /// <summary>
        /// The build process environment most recently received in full from the parent on this connection.
        /// When a <see cref="TaskHostConfiguration"/> arrives marked <see cref="InvariantPayloadTransferMode.Identical"/>
        /// it is reconstructed from this baseline.
        /// </summary>
        private Dictionary<string, string> _forwardEnvironmentBaseline;

        /// <summary>
        /// The global properties most recently received in full from the parent on this connection. When a
        /// <see cref="TaskHostConfiguration"/> arrives marked <see cref="InvariantPayloadTransferMode.Identical"/> they
        /// are reconstructed from this baseline.
        /// </summary>
        private Dictionary<string, string> _forwardGlobalParametersBaseline;

        /// <summary>
        /// The build process environment whose values are currently reflected in this task host process. Used to
        /// skip the redundant per-task environment apply + restore when the next task's environment is identical
        /// and the previous task did not mutate it. Set to <see langword="null"/> whenever a task blocks on a
        /// callback (<see cref="SaveOperatingEnvironment"/>) or the node is reused for a new build, so nested
        /// activity and build boundaries always force a fresh apply.
        /// </summary>
        private IDictionary<string, string> _lastAppliedConfigEnvironment;

        /// <summary>
        /// The event which is set when we should shut down.
        /// </summary>
        private ManualResetEvent _shutdownEvent;

        /// <summary>
        /// The reason we are shutting down.
        /// </summary>
        private NodeEngineShutdownReason _shutdownReason;

        /// <summary>
        /// Count of tasks that are actively executing (not blocked on a callback).
        /// When a task blocks on BuildProjectFile, this decrements. When it resumes, this increments.
        /// Used to determine if we can accept new TaskHostConfiguration packets.
        /// </summary>
        private int _activeTaskCount;

        /// <summary>
        /// Number of tasks currently blocked on a BuildProjectFile callback.
        /// A blocked task does NOT prevent new tasks from being scheduled to this TaskHost.
        /// </summary>
        private int _blockedTaskCount;

        /// <summary>
        /// The event which is set when a task has completed.
        /// </summary>
        private AutoResetEvent _taskCompleteEvent;

        /// <summary>
        /// The completed task packet waiting to be sent by the main thread.
        /// Distinct results must survive coalesced completion event signals.
        /// </summary>
        private readonly ConcurrentQueue<TaskHostTaskComplete> _taskCompletePackets = new();

        /// <summary>
        /// The event which is set when a task is cancelled
        /// </summary>
        private ManualResetEvent _taskCancelledEvent;

        /// <summary>
        /// Signalled when the current build cancelled a task. FOR UNIT TESTING ONLY: a cancellation
        /// from one build must not still be signalled when the node is reset for the next.
        /// </summary>
        internal ManualResetEvent TaskCancelledEvent => _taskCancelledEvent;

        /// <summary>
        /// Flag indicating if we should debug communications or not.
        /// </summary>
        private bool _debugCommunications;

        /// <summary>
        /// Flag indicating whether we should modify the environment based on any differences we find between that of the
        /// task host at startup and the environment passed to us in our initial task configuration packet.
        /// </summary>
        private bool _updateEnvironment;

        /// <summary>
        /// An interim step between MSBuildTaskHostDoNotUpdateEnvironment=1 and the default update behavior:  go ahead and
        /// do all the updates that we would otherwise have done by default, but log any updates that are made (at low
        /// importance) so that the user is aware.
        /// </summary>
        private bool _updateEnvironmentAndLog;

        /// <summary>
        /// Whether this task host was launched with node reuse, so it does not exit at the end of a
        /// build. Whether it then stays connected to its launcher as a sidecar, or disconnects into
        /// the machine-wide pool, is what <see cref="NodeBuildComplete.PrepareForReuse"/> says.
        /// </summary>
        private bool _nodeReuse;

        /// <summary>
        /// The task object cache.
        /// </summary>
        private RegisteredTaskObjectCacheBase _registeredTaskObjectCache = new();

#if FEATURE_REPORTFILEACCESSES
        /// <summary>
        /// The file accesses reported by the most recently completed task.
        /// </summary>
        private List<FileAccessData> _fileAccessData = new List<FileAccessData>();
#endif

        /// <summary>
        /// Counter for generating unique request IDs for callback correlation.
        /// </summary>
        private int _nextCallbackRequestId;

        /// <summary>
        /// Pending callback requests awaiting responses from the owning worker node.
        /// Key is the request ID, value is the TaskCompletionSource to signal when response arrives.
        /// </summary>
        private readonly ConcurrentDictionary<int, TaskCompletionSource<INodePacket>> _pendingCallbackRequests = new();

        /// <summary>
        /// All active task execution contexts, keyed by task ID.
        /// Supports nested task execution when tasks block on BuildProjectFile callbacks.
        /// </summary>
        private readonly ConcurrentDictionary<int, TaskExecutionContext> _taskContexts
            = new ConcurrentDictionary<int, TaskExecutionContext>();

        /// <summary>
        /// The task context for the calling thread. Each task runs on its own thread
        /// (spawned in HandleTaskHostConfiguration). When Task A blocks on BuildProjectFile,
        /// Task B starts on a new thread. AsyncLocal ensures each thread sees its own context
        /// for logging, pending callbacks, and environment state.
        /// </summary>
        private readonly AsyncLocal<TaskExecutionContext> _currentTaskContext
            = new AsyncLocal<TaskExecutionContext>();

#if FEATURE_APPDOMAIN
        private const string TaskContextIdSlot = "MSBuild.TaskHost.TaskContextId";
#endif

        /// <summary>
        /// Counter for generating task IDs when configuration doesn't provide one.
        /// </summary>
        private int _nextLocalTaskId;

        /// <summary>
        /// The packet version negotiated with the owning worker node.
        /// Used to determine if the worker node supports callback packets.
        /// </summary>
        private byte _parentPacketVersion;

        /// <summary>
        /// Minimum packet version required for IBuildEngine callback support.
        /// </summary>
        private const byte CallbacksMinPacketVersion = 4;

        /// <summary>
        /// Whether the owning worker node supports IBuildEngine callbacks.
        /// True if the worker node's packet version is high enough.
        /// </summary>
        private bool CallbacksSupported => _parentPacketVersion >= CallbacksMinPacketVersion;

        private RedirectConsoleWriter _consoleOutWriter;

        private RedirectConsoleWriter _consoleErrorWriter;

        private TextWriter _originalConsoleOut;

        private TextWriter _originalConsoleError;

        /// <summary>
        /// Gets the effective configuration for the current task thread.
        /// Uses the per-task context first, falling back to <see cref="_currentConfiguration"/>.
        /// </summary>
        private TaskHostConfiguration EffectiveConfiguration => GetCurrentConfiguration();

        /// <summary>
        /// Constructor.
        /// </summary>
        public OutOfProcTaskHostNode()
        {
            // We don't know what the current build thinks this variable should be until RunTask(), but as a fallback in case there are
            // communications before we get the configuration set up, just go with what was already in the environment from when this node
            // was initially launched.
            _debugCommunications = Traits.Instance.DebugNodeCommunication;

            _receivedPackets = new Queue<INodePacket>();

            // These WaitHandles are disposed in HandleShutDown()
            _packetReceivedEvent = new AutoResetEvent(false);
            _shutdownEvent = new ManualResetEvent(false);
            _taskCompleteEvent = new AutoResetEvent(false);
            _taskCancelledEvent = new ManualResetEvent(false);

            _packetFactory = new NodePacketFactory();

            INodePacketFactory thisINodePacketFactory = (INodePacketFactory)this;

            thisINodePacketFactory.RegisterPacketHandler(NodePacketType.TaskHostConfiguration, TaskHostConfiguration.FactoryForDeserialization, this);
            thisINodePacketFactory.RegisterPacketHandler(NodePacketType.TaskHostTaskCancelled, TaskHostTaskCancelled.FactoryForDeserialization, this);
            thisINodePacketFactory.RegisterPacketHandler(NodePacketType.NodeBuildComplete, NodeBuildComplete.FactoryForDeserialization, this);
            thisINodePacketFactory.RegisterPacketHandler(NodePacketType.TaskHostIsRunningMultipleNodesResponse, TaskHostIsRunningMultipleNodesResponse.FactoryForDeserialization, this);
            thisINodePacketFactory.RegisterPacketHandler(NodePacketType.TaskHostCoresResponse, TaskHostCoresResponse.FactoryForDeserialization, this);
            thisINodePacketFactory.RegisterPacketHandler(NodePacketType.TaskHostBuildResponse, TaskHostBuildResponse.FactoryForDeserialization, this);
            thisINodePacketFactory.RegisterPacketHandler(NodePacketType.TaskHostConsoleConfiguration, TaskHostConsoleConfiguration.FactoryForDeserialization, this);
            EngineServices = new EngineServicesImpl(this);
        }

        #region IBuildEngine Implementation (Properties)

        /// <summary>
        /// Returns the value of ContinueOnError for the currently executing task.
        /// </summary>
        public bool ContinueOnError
        {
            get
            {
                Assumed.NotNull(EffectiveConfiguration, "We should never have a null configuration during a BuildEngine callback!");
                return EffectiveConfiguration.ContinueOnError;
            }
        }

        /// <summary>
        /// Returns the line number of the location in the project file of the currently executing task.
        /// </summary>
        public int LineNumberOfTaskNode
        {
            get
            {
                Assumed.NotNull(EffectiveConfiguration, "We should never have a null configuration during a BuildEngine callback!");
                return EffectiveConfiguration.LineNumberOfTask;
            }
        }

        /// <summary>
        /// Returns the column number of the location in the project file of the currently executing task.
        /// </summary>
        public int ColumnNumberOfTaskNode
        {
            get
            {
                Assumed.NotNull(EffectiveConfiguration, "We should never have a null configuration during a BuildEngine callback!");
                return EffectiveConfiguration.ColumnNumberOfTask;
            }
        }

        /// <summary>
        /// Returns the project file of the currently executing task.
        /// </summary>
        public string ProjectFileOfTaskNode
        {
            get
            {
                Assumed.NotNull(EffectiveConfiguration, "We should never have a null configuration during a BuildEngine callback!");
                return EffectiveConfiguration.ProjectFileOfTask;
            }
        }

        #endregion // IBuildEngine Implementation (Properties)

        #region IBuildEngine2 Implementation (Properties)

        /// <summary>
        /// Implementation of IBuildEngine2.IsRunningMultipleNodes.
        /// Queries the owning worker node and returns the actual value.
        /// Returns false if the worker node doesn't support callbacks (cross-version scenario).
        /// </summary>
        public bool IsRunningMultipleNodes
        {
            get
            {
                if (!CallbacksSupported)
                {
                    LogErrorFromResource("BuildEngineCallbacksInTaskHostUnsupported");
                    return false;
                }

                var request = new TaskHostIsRunningMultipleNodesRequest();
                var response = SendCallbackRequestAndWaitForResponse<TaskHostIsRunningMultipleNodesResponse>(request);
                return response.IsRunningMultipleNodes;
            }
        }

        #endregion // IBuildEngine2 Implementation (Properties)

        #region IBuildEngine7 Implementation
        /// <summary>
        /// Enables or disables emitting a default error when a task fails without logging errors
        /// </summary>
        public bool AllowFailureWithoutError
        {
            get
            {
                TaskExecutionContext context = GetCurrentTaskContext();
                Assumed.NotNull(context);
                return context.AllowFailureWithoutError;
            }
            set
            {
                TaskExecutionContext context = GetCurrentTaskContext();
                Assumed.NotNull(context);
                context.AllowFailureWithoutError = value;
            }
        }
        #endregion

        #region IBuildEngine8 Implementation

        /// <summary>
        /// Contains all warnings that should be logged as errors.
        /// Non-null empty set when all warnings should be treated as errors.
        /// Fallback for code paths without a TaskExecutionContext (e.g., main thread).
        /// Task threads use EffectiveWarningsAs* which reads per-task context first.
        /// </summary>
        private ICollection<string> _warningsAsErrors;

        /// <summary>Fallback for WarningsNotAsErrors. See <see cref="_warningsAsErrors"/>.</summary>
        private ICollection<string> _warningsNotAsErrors;

        /// <summary>Fallback for WarningsAsMessages. See <see cref="_warningsAsErrors"/>.</summary>
        private ICollection<string> _warningsAsMessages;

        /// <summary>
        /// Gets the effective WarningsAsErrors for the current task context.
        /// Uses per-task saved values when available (during concurrent execution),
        /// falling back to the shared field.
        /// </summary>
        private ICollection<string> EffectiveWarningsAsErrors
        {
            get
            {
                var context = GetCurrentTaskContext();
                return context?.WarningsAsErrors ?? _warningsAsErrors;
            }
        }

        private ICollection<string> EffectiveWarningsNotAsErrors
        {
            get
            {
                var context = GetCurrentTaskContext();
                return context?.WarningsNotAsErrors ?? _warningsNotAsErrors;
            }
        }

        private ICollection<string> EffectiveWarningsAsMessages
        {
            get
            {
                var context = GetCurrentTaskContext();
                return context?.WarningsAsMessages ?? _warningsAsMessages;
            }
        }

        public bool ShouldTreatWarningAsError(string warningCode)
        {
            var warningsAsErrors = EffectiveWarningsAsErrors;
            var warningsAsMessages = EffectiveWarningsAsMessages;

            // Warnings as messages overrides warnings as errors.
            if (warningsAsErrors is null || warningsAsMessages?.Contains(warningCode) == true)
            {
                return false;
            }

            if (ChangeWaves.AreFeaturesEnabled(ChangeWaves.Wave18_6))
            {
                // An empty set means all warnings are errors.
                return (warningsAsErrors.Count == 0 && WarningAsErrorNotOverriden(warningCode)) || warningsAsErrors.Contains(warningCode);
            }

            // Pre-18.6 behavior preserved for backward compatibility: incorrectly checks WarningsAsMessages instead of WarningsAsErrors.
            return (warningsAsErrors.Count == 0 && WarningAsErrorNotOverriden(warningCode)) || warningsAsMessages.Contains(warningCode);
        }

        private bool WarningAsErrorNotOverriden(string warningCode)
        {
            return EffectiveWarningsNotAsErrors?.Contains(warningCode) != true;
        }
        #endregion

        #region IBuildEngine Implementation (Methods)

        /// <summary>
        /// Sends the provided error back to the owning worker node to be logged, tagging it with
        /// the worker node's ID so that, as far as anyone is concerned, it might as well have
        /// just come from the worker node to begin with.
        /// </summary>
        public void LogErrorEvent(BuildErrorEventArgs e)
        {
            SendBuildEvent(e);
        }

        /// <summary>
        /// Sends the provided warning back to the owning worker node to be logged, tagging it with
        /// the worker node's ID so that, as far as anyone is concerned, it might as well have
        /// just come from the worker node to begin with.
        /// </summary>
        public void LogWarningEvent(BuildWarningEventArgs e)
        {
            SendBuildEvent(e);
        }

        /// <summary>
        /// Sends the provided message back to the owning worker node to be logged, tagging it with
        /// the worker node's ID so that, as far as anyone is concerned, it might as well have
        /// just come from the worker node to begin with.
        /// </summary>
        public void LogMessageEvent(BuildMessageEventArgs e)
        {
            SendBuildEvent(e);
        }

        /// <summary>
        /// Sends the provided custom event back to the owning worker node to be logged, tagging it with
        /// the worker node's ID so that, as far as anyone is concerned, it might as well have
        /// just come from the worker node to begin with.
        /// </summary>
        public void LogCustomEvent(CustomBuildEventArgs e)
        {
            SendBuildEvent(e);
        }

        /// <summary>
        /// Implementation of IBuildEngine.BuildProjectFile. Delegates to the 5-param overload.
        /// </summary>
        public bool BuildProjectFile(string projectFileName, string[] targetNames, IDictionary globalProperties, IDictionary targetOutputs)
        {
            if (!CallbacksSupported)
            {
                LogErrorFromResource("BuildEngineCallbacksInTaskHostUnsupported");
                return false;
            }

            return BuildProjectFile(projectFileName, targetNames, globalProperties, targetOutputs, null);
        }

        #endregion // IBuildEngine Implementation (Methods)

        #region IBuildEngine2 Implementation (Methods)

        /// <summary>
        /// Implementation of IBuildEngine2.BuildProjectFile. Delegates to the 7-param BuildProjectFilesInParallel.
        /// </summary>
        public bool BuildProjectFile(string projectFileName, string[] targetNames, IDictionary globalProperties, IDictionary targetOutputs, string toolsVersion)
        {
            if (!CallbacksSupported)
            {
                LogErrorFromResource("BuildEngineCallbacksInTaskHostUnsupported");
                return false;
            }

            return BuildProjectFilesInParallel(
                [projectFileName],
                targetNames,
                [globalProperties],
                [targetOutputs],
                [toolsVersion],
                true,
                false);
        }

        /// <summary>
        /// Implementation of IBuildEngine2.BuildProjectFilesInParallel. Delegates to the 6-param IBuildEngine3 overload.
        /// </summary>
        public bool BuildProjectFilesInParallel(string[] projectFileNames, string[] targetNames, IDictionary[] globalProperties, IDictionary[] targetOutputsPerProject, string[] toolsVersion, bool useResultsCache, bool unloadProjectsOnCompletion)
        {
            if (!CallbacksSupported)
            {
                LogErrorFromResource("BuildEngineCallbacksInTaskHostUnsupported");
                return false;
            }

            if (projectFileNames is null)
            {
                return false;
            }

            Assumed.True(targetOutputsPerProject is null || projectFileNames.Length == targetOutputsPerProject.Length, $"projectFileNames has {projectFileNames.Length} entries but targetOutputsPerProject has {targetOutputsPerProject?.Length ?? 0} -- lengths must match.");

            bool includeTargetOutputs = targetOutputsPerProject is not null;

            BuildEngineResult result = BuildProjectFilesInParallel(projectFileNames, targetNames, globalProperties, new List<string>[projectFileNames.Length], toolsVersion, includeTargetOutputs);

            if (includeTargetOutputs && result.TargetOutputsPerProject is not null)
            {
                for (int i = 0; i < targetOutputsPerProject.Length && i < result.TargetOutputsPerProject.Count; i++)
                {
                    if (targetOutputsPerProject[i] is not null)
                    {
                        foreach (KeyValuePair<string, ITaskItem[]> output in result.TargetOutputsPerProject[i])
                        {
                            targetOutputsPerProject[i].Add(output.Key, output.Value);
                        }
                    }
                }
            }

            return result.Result;
        }

        #endregion // IBuildEngine2 Implementation (Methods)

        #region IBuildEngine3 Implementation

        /// <summary>
        /// Implementation of IBuildEngine3.BuildProjectFilesInParallel. This is the canonical form that
        /// sends the request to the owning worker node and waits for the response.
        /// </summary>
        public BuildEngineResult BuildProjectFilesInParallel(string[] projectFileNames, string[] targetNames, IDictionary[] globalProperties, IList<string>[] removeGlobalProperties, string[] toolsVersion, bool returnTargetOutputs)
        {
            if (!CallbacksSupported)
            {
                LogErrorFromResource("BuildEngineCallbacksInTaskHostUnsupported");
                return new BuildEngineResult(false, null);
            }

            string projectFilesJoined = null;

            if (MSBuildEventSource.Log.IsEnabled())
            {
                projectFilesJoined = string.Join(";", projectFileNames ?? []);
                string targetNamesJoined = string.Join(";", targetNames ?? []);
                MSBuildEventSource.Log.TaskHostBuildProjectFileStart(projectFilesJoined, targetNamesJoined);
            }

            var request = new TaskHostBuildRequest(
                projectFileNames,
                targetNames,
                TaskHostBuildRequest.ConvertGlobalProperties(globalProperties),
                TaskHostBuildRequest.ConvertRemoveGlobalProperties(removeGlobalProperties),
                toolsVersion,
                returnTargetOutputs);

            // Block while the callback is processed so the node can accept nested tasks.
            BlockForCallback();
            bool success = false;
            try
            {
                var response = SendCallbackRequestAndWaitForResponse<TaskHostBuildResponse>(request);
                var result = response.ToBuildEngineResult();
                success = result.Result;
                return result;
            }
            finally
            {
                if (MSBuildEventSource.Log.IsEnabled())
                {
                    MSBuildEventSource.Log.TaskHostBuildProjectFileStop(projectFilesJoined!, success);
                }

                ResumeAfterCallback();
            }
        }

        /// <summary>
        /// No-op. Explicit yield is not supported in the OOP TaskHost.
        /// Nested task dispatch uses BuildProjectFile callback blocking instead.
        /// </summary>
        public void Yield()
        {
        }

        /// <summary>
        /// No-op. See <see cref="Yield"/>.
        /// </summary>
        public void Reacquire()
        {
        }

        #endregion // IBuildEngine3 Implementation

        #region IBuildEngine4 Implementation

        /// <summary>
        /// Registers an object with the system that will be disposed of at some specified time
        /// in the future.
        /// </summary>
        /// <param name="key">The key used to retrieve the object.</param>
        /// <param name="obj">The object to be held for later disposal.</param>
        /// <param name="lifetime">The lifetime of the object.</param>
        /// <param name="allowEarlyCollection">The object may be disposed earlier that the requested time if
        /// MSBuild needs to reclaim memory.</param>
        public void RegisterTaskObject(object key, object obj, RegisteredTaskObjectLifetime lifetime, bool allowEarlyCollection)
        {
            _registeredTaskObjectCache.RegisterTaskObject(key, obj, lifetime, allowEarlyCollection);
        }

        /// <summary>
        /// Retrieves a previously registered task object stored with the specified key.
        /// </summary>
        /// <param name="key">The key used to retrieve the object.</param>
        /// <param name="lifetime">The lifetime of the object.</param>
        /// <returns>
        /// The registered object, or null is there is no object registered under that key or the object
        /// has been discarded through early collection.
        /// </returns>
        public object GetRegisteredTaskObject(object key, RegisteredTaskObjectLifetime lifetime)
        {
            return _registeredTaskObjectCache.GetRegisteredTaskObject(key, lifetime);
        }

        /// <summary>
        /// Unregisters a previously-registered task object.
        /// </summary>
        /// <param name="key">The key used to retrieve the object.</param>
        /// <param name="lifetime">The lifetime of the object.</param>
        /// <returns>
        /// The registered object, or null is there is no object registered under that key or the object
        /// has been discarded through early collection.
        /// </returns>
        public object UnregisterTaskObject(object key, RegisteredTaskObjectLifetime lifetime)
        {
            return _registeredTaskObjectCache.UnregisterTaskObject(key, lifetime);
        }

        #endregion

        #region IBuildEngine5 Implementation

        /// <summary>
        /// Logs a telemetry event.
        /// </summary>
        /// <param name="eventName">The event name.</param>
        /// <param name="properties">The list of properties associated with the event.</param>
        public void LogTelemetry(string eventName, IDictionary<string, string> properties)
        {
            SendBuildEvent(new TelemetryEventArgs
            {
                EventName = eventName,
                Properties = properties == null ? new Dictionary<string, string>() : new Dictionary<string, string>(properties),
            });
        }

        #endregion

        #region IBuildEngine6 Implementation

        /// <summary>
        /// Gets the global properties for the current project.
        /// </summary>
        /// <returns>An <see cref="IReadOnlyDictionary{String, String}" /> containing the global properties of the current project.</returns>
        public IReadOnlyDictionary<string, string> GetGlobalProperties()
        {
            return new Dictionary<string, string>(EffectiveConfiguration.GlobalProperties);
        }

        #endregion

        #region IBuildEngine9 Implementation

        public int RequestCores(int requestedCores)
        {
            ArgumentOutOfRangeException.ThrowIfNegativeOrZero(requestedCores);

            if (!CallbacksSupported)
            {
                // Callbacks not available (cross-version scenario). Throw so callers' existing
                // catch (NotImplementedException) blocks fire and fall back gracefully.
                throw new NotImplementedException();
            }

            var request = new TaskHostCoresRequest(requestedCores, isRelease: false);
            var response = SendCallbackRequestAndWaitForResponse<TaskHostCoresResponse>(request);
            return response.GrantedCores;
        }

        public void ReleaseCores(int coresToRelease)
        {
            ArgumentOutOfRangeException.ThrowIfNegativeOrZero(coresToRelease);

            if (!CallbacksSupported)
            {
                throw new NotImplementedException();
            }

            var request = new TaskHostCoresRequest(coresToRelease, isRelease: true);
            SendCallbackRequestAndWaitForResponse<TaskHostCoresResponse>(request);
        }

        #endregion

        #region IBuildEngine10 Members

        [Serializable]
        private sealed class EngineServicesImpl : EngineServices
        {
            private readonly OutOfProcTaskHostNode _taskHost;

            internal EngineServicesImpl(OutOfProcTaskHostNode taskHost)
            {
                _taskHost = taskHost;
            }

            /// <summary>
            /// No logging verbosity optimization in OOP nodes.
            /// </summary>
            public override bool LogsMessagesOfImportance(MessageImportance importance) => true;

            /// <inheritdoc />
            public override bool IsTaskInputLoggingEnabled
            {
                get
                {
                    Assumed.NotNull(_taskHost.EffectiveConfiguration, "We should never have a null configuration during a BuildEngine callback!");
                    return _taskHost.EffectiveConfiguration.IsTaskInputLoggingEnabled;
                }
            }

#if FEATURE_REPORTFILEACCESSES
            /// <summary>
            /// Reports a file access from a task.
            /// </summary>
            /// <param name="fileAccessData">The file access to report.</param>
            public void ReportFileAccess(FileAccessData fileAccessData)
            {
                _taskHost._fileAccessData.Add(fileAccessData);
            }
#endif
        }

        public EngineServices EngineServices { get; }

        #endregion

        #region INodePacketFactory Members

        /// <summary>
        /// Registers the specified handler for a particular packet type.
        /// </summary>
        /// <param name="packetType">The packet type.</param>
        /// <param name="factory">The factory for packets of the specified type.</param>
        /// <param name="handler">The handler to be called when packets of the specified type are received.</param>
        public void RegisterPacketHandler(NodePacketType packetType, NodePacketFactoryMethod factory, INodePacketHandler handler)
        {
            _packetFactory.RegisterPacketHandler(packetType, factory, handler);
        }

        /// <summary>
        /// Unregisters a packet handler.
        /// </summary>
        /// <param name="packetType">The packet type.</param>
        public void UnregisterPacketHandler(NodePacketType packetType)
        {
            _packetFactory.UnregisterPacketHandler(packetType);
        }

        /// <summary>
        /// Takes a serializer, deserializes the packet and routes it to the appropriate handler.
        /// </summary>
        /// <param name="nodeId">The node from which the packet was received.</param>
        /// <param name="packetType">The packet type.</param>
        /// <param name="translator">The translator containing the data from which the packet should be reconstructed.</param>
        public void DeserializeAndRoutePacket(int nodeId, NodePacketType packetType, ITranslator translator)
        {
            _packetFactory.DeserializeAndRoutePacket(nodeId, packetType, translator);
        }

        /// <summary>
        /// Takes a serializer and deserializes the packet.
        /// </summary>
        /// <param name="packetType">The packet type.</param>
        /// <param name="translator">The translator containing the data from which the packet should be reconstructed.</param>
        public INodePacket DeserializePacket(NodePacketType packetType, ITranslator translator)
        {
            return _packetFactory.DeserializePacket(packetType, translator);
        }

        /// <summary>
        /// Routes the specified packet
        /// </summary>
        /// <param name="nodeId">The node from which the packet was received.</param>
        /// <param name="packet">The packet to route.</param>
        public void RoutePacket(int nodeId, INodePacket packet)
        {
            _packetFactory.RoutePacket(nodeId, packet);
        }

        #endregion // INodePacketFactory Members

        #region INodePacketHandler Members

        /// <summary>
        /// This method is invoked by the NodePacketRouter when a packet is received and is intended for
        /// this recipient.
        /// </summary>
        /// <param name="node">The node from which the packet was received.</param>
        /// <param name="packet">The packet.</param>
        public void PacketReceived(int node, INodePacket packet)
        {
            lock (_receivedPackets)
            {
                _receivedPackets.Enqueue(packet);
                _packetReceivedEvent.Set();
            }
        }

        #endregion // INodePacketHandler Members

        #region INode Members

        /// <summary>
        /// Starts up the node and processes messages until the node is requested to shut down.
        /// </summary>
        /// <param name="shutdownException">The exception which caused shutdown, if any.</param>
        /// <returns>The reason for shutting down.</returns>
        public NodeEngineShutdownReason Run(out Exception shutdownException, bool nodeReuse = false, byte parentPacketVersion = 1)
        {
            _registeredTaskObjectCache = new RegisteredTaskObjectCacheBase();
            _parentPacketVersion = parentPacketVersion;

            shutdownException = null;

            // Snapshot the current environment
            _savedEnvironment = CommunicationsUtilities.GetEnvironmentVariables();

            _nodeReuse = nodeReuse;
            _nodeEndpoint = new NodeEndpointOutOfProcTaskHost(nodeReuse, parentPacketVersion);
            _nodeEndpoint.OnLinkStatusChanged += new LinkStatusChangedDelegate(OnLinkStatusChanged);
            _nodeEndpoint.Listen(this);

            WaitHandle[] waitHandles = [_shutdownEvent, _packetReceivedEvent, _taskCompleteEvent, _taskCancelledEvent];

            while (true)
            {
                int index = WaitHandle.WaitAny(waitHandles);
                switch (index)
                {
                    case 0: // shutdownEvent
                        NodeEngineShutdownReason shutdownReason = HandleShutdown();
                        return shutdownReason;

                    case 1: // packetReceivedEvent
                        INodePacket packet = null;

                        int packetCount = _receivedPackets.Count;

                        while (packetCount > 0)
                        {
                            lock (_receivedPackets)
                            {
                                if (_receivedPackets.Count > 0)
                                {
                                    packet = _receivedPackets.Dequeue();
                                }
                                else
                                {
                                    break;
                                }
                            }

                            if (packet != null)
                            {
                                HandlePacket(packet);
                            }
                        }

                        break;
                    case 2: // taskCompleteEvent
                        CompleteTask();
                        break;
                    case 3: // taskCancelledEvent
                        CancelTask();
                        break;
                }
            }

            // UNREACHABLE
        }
        #endregion

        /// <summary>
        /// Dispatches the packet to the correct handler.
        /// </summary>
        private void HandlePacket(INodePacket packet)
        {
            switch (packet.Type)
            {
                case NodePacketType.TaskHostConfiguration:
                    HandleTaskHostConfiguration(packet as TaskHostConfiguration);
                    break;
                case NodePacketType.TaskHostTaskCancelled:
                    _taskCancelledEvent.Set();
                    break;
                case NodePacketType.NodeBuildComplete:
                    HandleNodeBuildComplete(packet as NodeBuildComplete);
                    break;
                case NodePacketType.TaskHostConsoleConfiguration:
                    InitializeConsoleRedirection();
                    break;

                // Callback response packets - route to pending request
                case NodePacketType.TaskHostIsRunningMultipleNodesResponse:
                case NodePacketType.TaskHostCoresResponse:
                case NodePacketType.TaskHostBuildResponse:
                    HandleCallbackResponse(packet);
                    break;
            }
        }

        /// <summary>
        /// Handles a callback response packet by completing the pending request's TaskCompletionSource.
        /// This is called on the main thread and unblocks the task thread waiting for the response.
        /// </summary>
        private void HandleCallbackResponse(INodePacket packet)
        {
            if (packet is not ITaskHostCallbackPacket callbackPacket)
            {
                InternalError.Throw($"HandleCallbackResponse called with non-callback packet type: {packet.GetType().Name}");
                return;
            }

            // Try per-task context pending requests first, then fall back to global
            foreach (var kvp in _taskContexts)
            {
                if (kvp.Value.PendingCallbackRequests.TryRemove(callbackPacket.RequestId, out TaskCompletionSource<INodePacket> tcsFromContext))
                {
                    tcsFromContext.TrySetResult(packet);
                    return;
                }
            }

            if (_pendingCallbackRequests.TryRemove(callbackPacket.RequestId, out TaskCompletionSource<INodePacket> tcs))
            {
                tcs.TrySetResult(packet);
                return;
            }

            // No pending request matched -- this is a protocol bug (duplicate response,
            // corrupted request ID, or race with shutdown). Crash to surface the issue.
            InternalError.Throw($"TaskHost received callback response with no pending request. RequestId={callbackPacket.RequestId}, Type={packet.Type}");
        }

        /// <summary>
        /// Sends a callback request packet to the owning worker node and waits for the corresponding response.
        /// This is called from task threads and blocks until the response arrives on the main thread.
        /// </summary>
        /// <typeparam name="TResponse">The expected response packet type.</typeparam>
        /// <param name="request">The request packet to send (must implement ITaskHostCallbackPacket).</param>
        /// <returns>The response packet.</returns>
        /// <exception cref="InvalidOperationException">If the connection is lost.</exception>
        /// <remarks>
        /// This method is infrastructure for callback support. Used by IsRunningMultipleNodes,
        /// RequestCores/ReleaseCores, BuildProjectFile, etc.
        ///
        /// We intentionally do NOT check _taskCancelledEvent here. This aligns with in-process
        /// mode where IBuildEngine callbacks are direct method calls that complete regardless of
        /// cancellation state. The owning worker node continues processing callback requests even after
        /// sending TaskHostTaskCancelled, so the response will arrive. Cancellation is handled
        /// cooperatively via ICancelableTask.Cancel() on the task itself.
        ///
        /// NOTE: Unlike in-process mode, the IPC mechanism here *could* support cancellation-aware
        /// callbacks by failing the TCS when _taskCancelledEvent is signaled. This is a future
        /// opportunity if we need to abort long-running callbacks (e.g. BuildProjectFile) immediately
        /// on cancellation rather than waiting for the worker node to respond.
        ///
        /// Connection loss is handled by OnLinkStatusChanged, which fails all pending TCS
        /// with InvalidOperationException, causing this method to throw immediately.
        /// </remarks>
        private TResponse SendCallbackRequestAndWaitForResponse<TResponse>(ITaskHostCallbackPacket request)
            where TResponse : class, INodePacket
        {
            // Get context - use per-task pending requests if available
            var context = GetCurrentTaskContext();
            var pendingRequests = context?.PendingCallbackRequests ?? _pendingCallbackRequests;

            // Request IDs are unique across all task contexts for the process lifetime
            // (monotonic counter, never resets) to prevent cross-task or stale response misdelivery.
            int requestId = Interlocked.Increment(ref _nextCallbackRequestId);
            request.RequestId = requestId;

            var tcs = new TaskCompletionSource<INodePacket>(TaskCreationOptions.RunContinuationsAsynchronously);
            pendingRequests[requestId] = tcs;

            try
            {
                // Send the request packet to the owning worker node
                _nodeEndpoint.SendData(request);

                // Block until the response arrives (via HandleCallbackResponse -> TCS.SetResult)
                // or the connection is lost (via OnLinkStatusChanged -> TCS.TrySetException).
                // No timeout - callbacks like BuildProjectFile can legitimately take hours.
                INodePacket response = tcs.Task.GetAwaiter().GetResult();

                if (response is TResponse typedResponse)
                {
                    return typedResponse;
                }

                throw new InvalidOperationException(
                    $"Unexpected callback response type: expected {typeof(TResponse).Name}, got {response?.GetType().Name ?? "null"}");
            }
            finally
            {
                pendingRequests.TryRemove(requestId, out _);
            }
        }

        /// <summary>
        /// Marks this task as blocked on a callback so the node can accept nested tasks.
        /// Saves the current operating environment before blocking.
        /// </summary>
        private void BlockForCallback()
        {
            var context = GetCurrentTaskContext();
            if (context is not null)
            {
                SaveOperatingEnvironment(context);
                context.State = TaskExecutionState.BlockedOnCallback;
            }

            // Transition from "active" to "blocked" state.
            Interlocked.Increment(ref _blockedTaskCount);
            Interlocked.Decrement(ref _activeTaskCount);
        }

        /// <summary>
        /// Marks this task as active again after a callback completes.
        /// Restores the previously saved operating environment.
        /// </summary>
        private void ResumeAfterCallback()
        {
            // Transition from "blocked" back to "active" state.
            Interlocked.Increment(ref _activeTaskCount);
            Interlocked.Decrement(ref _blockedTaskCount);

            // Restore environment state after resuming
            var context = GetCurrentTaskContext();
            if (context is not null)
            {
                RestoreOperatingEnvironment(context);
                context.State = TaskExecutionState.Executing;
            }
        }

        /// <summary>
        /// Gets the task execution context for the current thread.
        /// </summary>
        private TaskExecutionContext GetCurrentTaskContext()
        {
            TaskExecutionContext context = _currentTaskContext.Value;
#if FEATURE_APPDOMAIN
            // AsyncLocal values do not cross AppDomain boundaries. Resolve the serialized task ID.
            if (context is null && CallContext.LogicalGetData(TaskContextIdSlot) is int taskId)
            {
                _taskContexts.TryGetValue(taskId, out context);
            }
#endif
            return context;
        }

        /// <summary>
        /// Gets the configuration for the currently executing task on this thread.
        /// On task threads, returns the per-task context configuration.
        /// On the main communication thread (e.g., infrastructure logging), the context
        /// is null so this falls back to the global <see cref="_currentConfiguration"/>.
        /// </summary>
        private TaskHostConfiguration GetCurrentConfiguration()
        {
            var context = GetCurrentTaskContext();
            return context?.Configuration ?? _currentConfiguration;
        }

        /// <summary>
        /// Creates a new task execution context for the given configuration.
        /// </summary>
        private TaskExecutionContext CreateTaskContext(TaskHostConfiguration configuration)
        {
            int taskId = Interlocked.Increment(ref _nextLocalTaskId);

            var context = new TaskExecutionContext(taskId, configuration);

            if (!_taskContexts.TryAdd(taskId, context))
            {
                context.Dispose();
                InternalError.Throw($"Task ID {taskId} already exists in TaskHost.");
            }

            return context;
        }

        /// <summary>
        /// Removes and disposes a task execution context.
        /// </summary>
        private void RemoveTaskContext(int taskId)
        {
            if (_taskContexts.TryRemove(taskId, out var context))
            {
                context.Dispose();
            }
        }

        /// <summary>
        /// Saves the current operating environment to the task context.
        /// Called before blocking on a callback that allows other tasks to run.
        /// </summary>
        private void SaveOperatingEnvironment(TaskExecutionContext context)
        {
            ArgumentNullException.ThrowIfNull(context);

            // A task is about to block and let a nested task run, which may change the process environment.
            _lastAppliedConfigEnvironment = null;

            context.SavedCurrentDirectory = Environment.CurrentDirectory;
            context.SavedEnvironment = new Dictionary<string, string>(
                CommunicationsUtilities.GetEnvironmentVariables(),
                StringComparer.OrdinalIgnoreCase);

            // Save debug/environment flags that are overwritten per-task in RunTask
            context.SavedDebugCommunications = _debugCommunications;
            context.SavedUpdateEnvironment = _updateEnvironment;
            context.SavedUpdateEnvironmentAndLog = _updateEnvironmentAndLog;
        }

        /// <summary>
        /// Restores the previously saved operating environment from the task context.
        /// </summary>
        private void RestoreOperatingEnvironment(TaskExecutionContext context)
        {
            ArgumentNullException.ThrowIfNull(context);

            if (context.SavedCurrentDirectory is null || context.SavedEnvironment is null)
            {
                return;
            }

            CommunicationsUtilities.SetEnvironment(context.SavedEnvironment);
            NativeMethodsShared.SetCurrentDirectory(context.SavedCurrentDirectory);

            // Restore debug/environment flags
            _debugCommunications = context.SavedDebugCommunications;
            _updateEnvironment = context.SavedUpdateEnvironment;
            _updateEnvironmentAndLog = context.SavedUpdateEnvironmentAndLog;

            context.SavedCurrentDirectory = null;
            context.SavedEnvironment = null;
        }

        /// <summary>
        /// Configure the task host according to the information received in the
        /// configuration packet
        /// </summary>
        private void HandleTaskHostConfiguration(TaskHostConfiguration taskHostConfiguration)
        {
            // Only _activeTaskCount must be zero — blocked tasks (waiting on BuildProjectFile
            // callbacks) don't prevent accepting a new nested task configuration.
            Assumed.Zero(_activeTaskCount, $"Why are we getting a TaskHostConfiguration packet while a task is actively executing? activeTaskCount={_activeTaskCount}");

            if (_blockedTaskCount > 0)
            {
                CommunicationsUtilities.Trace($"Nested task {taskHostConfiguration.TaskName} dispatched while {_blockedTaskCount} tasks are blocked on callbacks.");
            }

            _currentConfiguration = taskHostConfiguration;
            _parentPacketVersion = _nodeEndpoint.NegotiatedPacketVersion;
            ResolveIncomingEnvironment(taskHostConfiguration);
            ResolveIncomingGlobalParameters(taskHostConfiguration);

            // Create task execution context for this task
            var context = CreateTaskContext(taskHostConfiguration);
            context.State = TaskExecutionState.Executing;

            // Kick off the task running thread.
            var taskThread = new Thread(new ParameterizedThreadStart(RunTask));
            taskThread.Name = "Task runner for task " + taskHostConfiguration.TaskName;
            context.ExecutingThread = taskThread;

            taskThread.Start(context);
        }

        /// <summary>
        /// Resolves the build process environment of an incoming configuration. When the parent marked it
        /// <see cref="InvariantPayloadTransferMode.Identical"/> the environment was not serialized on the
        /// wire, so it is reconstructed from this connection's baseline; otherwise the baseline is refreshed
        /// with the full environment that was sent.
        /// </summary>
        private void ResolveIncomingEnvironment(TaskHostConfiguration configuration)
        {
            if (configuration.EnvironmentMode == InvariantPayloadTransferMode.Identical)
            {
                Assumed.NotNull(_forwardEnvironmentBaseline, "Received an EnvironmentIdentical TaskHostConfiguration before any full build process environment was sent on this connection.");
                configuration.SetResolvedBuildProcessEnvironment(_forwardEnvironmentBaseline);
            }
            else
            {
                _forwardEnvironmentBaseline = configuration.BuildProcessEnvironment;
            }
        }

        /// <summary>
        /// Resolves the global properties of an incoming configuration. When the parent marked them
        /// <see cref="InvariantPayloadTransferMode.Identical"/> they were not serialized on the wire, so they are
        /// reconstructed from this connection's baseline; otherwise the baseline is refreshed with the full
        /// dictionary that was sent.
        /// </summary>
        private void ResolveIncomingGlobalParameters(TaskHostConfiguration configuration)
        {
            if (configuration.GlobalParametersMode == InvariantPayloadTransferMode.Identical)
            {
                Assumed.NotNull(_forwardGlobalParametersBaseline, "Received a GlobalParametersIdentical TaskHostConfiguration before any full global properties were sent on this connection.");
                configuration.SetResolvedGlobalParameters(_forwardGlobalParametersBaseline);
            }
            else
            {
                _forwardGlobalParametersBaseline = configuration.GlobalProperties;
            }
        }

        /// <summary>
        /// The task has been completed
        /// </summary>
        private void CompleteTask()
        {
            if (_nodeEndpoint.LinkStatus == LinkStatus.Active)
            {
                while (_taskCompletePackets.TryDequeue(out TaskHostTaskComplete packet))
                {
                    _consoleOutWriter?.Flush();
                    _consoleErrorWriter?.Flush();
                    _nodeEndpoint.SendData(packet);
                }
            }

            // Only clear _currentConfiguration when no tasks remain (active or blocked).
            // A blocked task still needs the config for logging via EffectiveConfiguration.
            if (_activeTaskCount == 0 && _blockedTaskCount == 0)
            {
                _currentConfiguration = null;
            }

            // If the task has been canceled, the event will still be set.
            // If so, now that we've completed the task, we want to shut down
            // this node -- with no reuse, since we don't know whether the
            // task we canceled left the node in a good state or not.
            if (_taskCancelledEvent.WaitOne(0))
            {
                _shutdownReason = NodeEngineShutdownReason.BuildComplete;
                _shutdownEvent.Set();
            }
        }

        /// <summary>
        /// This task has been cancelled. Attempt to cancel the task
        /// </summary>
        private void CancelTask()
        {
            // Cancel all task wrappers -- with nested builds via BuildProjectFile callbacks,
            // multiple tasks may be active on the same TaskHost process.
            foreach (var kvp in _taskContexts)
            {
                var context = kvp.Value;
                lock (context)
                {
                    var ctxWrapper = context.TaskWrapper;
                    if (context.State == TaskExecutionState.Completed || ctxWrapper is null || ctxWrapper.CancelPending)
                    {
                        continue;
                    }

                    // Cancellation runs on the packet-processing thread, not the task's Execute thread.
                    var previousContext = _currentTaskContext.Value;
#if FEATURE_APPDOMAIN
                    object previousContextId = CallContext.LogicalGetData(TaskContextIdSlot);
#endif
                    try
                    {
                        _currentTaskContext.Value = context;
#if FEATURE_APPDOMAIN
                        CallContext.LogicalSetData(TaskContextIdSlot, context.TaskId);
#endif
                        ctxWrapper.CancelTask();
                    }
                    finally
                    {
                        _currentTaskContext.Value = previousContext;
#if FEATURE_APPDOMAIN
                        if (previousContextId is null)
                        {
                            CallContext.FreeNamedDataSlot(TaskContextIdSlot);
                        }
                        else
                        {
                            CallContext.LogicalSetData(TaskContextIdSlot, previousContextId);
                        }
#endif
                    }
                }
            }

            if (Environment.GetEnvironmentVariable("MSBUILDTASKHOSTABORTTASKONCANCEL") == "1")
            {
                if (_activeTaskCount > 0)
                {
#if FEATURE_THREAD_ABORT
                    foreach (var kvp in _taskContexts)
                    {
                        Thread t = kvp.Value.ExecutingThread;
                        if (t is not null && t.IsAlive)
                        {
                            t.Abort();
                        }
                    }
#endif
                }
            }
        }

        /// <summary>
        /// Handles the NodeBuildComplete packet.
        /// </summary>
        private void HandleNodeBuildComplete(NodeBuildComplete buildComplete)
        {
            Assumed.Zero(_activeTaskCount, "We should never have a task in the process of executing when we receive NodeBuildComplete.");

            // When this node is reused for a later build, reset the environment-reuse cache so the first task of
            // the next build performs a fresh apply rather than trusting state left over from this build.
            _lastAppliedConfigEnvironment = null;

            // Only an explicit, negotiated action establishes ownership. Older parents also send
            // PrepareForReuse=true, but expect the TaskHost to disconnect and acknowledge shutdown.
            if (buildComplete.Action == NodeBuildCompleteAction.ReuseWithConnection)
            {
                Assumed.True(_nodeReuse && buildComplete.PrepareForReuse);
                // The parent gates ownership on its change wave. A pooled child may have been
                // launched under a different wave, so its cached wave cannot override this action.
                PrepareForNextBuild();
                _nodeEndpoint.SendData(buildComplete);
                return;
            }

            if (buildComplete.Action == NodeBuildCompleteAction.Shutdown)
            {
                _shutdownReason = NodeEngineShutdownReason.BuildComplete;
                _shutdownEvent.Set();
                return;
            }

            Assumed.Equal(buildComplete.Action, NodeBuildCompleteAction.Legacy);
            if (_nodeReuse)
            {
                // Preserve the legacy pooling policy independently of PrepareForReuse.
                _shutdownReason = NodeEngineShutdownReason.BuildCompleteReuse;
                _shutdownEvent.Set();
                return;
            }

            // TaskHostNodes lock assemblies with custom tasks produced by build scripts if NodeReuse is on. This causes failures if the user builds twice.
            _shutdownReason = buildComplete.PrepareForReuse && Traits.Instance.EscapeHatches.ReuseTaskHostNodes ? NodeEngineShutdownReason.BuildCompleteReuse : NodeEngineShutdownReason.BuildComplete;
            _shutdownEvent.Set();
        }

        /// <summary>
        /// Disposes build-scoped state so this sidecar can serve the next build of its owner
        /// without being torn down and relaunched.
        /// </summary>
        /// <remarks>
        /// A TaskHost used to serve exactly one build: <see cref="XMake"/> constructed a fresh node
        /// per build, so build state was reset by construction and no field could be missed. A
        /// sidecar keeps its connection across builds and tearing the node down would tear that
        /// connection down with it, so it resets in place instead. Every field added to this class
        /// therefore has to be classified: build-scoped fields must be reset here, or their values
        /// leak into the next, unrelated build served by this same process.
        /// </remarks>
        internal void PrepareForNextBuild()
        {
            // Only state that the next build will not re-establish for itself belongs here.
            // Per-task state -- the configuration, the warning sets, the environment flags, the task
            // wrapper and its completion packet -- is assigned unconditionally from each incoming
            // TaskHostConfiguration before it is ever read, so clearing it here would be dead code
            // and clearing the completion queue could discard a result that has not been sent yet.

            // Defensive, and matches HandleShutdown: a task blocked on a callback would never
            // unblock once the parent stops answering for this build. No-op when nothing is pending.
            FailAllPendingCallbackRequests("TaskHost resetting for the next build.");

            // Build-lifetime objects registered by tasks. Nothing else disposes these while the node
            // stays alive; a node that exited at the end of a build did it in HandleShutdown.
            DisposeBuildScopedResources();

            // A cancellation that arrived as the build was ending would otherwise still be signalled
            // and would spin the next build's wait loop.
            _taskCancelledEvent.Reset();

            // Release the build directory while idle; Windows holds a handle to the current directory.
            NativeMethodsShared.SetCurrentDirectory(BuildEnvironmentHelper.Instance.CurrentMSBuildToolsDirectory);

            // Restore the launch environment while idle. RunTask applies the next task's environment.
            try
            {
                CommunicationsUtilities.SetEnvironment(_savedEnvironment);
            }
            catch (Exception ex) when (!ExceptionHandling.IsCriticalException(ex))
            {
                CommunicationsUtilities.Trace($"Failed to restore the sidecar TaskHost environment: {ex}");
            }
        }

        /// <summary>
        /// Perform necessary actions to shut down the node.
        /// </summary>
        private NodeEngineShutdownReason HandleShutdown()
        {
            // FIRST: Fail all pending callback requests so blocked task threads can unblock.
            // This must happen BEFORE joining threads to prevent deadlock.
            FailAllPendingCallbackRequests("TaskHost shutting down.");

            // Wait for all task threads before shutting down so that we can cleanly dispose all WaitHandles.
            foreach (var kvp in _taskContexts)
            {
                kvp.Value.ExecutingThread?.Join();
            }

            DisposeBuildScopedResources();
            _registeredTaskObjectCache = null;

            using StreamWriter debugWriter = _debugCommunications
                    ? File.CreateText(string.Format(CultureInfo.CurrentCulture, Path.Combine(FileUtilities.TempFileDirectory, @"MSBuild_NodeShutdown_{0}.txt"), EnvironmentUtilities.CurrentProcessId))
                    : null;

            debugWriter?.WriteLine("Node shutting down with reason {0}.", _shutdownReason);

            // On Windows, a process holds a handle to the current directory,
            // so reset it away from a user-requested folder that may get deleted.
            NativeMethodsShared.SetCurrentDirectory(BuildEnvironmentHelper.Instance.CurrentMSBuildToolsDirectory);

            // Restore the original environment, best effort.
            try
            {
                CommunicationsUtilities.SetEnvironment(_savedEnvironment);
            }
            catch (Exception ex)
            {
                debugWriter?.WriteLine("Failed to restore the original environment: {0}.", ex);
            }

            SendShutdownNotification(_nodeEndpoint);

            // Flush all packets to the pipe and close it down. This blocks until shutdown is complete.
            _nodeEndpoint.Disconnect();

            // Dispose these WaitHandles
            _packetReceivedEvent.Dispose();
            _shutdownEvent.Dispose();
            _taskCompleteEvent.Dispose();
            _taskCancelledEvent.Dispose();

            return _shutdownReason;
        }

        internal void SendShutdownNotification(INodeEndpoint endpoint)
        {
            if (endpoint.LinkStatus == LinkStatus.Active)
            {
                // The parent can close the pipe as soon as it receives this packet. That expected
                // disconnect must not change BuildCompleteReuse into ConnectionFailed.
                endpoint.ClientWillDisconnect();
                endpoint.OnLinkStatusChanged -= new LinkStatusChangedDelegate(OnLinkStatusChanged);
                endpoint.SendData(new NodeShutdown(_shutdownReason == NodeEngineShutdownReason.Error ? NodeShutdownReason.Error : NodeShutdownReason.Requested));
            }
        }

        private void InitializeConsoleRedirection()
        {
            if (_nodeEndpoint.NegotiatedPacketVersion < NodePacketTypeExtensions.ConsoleOutputForwardingMinVersion)
            {
                return;
            }

            _originalConsoleOut = Console.Out;
            _originalConsoleError = Console.Error;
            _consoleOutWriter = new RedirectConsoleWriter(
                text => _nodeEndpoint.SendData(new ConsoleWritePacket(text, ConsoleOutput.Standard)));
            _consoleErrorWriter = new RedirectConsoleWriter(
                text => _nodeEndpoint.SendData(new ConsoleWritePacket(text, ConsoleOutput.Error)));
            Console.SetOut(_consoleOutWriter);
            Console.SetError(_consoleErrorWriter);
        }

        private void ShutdownConsoleRedirection()
        {
            if (_consoleOutWriter is null)
            {
                return;
            }

            try
            {
                using (_consoleErrorWriter)
                {
                    _consoleOutWriter.Dispose();
                }
            }
            finally
            {
                Console.SetOut(_originalConsoleOut);
                Console.SetError(_originalConsoleError);
                _consoleOutWriter = null;
                _consoleErrorWriter = null;
                _originalConsoleOut = null;
                _originalConsoleError = null;
            }
        }

        private void DisposeBuildScopedResources()
        {
            try
            {
                _registeredTaskObjectCache.DisposeCacheObjects(RegisteredTaskObjectLifetime.Build);
            }
            finally
            {
                ShutdownConsoleRedirection();
            }
        }

        /// <summary>
        /// Event handler for the node endpoint's LinkStatusChanged event.
        /// </summary>
        private void OnLinkStatusChanged(INodeEndpoint endpoint, LinkStatus status)
        {
            switch (status)
            {
                case LinkStatus.ConnectionFailed:
                case LinkStatus.Failed:
                    _shutdownReason = NodeEngineShutdownReason.ConnectionFailed;

                    // Fail all pending callback requests so task threads unblock immediately
                    // instead of waiting indefinitely for responses that will never arrive.
                    FailAllPendingCallbackRequests("TaskHost lost connection to owning worker node during callback.");

                    _shutdownEvent.Set();
                    break;

                default:
                    break;
            }
        }

        /// <summary>
        /// Fails all pending callback requests (both global and per-task) with an InvalidOperationException.
        /// Used during shutdown and connection loss to unblock task threads waiting on callback responses.
        /// </summary>
        private void FailAllPendingCallbackRequests(string errorMessage)
        {
            foreach (var kvp in _pendingCallbackRequests)
            {
                if (_pendingCallbackRequests.TryRemove(kvp.Key, out TaskCompletionSource<INodePacket> tcs))
                {
                    tcs.TrySetException(new InvalidOperationException(errorMessage));
                }
            }

            foreach (var contextKvp in _taskContexts)
            {
                foreach (var reqKvp in contextKvp.Value.PendingCallbackRequests)
                {
                    if (contextKvp.Value.PendingCallbackRequests.TryRemove(reqKvp.Key, out TaskCompletionSource<INodePacket> ctxTcs))
                    {
                        ctxTcs.TrySetException(new InvalidOperationException(errorMessage));
                    }
                }
            }
        }

        /// <summary>
        /// Task runner method
        /// </summary>
        private void RunTask(object state)
        {
            Interlocked.Increment(ref _activeTaskCount);
            OutOfProcTaskHostTaskResult taskResult = null;
            TaskExecutionContext taskContext = state as TaskExecutionContext;
            TaskHostConfiguration taskConfiguration = taskContext?.Configuration ?? state as TaskHostConfiguration;

            if (taskContext is not null)
            {
                _currentTaskContext.Value = taskContext;
#if FEATURE_APPDOMAIN
                CallContext.LogicalSetData(TaskContextIdSlot, taskContext.TaskId);
#endif
            }

            IDictionary<string, TaskParameter> taskParams = taskConfiguration.TaskParameters;

            // We only really know the values of these variables for sure once we see what we received from the owning worker node
            // environment -- otherwise if this was a completely new build, we could lose out on expected environment
            // variables.
            _debugCommunications = taskConfiguration.BuildProcessEnvironment.ContainsValueAndIsEqual("MSBUILDDEBUGCOMM", "1", StringComparison.OrdinalIgnoreCase);
            _updateEnvironment = !taskConfiguration.BuildProcessEnvironment.ContainsValueAndIsEqual("MSBuildTaskHostDoNotUpdateEnvironment", "1", StringComparison.OrdinalIgnoreCase);
            _updateEnvironmentAndLog = taskConfiguration.BuildProcessEnvironment.ContainsValueAndIsEqual("MSBuildTaskHostUpdateEnvironmentAndLog", "1", StringComparison.OrdinalIgnoreCase);
            _warningsAsErrors = taskConfiguration.WarningsAsErrors;
            _warningsNotAsErrors = taskConfiguration.WarningsNotAsErrors;
            _warningsAsMessages = taskConfiguration.WarningsAsMessages;

            // Store warning settings in per-task context so EffectiveWarningsAs* accessors
            // return the correct values when multiple tasks run concurrently.
            if (taskContext is not null)
            {
                taskContext.WarningsAsErrors = taskConfiguration.WarningsAsErrors;
                taskContext.WarningsNotAsErrors = taskConfiguration.WarningsNotAsErrors;
                taskContext.WarningsAsMessages = taskConfiguration.WarningsAsMessages;
            }
            OutOfProcTaskAppDomainWrapper taskWrapper = null;
            try
            {
                // Change to the startup directory
                NativeMethodsShared.SetCurrentDirectory(taskConfiguration.StartupDirectory);

                bool canSkipEnvironmentApply = _lastAppliedConfigEnvironment is not null
                    && _blockedTaskCount == 0
                    && _activeTaskCount == 1
                    && CommunicationsUtilities.AreDictionariesEquivalent(taskConfiguration.BuildProcessEnvironment, _lastAppliedConfigEnvironment);

                if (!canSkipEnvironmentApply)
                {
                    if (_updateEnvironment)
                    {
                        InitializeMismatchedEnvironmentTable(taskConfiguration.BuildProcessEnvironment);
                    }

                    // Now set the new environment
                    SetTaskHostEnvironment(taskConfiguration.BuildProcessEnvironment);
                    DotnetHostEnvironmentHelper.ClearBootstrapDotnetRootEnvironment(taskConfiguration.BuildProcessEnvironment);
                }

                _lastAppliedConfigEnvironment = taskConfiguration.BuildProcessEnvironment;

                // Set culture
                Thread.CurrentThread.CurrentCulture = taskConfiguration.Culture;
                Thread.CurrentThread.CurrentUICulture = taskConfiguration.UICulture;

                string taskName = taskConfiguration.TaskName;
                string taskLocation = taskConfiguration.TaskLocation;

                TaskFactoryUtilities.RegisterAssemblyResolveHandlersFromManifest(taskLocation);

                // We will not create an appdomain now because of a bug
                // As a fix, we will create the class directly without wrapping it in a domain
                taskWrapper = new OutOfProcTaskAppDomainWrapper();

                // Store in per-task context so CancelTask() can find the correct wrapper
                // when multiple tasks are active (nested builds via BuildProjectFile callbacks).
                if (taskContext is not null)
                {
                    taskContext.TaskWrapper = taskWrapper;
                }

                taskResult = taskWrapper.ExecuteTask(
                    this as IBuildEngine,
                    taskName,
                    taskLocation,
                    taskConfiguration.ProjectFileOfTask,
                    taskConfiguration.LineNumberOfTask,
                    taskConfiguration.ColumnNumberOfTask,
                    taskConfiguration.TargetName,
                    taskConfiguration.ProjectFile,
#if FEATURE_APPDOMAIN
                    taskConfiguration.AppDomainSetup,
#endif
                    taskConfiguration.HostServices,
                    taskParams);
            }
            catch (ThreadAbortException)
            {
                // This thread was aborted as part of Cancellation, we will return a failure task result
                taskResult = new OutOfProcTaskHostTaskResult(TaskCompleteType.Failure);
            }
            catch (Exception e) when (!ExceptionHandling.IsCriticalException(e))
            {
                taskResult = new OutOfProcTaskHostTaskResult(TaskCompleteType.CrashedDuringExecution, e);
            }
            finally
            {
                TaskHostTaskComplete taskCompletePacket = null;
                try
                {
                    // BlockForCallback/ResumeAfterCallback are always paired, so a task
                    // should never be in BlockedOnCallback state when it completes.
                    Assumed.True(taskContext is null || taskContext.State != TaskExecutionState.BlockedOnCallback, "Task completed while still in BlockedOnCallback state.");

                    Interlocked.Decrement(ref _activeTaskCount);

                    IDictionary<string, string> currentEnvironment = CommunicationsUtilities.GetEnvironmentVariables();
                    currentEnvironment = UpdateEnvironmentForMainNode(currentEnvironment);

                    bool environmentUnchangedByTask =
                        CommunicationsUtilities.AreDictionariesEquivalent(currentEnvironment, taskConfiguration.BuildProcessEnvironment);

                    taskResult ??= new OutOfProcTaskHostTaskResult(TaskCompleteType.Failure);
                    taskCompletePacket = new TaskHostTaskComplete(
                        taskResult,
#if FEATURE_REPORTFILEACCESSES
                        _fileAccessData,
#endif
                        currentEnvironment);

                    if (NodePacketTypeExtensions.GetNegotiatedPacketVersion(_parentPacketVersion) >= NodePacketTypeExtensions.EnvironmentDeltaMinVersion && environmentUnchangedByTask)
                    {
                        taskCompletePacket.EnvironmentMode = InvariantPayloadTransferMode.Identical;
                    }

#if FEATURE_APPDOMAIN
                    foreach (TaskParameter param in taskParams.Values)
                    {
                        // Tell remoting to forget connections to the parameter
                        RemotingServices.Disconnect(param);
                    }
#endif

                    bool canSkipEnvironmentRestore = environmentUnchangedByTask
                        && _blockedTaskCount == 0
                        && ReferenceEquals(_lastAppliedConfigEnvironment, taskConfiguration.BuildProcessEnvironment);

                    if (!canSkipEnvironmentRestore)
                    {
                        // Restore the original clean environment
                        CommunicationsUtilities.SetEnvironment(_savedEnvironment);
                        _lastAppliedConfigEnvironment = null;
                    }
                }
                catch (Exception e)
                {
                    // Create a minimal taskCompletePacket to carry the exception so that the TaskHostTask does not hang while waiting
                    taskCompletePacket = new TaskHostTaskComplete(
                        new OutOfProcTaskHostTaskResult(TaskCompleteType.CrashedAfterExecution, e),
#if FEATURE_REPORTFILEACCESSES
                        _fileAccessData,
#endif
                        null);
                }
                finally
                {
#if FEATURE_REPORTFILEACCESSES
                    _fileAccessData = new List<FileAccessData>();
#endif

                    if (taskContext is not null)
                    {
                        // Keep the context and AppDomain alive until an in-flight Cancel returns.
                        lock (taskContext)
                        {
                            taskContext.State = TaskExecutionState.Completed;
                            taskWrapper?.CleanupTask();
                            _currentTaskContext.Value = null;
#if FEATURE_APPDOMAIN
                            CallContext.FreeNamedDataSlot(TaskContextIdSlot);
#endif
                            RemoveTaskContext(taskContext.TaskId);
                        }
                    }
                    else
                    {
                        taskWrapper?.CleanupTask();
                    }

                    // The task has now fully completed executing.
                    _taskCompletePackets.Enqueue(taskCompletePacket);
                    // Guard against ObjectDisposedException if HandleShutdown already disposed
                    // the event (can happen if thread.Join timed out during shutdown).
                    try
                    {
                        _taskCompleteEvent.Set();
                    }
                    catch (ObjectDisposedException)
                    {
                        // Shutdown already disposed the event -- nothing to signal.
                    }
                }
            }
        }

        /// <summary>
        /// Set the environment for the task host -- includes possibly munging the given
        /// environment somewhat to account for expected environment differences between,
        /// e.g. worker node processes and task hosts of different bitnesses.
        /// </summary>
        private void SetTaskHostEnvironment(IDictionary<string, string> environment)
        {
            Assumed.NotNull(s_mismatchedEnvironmentValues);
            IDictionary<string, string> updatedEnvironment = null;

            if (_updateEnvironment)
            {
                foreach (KeyValuePair<string, KeyValuePair<string, string>> variable in s_mismatchedEnvironmentValues)
                {
                    string oldValue = variable.Value.Key;
                    string newValue = variable.Value.Value;

                    // We don't check the return value, because having the variable not exist == be
                    // null is perfectly valid, and mismatchedEnvironmentValues stores those values
                    // as null as well, so the String.Equals should still return that they are equal.
                    string environmentValue = null;
                    environment.TryGetValue(variable.Key, out environmentValue);

                    if (String.Equals(environmentValue, oldValue, StringComparison.OrdinalIgnoreCase))
                    {
                        if (updatedEnvironment == null)
                        {
                            if (_updateEnvironmentAndLog)
                            {
                                LogMessageFromResource(MessageImportance.Low, "ModifyingTaskHostEnvironmentHeader");
                            }

                            updatedEnvironment = new Dictionary<string, string>(environment, StringComparer.OrdinalIgnoreCase);
                        }

                        if (newValue != null)
                        {
                            if (_updateEnvironmentAndLog)
                            {
                                LogMessageFromResource(MessageImportance.Low, "ModifyingTaskHostEnvironmentVariable", variable.Key, newValue, environmentValue ?? String.Empty);
                            }

                            updatedEnvironment[variable.Key] = newValue;
                        }
                        else
                        {
                            updatedEnvironment.Remove(variable.Key);
                        }
                    }
                }
            }

            // if it's still null here, there were no changes necessary -- so just
            // set it to what was already passed in.
            if (updatedEnvironment == null)
            {
                updatedEnvironment = environment;
            }

            CommunicationsUtilities.SetEnvironment(updatedEnvironment);
        }

        /// <summary>
        /// Given the environment of the task host at the end of task execution, make sure that any
        /// processor-specific variables have been re-applied in the correct form for the main node,
        /// so that when we pass this dictionary back to the main node, all it should have to do
        /// is just set it.
        /// </summary>
        private IDictionary<string, string> UpdateEnvironmentForMainNode(IDictionary<string, string> environment)
        {
            Assumed.NotNull(s_mismatchedEnvironmentValues);
            IDictionary<string, string> updatedEnvironment = null;

            if (_updateEnvironment)
            {
                foreach (KeyValuePair<string, KeyValuePair<string, string>> variable in s_mismatchedEnvironmentValues)
                {
                    // Since this is munging the property list for returning to the owning worker node process,
                    // then the value we wish to replace is the one that is in this process, and the
                    // replacement value is the one that originally came from the worker node process,
                    // instead of the other way around.
                    string oldValue = variable.Value.Value;
                    string newValue = variable.Value.Key;

                    // We don't check the return value, because having the variable not exist == be
                    // null is perfectly valid, and mismatchedEnvironmentValues stores those values
                    // as null as well, so the String.Equals should still return that they are equal.
                    string environmentValue = null;
                    environment.TryGetValue(variable.Key, out environmentValue);

                    if (String.Equals(environmentValue, oldValue, StringComparison.OrdinalIgnoreCase))
                    {
                        updatedEnvironment ??= new Dictionary<string, string>(environment, StringComparer.OrdinalIgnoreCase);

                        if (newValue != null)
                        {
                            updatedEnvironment[variable.Key] = newValue;
                        }
                        else
                        {
                            updatedEnvironment.Remove(variable.Key);
                        }
                    }
                }
            }

            // if it's still null here, there were no changes necessary -- so just
            // set it to what was already passed in.
            if (updatedEnvironment == null)
            {
                updatedEnvironment = environment;
            }

            return updatedEnvironment;
        }

        /// <summary>
        /// Make sure the mismatchedEnvironmentValues table has been populated.  Note that this should
        /// only do actual work on the very first run of a task in the task host -- otherwise, it should
        /// already have been populated.
        /// </summary>
        private void InitializeMismatchedEnvironmentTable(IDictionary<string, string> environment)
        {
            if (s_mismatchedEnvironmentValues == null)
            {
                // This is the first time that we have received a TaskHostConfiguration packet, so we
                // need to construct the mismatched environment table based on our current environment
                // (assumed to be effectively identical to startup) and the environment we were given
                // via the task host configuration, assumed to be effectively identical to the startup
                // environment of the task host, given that the configuration packet is sent immediately
                // after the node is launched.
                s_mismatchedEnvironmentValues = new Dictionary<string, KeyValuePair<string, string>>(StringComparer.OrdinalIgnoreCase);

                foreach (KeyValuePair<string, string> variable in _savedEnvironment)
                {
                    string oldValue = variable.Value;
                    string newValue;
                    if (!environment.TryGetValue(variable.Key, out newValue))
                    {
                        s_mismatchedEnvironmentValues[variable.Key] = new KeyValuePair<string, string>(null, oldValue);
                    }
                    else
                    {
                        if (!String.Equals(oldValue, newValue, StringComparison.OrdinalIgnoreCase))
                        {
                            s_mismatchedEnvironmentValues[variable.Key] = new KeyValuePair<string, string>(newValue, oldValue);
                        }
                    }
                }

                foreach (KeyValuePair<string, string> variable in environment)
                {
                    string newValue = variable.Value;
                    string oldValue;
                    if (!_savedEnvironment.TryGetValue(variable.Key, out oldValue))
                    {
                        s_mismatchedEnvironmentValues[variable.Key] = new KeyValuePair<string, string>(newValue, null);
                    }
                    else
                    {
                        if (!String.Equals(oldValue, newValue, StringComparison.OrdinalIgnoreCase))
                        {
                            s_mismatchedEnvironmentValues[variable.Key] = new KeyValuePair<string, string>(newValue, oldValue);
                        }
                    }
                }
            }
        }

        /// <summary>
        /// Sends the requested packet across to the main node.
        /// </summary>
        private void SendBuildEvent(BuildEventArgs e)
        {
            if (_nodeEndpoint?.LinkStatus == LinkStatus.Active)
            {
#pragma warning disable SYSLIB0050
                // Types which are not serializable and are not IExtendedBuildEventArgs as
                // those always implement custom serialization by WriteToStream and CreateFromStream.
                if (!e.GetType().IsSerializable && e is not IExtendedBuildEventArgs)
#pragma warning disable SYSLIB0050
                {
                    // log a warning and bail.  This will end up re-calling SendBuildEvent, but we know for a fact
                    // that the warning that we constructed is serializable, so everything should be good.
                    LogWarningFromResource("ExpectedEventToBeSerializable", e.GetType().Name);
                    return;
                }

                TaskHostConfiguration configuration = EffectiveConfiguration;
                LogMessagePacketBase logMessage = new(new KeyValuePair<int, BuildEventArgs>(configuration.NodeId, e));
                _nodeEndpoint.SendData(logMessage);
            }
        }

        /// <summary>
        /// Generates the message event corresponding to a particular resource string and set of args
        /// </summary>
        private void LogMessageFromResource(MessageImportance importance, string messageResource, params object[] messageArgs)
        {
            Assumed.NotNull(EffectiveConfiguration, "We should never have a null configuration when we're trying to log messages!");

            BuildMessageEventArgs message = new(
                message: MessageFormatter.Format(AssemblyResources.GetString(messageResource), messageArgs),
                helpKeyword: null,
                senderName: EffectiveConfiguration.TaskName,
                importance);

            LogMessageEvent(message);
        }

        /// <summary>
        /// Generates the error event corresponding to a particular resource string and set of args
        /// </summary>
        private void LogWarningFromResource(string messageResource, params object[] messageArgs)
        {
            Assumed.NotNull(EffectiveConfiguration, "We should never have a null configuration when we're trying to log warnings!");

            BuildWarningEventArgs warning = new(
                subcategory: null,
                code: null,
                file: ProjectFileOfTaskNode,
                lineNumber: LineNumberOfTaskNode,
                columnNumber: ColumnNumberOfTaskNode,
                endLineNumber: 0,
                endColumnNumber: 0,
                message: MessageFormatter.Format(AssemblyResources.GetString(messageResource), messageArgs),
                helpKeyword: null,
                senderName: EffectiveConfiguration.TaskName);

            LogWarningEvent(warning);
        }

        /// <summary>
        /// Generates the error event corresponding to a particular resource string and set of args
        /// </summary>
        private void LogErrorFromResource(string messageResource)
        {
            Assumed.NotNull(EffectiveConfiguration, "We should never have a null configuration when we're trying to log errors!");

            BuildErrorEventArgs error = new(
                subcategory: null,
                code: null,
                file: ProjectFileOfTaskNode,
                lineNumber: LineNumberOfTaskNode,
                columnNumber: ColumnNumberOfTaskNode,
                endLineNumber: 0,
                endColumnNumber: 0,
                message: AssemblyResources.GetString(messageResource),
                helpKeyword: null,
                senderName: EffectiveConfiguration.TaskName);

            LogErrorEvent(error);
        }
    }
}