CommandLineBuilder Class

Article
05/05/2015

Comprises utility methods for constructing a command line.

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.CommandLineBuilder
Microsoft.Build.Tasks.CommandLineBuilderExtension

Namespace: Microsoft.Build.Utilities
Assembly: Microsoft.Build.Utilities.Core (in Microsoft.Build.Utilities.Core.dll)

Syntax

'Declaration
Public Class CommandLineBuilder

public class CommandLineBuilder

public ref class CommandLineBuilder

type CommandLineBuilder =  class end

public class CommandLineBuilder

The CommandLineBuilder type exposes the following members.

Constructors

	Name	Description
	CommandLineBuilder()	Initializes a new instance of the CommandLineBuilder 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.
	CommandLineBuilder(Boolean)	Default constructorMSBuild 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
	CommandLine	Gets the StringBuilder instance representing the command line for inheriting classes.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.
	Length	Represents the length of the command line.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
	AppendFileNameIfNotNull(String)	Appends the command line with file name represented by the parameter, inserting quotation marks if necessary.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.
	AppendFileNameIfNotNull(ITaskItem)	Appends the command line with the file name of the specified ITaskItem object.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.
	AppendFileNamesIfNotNull(array<String[], String)	Appends the command line with the list of file names in the specified string array, separated by the specified delimiter.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.
	AppendFileNamesIfNotNull(array<ITaskItem[], String)	Appends the command line with the list of file names in the specified ITaskItem array, separated by the specified delimiter.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.
	AppendFileNameWithQuoting	Appends the command line with a file name, and surrounds the file name with quotation marks as necessary.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.
	AppendQuotedTextToBuffer	Appends given text to the buffer after first quoting the text if necessary.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.
	AppendSpaceIfNotEmpty	Adds a space to the specified string, given the string is not empty.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.
	AppendSwitch	Appends the command line with the specified switch.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.
	AppendSwitchIfNotNull(String, ITaskItem)	Appends the command line with a switch that takes a task item specification that acts a single string parameter.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.
	AppendSwitchIfNotNull(String, String)	Appends the command line with a switch that takes a single string parameter.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.
	AppendSwitchIfNotNull(String, array<ITaskItem[], String)	Appends the command line with a switch that takes an array of task item specifications that act as string 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.
	AppendSwitchIfNotNull(String, array<String[], String)	Appends the command line with a switch that takes an array of string 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.
	AppendSwitchUnquotedIfNotNull(String, ITaskItem)	Appends the command line with a switch that takes a task item specification as a single string parameter, without attempting to encapsulate the switch parameter with quotation marks.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.
	AppendSwitchUnquotedIfNotNull(String, String)	Appends the command line with a switch that takes a single string parameter, without attempting to encapsulate the switch parameter with quotation marks.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.
	AppendSwitchUnquotedIfNotNull(String, array<ITaskItem[], String)	Appends the command line with a switch that takes an array of task item specifications that act as string parameters, without attempting to encapsulate them with quotation marks.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.
	AppendSwitchUnquotedIfNotNull(String, array<String[], String)	Appends the command line with a switch that takes an array of string parameters, without attempting to encapsulate switch parameters with quotation marks.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.
	AppendTextUnquoted	Appends the command line with string, without attempting to encapsulate the string with quotation marks.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.
	AppendTextWithQuoting	Appends the command line with string, and surrounds the string with quotations marks as necessary.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.)
	Finalize	(Inherited from Object.)
	GetHashCode	(Inherited from Object.)
	GetType	(Inherited from Object.)
	IsQuotingRequired	Determines whether the specified string parameter should be surrounded with quotation marks because it contains white space.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.)
	ToString	Returns the command line as a string.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 Object.ToString().)
	VerifyThrowNoEmbeddedDoubleQuotes	Returns an error if the command line parameter contains a double-quote (") character. Because double quotes are illegal in command line parameters, this method helps prevent parameter injection attacks.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

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.