ToolTask Class

Definition

When overridden in a derived form, provides functionality for a task that wraps a command line tool.

public ref class ToolTask abstract : Microsoft::Build::Utilities::Task, Microsoft::Build::Framework::ICancelableTask
public abstract class ToolTask : Microsoft.Build.Utilities.Task, Microsoft.Build.Framework.ICancelableTask
type ToolTask = class
    inherit Task
    interface ICancelableTask
    interface ITask
Public MustInherit Class ToolTask
Inherits Task
Implements ICancelableTask
Inheritance
ToolTask
Derived
Implements

Examples

The following example creates a ToolTask that runs Ilasm.exe (IL Assembler). The CommandLineBuilder, ToolLocationHelper, and TaskLoggingHelper classes are used to generate the information needed to run the task.

using System;
using System.Collections;
using System.Text;
using Microsoft.Build.Utilities;
using Microsoft.Build.Framework;

namespace MSBuildTasks
{
    /// <summary>
    /// A very simple and incomplete ToolTask to wrap the ILASM.EXE tool.
    /// </summary>
    public class ILAsm : ToolTask
    {
        #region Member Data
        /// <summary>
        /// Gets the collection of parameters used by the task class.
        /// </summary>
        /// <value>Parameter bag.</value>
        protected internal Hashtable Bag
        {
            get
            {
                return bag;
            }
        }

        private Hashtable bag = new Hashtable();
        #endregion

        #region ILAsm Task Properties
        /// <summary>
        /// The Source file that is to be compled (.il)
        /// </summary>
        public ITaskItem Source
        {
            get { return Bag["Source"] as ITaskItem; }
            set { Bag["Source"] = value; }
        }
        /// <summary>
        /// Either EXE or DLL indicating the assembly type to be generated
        /// </summary>
        public string TargetType
        {
            get { return Bag["TargetType"] as string; }
            set { Bag["TargetType"] = value; }
        }
        #endregion

        #region ToolTask Members
        protected override string ToolName
        {
            get { return "ILAsm.exe"; }
        }

        /// <summary>
        /// Use ToolLocationHelper to find ILASM.EXE in the Framework directory
        /// </summary>
        /// <returns></returns>
        protected override string GenerateFullPathToTool()
        {
            // Ask ToolLocationHelper to find ILASM.EXE - it will look in the latest framework directory available
            return ToolLocationHelper.GetPathToDotNetFrameworkFile(ToolName, TargetDotNetFrameworkVersion.VersionLatest);
        }
        #endregion

        #region ILAsm Task Members
        /// <summary>
        /// Construct the command line from the task properties by using the CommandLineBuilder
        /// </summary>
        /// <returns></returns>
        protected override string GenerateCommandLineCommands()
        {
            CommandLineBuilder builder = new CommandLineBuilder();

            // We don't need the tool's logo information shown
            builder.AppendSwitch("/nologo");

            string targetType = Bag["TargetType"] as string;
            // Be explicit with our switches
            if (targetType != null)
            {
                if (String.Compare(targetType, "DLL", true) == 0)
                {
                    builder.AppendSwitch("/DLL");
                }
                else if (String.Compare(targetType, "EXE", true) == 0)
                {
                    builder.AppendSwitch("/EXE");
                }
                else
                {
                    Log.LogWarning("Invalid TargetType (valid values are DLL and EXE) specified: {0}", targetType);
                }
            }

            // Add the filename that we want the tool to process
            builder.AppendFileNameIfNotNull(Bag["Source"] as ITaskItem);

            // Log a High importance message stating the file that we are assembling
            Log.LogMessage(MessageImportance.High, "Assembling {0}", Bag["Source"]);

            // We have all of our switches added, return the commandline as a string
            return builder.ToString();
        }
        #endregion
    }
}
Imports System.Collections
Imports System.Text
Imports Microsoft.Build.Utilities
Imports Microsoft.Build.Framework

Namespace MSBuildTasks

    ''' <summary>
    ''' A very simple and incomplete ToolTask to wrap the ILASM.EXE tool.
    ''' </summary>
    Public Class ILAsm
        Inherits ToolTask

        ''' <summary>
        ''' Parameter bag.
        ''' </summary>
        Protected Friend ReadOnly Property Bag() As Hashtable
            Get
                Return propertyBag
            End Get
        End Property

        Private propertyBag As New Hashtable()

        ''' <summary>
        ''' The Source file that is to be compled (.il)
        ''' </summary>
        Public Property [Source]() As ITaskItem
            Get
                Return Bag("Source")
            End Get
            Set(ByVal value As ITaskItem)
                Bag("Source") = value
            End Set
        End Property

        ''' <summary>
        ''' Either EXE or DLL indicating the assembly type to be generated
        ''' </summary>
        Public Property TargetType() As String
            Get
                Return Bag("TargetType")
            End Get
            Set(ByVal value As String)
                Bag("TargetType") = value
            End Set
        End Property '

        Protected Overrides ReadOnly Property ToolName() As String
            Get
                Return "ILAsm.exe"
            End Get
        End Property

        ''' <summary>
        ''' Use ToolLocationHelper to find ILASM.EXE in the Framework directory
        ''' </summary>
        Protected Overrides Function GenerateFullPathToTool() As String
            ' Ask ToolLocationHelper to find ILASM.EXE - it will look in the latest framework directory available
            Return ToolLocationHelper.GetPathToDotNetFrameworkFile(ToolName, TargetDotNetFrameworkVersion.VersionLatest)
        End Function

        ''' <summary>
        ''' Construct the command line from the task properties by using the CommandLineBuilder
        ''' </summary>
        Protected Overrides Function GenerateCommandLineCommands() As String
            Dim builder As New CommandLineBuilder()

            ' We don't need the tool's logo information shown
            builder.AppendSwitch("/nologo")

            Dim targetType As String = Bag("TargetType")
            ' Be explicit with our switches
            If Not (targetType Is Nothing) Then
                If [String].Compare(targetType, "DLL", True) = 0 Then
                    builder.AppendSwitch("/DLL")
                ElseIf [String].Compare(targetType, "EXE", True) = 0 Then
                    builder.AppendSwitch("/EXE")
                Else
                    Log.LogWarning("Invalid TargetType (valid values are DLL and EXE) specified: {0}", targetType)
                End If
            End If
            ' Add the filename that we want the tool to process
            builder.AppendFileNameIfNotNull(Bag("Source"))

            ' Log a High importance message stating the file that we are assembling
            Log.LogMessage(MessageImportance.High, "Assembling {0}", Bag("Source"))

            ' We have all of our switches added, return the commandline as a string
            Return builder.ToString()
        End Function
    End Class
End Namespace

Remarks

This abstract class provides default implementations for the methods and properties of a task that wraps a command line tool.

Constructors

ToolTask()

Initializes a new instance of the ToolTask class.

ToolTask(ResourceManager)

Initializes a new instance of the ToolTask class with the specified ResourceManager.

ToolTask(ResourceManager, String)

Initializes a new instance of the ToolTask class with the specified ResourceManager and Help keyword prefix.

Properties

BuildEngine

Gets or sets the instance of the IBuildEngine object used by the task.

(Inherited from Task)
BuildEngine2

Gets the instance of the IBuildEngine2 object used by the task.

(Inherited from Task)
BuildEngine3

Gets the instance of the IBuildEngine3 object used by the task.

(Inherited from Task)
BuildEngine4

Gets the instance of the IBuildEngine4 object used by the task.

(Inherited from Task)
EchoOff

Gets or sets a value that indicates whether command line echoing is turned off.

EnvironmentOverride

Gets a set of environment variable name-value pairs. Designed to be overridden in a custom task class (derived from ToolTask) to return a set of new or altered environment variables to create the execution context of the associated tool.

EnvironmentVariables

Array of equals-separated pairs of environment variables that should be passed to the spawned executable, in addition to (or selectively overriding) the regular environment block.

ExitCode

Gets the returned exit code of the executable file.

HasLoggedErrors

Gets a value that indicates whether this ToolTask has logged any errors.

HelpKeywordPrefix

Gets or sets the prefix used to compose Help keywords from resource names.

(Inherited from Task)
HostObject

Gets or sets the host object associated with the task.

(Inherited from Task)
Log

Gets an instance of a TaskLoggingHelper class containing task logging methods.

(Inherited from Task)
LogStandardErrorAsError

Should ALL messages received on the standard error stream be logged as errors.

ResponseFileEncoding

Gets the Encoding of the response file.

StandardErrorEncoding

Gets the Encoding of the standard error stream of the task.

StandardErrorImportance

Task Parameter: Importance with which to log text from the standard error stream.

StandardErrorImportanceToUse

Gets the actual importance at which standard error messages will be logged.

StandardErrorLoggingImportance

Gets the MessageImportance with which to log errors.

StandardOutputEncoding

Gets the Encoding of the standard output stream of the task.

StandardOutputImportance

Task Parameter: Importance with which to log text from the standard out stream.

StandardOutputImportanceToUse

Gets the actual importance at which standard out messages will be logged.

StandardOutputLoggingImportance

Gets the MessageImportance with which to log errors.

TaskProcessTerminationTimeout

A timeout to wait for a task to terminate before killing it. In milliseconds.

TaskResources

Gets or sets the culture-specific resources associated with the task.

(Inherited from Task)
Timeout

Gets or sets the amount of time after which the task executable is terminated.

ToolCanceled

Used to signal when a tool has been cancelled.

ToolExe

Projects may set this to override a task's ToolName. Tasks may override this to prevent that.

ToolName

Gets the name of the executable file to run.

ToolPath

Gets or sets the path of the executable file to run.

UseCommandProcessor

Gets or sets a value that indicates whether the tool task will create a batch file for the command-line and execute that using the command-processor, rather than executing the command directly.

YieldDuringToolExecution

Gets or sets a value that indicates whether the task will yield the node during tool execution.

Methods

CallHostObjectToExecute()

Calls the host object to perform the work of the task.

Cancel()

Cancels the process executing the task by asking it to close nicely, then after a short period, forcing termination.

DeleteTempFile(String)

Deletes the specified temporary file.

Equals(Object)

Determines whether the specified object is equal to the current object.

(Inherited from Object)
Execute()

Runs the executable file with the specified task parameters.

ExecuteTool(String, String, String)

Creates a temporary response (.rsp) file and runs the executable file.

GenerateCommandLineCommands()

Returns a string value containing the command line arguments to pass directly to the executable file.

GenerateFullPathToTool()

Returns the fully qualified path to the executable file.

GenerateResponseFileCommands()

Returns a string value containing the command line arguments to add to the response (.rsp) file before running the executable file.

GetHashCode()

Serves as the default hash function.

(Inherited from Object)
GetProcessStartInfo(String, String, String)

Initializes the information required to spawn the process executing the tool.

GetResponseFileSwitch(String)

Returns the command line switch used by the executable file to specify a response (.rsp) file.

GetType()

Gets the Type of the current instance.

(Inherited from Object)
GetWorkingDirectory()

Returns the directory in which to run the executable file.

HandleTaskExecutionErrors()

Handles execution errors raised by the executable file.

InitializeHostObject()

Initializes the host object of the task.

LogEventsFromTextOutput(String, MessageImportance)

Parses a single line of text to identify any errors or warnings in canonical format.

LogPathToTool(String, String)

Logs the tool name and path to all registered loggers.

LogToolCommand(String)

Logs the starting point of the run to all registered loggers.

MemberwiseClone()

Creates a shallow copy of the current Object.

(Inherited from Object)
ResponseFileEscape(String)

Overridable method to escape the content of the response file.

SkipTaskExecution()

Indicates whether task execution should be skipped.

ToString()

Returns a string that represents the current object.

(Inherited from Object)
ValidateParameters()

Indicates whether all task parameters are valid.

Applies to