Engine Constructors

Definition

Namespace:

Microsoft.Build.BuildEngine

Assembly:

Microsoft.Build.Engine.dll

Package:

Microsoft.Build.Engine v17.11.4

Initializes a new instance of the Engine class.

Overloads

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)	Constructor providing the global properties the engine should inherit.
Engine(ToolsetDefinitionLocations)	Constructor to specify whether toolsets should be initialized from the msbuild configuration file and from the registry
Engine(String)	Obsolete. Constructor to initialize binPath.
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, ToolsetDefinitionLocations, Int32, String)	Constructor used by msbuild.exe and any other multiproc aware MSBuild hosts.

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

Engine()

Source:

Engine.cs

Default constructor that reads toolset information from both the registry and configuration file. The need for parameterless constructor is dictated by COM interop.

public:
 Engine();

public Engine ();

Public Sub New ()

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

Engine(BuildPropertyGroup)

Source:

Engine.cs

Constructor providing the global properties the engine should inherit.

public:
 Engine(Microsoft::Build::BuildEngine::BuildPropertyGroup ^ globalProperties);

public Engine (Microsoft.Build.BuildEngine.BuildPropertyGroup globalProperties);

new Microsoft.Build.BuildEngine.Engine : Microsoft.Build.BuildEngine.BuildPropertyGroup -> Microsoft.Build.BuildEngine.Engine

Public Sub New (globalProperties As BuildPropertyGroup)

Parameters

globalProperties

BuildPropertyGroup

A BuildPropertyGroup that represents properties to be passed to the child engine.

Engine(ToolsetDefinitionLocations)

Source:

Engine.cs

Constructor to specify whether toolsets should be initialized from the msbuild configuration file and from the registry

public:
 Engine(Microsoft::Build::BuildEngine::ToolsetDefinitionLocations locations);

public Engine (Microsoft.Build.BuildEngine.ToolsetDefinitionLocations locations);

new Microsoft.Build.BuildEngine.Engine : Microsoft.Build.BuildEngine.ToolsetDefinitionLocations -> Microsoft.Build.BuildEngine.Engine

Public Sub New (locations As ToolsetDefinitionLocations)

Parameters

locations

ToolsetDefinitionLocations

A ToolsetDefinitionLocations enumeration that specifies the location of the Toolset definition.

Engine(String)

Source:

Engine.cs

Caution

If you were simply passing in the .NET Framework location as the BinPath, just change to the parameterless Engine() constructor. Otherwise, you can define custom toolsets in the registry or config file, or by adding elements to the Engine's ToolsetCollection. Then use either the Engine() or Engine(ToolsetLocations) constructor instead.

Constructor to initialize binPath.

public:
 Engine(System::String ^ binPath);

[System.Obsolete("If you were simply passing in the .NET Framework location as the BinPath, just change to the parameterless Engine() constructor. Otherwise, you can define custom toolsets in the registry or config file, or by adding elements to the Engine's ToolsetCollection. Then use either the Engine() or Engine(ToolsetLocations) constructor instead.")]
public Engine (string binPath);

[<System.Obsolete("If you were simply passing in the .NET Framework location as the BinPath, just change to the parameterless Engine() constructor. Otherwise, you can define custom toolsets in the registry or config file, or by adding elements to the Engine's ToolsetCollection. Then use either the Engine() or Engine(ToolsetLocations) constructor instead.")>]
new Microsoft.Build.BuildEngine.Engine : string -> Microsoft.Build.BuildEngine.Engine

Public Sub New (binPath As String)

Parameters

binPath

String

The path to MSBuild.exe.

Attributes

ObsoleteAttribute

Engine(BuildPropertyGroup, ToolsetDefinitionLocations)

Source:

Engine.cs

Constructor to specify the global properties the engine should inherit and the locations the engine should inspect for toolset definitions.

public:
 Engine(Microsoft::Build::BuildEngine::BuildPropertyGroup ^ globalProperties, Microsoft::Build::BuildEngine::ToolsetDefinitionLocations locations);

public Engine (Microsoft.Build.BuildEngine.BuildPropertyGroup globalProperties, Microsoft.Build.BuildEngine.ToolsetDefinitionLocations locations);

new Microsoft.Build.BuildEngine.Engine : Microsoft.Build.BuildEngine.BuildPropertyGroup * Microsoft.Build.BuildEngine.ToolsetDefinitionLocations -> Microsoft.Build.BuildEngine.Engine

Public Sub New (globalProperties As BuildPropertyGroup, locations As ToolsetDefinitionLocations)

Parameters

globalProperties

BuildPropertyGroup

A BuildPropertyGroup that represents properties to be passed to the child engine.

locations

ToolsetDefinitionLocations

A ToolsetDefinitionLocations enumeration specifies the location of the Toolset definition.

Engine(BuildPropertyGroup, ToolsetDefinitionLocations, Int32, String)

Source:

Engine.cs

Constructor used by msbuild.exe and any other multiproc aware MSBuild hosts.

public:
 Engine(Microsoft::Build::BuildEngine::BuildPropertyGroup ^ globalProperties, Microsoft::Build::BuildEngine::ToolsetDefinitionLocations locations, int numberOfCpus, System::String ^ localNodeProviderParameters);

public Engine (Microsoft.Build.BuildEngine.BuildPropertyGroup globalProperties, Microsoft.Build.BuildEngine.ToolsetDefinitionLocations locations, int numberOfCpus, string localNodeProviderParameters);

new Microsoft.Build.BuildEngine.Engine : Microsoft.Build.BuildEngine.BuildPropertyGroup * Microsoft.Build.BuildEngine.ToolsetDefinitionLocations * int * string -> Microsoft.Build.BuildEngine.Engine

Public Sub New (globalProperties As BuildPropertyGroup, locations As ToolsetDefinitionLocations, numberOfCpus As Integer, localNodeProviderParameters As String)

Parameters

globalProperties

BuildPropertyGroup

A BuildPropertyGroup that represents properties to be passed to the child engine.

locations

ToolsetDefinitionLocations

A ToolsetDefinitionLocations enumeration specifies the location of the Toolset definition.

numberOfCpus

Int32

An integer that specifies the number of CPUs or cores in the system.

localNodeProviderParameters

String

A string of parameters that are used to configure the MSBuild engine. You must format the parameters as ParameterName=ParameterValue. The valid semicolon-separated, optional parameters are as follows:

MSBUILDLOCATION Indicates where the build process can find MSBuild.exe. This path enables the MSBuild engine to locate MSBuild.exe and start it as a local node. MSBUILDLOCATION is the only essential parameter for a host. The default value is C:\Windows\Microsoft.Net\Framework\v3.5.

NODEREUSE Indicates whether the child nodes should remain after the build finishes, in case they can be used later by another build. The nodes are discarded automatically after one minute of non-use. The default value is true.