CommandLineBuilder Class

Definition

Namespace:

Microsoft.Build.Utilities

Assembly:

Microsoft.Build.Utilities.Core.dll

Package:

Microsoft.Build.Utilities.Core v17.11.4

Source:

CommandLineBuilder.cs

(1) Make sure values containing hyphens are quoted (RC at least requires this) (2) Escape any embedded quotes. -- Literal double quotes should be written in the form " not "" -- Backslashes falling just before doublequotes must be doubled. -- Literal double quotes can only occur in pairs (you cannot pass a single literal double quote) -- Functional double quotes (for example to handle spaces) are best put around both name and value in switches like /Dname=value.

public ref class CommandLineBuilder

public class CommandLineBuilder

type CommandLineBuilder = class

Public Class CommandLineBuilder

Inheritance

Object

CommandLineBuilder

Derived

Microsoft.Build.Tasks.CommandLineBuilderExtension

Remarks

Below are some quoting experiments, using the /D switch with the CL and RC preprocessor. The /D switch is a little more tricky than most switches, because it has a name=value pair. The table below contains what the preprocessor actually embeds when passed the switch in the first column:

CL via cmd line CL via response file RC /DFOO="A" A A /D"FOO="A"" A A A /DFOO=A A A /D"FOO=A" A A /DFOO=""A"" A A A

/DFOO=\"A\" "A" "A" /DFOO="""A""" "A" broken "A" /D"FOO=\"A\"" "A" "A" /D"FOO=""A""" "A" "A"

/DFOO="A B" A B A B /D"FOO=A B" A B A B

/D"FOO="A B"" broken /DFOO=\"A B\" broken /D"FOO=\"A B\"" "A B" "A B" "A B" /D"FOO=""A B""" "A B" broken broken

From my experiments (with CL and RC only) it seems that -- Literal double quotes are most reliably written in the form \" not "" -- Backslashes falling just before doublequotes must be doubled. -- Values containing literal double quotes must be quoted. -- Literal double quotes can only occur in pairs (you cannot pass a single literal double quote) -- For /Dname=value style switches, functional double quotes (for example to handle spaces) are best put around both name and value (in other words, these kinds of switches don't need special treatment for their '=' signs). -- Values containing hyphens should be quoted; RC requires this, and CL does not mind.

Constructors

CommandLineBuilder()	Default constructor
CommandLineBuilder(Boolean, Boolean)	Default constructor
CommandLineBuilder(Boolean)	Default constructor

Properties

CommandLine	Retrieves the private StringBuilder instance for inheriting classes
Length	Returns the length of the current command

Methods

AppendFileNameIfNotNull(ITaskItem)	Appends a file name quoting it if necessary. This method appends a space to the command line (if it's not currently empty) before the file name.
AppendFileNameIfNotNull(String)	Appends a file name quoting it if necessary. This method appends a space to the command line (if it's not currently empty) before the file name.
AppendFileNamesIfNotNull(ITaskItem[], String)	Appends array of ITaskItem specs as file names, quoting them if necessary, delimited by a delimiter. This method appends a space to the command line (if it's not currently empty) before the file names.
AppendFileNamesIfNotNull(String[], String)	Appends array of file name strings, quoting them if necessary, delimited by a delimiter. This method appends a space to the command line (if it's not currently empty) before the file names.
AppendFileNameWithQuoting(String)	Appends a file name. Quotes are added if they are needed. If the first character of the file name is a dash, "." is prepended to avoid confusing the file name with a switch This method does not append a space to the command line before executing.
AppendQuotedTextToBuffer(StringBuilder, String)	Appends given text to the buffer after first quoting the text if necessary.
AppendSpaceIfNotEmpty()	Add a space or newline to the specified string if and only if it's not empty.
AppendSwitch(String)	Appends a command-line switch that has no separate value, without any quoting. This method appends a space to the command line (if it's not currently empty) before the switch.
AppendSwitchIfNotNull(String, ITaskItem)	Append a switch [overload] This method appends a space to the command line (if it's not currently empty) before the switch.
AppendSwitchIfNotNull(String, ITaskItem[], String)	Appends a command-line switch that takes a ITaskItem[] parameter, and add double-quotes around the individual filenames if necessary. This method appends a space to the command line (if it's not currently empty) before the switch.
AppendSwitchIfNotNull(String, String)	Appends a command-line switch that takes a single string parameter, quoting the parameter if necessary. This method appends a space to the command line (if it's not currently empty) before the switch.
AppendSwitchIfNotNull(String, String[], String)	Appends a command-line switch that takes a string[] parameter, and add double-quotes around the individual filenames if necessary. This method appends a space to the command line (if it's not currently empty) before the switch.
AppendSwitchUnquotedIfNotNull(String, ITaskItem)	Appends the literal parameter without trying to quote. This method appends a space to the command line (if it's not currently empty) before the switch.
AppendSwitchUnquotedIfNotNull(String, ITaskItem[], String)	Appends a command-line switch that takes a ITaskItem[] parameter, not quoting the individual parameters This method appends a space to the command line (if it's not currently empty) before the switch.
AppendSwitchUnquotedIfNotNull(String, String)	Appends the literal parameter without trying to quote. This method appends a space to the command line (if it's not currently empty) before the switch.
AppendSwitchUnquotedIfNotNull(String, String[], String)	Appends a command-line switch that takes a string[] parameter, not quoting the individual parameters This method appends a space to the command line (if it's not currently empty) before the switch.
AppendTextUnquoted(String)	Appends a string. No quotes are added. This method does not append a space to the command line before executing.
AppendTextWithQuoting(String)	Appends a string. Quotes are added if they are needed. This method does not append a space to the command line before executing.
IsQuotingRequired(String)	Checks the given switch parameter to see if it must/can be quoted.
ToString()	Return the command-line as a string.
VerifyThrowNoEmbeddedDoubleQuotes(String, String)	Throws if the parameter has a double-quote in it. This is used to prevent parameter injection. It's virtual so that tools can override this method if they want to have quotes escaped in filenames