WiX Toolset使用技巧——快捷方式处理

admin

在开始菜单中创建快捷方式
当我们安装应用时，在用户的开始菜单中添加启动应用的快捷方式是一个普遍需求。本节将介绍如何在开始菜单中创建快捷方式。我们假设你有一个WiX源文件，并且配置了文件内容，关于文件配置详见： 译文：WiX Toolset使用技巧——文件处理 。

步骤1：定义目录结构
因为开始菜单快捷方式要安装在与常规应用文件不同的目录下，因此我们需要修改安装目录结构。以下WiX代码段需要放在Id值为TARGETDIR的 <Directory> 元素下，同时我们在为开始菜单添加目录结构信息：

1. <Directory Id="ProgramMenuFolder">
   
2.     <Directory Id="ApplicationProgramsFolder" Name="My Application Name"/>
   
3. </Directory>

复制代码

Id值ProgramMenuFolder是一个标准的Windows安装程序属性 —— 用于指向目标机器的开始菜单文件夹。第二个目录元素在开始菜单下创建了一个名为My Application Name的子文件夹，并同时给其赋了一个Id值，以供WiX项目其他位置使用。

步骤2：添加快捷方式到安装包
使用以下三个元素将快捷方式添加到安装程序中：

一个 <Component> 元素 —— 指定安装的最小单位
一个 <Shortcut> 元素 —— 指定需要安装的快捷方式
一个 <RemoveFolder> 元素 —— 确保在卸载应用程序时进行合理的清理。
以下 代码使用了步骤1中的目录结构，并创建了开始菜单快捷方式。

1. <DirectoryRef Id="ApplicationProgramsFolder">
   
2.     <Component Id="ApplicationShortcut" Guid="PUT-GUID-HERE">
   
3.         <Shortcut Id="ApplicationStartMenuShortcut"
   
4.                 Name="My Application Name"
   
5.                 Description="My Application Description"
   
6.                 Target="[#myapplication.exe]"
   
7.                 WorkingDirectory="APPLICATIONROOTDIRECTORY"/>
   
8.         <RemoveFolder Id="ApplicationProgramsFolder" On="uninstall"/>
   
9.         <RegistryValue Root="HKCU" Key="Software\Microsoft\MyApplicationName" Name="installed" Type="integer" Value="1" KeyPath="yes"/>
   
10.     </Component>
    
11. </DirectoryRef>
    
12. <DirectoryRef>

复制代码

元素用于引用步骤1中创建的目录结构。通过引用ApplicationProgramsFolder目录，快捷方式将会安装到开始菜单的My Application Name文件夹下面。

DirectoryRef下面是一个独立的组件 —— 用于组合安装快捷方式的元素。第一个元素是Shortcut，它在开始菜单中创建 实际的快捷方式。快捷方式的Id属性值是一个唯一值。Name属性是在开始菜单中显示的文本。Description属性则是一个可选属性，它用于添加额外的应用描述。Target属性则指向磁盘 上要启动的可执行文件。注意，它通过使用 [#FileId] 的语法来引用完整路径，其中 myapplication.exe 是在之前定义的内容。WorkingDirectory属性则设置快捷方式的工作目录。

如果你需要为快捷方式设置一个可选的图标，你首先需要使用 <Icon> 元素将图标包含到安装包中，然后在Shortcut元素的Icon属性上引用它。

另外，添加快捷方式部件还含有另外两个重要部分。第一个部分是RemoveFolder元素，用于确保在用户卸载应用时能够从开始菜单中正确移除ApplicationProgramsFolder。第二个部分是在安装时创建一个注册表项，用于指示应用已安装。这是必需的，因为在为当前用户安装非广告的快捷方式时，快捷方式是不能作为组件的KeyPath —— 即组件需要一个KeyPath，所以添加了 一个注册表项。关于更多创建 注册表项的内容详见： 原文：How To: Write a registry entry during installation

步骤3：告诉Windows安装程序要安装的快捷方式
在为安装包定义了目录结构和列出了快捷方式后，最后一步就是告诉Windows安装程序要安装的快捷方式了。我们使用 <Feature> 元素来处理。以下代码段添加了快捷方式组件的引用，并需要将它插入到一个Feature元素内：

1. <ComponentRef Id="ApplicationShortcut" />

复制代码

其中 <ComponentRef> 元素通过Id属性来引用步骤2中创建的部件。

完整示例
下面的完整示例使用了以上的内容。此示例可以添加到WiX项目中编译，或者通过命令行编译链接，以此生成安装包：

1. <?xml version="1.0" encoding="UTF-8"?>
   
2. <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
   
3.     <Product Id="*" UpgradeCode="PUT-GUID-HERE" Version="1.0.0.0" Language="1033" Name="My Application Name" Manufacturer="My Manufacturer Name">
   
4.         <Package InstallerVersion="300" Compressed="yes"/>
   
5.         <Media Id="1" Cabinet="myapplication.cab" EmbedCab="yes" />
   
6. 
   
7.         <Directory Id="TARGETDIR" Name="SourceDir">
   
8.             <Directory Id="ProgramFilesFolder">
   
9.                 <Directory Id="APPLICATIONROOTDIRECTORY" Name="My Application Name"/>
   
10.             </Directory>
    
11.             <!-- Step 1: Define the directory structure -->
    
12.             <Directory Id="ProgramMenuFolder">
    
13.                 <Directory Id="ApplicationProgramsFolder" Name="My Application Name"/>
    
14.             </Directory>
    
15.         </Directory>
    
16. 
    
17.         <DirectoryRef Id="APPLICATIONROOTDIRECTORY">
    
18.             <Component Id="myapplication.exe" Guid="PUT-GUID-HERE">
    
19.                 <File Id="myapplication.exe" Source="MySourceFiles\MyApplication.exe" KeyPath="yes" Checksum="yes"/>
    
20.             </Component>
    
21.             <Component Id="documentation.html" Guid="PUT-GUID-HERE">
    
22.                 <File Id="documentation.html" Source="MySourceFiles\documentation.html" KeyPath="yes"/>
    
23.             </Component>
    
24.         </DirectoryRef>
    
25. 
    
26.         <!-- Step 2: Add the shortcut to your installer package -->
    
27.         <DirectoryRef Id="ApplicationProgramsFolder">
    
28.             <Component Id="ApplicationShortcut" Guid="PUT-GUID-HERE">
    
29.                 <Shortcut Id="ApplicationStartMenuShortcut"
    
30.                     Name="My Application Name"
    
31.                 Description="My Application Description"
    
32.                     Target="[#myapplication.exe]"
    
33.                         WorkingDirectory="APPLICATIONROOTDIRECTORY"/>
    
34.                 <RemoveFolder Id="ApplicationProgramsFolder" On="uninstall"/>
    
35.                 <RegistryValue Root="HKCU" Key="Software\Microsoft\MyApplicationName" Name="installed" Type="integer" Value="1" KeyPath="yes"/>
    
36.         </Component>
    
37.         </DirectoryRef>
    
38. 
    
39.         <Feature Id="MainApplication" Title="Main Application" Level="1">
    
40.             <ComponentRef Id="myapplication.exe" />
    
41.             <ComponentRef Id="documentation.html" />
    
42.             <!-- Step 3: Tell WiX to install the shortcut -->
    
43.             <ComponentRef Id="ApplicationShortcut" />   
    
44.         </Feature>
    
45.     </Product>
    
46. </Wix>

复制代码

创建网页的快捷方式

WiX支持在安装过程中创建网址快捷方式。本节将演示如何为你的安装程序引用必要的工具库并添加Internet的快捷方式。本节学习基础：先学习上一节的“在开始菜单中创建快捷方式”。

步骤1：为项目添加WiX工具扩展库
WiX对网页快捷方式的支持在WiX扩展库中，所以你需要先将它添加到项目中。如果你是通过命令行使用WiX，则你可以使用以下命令：

-ext WiXUtilExtension
如果你通过Visual Studio来使用Wix，则你可以使用以下步骤添加扩展引用：

在Visual Studio中打开WiX项目
在解决方案管理器中右键项目，然后选择添加引用
在列表中选择 WixUtilExtension.dll 程序集，然后点击添加
关闭添加 引用对话框
步骤2：为项目添加WiX工具扩展库命名空间

在将库添加到项目中后，你需要向项目中添加工具扩展库的命名空间，以便于你可以访问到相应的WiX元素。添加命名空间可以通过修改项目中的顶级 <Wix> 元素来处理 —— 添加如下代码：

1. xmlns:util="http://schemas.microsoft.com/wix/UtilExtension"

复制代码

具有标准命名空间和Utility扩展 命名空间的完整Wix元素示例如下：

1. <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"
   
2.     xmlns:util="http://schemas.microsoft.com/wix/UtilExtension">

复制代码

步骤3：添加Internet快捷方式到安装包中

Intertnet快捷方式通过 <Util:InternetShortcut> 元素创建。下面示例展示了如何添加一个InternetShortcut元素 —— 在上一节示例基础上修改的：

1. <DirectoryRef Id="ApplicationProgramsFolder">
   
2.     <Component Id="ApplicationShortcut" Guid="PUT-GUID-HERE">
   
3.         <Shortcut Id="ApplicationStartMenuShortcut"
   
4.                 Name="My Application Name"
   
5.                 Description="My Application Description"
   
6.                 Target="[#MyApplicationExeFileId]"
   
7.                 WorkingDirectory="APPLICATIONROOTDIRECTORY"/>
   
8.         <util:InternetShortcut Id="OnlineDocumentationShortcut"
   
9.                         Name="My Online Documentation"
   
10.                             Target="http://wixtoolset.org/"/>
    
11.         <RemoveFolder Id="ApplicationProgramsFolder" On="uninstall"/>
    
12.         <RegistryValue Root="HKCU" Key="Software\Microsoft\MyApplicationName" Name="installed" Type="integer" Value="1" KeyPath="yes"/>
    
13.     </Component>
    
14. </DirectoryRef>

复制代码

其中InternetShortcut为Id属性设置了唯一id，并且它位于应用的开始菜单文件夹下。Name属性指定了在开始菜单中显示的快捷方式名称。Target属性指定了快捷方式指向的目标地址。 <DirectoryRef> 元素则用于引用在项目文件中定义的目录结构。通过引用ApplicationProgramsFolder目录，快捷方式将会被安装到用户开始菜单的My Application Name文件夹下面。

创建卸载快捷方式
当安装应用时，在开始菜单中提供卸载应用的快捷方式通常也是一个普遍需求。本节将演示在开始菜单中创建通过所有ICE验证检查的卸载快捷方式所需的步骤。

本节学习基础：已经学习如何在开始菜单中创建快捷方式 —— 本文第一部分。

步骤1：添加卸载快捷方式
使用 <Shortcut> 元素添加卸载快捷方式到开时菜单，同时将快捷方式指向msiexec.exe（实际调用卸载操作的Windows Installer可执行文件）。在ApplicationShortcut部件 中的任何位置添加以下内容：

1. <Shortcut Id="UninstallProduct"            
   
2.         Name="Uninstall My Application"
   
3.         Target="[SystemFolder]msiexec.exe"
   
4.         Arguments="/x [ProductCode]"
   
5.         Description="Uninstalls My Application" />

复制代码

Target属性指向msiexec.exe位置。其中SystemFolder属性将解析为msiexec.exe所在的System32目录。Arguments属性通知msiexec.exe要卸载哪个产品 —— 通过传递ProductCode值。

为了避免在构建时的ICE验证错误，同时添加快捷方式和注册表项以及RemoveFolder元素是重要的。关于它们的描述可以看本文第一部分：在开始菜单 中创建快捷方式。

完整示例
下面的完整示例使用了以上的内容。此示例可以添加到WiX项目中编译，或者通过命令行编译链接，以此生成安装包：

1. <?xml version="1.0" encoding="UTF-8"?>
   
2. <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
   
3.     <Product Id="*" UpgradeCode="PUT-GUID-HERE" Version="1.0.0.0" Language="1033" Name="My Application Name" Manufacturer="My Manufacturer Name">
   
4.         <Package InstallerVersion="300" Compressed="yes"/>
   
5.         <Media Id="1" Cabinet="myapplication.cab" EmbedCab="yes" />
   
6. 
   
7.         <Directory Id="TARGETDIR" Name="SourceDir">
   
8.             <Directory Id="ProgramFilesFolder">
   
9.                 <Directory Id="APPLICATIONROOTDIRECTORY" Name="My Application Name"/>
   
10.             </Directory>
    
11.             <Directory Id="ProgramMenuFolder">
    
12.                 <Directory Id="ApplicationProgramsFolder" Name="My Application Name"/>
    
13.             </Directory>
    
14.         </Directory>
    
15. 
    
16.         <DirectoryRef Id="APPLICATIONROOTDIRECTORY">
    
17.             <Component Id="myapplication.exe" Guid="PUT-GUID-HERE">
    
18.                 <File Id="myapplication.exe" Source="MySourceFiles\MyApplication.exe" KeyPath="yes" Checksum="yes"/>
    
19.             </Component>
    
20.             <Component Id="documentation.html" Guid="PUT-GUID-HERE">
    
21.                 <File Id="documentation.html" Source="MySourceFiles\documentation.html" KeyPath="yes"/>
    
22.             </Component>
    
23.         </DirectoryRef>
    
24. 
    
25.         <DirectoryRef Id="ApplicationProgramsFolder">
    
26.             <Component Id="ApplicationShortcut" Guid="PUT-GUID-HERE">
    
27.                 <Shortcut Id="ApplicationStartMenuShortcut"
    
28.                     Name="My Application Name"
    
29.                 Description="My Application Description"
    
30.                     Target="[#myapplication.exe]"
    
31.                         WorkingDirectory="APPLICATIONROOTDIRECTORY"/>
    
32.                 <!-- Step 1: Add the uninstall shortcut to your installer package -->
    
33.                 <Shortcut Id="UninstallProduct"            
    
34.                         Name="Uninstall My Application"
    
35.                         Description="Uninstalls My Application"
    
36.                         Target="[System64Folder]msiexec.exe"
    
37.                         Arguments="/x [ProductCode]"/>
    
38.                 <RemoveFolder Id="ApplicationProgramsFolder" On="uninstall"/>
    
39.                 <RegistryValue Root="HKCU" Key="Software\Microsoft\MyApplicationName" Name="installed" Type="integer" Value="1" KeyPath="yes"/>
    
40.         </Component>
    
41.         </DirectoryRef>
    
42. 
    
43.         <Feature Id="MainApplication" Title="Main Application" Level="1">
    
44.             <ComponentRef Id="myapplication.exe" />
    
45.             <ComponentRef Id="documentation.html" />
    
46.             <ComponentRef Id="ApplicationShortcut" />   
    
47.         </Feature>
    
48.     </Product>
    
49. </Wix>

复制代码