ToolTask Class
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
When overridden in a derived form, provides functionality for a task that wraps a command line tool.
Microsoft.Build.Utilities.Task
Microsoft.Build.Utilities.ToolTask
Microsoft.Build.Tasks.ToolTaskExtension
Microsoft.Build.Tasks.Xaml.XamlDataDrivenToolTask
Namespace: Microsoft.Build.Utilities
Assembly: Microsoft.Build.Utilities.v4.0 (in Microsoft.Build.Utilities.v4.0.dll)
The ToolTask type exposes the following members.
| Name | Description | |
|---|---|---|
|
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. |
| Name | Description | |
|---|---|---|
|
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 | (Inherited from Task.) |
|
EchoOff | Indicates that command line echoing is turned off. |
|
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. |
|
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 | 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 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. |
|
YieldDuringToolExecution | Indicates if the task will yield the node during tool execution. |
| Name | Description | |
|---|---|---|
|
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 | Deletes the specified temporary file. |
|
Equals(Object) | Determines whether the specified Object is equal to the current Object. (Inherited from Object.) |
|
Execute | Runs the exectuable file with the specified task parameters. (Overrides Task.Execute().) |
|
ExecuteTool | Creates a temporoary response (.rsp) file and runs the executable file. |
|
Finalize | Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.) |
|
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 a hash function for a particular type. (Inherited from Object.) |
|
GetProcessStartInfo | Initializes the information required to spawn the process executing the tool. |
|
GetResponseFileSwitch | Returns the command line switch used by the executable file to specifiy 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 | Parses a single line of text to identify any errors or warnings in canonical format. |
|
LogPathToTool | Logs the tool name and path to all registered loggers. |
|
LogToolCommand | Logs the starting point of the run to all registered loggers. |
|
MemberwiseClone | Creates a shallow copy of the current Object. (Inherited from Object.) |
|
ResponseFileEscape | |
|
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 paratmeters are valid. |
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 } }
Windows 8 Consumer Preview, Windows Server 8 Beta, Windows 7, Windows Server 2008 SP2, Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.