Wix 4中WIX_DIR_COMMON_DOCUMENTS属性无法使用的问题求助

环境与需求 #

• 系统：Windows 10 Pro
• 工具：Visual Studio 2022 + Wix 4 Heatwave扩展
• 项目类型：MSI Package
• 已安装NuGet包：WixToolset.Util（4.0.1版本，后测试4.0.2版本）
• 需求：将应用部分文件部署到C:\Users\Public\Documents文件夹，计划使用WIX_DIR_COMMON_DOCUMENTS属性

问题现象 #

编译项目时持续报错：

Error WIX0094 The identifier 'Property:WIX_DIR_COMMON_DOCUMENTS' could not be found. Ensure you have typed the reference correctly and that all the necessary inputs are provided to the linker.

移除<PropertyRef Id="WIX_DIR_COMMON_DOCUMENTS" />及其相关引用后，项目可正常编译。

已尝试操作 #

• 检查属性拼写无误
• 卸载并重装WixToolset.Util包
• 修改源码Schema URI
• 清理项目并重启Visual Studio
• 确认WixToolset.UI包功能正常，排除通用包安装冲突

项目主wxs文件代码 #

<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs"
 xmlns:ui="http://wixtoolset.org/schemas/v4/wxs/ui"
 xmlns:util="http://wixtoolset.org/schemas/v4/wxs/util">    
  <Package Name="App" 
           Manufacturer="Company" 
           Version="1.0.0.0" 
           UpgradeCode="xxxxxxxxxxxx"
           Compressed="yes">
    <MajorUpgrade DowngradeErrorMessage="!(loc.DowngradeError)" />        
    <WixVariable Id="WixUILicenseRtf" Value="$(var.ProjectDir)\Eula.rtf" />
    <PropertyRef Id="WIX_DIR_COMMON_DOCUMENTS" />
    <ui:WixUI
        Id="WixUI_Minimal"
        InstallDirectory="INSTALLFOLDER"
    />
    <Feature Id="Main">
      <ComponentGroupRef Id="ABC" />
      <ComponentGroupRef Id="ABCD" />
    </Feature>    
  </Package>
</Wix>

更新情况 #

在另一台工作站重复操作，仅安装WixToolSet.Util包4.0.2并声明该属性，仍出现相同错误。

解决方法 #

Wix 4中WIX_DIR_COMMON_DOCUMENTS并非预定义属性，需通过util:CommonFolder元素显式声明来获取公共文档目录：

1. 确保代码中已正确引用util命名空间（你的代码已包含该引用）
2. 替换原有的<PropertyRef Id="WIX_DIR_COMMON_DOCUMENTS" />为以下代码：

<util:CommonFolder Id="WIX_DIR_COMMON_DOCUMENTS" Folder="CommonDocuments" />

3. 后续可通过[WIX_DIR_COMMON_DOCUMENTS]引用该目录路径，例如在组件中指定文件安装位置：

<Component Id="CommonDocFile" Guid="*">
  <File Source="$(var.ProjectDir)\YourDocument.txt" DestinationDirectory="WIX_DIR_COMMON_DOCUMENTS" />
</Component>

说明 #

Wix 4对系统文件夹的获取方式做了调整，原Wix 3中的部分预定义属性在Wix 4中需要通过util扩展的CommonFolder元素显式声明才能使用。

内容的提问来源于stack exchange，提问作者John Kastana