WiX Toolset

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.