Documentation updates

barnson · barnson · commit b3457457eb76 · 2026-03-05T10:37:24.000-05:00
Fixes wixtoolset/issues#7981 Fixes wixtoolset/issues#9200 Fixes wixtoolset/issues#9237 Fixes wixtoolset/issues#9238
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -92,6 +92,7 @@ export default defineConfig({
           ] },
 
           { label: 'Tools and concepts', collapsed: true, items: [
+            'wix/tools/identifiers',
             'wix/tools/msbuild',
             'wix/tools/preprocessor',
             'wix/tools/payloads',
@@ -100,8 +101,7 @@ export default defineConfig({
             'wix/tools/dtf',
             'wix/tools/patches',
             'wix/tools/codepage',
-            'wix/tools/wixexe',
-            'wix/tools/heat'
+            'wix/tools/wixexe'
           ] },
 
           { label: 'WiX extensions and custom actions', collapsed: true, autogenerate: { directory: '/wix/tools/wixext' } },
diff --git a/src/content/docs/wix/index.md b/src/content/docs/wix/index.md
@@ -43,7 +43,7 @@ revenue-generating use of the project’s releases requires participation in the
 
 ### Running packages built with WiX
 
-In general, packages you build with WiX will work on Windows 7 or later. Code that you introduce -- for example, custom actions or bootstrapper applications -- can require later versions of Windows.
+In general, packages you build with WiX work on Windows 7 and later. Code you write--for example, custom actions or bootstrapper applications--can require later versions of Windows. In general, the WiX team prioritizes issues related to _supported_ versions of Windows. Once a version of Windows is no longer supported by Microsoft, public interest in those versions is limited.
 
 ### Building packages with WiX
 
diff --git a/src/content/docs/wix/tools/burn/builtin-variables.md b/src/content/docs/wix/tools/burn/builtin-variables.md
@@ -60,6 +60,8 @@ The Burn engine offers a set of commonly-used variables so you can use them with
 | WindowsFolder | The well-known folder for CSIDL_WINDOWS. |
 | WindowsVolume | The well-known folder for the windows volume. |
 | WixBundleAction | Numeric value of BOOTSTRAPPER_ACTION from the command-line and updated during the call to IBootstrapperEngine::Plan. |
+| WixBundleAuthoredScope | Reports the bundle's scope at build time: 1=Per-machine, 2=Per-machine or per-user, 3=Per-user or per-machine, 4=Per-user |
+| WixBundleDetectedScope | Reports the scope of the bundle when it was originally installed: 1=Per-machine, 2=Per-user |
 | WixBundleDirectoryLayout | The folder provided to the `-layout` switch (default is the directory containing the bundle executable). This variable can also be set by the bootstrapper application to modify where files will be laid out. |
 | WixBundleElevated | Non-zero if the bundle was launched elevated and set to `1` once the bundle is elevated. For example, use this variable to show or hide the elevation shield in the bootstrapper application UI. |
 | WixBundleExecutePackageCacheFolder | The absolute path to the currently executing package's cache folder. This variable is only available while a package is executing. |
@@ -70,6 +72,7 @@ The Burn engine offers a set of commonly-used variables so you can use them with
 | WixBundleManufacturer | The manufacturer of the bundle (from `Bundle/@Manufacturer`). |
 | WixBundleOriginalSource | The source path where the bundle originally ran. |
 | WixBundleOriginalSourceFolder | The folder where the bundle originally ran. |
+| WixBundlePlannedScope | Reports the scope of the bundle when the BA began the planning phase: 1=Per-machine, 2=Per-user |
 | WixBundleSourceProcessPath | The source path of the bundle where originally executed. Will only be set when bundle is executing in the clean room. (Removed in WiX v5) |
 | WixBundleSourceProcessFolder | The source folder of the bundle where originally executed. Will only be set when bundle is executing in the clean room. (Removed in WiX v5) |
 | WixBundleProviderKey | The bundle dependency provider key. |
diff --git a/src/content/docs/wix/tools/identifiers.md b/src/content/docs/wix/tools/identifiers.md
@@ -0,0 +1,50 @@
+---
+title: Identifiers
+---
+
+Identifiers in WiX follow familiar rules for allowed characters:
+
+- All characters must be in the ASCII range.
+- The first character must be a letter (`A-Z` or `a-z`) or an underscore (`_`).
+- The remaining characters must be a letter (`A-Z` or `a-z`), an underscore (`_`), a period (`.`), or a digit (`0-9`).
+
+These rules match Windows Installer's own rules. [MSI has additional rules and conventions.](https://learn.microsoft.com/en-us/windows/win32/msi/about-properties)
+
+
+## Access modifiers
+
+WiX supports specifying scope to identifiers, much like access modifiers in languages like C#:
+
+- `global`: Indicates the identifier is globally visible to all other sections.
+- `library`: Indicates the identifier is visible only to sections in the same library.
+- `file`: Indicates the identifier is visible only to sections in the same source file.
+- `section`: Indicates the identifier is visible only to the section where it is defined.
+- `virtual`: Indicates the identifier can be overridden by another symbol. Virtual identifiers are always `global`.
+- `override`: Indicates the identifier overrides a virtual symbol. Overridden virtual identifiers are always `global`.
+
+Identifiers are `global` by default. Global identifiers are recorded in the output (package or bundle, for example) literally. Library, file, and section identifiers are given stable, calculated identifiers in the output so they cannot be referred to except as allowed by the access modifier. For example, an identifier of `section Foo` cannot be referred to except within the section (fragment, for example); if an identifier is required by the output (such as a file id in an MSI package), WiX supplies a stable, calculated identifier instead of `Foo`. That lets you keep `Foo` "private."
+
+### Virtual and overridden identifiers
+
+It's frequently useful to provide a default aspect to an identifier but allow the developer to override that default. The canonical example is to schedule a custom action at a particular point in `InstallExecuteSequence` but to allow a developer to override the default scheduling. (Note that such overrides aren't always a good idea; consider carefully why the default is what it is.)
+
+For example, WiX extensions define custom action scheduling with the `virtual` access modifier:
+
+```xml
+<InstallExecuteSequence>
+    <Custom
+        Action="virtual $(var.Prefix)CloseApplications$(var.Suffix)"
+        Before="InstallFiles"
+        Condition="VersionNT &gt; 400" />
+</InstallExecuteSequence>
+```
+
+To reschedule it, use the `override` access modifier to override the scheduling provided by the `virtual` symbol:
+
+```xml
+<InstallExecuteSequence>
+    <Custom
+        Action="override Wix4CloseApplications_$(sys.BUILDARCHSHORT)"
+        After="InstallInitialize" />
+</InstallExecuteSequence>
+```
diff --git a/src/content/docs/wix/tools/msbuild.md b/src/content/docs/wix/tools/msbuild.md
@@ -2,7 +2,7 @@
 title: MSBuild
 ---
 
-WiX v4 is available as an MSBuild SDK. SDK-style projects have smart defaults that make for simple .wixproj project authoring. For example, here's a minimal .wixproj that builds an MSI from the .wxs source files in the project directory:
+WiX is available as an MSBuild SDK. SDK-style projects have smart defaults that make for simple .wixproj project authoring. For example, here's a minimal .wixproj that builds an MSI from the .wxs source files in the project directory:
 
 ```xml
 <Project Sdk="WixToolset.Sdk/6.0.2">
@@ -116,7 +116,7 @@ variables will not be available when using the command-line to build a project f
 Sometimes you need to add or modify several of the same properties in multiple MSBuild projects, like manufacturer name, copyright, product name, and so forth. Instead of editing every single project, you can manage properties from a central location in a file named Directory.Build.props.
 
 :::info
-Directory.Build.props is a feature of Microsoft.Common.props, which the WiX v4 MSBuild targets consume. The same is also true of Directory.Build.targets and Microsoft.Common.targets. [You can read more about this support here.](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-directory)
+Directory.Build.props is a feature of Microsoft.Common.props, which the WiX MSBuild targets consume. The same is also true of Directory.Build.targets and Microsoft.Common.targets. [You can read more about this support here.](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-directory)
 :::
 
 To use Directory.Build.props, add it to the root of your project -- MSBuild will find the file in parent directories -- and give it a property group. For example:
diff --git a/src/content/docs/wix/tools/preprocessor.md b/src/content/docs/wix/tools/preprocessor.md
@@ -97,7 +97,7 @@ $(MyVariable)
 ```
 
 :::tip
-In WiX v3, user-defined variables were referenced with the syntax `$(var.MyVariable)`. WiX v4 uses `$(MyVariable)` instead and supports `$(var.MyVariable)` for backward compatibility.
+WiX uses `$(MyVariable)` instead and supports `$(var.MyVariable)` for compatibility with WiX v3.
 :::
 
 
diff --git a/src/content/docs/wix/tools/wixexe.md b/src/content/docs/wix/tools/wixexe.md
@@ -355,7 +355,7 @@ _sourceFile_ can include wildcards like `*.wxs`.
 | `Win64AttributeRenamed` | The Win64 attribute has been renamed. Use the Bitness attribute instead. |
 | `Win64AttributeRenameCannotBeAutomatic` | Breaking change: The Win64 attribute's value '{0}' cannot be converted automatically to the new Bitness attribute. |
 | `TagElementRenamed` | The Tag element has been renamed. Use the element 'SoftwareTag' name. |
-| `IntegratedDependencyNamespace` | The Dependency namespace has been incorporated into WiX v4 namespace. |
+| `IntegratedDependencyNamespace` | The Dependency namespace has been incorporated into WiX namespace. |
 | `RemoveUnusedNamespaces` | Remove unused namespaces. |
 | `RemotePayloadRenamed` | The Remote element has been renamed. Use the "XxxPackagePayload" element instead. |
 | `NameAttributeMovedToRemotePayload` | The XxxPackage/@Name attribute must be specified on the child XxxPackagePayload element when using a remote payload. |
@@ -375,7 +375,7 @@ _sourceFile_ can include wildcards like `*.wxs`.
 | `MsuPackageKBObsolete` | The MsuPackage element contains obsolete '{0}' attribute. Windows no longer supports silently removing MSUs so the attribute is unnecessary. The attribute will be removed. |
 | `MsuPackagePermanentObsolete` | The MsuPackage element contains obsolete '{0}' attribute. MSU packages are now always permanent because Windows no longer supports silently removing MSUs. The attribute will be removed. |
 | `MoveNamespacesToRoot` | Namespace should be defined on the root. The '{0}' namespace was move to the root element. |
-| `CustomActionIdsIncludePlatformSuffix` | Custom action ids have changed in WiX v4 extensions. Because WiX v4 has platform-specific custom actions, the platform is applied as a suffix: _X86, _X64, _A64 (Arm64). When manually rescheduling custom actions, you must use the new custom action id, with platform suffix. |
+| `CustomActionIdsIncludePlatformSuffix` | Custom action ids have changed in WiX v4 extensions. Because WiX now has platform-specific custom actions, the platform is applied as a suffix: _X86, _X64, _A64 (Arm64). When manually rescheduling custom actions, you must use the new custom action id, with platform suffix. |
 | `StandardDirectoryRefDeprecated` | The {0} directory should no longer be explicitly referenced. Remove the DirectoryRef element with Id attribute '{0}'. |
 | `EmptyStandardDirectoryRefNotConvertable` | Referencing '{0}' directory directly is no longer supported. The DirectoryRef will not be removed but you will probably need to reference a more specific directory. |
 | `WixMbaPrereqLicenseUrlDeprecated` | The magic WixVariable 'WixMbaPrereqLicenseUrl' has been removed. Add bal:PrereqLicenseUrl="_url_" to a prereq package instead. |
diff --git a/src/content/docs/wix/tools/wixext/quietexec.md b/src/content/docs/wix/tools/wixext/quietexec.md
@@ -113,7 +113,7 @@ WixSilentExec supports silent and deferred execution like WixQuietExec.
 
 ## 64-bit awareness
 
-WixQuietExec64 and WixSilentExec64 are variants of WixQuietExec and WixSilentExec that are 32-bit custom actions (regardless of name) that are 64-bit aware. Specifically, they know how to turn off file-system redirections (for example) to support running 64-bit processes. WiX v4 has native custom actions for all three supported platforms (x86, x64, and Arm64), so if you need to call a 64-bit process from a 32-bit package, use those by hard-coding the `BinaryRef`. For example:
+WixQuietExec64 and WixSilentExec64 are variants of WixQuietExec and WixSilentExec that are 32-bit custom actions (regardless of name) that are 64-bit aware. Specifically, they know how to turn off file-system redirections (for example) to support running 64-bit processes. WiX has native custom actions for all three supported platforms (x86, x64, and Arm64), so if you need to call a 64-bit process from a 32-bit package, use those by hard-coding the `BinaryRef`. For example:
 
 ```xml
 <CustomAction
diff --git a/src/content/docs/wix/whatsnew/configurable_scope_bundles.md b/src/content/docs/wix/whatsnew/configurable_scope_bundles.md
@@ -5,9 +5,62 @@ sidebar:
 ---
 
 :::tip
-Content to come:
+Configurable scope bundles are available in WiX v7 and later.
+:::
+
+Burn supports ["dual-purpose" packages](https://learn.microsoft.com/en-us/windows/win32/msi/single-package-authoring) that can be installed either per-user or per-machine. Bundles that contain a dual-purpose package are considered configurable-scope bundles. When such bundles are installed, their bootstrapper application tells Burn how to install the dual-purpose packages:
+
+- Default: Install dual-purpose packages based on their authoring. `Package/@Scope="perUserOrMachine` packages are installed per-user by default. `Package/@Scope="perMachineOrUser` packages are installed per-machine by default.
+- PerUser: Dual-purpose packages are installed per-user.
+- PerMachine: Dual-purpose packages are installed per-machine.
 
-- https://github.com/wixtoolset/issues/issues/9235
-- https://github.com/wixtoolset/issues/issues/9237
-- https://github.com/wixtoolset/issues/issues/9238
+:::tip
+Single-purpose per-user or per-machine packages do not change their scope based on the BA's choice. They're fixed in scope at build time.
 :::
+
+
+## Supporting configurable-scope bundles with custom bootstrapper applications
+
+Custom bootstrapper applications can offer UI or business logic to determine the scope a bundle will be installed with. Once the scope decision has been made, the BA provides it to Burn during planning. To do so, pass the scope argument to the `Plan` function. 
+
+In a managed-code BA, pass one of `BundleScope.Default`, `BundleScope.PerUser`, or `BundleScope.PerMachine` to `Plan`.
+
+In a native-code BA, pass one of `BOOTSTRAPPER_SCOPE_DEFAULT`, `BOOTSTRAPPER_SCOPE_PER_USER`, or `BOOTSTRAPPER_SCOPE_PER_MACHINE` to `Plan`.
+
+
+## Supporting configurable-scope bundles with WixStandardBootstrapperApplication 
+
+WixStdBA supports configurable-scope bundles and all the stock WixStdBA themes include scope-selection radio buttons on the Options page. WixStdBA relies on the bundle variable `WixStdBAScope` to be set either to `PerUser` for per-user scope or `PerMachine` for per-machine scope. The stock WixStdBA themes accomplish this with radio buttons like this:
+
+```xml
+<RadioButtons Name="WixStdBAScope">
+  <RadioButton X="11" Y="180" Height="20" Width="-11" Value="PerUser" EnableCondition="WixBundleAuthoredScope = 2 OR WixBundleAuthoredScope = 3" HideWhenDisabled="yes" FontId="3">#(loc.OptionsPerUserScopeText)</RadioButton>
+  <RadioButton X="11" Y="200" Height="20" Width="-11" Value="PerMachine" EnableCondition="WixBundleAuthoredScope = 2 OR WixBundleAuthoredScope = 3" HideWhenDisabled="yes" FontId="3">#(loc.OptionsPerMachineScopeText)</RadioButton>
+</RadioButtons>
+```
+
+The `EnableCondition="WixBundleAuthoredScope = 2 OR WixBundleAuthoredScope = 3"` attribute value enables the scope-selection radio buttons only when a configurable-scope bundle is being executed.
+
+You can have an entirely custom theme using any UI you prefer: Just have it set `WixStdBAScope` to either `PerUser` for per-user scope or `PerMachine` for per-machine scope. You can also set `WixStdBAScope` to a static value in your `Bundle` authoring if you want to force a particular scope for any dual-purpose packages.
+
+
+## Configurable-scope bundle variables
+
+Burn adds some variables that you can use in WixStdBA custom themes or in your own BAs to detect that a bundle has configurable scope.
+
+- WixBundleAuthoredScope: Reports the bundle's scope at build time:
+  - 1: Per-machine
+  - 2: Per-machine or per-user
+  - 3: Per-user or per-machine
+  - 4: Per-user
+- WixBundleDetectedScope: Reports the scope of the bundle when it was originally installed:
+  - 1: Per-machine
+  - 2: Per-user
+- WixBundlePlannedScope: Reports the scope of the bundle when the BA began the planning phase:
+  - 1: Per-machine
+  - 2: Per-user
+
+
+## Configurable-scope bundles as `BundlePackage`s
+
+Bundles can include configurable-scope bundles in their chains. When the consuming bundle is built, XXX
diff --git a/src/content/docs/wix/whatsnew/index.md b/src/content/docs/wix/whatsnew/index.md
@@ -4,6 +4,11 @@ sidebar:
   order: 2
 ---
 
+## What's new in WiX v7
+
+WiX v7.0.0-rc.2 is available. See [the release notes](/wix/whatsnew/releasenotes/#wix-v7) for details about this prerelease.
+
+
 ## What's new in WiX v6
 
 WiX v6 continues to be highly compatible in its language syntax with WiX v5 and even v4. We're liking how easy it is to pick up new versions of WiX without worrying about code conversion.
diff --git a/src/content/docs/wix/whatsnew/obsolete.md b/src/content/docs/wix/whatsnew/obsolete.md
@@ -1,14 +1,23 @@
 ---
-title: Heat harvesting
+title: Deprecated and obsolete features
+sidebar:
+  order: 8
 ---
 
+:::tip
+The features described here are deprecated and have been or will be removed from WiX.
+:::
+
+
+## Heat harvesting
+
 :::caution[Obsolete]
-`heat.exe` and the information on this page is obsolete. It will be deprecated in a future version of WiX.
-Consider adopting [HeatWave's advanced harvesting](/heatwave/build-tools/harvesting/) or the [`Files` element in WiX v5+](/wix/schema/wxs/files/).
+Heat is obsolete. It was removed in WiX v7.
+Consider adopting [HeatWave's advanced harvesting](/heatwave/build-tools/harvesting/) or the [`Files` element](/wix/schema/wxs/files/) or [`Payloads` element](/wix/schema/wxs/payloads/).
 See the [harvesting technology comparisons](/heatwave/build-tools/harvesting/comparisons/) for more details.
 :::
 
-In WiX v4, Heat is available in a WiX extension NuGet Package. To use Heat to harvest directories, files, or projects:
+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](https://www.nuget.org/packages/WixToolset.Heat/).
 2. Add an item group based on the kind of harvesting you want to do in your project:
diff --git a/src/content/docs/wix/whatsnew/releasenotes.md b/src/content/docs/wix/whatsnew/releasenotes.md
@@ -6,6 +6,7 @@ sidebar:
 
 ## WiX v7
 
+- WiX v7.0.0-rc.2 was published 5-Mar-2026.
 - WiX v7.0.0-rc.1 was published 6-Feb-2026.
 
 WiX v7 continues our three-year-old tradition of shipping releases annually and adding features and fixing bugs while maintaining high compatibility with previous releases.
