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.

Parameter	Description
SuppressAllWarnings	Optional boolean parameter. Specifies that all warnings should be suppressed. This is equivalent to the -sw switch.
SuppressSchemaValidation	Optional boolean parameter. Specifies that schema validation of documents should be suppressed. This is equivalent to the -ss switch.
SuppressSpecificWarnings	Optional string parameter. Specifies that certain warnings should be suppressed. This is equivalent to the -sw[N] switch.
TreatSpecificWarningsAsErrors	Optional string parameter. Specifies that certain warnings should be treated as errors. This is equivalent to the -wx[N] switch.
TreatWarningsAsErrors	Optional boolean parameter. Specifies that all warnings should be treated as errors. This is equivalent to the -wx switch.

VerboseOutput	Optional 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.

Parameter	Description
CompilerAdditionalOptions	Optional string parameter. Specifies additional command line parameters to append when calling candle.exe.
CompilerSuppressAllWarnings	Optional boolean parameter. Specifies that all compiler warnings should be suppressed. This is equivalent to the -sw switch in candle.exe.
CompilerSuppressSchemaValidation	Optional boolean parameter. Specifies that the compiler should suppress schema validation of documents. This is equivalent to the -ss switch in candle.exe.
CompilerSuppressSpecificWarnings	Optional string parameter. Specifies that certain compiler warnings should be suppressed. This is equivalent to the -sw[N] switch in candle.exe.
CompilerTreatSpecificWarningsAsErrors	Optional string parameter. Specifies that certain compiler warnings should be treated as errors. This is equivalent to the -wx[N] switch in candle.exe.
CompilerTreatWarningsAsErrors	Optional boolean parameter. Specifies that all compiler warnings should be treated as errors. This is equivalent to the -wx switch in candle.exe.
CompilerVerboseOutput	Optional boolean parameter. Specifies that the compiler should provide verbose output. This is equivalent to the -v switch in candle.exe.
DefineConstants	Optional string parameter. Specifies a semicolon-delimited list of preprocessor variables. This is equivalent to the -d<name>[=<value>] switch in candle.exe.
SuppressFilesVitalByDefault	Optional boolean parameter. Specifies that the compiler should suppress marking files as vital by default. This is equivalent to the -sfdvital switch in candle.exe.
PreprocessToStdOut	Optional boolean parameter. Specifies that the compiler should output preprocessing information to stdout. This is equivalent to the -p switch in candle.exe.
PreprocessToFile	Optional string parameter. Specifies that the compiler should output preprocessing information to a file. This is equivalent to the -p<file> switch in candle.exe.
IncludeSearchPaths	Optional string parameter. Specifies directories to add to the compiler include search path. This is equivalent to the -I<dir> switch in candle.exe.
InstallerPlatform	Optional 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.
OnlyValidateDocuments	Optional boolean parameter. Specifies that the compiler should only validate documents. This is equivalent to the -zs switch in candle.exe.
Pedantic	Optional boolean parameter. Specifies that the compiler should display pedantic messages. This is equivalent to the -pedantic switch in candle.exe.
ShowSourceTrace	Optional 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.