diff --git a/astro.config.mjs b/astro.config.mjs index 21482ab..63295c2 100644 --- 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 index a5c855e..4dc40ef 100644 --- 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 index 57b5a39..33dea33 100644 --- 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 new file mode 100644 index 0000000..504a5dc --- /dev/null +++ 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 + + + +``` + +To reschedule it, use the `override` access modifier to override the scheduling provided by the `virtual` symbol: + +```xml + + + +``` diff --git a/src/content/docs/wix/tools/msbuild.md b/src/content/docs/wix/tools/msbuild.md index 4bc0103..919c1f5 100644 --- 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 @@ -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 index 63b2e3f..582cdc5 100644 --- 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 index faca3d6..13d1146 100644 --- 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 index 61abdca..2a0182d 100644 --- 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 + #(loc.OptionsPerUserScopeText) + #(loc.OptionsPerMachineScopeText) + +``` + +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 \ No newline at end of file diff --git a/src/content/docs/wix/whatsnew/index.md b/src/content/docs/wix/whatsnew/index.md index 80be0f8..627bb46 100644 --- 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/tools/heat.md b/src/content/docs/wix/whatsnew/obsolete.md similarity index 97% rename from src/content/docs/wix/tools/heat.md rename to src/content/docs/wix/whatsnew/obsolete.md index 8b15cbf..fed687b 100644 --- a/src/content/docs/wix/tools/heat.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 index e81d1b5..753a213 100644 --- 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.