ToolTask Class

 

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

Namespace:   Microsoft.Build.Utilities
Assembly:  Microsoft.Build.Utilities.v4.0 (in Microsoft.Build.Utilities.v4.0.dll)


public abstract class ToolTask : Task, ICancelableTask, ITask

NameDescription
System_CAPS_protmethodToolTask()

Initializes a new instance of the ToolTask class.

System_CAPS_protmethodToolTask(ResourceManager)

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

System_CAPS_protmethodToolTask(ResourceManager, String)

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

NameDescription
System_CAPS_pubpropertyBuildEngine

Gets or sets the instance of the IBuildEngine object used by the task.(Inherited from Task.)

System_CAPS_pubpropertyBuildEngine2

Gets the instance of the IBuildEngine2 object used by the task.(Inherited from Task.)

System_CAPS_pubpropertyBuildEngine3

Gets the instance of the IBuildEngine3 object used by the task.(Inherited from Task.)

System_CAPS_pubpropertyBuildEngine4

Gets the instance of the IBuildEngine4 object used by the task.(Inherited from Task.)

System_CAPS_pubpropertyEchoOff

Indicates that command line echoing is turned off.

System_CAPS_protpropertyEnvironmentOverride

Obsolete. 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.

System_CAPS_pubpropertyEnvironmentVariables

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.

System_CAPS_pubpropertyExitCode

Gets the returned exit code of the executable file.

System_CAPS_protpropertyHasLoggedErrors

Whether this ToolTask has logged any errors

System_CAPS_protpropertyHelpKeywordPrefix

Gets or sets the prefix used to compose Help keywords from resource names.(Inherited from Task.)

System_CAPS_pubpropertyHostObject

Gets or sets the host object associated with the task.(Inherited from Task.)

System_CAPS_pubpropertyLog

Gets an instance of a TaskLoggingHelper class containing task logging methods.(Inherited from Task.)

System_CAPS_pubpropertyLogStandardErrorAsError

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

System_CAPS_protpropertyResponseFileEncoding

Gets the Encoding of the response file.

System_CAPS_protpropertyStandardErrorEncoding

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

System_CAPS_pubpropertyStandardErrorImportance

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

System_CAPS_protpropertyStandardErrorImportanceToUse

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

System_CAPS_protpropertyStandardErrorLoggingImportance

Gets the MessageImportance with which to log errors.

System_CAPS_protpropertyStandardOutputEncoding

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

System_CAPS_pubpropertyStandardOutputImportance

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

System_CAPS_protpropertyStandardOutputImportanceToUse

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

System_CAPS_protpropertyStandardOutputLoggingImportance

Gets the MessageImportance with which to log errors.

System_CAPS_protpropertyTaskProcessTerminationTimeout

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

System_CAPS_protpropertyTaskResources

Gets or sets the culture-specific resources associated with the task.(Inherited from Task.)

System_CAPS_pubpropertyTimeout

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

System_CAPS_protpropertyToolCanceled

Used to signal when a tool has been cancelled.

System_CAPS_pubpropertyToolExe

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

System_CAPS_protpropertyToolName

Gets the name of the executable file to run.

System_CAPS_pubpropertyToolPath

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

System_CAPS_pubpropertyUseCommandProcessor

Gets or sets a switch that specifies 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.

System_CAPS_pubpropertyYieldDuringToolExecution

Indicates if the task will yield the node during tool execution.

NameDescription
System_CAPS_protmethodCallHostObjectToExecute()

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

System_CAPS_pubmethodCancel()

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

System_CAPS_protmethodDeleteTempFile(String)

Deletes the specified temporary file.

System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_pubmethodExecute()

Runs the exectuable file with the specified task parameters.(Overrides Task.Execute().)

System_CAPS_protmethodExecuteTool(String, String, String)

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

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_protmethodGenerateCommandLineCommands()

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

System_CAPS_protmethodGenerateFullPathToTool()

Returns the fully qualified path to the executable file.

System_CAPS_protmethodGenerateResponseFileCommands()

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

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_protmethodGetProcessStartInfo(String, String, String)

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

System_CAPS_protmethodGetResponseFileSwitch(String)

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

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_protmethodGetWorkingDirectory()

Returns the directory in which to run the executable file.

System_CAPS_protmethodHandleTaskExecutionErrors()

Handles execution errors raised by the executable file.

System_CAPS_protmethodInitializeHostObject()

Initializes the host object of the task.

System_CAPS_protmethodLogEventsFromTextOutput(String, MessageImportance)

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

System_CAPS_protmethodLogPathToTool(String, String)

Logs the tool name and path to all registered loggers.

System_CAPS_protmethodLogToolCommand(String)

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

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_protmethodResponseFileEscape(String)

Overridable method to escape the content of the response file.

System_CAPS_protmethodSkipTaskExecution()

Indicates whether task execution should be skipped.

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

System_CAPS_protmethodValidateParameters()

Indicates whether all task paratmeters are valid.

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

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
    }
}

.NET Framework
Available since 2.0

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: