Skip to main content

Heat harvesting

In WiX v4, Heat is available in a WiX extension NuGet Package. To use Heat to harvest directories, files, or projects:

  1. Add a reference to the WixToolset.Heat NuGet package.
  2. Add an item group based on the kind of harvesting you want to do in your project:
    • HarvestDirectory to harvest files from a directory
    • HarvestFile to harvest data from a file
    • HarvestProject to harvest output from a project

Using HarvestDirectory to harvest files from a directory

HarvestDirectory items can contain the following metadata to control harvesting:

MetadataDescription
ComponentGroupNameOptional string metadata. When harvesting multiple directories in a project, specify this metadata to create unique file names for the generated authoring. The name of the ComponentGroup to create for all the generated authoring.
DirectoryRefIdOptional string metadata. The ID of the directory to reference instead of TARGETDIR.
KeepEmptyDirectoriesOptional boolean metadata. Whether to create Directory entries for empty directories. The default is false.
PreprocessorVariableOptional string metadata. Substitute SourceDir for another a preprocessor variable name. For example, specify MyDir to have Heat use $(MyDir) instead of SourceDir.
SuppressComOptional boolean metadata. Suppress generation of COM registry elements. The default is false.
SuppressRegistryOptional boolean metadata. Suppress generation of any registry elements. The default is false.
SuppressRootDirectoryOptional boolean metadata. Suppress generation of a Directory element for the parent directory of the file. The default is false.
TransformsOptional string metadata. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring.

The following properties control harvesting:

PropertyDescription
HarvestDirectoryAutogenerateGuidsOptional boolean property. Whether to generate authoring that relies on auto-generation of component GUIDs. The default is $(HarvestAutogenerateGuids) if specified; otherwise, true.
HarvestDirectoryComponentGroupNameOptional string property. When harvesting multiple directories in a project, specify this metadata to create unique file names for the generated authoring. The component group name that will contain all generated authoring.
HarvestDirectoryDirectoryRefIdOptional string property. The identifier of the Directory element that will contain all generated authoring.
HarvestDirectoryGenerateGuidsNowOptional boolean property. Whether to generate authoring that generates durable GUIDs when harvesting. The default is $(HarvestGenerateGuidsNow) if specified; otherwise, false.
HarvestDirectoryKeepEmptyDirectoriesOptional boolean property. Whether to create Directory entries for empty directories when harvesting. The default is false.
HarvestDirectoryNoLogoOptional boolean property. Whether to show the logo for heat.exe. The default is $(NoLogo) if specified; otherwise, false.
HarvestDirectoryPreprocessorVariableOptional string property. Substitute SourceDir for another a preprocessor variable name. For example, specify MyDir to have Heat use $(MyDir) instead of SourceDir.
HarvestDirectorySuppressAllWarningsOptional boolean parameter. Specifies that all warnings should be suppressed. The default is $(HarvestSuppressAllWarnings) if specified; otherwise, false.
HarvestDirectorySuppressComOptional boolean property. Whether to suppress generation of COM registry elements when harvesting files in directories. The default is false.
HarvestDirectorySuppressFragmentsOptional boolean property. Whether to suppress generation of separate fragments when harvesting. The default is $(HarvestSuppressFragments) if specified; otherwise, true.
HarvestDirectorySuppressRegistryOptional boolean property. Whether to suppress generation of all registry elements when harvesting files in directories. The default is false.
HarvestDirectorySuppressRootDirectoryOptional boolean property. Whether to suppress generation of a Directory element for all authoring when harvesting. The default is false.
HarvestDirectorySuppressSpecificWarningsOptional string parameter. Specifies that certain warnings should be suppressed. The default is $(HarvestSuppressSpecificWarnings) if specified.
HarvestDirectorySuppressUniqueIdsOptional boolean property. Whether to suppress generation of unique component IDs. The default is $(HarvestSuppressUniqueIds) if specified; otherwise, false.
HarvestDirectoryTransformsOptional string property. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. The default is $(HarvestTransforms) if specified.
HarvestDirectoryTreatSpecificWarningsAsErrorsOptional string parameter. Specifies that certain warnings should be treated as errors. The default is $(HarvestTreatSpecificWarningsAsErrors) if specified.
HarvestDirectoryTreatWarningsAsErrorsOptional boolean parameter. Specifies that all warnings should be treated as errors. The default is $(HarvestTreatWarningsAsErrors) if specified; otherwise, false.
HarvestDirectoryVerboseOutputOptional boolean parameter. Specifies that the tool should provide verbose output. The default is $(HarvestVerboseOutput) if specified; otherwise, false.

Example:

<Project Sdk="WixToolset.Sdk">
<ItemGroup>
<HarvestDirectory Include="FilesDir">
<ComponentGroupName>HarvestedComponents</ComponentGroupName>
<DirectoryRefId>ApplicationFolder</DirectoryRefId>
<SuppressRootDirectory>true</SuppressRootDirectory>
</HarvestDirectory>

<BindPath Include="FilesDir" />
</ItemGroup>

<ItemGroup>
<PackageReference Include="WixToolset.Heat" />
</ItemGroup>
</Project>

Using HarvestFile to harvest data from a file

HarvestFile items can contain the following metadata to control harvesting:

MetadataDescription
ComponentGroupNameOptional string metadata. The name of the ComponentGroup to create for all the generated authoring.
DirectoryRefIdOptional string metadata. The ID of the directory to reference instead of TARGETDIR.
PreprocessorVariableOptional string metadata. Substitute SourceDir for another a preprocessor variable name. For example, specify MyDir to have Heat use $(MyDir) instead of SourceDir.
SuppressComOptional boolean metadata. Suppress generation of COM registry elements. The default is false.
SuppressRegistryOptional boolean metadata. Suppress generation of any registry elements. The default is false.
SuppressRootDirectoryOptional boolean metadata. Suppress generation of a Directory element for the parent directory of the file. The default is false.
TransformsOptional string metadata. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring.

The following properties control harvesting:

PropertyDescription
HarvestFileAutogenerateGuidsOptional boolean property. Whether to generate authoring that relies on auto-generation of component GUIDs. The default is $(HarvestAutogenerateGuids) if specified; otherwise, true.
HarvestFileComponentGroupNameOptional string property. When harvesting multiple directories in a project, specify this metadata to create unique file names for the generated authoring. The component group name that will contain all generated authoring.
HarvestFileDirectoryRefIdOptional string property. The identifier of the Directory element that will contain all generated authoring.
HarvestFileGenerateGuidsNowOptional boolean property. Whether to generate authoring that generates durable GUIDs when harvesting. The default is $(HarvestGenerateGuidsNow) if specified; otherwise, false.
HarvestFileNoLogoOptional boolean property. Whether to show the logo for heat.exe. The default is $(NoLogo) if specified; otherwise, false.
HarvestFilePreprocessorVariableOptional string property. Substitute SourceDir for another a preprocessor variable name. For example, specify MyDir to have Heat use $(MyDir) instead of SourceDir.
HarvestFileSuppressAllWarningsOptional boolean parameter. Specifies that all warnings should be suppressed. The default is $(HarvestSuppressAllWarnings) if specified; otherwise, false.
HarvestFileSuppressComOptional boolean property. Whether to suppress generation of COM registry elements when harvesting files in directories. The default is false.
HarvestFileSuppressFragmentsOptional boolean property. Whether to suppress generation of separate fragments when harvesting. The default is $(HarvestSuppressFragments) if specified; otherwise, true.
HarvestFileSuppressRegistryOptional boolean property. Whether to suppress generation of all registry elements when harvesting files in directories. The default is false.
HarvestFileSuppressRootDirectoryOptional boolean property. Whether to suppress generation of a Directory element for all authoring when harvesting. The default is false.
HarvestFileSuppressSpecificWarningsOptional string parameter. Specifies that certain warnings should be suppressed. The default is $(HarvestSuppressSpecificWarnings) if specified.
HarvestFileSuppressUniqueIdsOptional boolean property. Whether to suppress generation of unique component IDs. The default is $(HarvestSuppressUniqueIds) if specified; otherwise, false.
HarvestFileTransformsOptional string property. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. The default is $(HarvestTransforms) if specified.
HarvestFileTreatSpecificWarningsAsErrorsOptional string parameter. Specifies that certain warnings should be treated as errors. The default is $(HarvestTreatSpecificWarningsAsErrors) if specified.
HarvestFileTreatWarningsAsErrorsOptional boolean parameter. Specifies that all warnings should be treated as errors. The default is $(HarvestTreatWarningsAsErrors) if specified; otherwise, false.
HarvestFileVerboseOutputOptional boolean parameter. Specifies that the tool should provide verbose output. The default is $(HarvestVerboseOutput) if specified; otherwise, false.

Example:

<Project Sdk="WixToolset.Sdk">
<PropertyGroup>
<HarvestFileSuppressUniqueIds>true</HarvestFileSuppressUniqueIds>
</PropertyGroup>

<ItemGroup>
<HarvestFile Include="MyProgram.txt">
<ComponentGroupName>TxtProductComponents</ComponentGroupName>
<DirectoryRefId>INSTALLFOLDER</DirectoryRefId>
<SuppressRootDirectory>true</SuppressRootDirectory>
</HarvestFile>

<HarvestFile Include="MyProgram.json">
<ComponentGroupName>JsonProductComponents</ComponentGroupName>
<DirectoryRefId>INSTALLFOLDER</DirectoryRefId>
<SuppressRootDirectory>true</SuppressRootDirectory>
</HarvestFile>
</ItemGroup>

<ItemGroup>
<PackageReference Include="WixToolset.Heat" />
</ItemGroup>
</Project>

Using HarvestProject to harvest output from a project

Harvesting projects is disabled by default because it may not always work correctly. To enable it, set EnableProjectHarvesting to true in your project file.

HarvestProject items can contain the following metadata to control harvesting:

MetadataDescription
ProjectOutputGroupsSemicolon-delimited list of project output groups to harvest. Examples include Binaries and Source.
TransformsOptional string metadata. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring.

The following properties control harvesting:

PropertyDescription
HarvestProjectsAutogenerateGuidsOptional boolean property. Whether to generate authoring that relies on auto-generation of component GUIDs. The default is $(HarvestAutogenerateGuids) if specified; otherwise, true.
HarvestProjectsGenerateGuidsNowOptional boolean property. Whether to generate authoring that generates durable GUIDs when harvesting. The default is $(HarvestGenerateGuidsNow) if specified; otherwise, false.
HarvestProjectsNoLogoOptional boolean property. Whether to show the logo for heat.exe. The default is $(NoLogo) if specified; otherwise, false.
HarvestProjectsProjectOutputGroupsOptional string property. Semicolon-delimited list of project output groups to harvest. Possible Values: Binaries, Symbols, Documents, Satellites, Sources & Content.
HarvestProjectsSuppressAllWarningsOptional boolean parameter. Specifies that all warnings should be suppressed. The default is $(HarvestSuppressAllWarnings) if specified; otherwise, false.
HarvestProjectsSuppressFragmentsOptional boolean property. Whether to suppress generation of separate fragments when harvesting. The default is $(HarvestSuppressFragments) if specified; otherwise, true.
HarvestProjectsSuppressSpecificWarningsOptional string parameter. Specifies that certain warnings should be suppressed. The default is $(HarvestSuppressSpecificWarnings) if specified.
HarvestProjectsSuppressUniqueIdsOptional boolean property. Whether to suppress generation of unique component IDs. The default is $(HarvestSuppressUniqueIds) if specified; otherwise, false.
HarvestProjectsTransformsOptional string property. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. The default is $(HarvestTransforms) if specified.
HarvestProjectsTreatSpecificWarningsAsErrorsOptional string parameter. Specifies that certain warnings should be treated as errors. The default is $(HarvestTreatSpecificWarningsAsErrors) if specified.
HarvestProjectsTreatWarningsAsErrorsOptional boolean parameter. Specifies that all warnings should be treated as errors. The default is $(HarvestTreatWarningsAsErrors) if specified; otherwise, false.
HarvestProjectsVerboseOutputOptional boolean parameter. Specifies that the tool should provide verbose output. The default is $(HarvestVerboseOutput) if specified; otherwise, false.

Example:

<Project Sdk="WixToolset.Sdk">
<PropertyGroup>
<EnableProjectHarvesting>true</EnableProjectHarvesting>
<HarvestProjectsSuppressUniqueIds>true</HarvestProjectsSuppressUniqueIds>
</PropertyGroup>

<ItemGroup>
<HarvestProject Include="..\MyProgram\MyProgram.csproj" ProjectOutputGroups="Binaries;Content;" />
</ItemGroup>

<!-- As soon as EnableProjectHarvesting set to true, Heat will try to Harvest all referenced projects. Notice the DoNotHarvest flag, this tells Heat not to do that. -->
<ItemGroup>
<ProjectReference Include="..\MyProgram\MyProgram.csproj" DoNotHarvest="true" />
</ItemGroup>

<ItemGroup>
<PackageReference Include="WixToolset.Heat" />
</ItemGroup>
</Project>

Once harvested, you can use these ouput groups in your wxs file as with a ComponentGroupRef.

Example:

<ComponentGroupRef Id="MyProgram.Binaries" />
<ComponentGroupRef Id="MyProgram.Content" />