Engine Class

Reference

Definition

Namespace:: Microsoft.Build.BuildEngine

Assembly:: Microsoft.Build.Engine.dll

Package:: Microsoft.Build.Engine v17.11.4

Source:: Engine.cs

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Caution

This class has been deprecated. Please use Microsoft.Build.Evaluation.ProjectCollection from the Microsoft.Build assembly instead.

This class represents the MSBuild engine. In a system of project-to-project dependencies, this class keeps track of the various projects being built, so that we can avoid building the same target in the same project more than once in a given build.

public ref class Engine

[System.Obsolete("This class has been deprecated. Please use Microsoft.Build.Evaluation.ProjectCollection from the Microsoft.Build assembly instead.")]
public class Engine

public class Engine

[<System.Obsolete("This class has been deprecated. Please use Microsoft.Build.Evaluation.ProjectCollection from the Microsoft.Build assembly instead.")>]
type Engine = class

type Engine = class

Public Class Engine

Inheritance: Object
Engine

Attributes: ObsoleteAttribute

Examples

The following example creates an Engine object and uses the BuildProjectFile method to build a project file. The FileLogger class is used to log information to a file.

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.Build.BuildEngine;

namespace BuildAProjectCS
{
    class Program
    {
        static void Main(string[] args)
        {
            // Instantiate a new Engine object
            Engine engine = new Engine();

            // Point to the path that contains the .NET Framework 2.0 CLR and tools
            engine.BinPath = @"c:\windows\microsoft.net\framework\v2.0.xxxxx";

            // Instantiate a new FileLogger to generate build log
            FileLogger logger = new FileLogger();

            // Set the logfile parameter to indicate the log destination
            logger.Parameters = @"logfile=C:\temp\build.log";

            // Register the logger with the engine
            engine.RegisterLogger(logger);

            // Build a project file
            bool success = engine.BuildProjectFile(@"c:\temp\validate.proj");

            //Unregister all loggers to close the log file
            engine.UnregisterAllLoggers();

            if (success)
                Console.WriteLine("Build succeeded.");
            else
                Console.WriteLine(@"Build failed. View C:\temp\build.log for details");
        }
    }
}

Module Module1
    'Add references to Microsoft.Build.Framework and
    'Microsoft.Build.BuildEngine
    Sub Main()
        'Create a new Engine object
        Dim engine As New Engine()

        'Point to the path that contains the .NET Framework 2.0 CLR and tools
        engine.BinPath = "c:\windows\microsoft.net\framework\v2.0.xxxxx"

        'Instantiate a new FileLogger to generate a build log
        Dim logger As New FileLogger()

        'Set logfile parameter to indicate the log destination
        logger.Parameters = "logfile=c:\temp\build.log"

        'Register the logger with the engine
        engine.RegisterLogger(logger)

        'Build the project file
        Dim success As Boolean = engine.BuildProjectFile("c:\temp\validate.proj")

        'Unregister all loggers to close the log file
        engine.UnregisterAllLoggers()

        If success Then
            Console.WriteLine("Build succeeded.")
        Else
            Console.WriteLine("Build failed. View C:\temp\build.log for details.")
        End If
    End Sub

End Module

Remarks

In a system of project-to-project dependencies, the Engine maintains the building projects, making it possible to avoid building the same target in the same project more than once in a given build.

Constructors

Engine()	Default constructor that reads toolset information from both the registry and configuration file. The need for parameterless constructor is dictated by COM interop.
Engine(BuildPropertyGroup, ToolsetDefinitionLocations, Int32, String)	Constructor used by msbuild.exe and any other multiproc aware MSBuild hosts.
Engine(BuildPropertyGroup, ToolsetDefinitionLocations)	Constructor to specify the global properties the engine should inherit and the locations the engine should inspect for toolset definitions.
Engine(BuildPropertyGroup)	Constructor providing the global properties the engine should inherit.
Engine(String)	Obsolete. Constructor to initialize binPath.
Engine(ToolsetDefinitionLocations)	Constructor to specify whether toolsets should be initialized from the msbuild configuration file and from the registry

Properties

BinPath	Obsolete. Obsolete way to get or set the tools path for the current default tools version.
BuildEnabled	This is the default value used by newly created projects for whether or not the building of targets is enabled. This is for security purposes in case a host wants to closely control which projects it allows to run targets/tasks.
DefaultToolsVersion	The default tools version of this Engine. Projects use this tools version if they aren't otherwise told what tools version to use. This value is gotten from the .exe.config file, or else in the registry, or if neither specify a default tools version then it is hard-coded to the tools version "2.0".
GlobalEngine	Returns an instance of the Engine that is global (shared) for this AppDomain. Delays creation until necessary.
GlobalProperties	Accessor for the engine's global properties. Global properties are those that would be set via the /p: switch at the command-line, or things that the IDE wants to set before building a project (such as the "Configuration" property). These global properties shall be applied to all projects that are built with this engine.
IsBuilding	Is this engine in the process of building?
OnlyLogCriticalEvents	When true, only log critical events such as warnings and errors. Has to be in here for API compat
Toolsets	Returns the collection of Toolsets recognized by this Engine instance.
Version	Gets the file version of the file in which the Engine assembly lies.

Methods

BuildProject(Project, String)	Builds a single target in an already-loaded project.
BuildProject(Project, String[], IDictionary, BuildSettings)	Builds a list of targets in an already-loaded project using the specified flags, and returns the target outputs.
BuildProject(Project, String[], IDictionary)	Builds a list of targets in an already-loaded project, and returns the target outputs.
BuildProject(Project, String[])	Builds a list of targets in an already-loaded project.
BuildProject(Project)	Builds the default targets in an already-loaded project.
BuildProjectFile(String, String)	Loads a project file from disk, and builds the specified target.
BuildProjectFile(String, String[], BuildPropertyGroup, IDictionary, BuildSettings, String)	Loads a project file from disk, and builds the specified list of targets. This overload takes a set of global properties to use for the build, returns the target outputs, and also allows the caller to specify additional build flags.
BuildProjectFile(String, String[], BuildPropertyGroup, IDictionary, BuildSettings)	Loads a project file from disk, and builds the specified list of targets. This overload takes a set of global properties to use for the build, returns the target outputs, and also allows the caller to specify additional build flags.
BuildProjectFile(String, String[], BuildPropertyGroup, IDictionary)	Loads a project file from disk, and builds the specified list of targets. This overload takes a set of global properties to use for the build and returns the target outputs.
BuildProjectFile(String, String[], BuildPropertyGroup)	Loads a project file from disk, and builds the specified list of targets. This overload takes a set of global properties to use for the build.
BuildProjectFile(String, String[])	Loads a project file from disk, and builds the specified list of targets.
BuildProjectFile(String)	Loads a project file from disk, and builds the default targets.
BuildProjectFiles(String[], String[][], BuildPropertyGroup[], IDictionary[], BuildSettings, String[])	Loads a set of project files from disk, and builds the given list of targets for each one. This overload takes a set of global properties for each project to use for the build, returns the target outputs, and also allows the caller to specify additional build flags.
CreateNewProject()	Creates a new empty Project object that is associated with this engine. All projects must be associated with an engine, because they need loggers, global properties, reserved properties, etc.
GetLoadedProject(String)	Retrieves the project object for the specified project file full path, if it has been loaded by this Engine. Returns null if this project is unknown to us.
RegisterDistributedLogger(ILogger, LoggerDescription)	Called to register distributed loggers with the engine. This method is not thread safe. All loggers should registered prior to starting the build in order to guarantee uniform behavior
RegisterLogger(ILogger)	Called to register loggers with the engine. Once loggers are registered, all build events will be sent to them.
Shutdown()	Called when the host is done with this engine; unregisters loggers and shuts down nodes and TEM's.
UnloadAllProjects()	Remove all references to Project objects from our cache. This is called by the IDE on Solution Close.
UnloadProject(Project)	Removes a project object from our hash table of loaded projects. After this is called, it is illegal to attempt to do anything else with the Project, so don't call it unless you are completely done with the project. IDEs should call this when they're done with a particular project. This causes us to unhook the project from the Engine object, so that there will be no more references to the project, and the garbage collector can clean up.
UnregisterAllLoggers()	Clear out all registered loggers so that none are registered.

Applies to

Partilhar via