ToolTask Class
When overridden in a derived form, provides functionality for a task that wraps a command line tool.
MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0.
Inheritance Hierarchy
System.Object
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.Core (in Microsoft.Build.Utilities.Core.dll)
Syntax
'Declaration
Public MustInherit Class ToolTask _
Inherits Task _
Implements ICancelableTask, ITask
public abstract class ToolTask : Task,
ICancelableTask, ITask
public ref class ToolTask abstract : public Task,
ICancelableTask, ITask
[<AbstractClass>]
type ToolTask =
class
inherit Task
interface ICancelableTask
interface ITask
end
public abstract class ToolTask extends Task implements ICancelableTask, ITask
The ToolTask type exposes the following members.
Constructors
Name | Description | |
---|---|---|
ToolTask() | Initializes a new instance of the ToolTask class.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
ToolTask(ResourceManager) | Initializes a new instance of the ToolTask class with the specified ResourceManager.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
ToolTask(ResourceManager, String) | Initializes a new instance of the ToolTask class with the specified ResourceManager and Help keyword prefix.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. |
Top
Properties
Name | Description | |
---|---|---|
BuildEngine | Gets or sets the instance of the IBuildEngine object used by the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. (Inherited from Task.) | |
BuildEngine2 | Gets the instance of the IBuildEngine2 object used by the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. (Inherited from Task.) | |
BuildEngine3 | Gets the instance of the IBuildEngine3 object used by the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. (Inherited from Task.) | |
BuildEngine4 | Gets the instance of the IBuildEngine4 object used by the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. (Inherited from Task.) | |
EchoOff | Indicates that command line echoing is turned off.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
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. MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
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.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
ExitCode | Gets the returned exit code of the executable file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
HasLoggedErrors | Whether this ToolTask has logged any errorsMSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
HelpKeywordPrefix | Gets or sets the prefix used to compose Help keywords from resource names.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. (Inherited from Task.) | |
HostObject | Gets or sets the host object associated with the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. (Inherited from Task.) | |
Log | Gets an instance of a TaskLoggingHelper class containing task logging methods.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. (Inherited from Task.) | |
LogStandardErrorAsError | Should ALL messages received on the standard error stream be logged as errors.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
ResponseFileEncoding | Gets the Encoding of the response file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
StandardErrorEncoding | Gets the Encoding of the standard error stream of the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
StandardErrorImportance | Task Parameter: Importance with which to log text from the standard error stream.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
StandardErrorImportanceToUse | Gets the actual importance at which standard error messages will be logged.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
StandardErrorLoggingImportance | Gets the MessageImportance with which to log errors.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
StandardOutputEncoding | Gets the Encoding of the standard output stream of the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
StandardOutputImportance | Task Parameter: Importance with which to log text from the standard out stream.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
StandardOutputImportanceToUse | Gets the actual importance at which standard out messages will be logged.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
StandardOutputLoggingImportance | Gets the MessageImportance with which to log errors.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
TaskProcessTerminationTimeout | A timeout to wait for a task to terminate before killing it. In milliseconds.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
TaskResources | Gets or sets the culture-specific resources associated with the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. (Inherited from Task.) | |
Timeout | Gets or sets the amount of time after which the task executable is terminated.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
ToolCanceled | Used to signal when a tool has been cancelled.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
ToolExe | Projects may set this to override a task's ToolName. Tasks may override this to prevent that.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
ToolName | Gets the name of the executable file to run.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
ToolPath | Gets or sets the path of the executable file to run.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
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.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
YieldDuringToolExecution | Indicates if the task will yield the node during tool execution.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. |
Top
Methods
Name | Description | |
---|---|---|
CallHostObjectToExecute | Calls the host object to perform the work of the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
Cancel | Cancels the process executing the task by asking it to close nicely, then after a short period, forcing termination.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
DeleteTempFile | Deletes the specified temporary file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
Equals | (Inherited from Object.) | |
Execute | Runs the exectuable file with the specified task parameters.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. (Overrides Task.Execute().) | |
ExecuteTool | Creates a temporoary response (.rsp) file and runs the executable file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
Finalize | (Inherited from Object.) | |
GenerateCommandLineCommands | Returns a string value containing the command line arguments to pass directly to the executable file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
GenerateFullPathToTool | Returns the fully qualified path to the executable file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
GenerateResponseFileCommands | Returns a string value containing the command line arguments to add to the response (.rsp) file before running the executable file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
GetHashCode | (Inherited from Object.) | |
GetProcessStartInfo | Initializes the information required to spawn the process executing the tool.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
GetResponseFileSwitch | Returns the command line switch used by the executable file to specifiy a response (.rsp) file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
GetType | (Inherited from Object.) | |
GetWorkingDirectory | Returns the directory in which to run the executable file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
HandleTaskExecutionErrors | Handles execution errors raised by the executable file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
InitializeHostObject | Initializes the host object of the task.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
LogEventsFromTextOutput | Parses a single line of text to identify any errors or warnings in canonical format.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
LogPathToTool | Logs the tool name and path to all registered loggers.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
LogToolCommand | Logs the starting point of the run to all registered loggers.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
MemberwiseClone | (Inherited from Object.) | |
ResponseFileEscape | Overridable method to escape the content of the response file.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
SkipTaskExecution | Indicates whether task execution should be skipped.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. | |
ToString | (Inherited from Object.) | |
ValidateParameters | Indicates whether all task paratmeters are valid.MSBuild is now included in Visual Studio instead of the .NET Framework. You can use MSBuild 12.0 side-by-side with versions previously deployed with the .NET Framework.For more information, see What's New in MSBuild 12.0. |
Top
Remarks
This abstract class provides default implementations for the methods and properties of a task that wraps a command line tool.
Examples
The following example creates a ToolTask that runs Ilasm.exe. The CommandLineBuilder, ToolLocationHelper, and TaskLoggingHelper classes are used to generate the information needed to run the task.
Imports System
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
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
}
}
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.