Skip to main content
Version: v3

Candle Task

The Candle task wraps candle.exe, the WiX compiler. It supports a variety of settings that are described in more detail below. To control these settings in your .wixproj file, you can create a PropertyGroup and specify the settings that you want to use for your build process. The following is a sample PropertyGroup that contains settings that will be used by the Candle task:

<PropertyGroup>
<CompilerTreatWarningsAsErrors>False</CompilerTreatWarningsAsErrors>
<CompilerVerboseOutput>True</CompilerVerboseOutput>
<DefineConstants>Variable1=value1;Variable2=value2</DefineConstants>
<InstallerPlatform>x86</InstallerPlatform>
<SuppressSpecificWarnings>1111</SuppressSpecificWarnings>
<TreatSpecificWarningsAsErrors>2222</TreatSpecificWarningsAsErrors>
</PropertyGroup>

The following table describes the common WiX MSBuild parameters that are applicable to the Candle task.

ParameterDescription
SuppressAllWarningsOptional boolean parameter.

Specifies that all warnings should be suppressed. This is equivalent to the -sw switch.
SuppressSchemaValidationOptional boolean parameter.

Specifies that schema validation of documents should be suppressed. This is equivalent to the -ss switch.
SuppressSpecificWarningsOptional string parameter.

Specifies that certain warnings should be suppressed. This is equivalent to the -sw[N] switch.
TreatSpecificWarningsAsErrorsOptional string parameter.

Specifies that certain warnings should be treated as errors. This is equivalent to the -wx[N] switch.
TreatWarningsAsErrorsOptional boolean parameter.

Specifies that all warnings should be treated as errors. This is equivalent to the -wx switch.
VerboseOutputOptional boolean parameter.

Specifies that the tool should provide verbose output. This is equivalent to the -v switch.

The following table describes the parameters that are specific to the Candle task.

ParameterDescription
CompilerAdditionalOptionsOptional string parameter.

Specifies additional command line parameters to append when calling candle.exe.
CompilerSuppressAllWarningsOptional boolean parameter.

Specifies that all compiler warnings should be suppressed. This is equivalent to the -sw switch in candle.exe.
CompilerSuppressSchemaValidationOptional boolean parameter.

Specifies that the compiler should suppress schema validation of documents. This is equivalent to the -ss switch in candle.exe.
CompilerSuppressSpecificWarningsOptional string parameter.

Specifies that certain compiler warnings should be suppressed. This is equivalent to the -sw[N] switch in candle.exe.
CompilerTreatSpecificWarningsAsErrorsOptional string parameter.

Specifies that certain compiler warnings should be treated as errors. This is equivalent to the -wx[N] switch in candle.exe.
CompilerTreatWarningsAsErrorsOptional boolean parameter.

Specifies that all compiler warnings should be treated as errors. This is equivalent to the -wx switch in candle.exe.
CompilerVerboseOutputOptional boolean parameter.

Specifies that the compiler should provide verbose output. This is equivalent to the -v switch in candle.exe.
DefineConstantsOptional string parameter.

Specifies a semicolon-delimited list of preprocessor variables. This is equivalent to the -d<name>[=<value>] switch in candle.exe.
SuppressFilesVitalByDefaultOptional boolean parameter.

Specifies that the compiler should suppress marking files as vital by default. This is equivalent to the -sfdvital switch in candle.exe.
PreprocessToStdOutOptional boolean parameter.

Specifies that the compiler should output preprocessing information to stdout. This is equivalent to the -p switch in candle.exe.
PreprocessToFileOptional string parameter.

Specifies that the compiler should output preprocessing information to a file. This is equivalent to the -p<file> switch in candle.exe.
IncludeSearchPathsOptional string parameter.

Specifies directories to add to the compiler include search path. This is equivalent to the -I<dir> switch in candle.exe.
InstallerPlatformOptional string parameter.

Specifies the processor architecture for the package. Valid values are x86, x64, and ia64. (Deprecated values include intel for x86 and intel64 for ia64.) This is equivalent to the -arch switch in candle.exe.

Sets the sys.BUILDARCH preprocessor variable and, when the value is x64 or ia64, defaults the Win64 attribute to "yes" on all Package, Component, CustomAction, and RegistrySearch elements in the source file.
OnlyValidateDocumentsOptional boolean parameter.

Specifies that the compiler should only validate documents. This is equivalent to the -zs switch in candle.exe.
PedanticOptional boolean parameter.

Specifies that the compiler should display pedantic messages. This is equivalent to the -pedantic switch in candle.exe.
ShowSourceTraceOptional boolean parameter.

Specifies that the compiler should show source trace information for errors, warnings and verbose messages. This is equivalent to the -trace switch in candle.exe.