This topic has not yet been rated - Rate this topic

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

The ToolTask type exposes the following members.

  Name Description
Protected method ToolTask() Initializes a new instance of the ToolTask class.
Protected method ToolTask(ResourceManager) Initializes a new instance of the ToolTask class with the specified ResourceManager.
Protected method ToolTask(ResourceManager, String) Initializes a new instance of the ToolTask class with the specified ResourceManager and Help keyword prefix.
Top
  Name Description
Public property BuildEngine Gets or sets the instance of the IBuildEngine object used by the task. (Inherited from Task.)
Public property BuildEngine2 Gets the instance of the IBuildEngine2 object used by the task. (Inherited from Task.)
Public property BuildEngine3 Gets the instance of the IBuildEngine3 object used by the task. (Inherited from Task.)
Public property EchoOff Indicates that command line echoing is turned off.
Protected property EnvironmentOverride 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.
Public property 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.
Public property ExitCode Gets the returned exit code of the executable file.
Protected property HasLoggedErrors Whether this ToolTask has logged any errors
Protected property HelpKeywordPrefix Gets or sets the prefix used to compose Help keywords from resource names. (Inherited from Task.)
Public property HostObject Gets or sets the host object associated with the task. (Inherited from Task.)
Public property Log Gets an instance of a TaskLoggingHelper class containing task logging methods. (Inherited from Task.)
Public property LogStandardErrorAsError Should ALL messages received on the standard error stream be logged as errors.
Protected property ResponseFileEncoding Gets the Encoding of the response file.
Protected property StandardErrorEncoding Gets the Encoding of the standard error stream of the task.
Public property StandardErrorImportance Task Parameter: Importance with which to log text from the standard error stream.
Protected property StandardErrorImportanceToUse Gets the actual importance at which standard error messages will be logged.
Protected property StandardErrorLoggingImportance Gets the MessageImportance with which to log errors.
Protected property StandardOutputEncoding Gets the Encoding of the standard output stream of the task.
Public property StandardOutputImportance Task Parameter: Importance with which to log text from the standard out stream.
Protected property StandardOutputImportanceToUse Gets the actual importance at which standard out messages will be logged.
Protected property StandardOutputLoggingImportance Gets the MessageImportance with which to log errors.
Protected property TaskProcessTerminationTimeout A timeout to wait for a task to terminate before killing it. In milliseconds.
Protected property TaskResources Gets or sets the culture-specific resources associated with the task. (Inherited from Task.)
Public property Timeout Gets or sets the amount of time after which the task executable is terminated.
Protected property ToolCanceled Used to signal when a tool has been cancelled.
Public property ToolExe Projects may set this to override a task's ToolName. Tasks may override this to prevent that.
Protected property ToolName Gets the name of the executable file to run.
Public property ToolPath Gets or sets the path of the executable file to run.
Public property UseCommandProcessor 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.
Public property YieldDuringToolExecution Indicates if the task will yield the node during tool execution.
Top
  Name Description
Protected method CallHostObjectToExecute Calls the host object to perform the work of the task.
Public method Cancel Cancels the process executing the task by asking it to close nicely, then after a short period, forcing termination.
Protected method DeleteTempFile Deletes the specified temporary file.
Public method Equals(Object) Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Public method Execute Runs the exectuable file with the specified task parameters. (Overrides Task.Execute().)
Protected method ExecuteTool Creates a temporoary response (.rsp) file and runs the executable file.
Protected method Finalize Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Protected method GenerateCommandLineCommands Returns a string value containing the command line arguments to pass directly to the executable file.
Protected method GenerateFullPathToTool Returns the fully qualified path to the executable file.
Protected method GenerateResponseFileCommands Returns a string value containing the command line arguments to add to the response (.rsp) file before running the executable file.
Public method GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Protected method GetProcessStartInfo Initializes the information required to spawn the process executing the tool.
Protected method GetResponseFileSwitch Returns the command line switch used by the executable file to specifiy a response (.rsp) file.
Public method GetType Gets the Type of the current instance. (Inherited from Object.)
Protected method GetWorkingDirectory Returns the directory in which to run the executable file.
Protected method HandleTaskExecutionErrors Handles execution errors raised by the executable file.
Protected method InitializeHostObject Initializes the host object of the task.
Protected method LogEventsFromTextOutput Parses a single line of text to identify any errors or warnings in canonical format.
Protected method LogPathToTool Logs the tool name and path to all registered loggers.
Protected method LogToolCommand Logs the starting point of the run to all registered loggers.
Protected method MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Protected method SkipTaskExecution Indicates whether task execution should be skipped.
Public method ToString Returns a string that represents the current object. (Inherited from Object.)
Protected method ValidateParameters Indicates whether all task paratmeters are valid.
Top

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 (MSIL 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

Supported in: 4, 3.5, 3.0, 2.0

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ