WIP: Organized obsolescence of Heat in v4

[robmen]

User stories

• As a setup developer I can migrate v3 harvesting functionality that works in CI/CD builds with v4.

• As a WiX developer I can isolate Heat from the core tools such that I can deprecate and replace Heat with better code generation technology in a future release.

Proposal

heat.exe and its MSBuild targets (HeatDirectory, HeatFile, HeatProject)--collectively referenced as "Heat" hereafter--are highly desired features by setup developers.
Unfortunately, there are a few issues with Heat. Some of these are long-standing and some are new in WiX v4:

1. Heat was designed to be run manually and the generated .wxs code checked into source control, which is not how the tool is generally used.
2. Heat is built on the WiX CodeModel which is an outdated design choice and obsolete in WiX v4.
3. Some Heat features require the .NET Framework to work.

Given the popularity of code generation at build-time, we need to entirely re-evaluate the current workflow provided by "Heat" and design a better implementation.
However, this re-evaluation work will not be undertaken in WiX v4.
So the existing Heat functionality will need to be preserved to enable migration from v3 to v4.
At the same time, we need to start the process of obsoleting Heat in v4 to telegraph its removal in a future release.

To that end, Heat will be isolated in a separate NuGet package: WixToolset.Heat.
A NuGet package is used because it can integrate with MSBuild and nuget.exe can deliver the Heat binaries to all Windows-based CI/CD systems.

To integrate the MSBuild targets, a PackageReference item to WixToolset.Heat in a v4 .wixproj should be all that is necessary for the targets to work.

For use outside of MSBuild, heat.exe could be acquired via nuget.exe install and the executable should be available in the tools\<tfm> folder.

Considerations

• If an installation package (MSI/Bundle) is provided for WiX v4, then heat.exe should also be included with wix.exe, thmviewer.exe, etc.

• In v4, wix.exe absorbed the functionality of all the v3 executables (candle.exe, light.exe, smoke.exe, pyro.exe) as commands (or subcommands of commands) except for heat.exe. Given this evolution during v4 converting heat.exe to a generate (or harvest) command would be logical. However, given the plan to re-evaluate the code generation process in a future release, it is better to isolate a standalone heat.exe than give false expectations that code generation will necessarily be a wix.exe command.

See Also

The original feature template follows:

• Describe the scenario and benefits that the feature supports.

heat.exe and its MSBuild tasks (HeatDirectory, HeatFile, HeatProject) are highly desired features but flawed in their design and implementation. In a future release (ideally v5), the concept of harvesting needs to be re-evaluated entirely and better integrated into the WiX toolset. Therefore, the current concept of "Heat" should be supported but clearly on a path to obsolescence.

• Describe how you're accomplishing the feature today (if possible).

heat.exe consumes resources to maintain a form factor with no future. That effort would be better spent on pretty much anything else.

• Describe what you'd like the new feature to do.

In WiX v4, wix.exe has emerged as the single executable "to rule them all", which makes heat.exe the "odd .exe out". Given the evolution of the other v3 .exes to commands on wix.exe and its extensions, converting heat.exe to a harvest command would be logical. However, in a future release (ideally the next release, v5), we need to explore the concept of harvesting and how to best integrate it into the build pipeline. At this time, I think it is highly likely language enhancements will be preferred over maintaining a standalone command like wix.exe harvest

To that end, changes to Heat should be focused on extracting it from deep integration within WiX v4 (such as the direct import of wix.harvesting.targets in wix.targets) while still making heat.exe and the Heat MSBuild tasks available to enable migration from WiX v3 to v4.