zz将 VSTO 插件部署给所有用户

原文:zz将 VSTO 插件部署给所有用户

　　注：本文原作者 Misha Shneerson 是 VSTO 团队的工程师。原文可以在下列地址找到：http://blogs.msdn.com/mshneer/archive/2007/09/05/deploying-your-vsto-add-in-to-all-users-part-i.aspx。

　　VSTO 插件（也叫“托管代码 Office 插件”）在部署方面有一个严重的不足，简单来说，微软只告诉了我们如何把这些插件部署到单个用户环境；而“如何一次性部署到一台机器的所有用户环境中”成为了我们的阿喀琉斯之踵。本文将给告诉你如何解决这个问题。

　　首先让我们了解一些背景知识。

　　Office 2007 已经内置了对托管代码插件的支持，通过一个叫“Manifest”的注册表值，Office 应用程序可以区分传统的 COM 插件和托管代码插件。这个键值可以在下列位置找到：HKCU\Software\Microsoft\Office\<App> \AddIns\<AddInName>。

　　传统的 COM 插件可以通过在 HKLM\Software\Microsoft\Office\<App>\AddIns 注册自己的信息从而实现让本机所有的用户都可以使用。但是托管代码插件只能注册在 HKCU 里面，注册在 HKLM 里面的托管代码插件会被忽略。

　　要创建一个安装包，做到能够往启动安装程序的那个用户的注册表里面写入 插件信息并不困难。但是，要把同样的信息复制到本机所有用户的注册表键里面，就需要比较高级的 Win32 API 使用技巧了。如果还要再稍微深入一步，我们可以让安装程序把插件注册信息写入“模板”（存在于 C:\Documents and Settings\Default User\ntuser.dat），这样可以保证将来使用本机的新用户直接就有相应的注册表信息。关于这种技巧，请参见 Raymond Chen 的文章。

　　已经在抓脑袋了？其实有一种相对来说容易得多的解决方案。诀窍就在于使用 Office 的一个内部机制，在用户启动 Office 应用程序的时候，把 HKLM 里面注册的信息复制到当前用户的 HKCU 里面去。

　　针对 Office 2007，这个神奇的键值就在这里：HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings。如果你的电脑已经安装了 Office 2007，你可以打开注册表编辑器察看一下那里（如果是 x64 的操作系统，则应该在 Wow6432Node 的相应位置里面）。你会发现里面有不少看似随机的键，这些随机的键里面，又有“Create”以及“Delete”键；再进入一层看，就会发现里面似乎包 含着某些完整路径的注册表信息！

　　我们所见到的就是 Office 2007 的一种 HKLM 到 HKCU 的信息复制机制，而这种机制可以在注册表中进行完全的控制。让我们来进一步研究这种机制到底是怎么工作的。我们可以先做一个小练习——把下面的内容复制到 记事本程序，存为“testpropagation_create.reg”文件。然后运行这个文件，把其中的信息导入 HKLM。

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation]
"Count"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation\Create\Software\Microsoft\Office\TestKey]
"TestValue"="Test"

　　然后启动 Excel 2007，再检查一下注册表，你会发现你的 HKCU 中，有两个新的键值被创建出来了：

• HKCU\Software\Microsoft\Office\TestKey 有了一个值：TestValue
• HKCU\Software\Microsoft\Office\12.0\User Settings\TestPropagation 有一个 Count 值，并且等于 1

　　下一步，我们看看如何用同样的机制来删除键值。把下面的内容复制并保存到“testpropagation_delete.reg”文件，并且运行：

Windows Registry Editor Version 5.00
[-HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation\Create]
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation]
"Count"=dword:00000002
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation\Delete\Software\Microsoft\Office\TestKey]

　　高亮显示的文字标明了和之前一个文件不同的地方。我们先移除之前创建的 TestPropagation\Create 键，注意前面的“-”符号，它表示删除键值。为了让指令正确执行，我们需要保证 HKLM 里面的 Count 值和 HKCU 里面的 Count 值不同，所以把 Count 的值设置成了 2。最后，Software\Microsoft\Office\TestKey 被放在了 TestPropagation\Delete 里面，这样 Office 就知道应该是删除那个键值，而不是创建。

　　执行了 testpropagation_delete.reg 之后，你会发现：

• HKCU\Software\Microsoft\Office\TestKey 键已经被删除
• HKCU\Software\Microsoft\Office\12.0\User Settings\TestPropagation 键的 Count 值被设置成了 2

　　好了，现在我们已经清楚了 Office 的注册表键值复制机制是怎么工作的。至于怎么利用这种机制来改进我们的插件安装程序，应该也能猜个八九不离十了吧？在本文的下篇中，我们将一起来看如何为 一个 VSTO 2005 SE 的插件安装程序做一个自定义动作，结合上述机制，达到“部署到本机所有用户”的最终目的。

　　在“上篇”中，我们介绍了准备知识。本文要把它付诸实用：如何在你的 Office 2007 插件安装程序中具体实现“部署到所有本机所有用户”，这包括任何安装程序都要处置的“安装”、“修复”和“删除”三大功能：

• 在安装插件的时候，我们需要写入一些类似“上篇”中“testpropagation_create.reg”文件的注册表键值，其中包含的“Create”指令会让 Office 把注册表键值复制到用户的 HKCU 里面去。
• 在卸载插件的时候，我们要把“Create”指令替换成“Delete”指令，让 Office 删除 HKCU 中对应的键值。同时，我们还需要把“Count”注册表值减少，这样可以保证 Office 要执行“Delete”指令。
• 在执行修复的时候，我们需要增加“Count”的值，这样会让 Office 再把 HKLM 里面的键值复制到 HKCU。

　　我们先来处理安装的时候需要用到的键值。最方便的方法莫过于修改一下现 成的 VSTO 2005 SE 插件安装程序工程（创建插件工程时附带自动创建的安装程序工程）。就让我们来开一个新的 Excel 2007 插件工程好了，起个名字叫“MyAddIn”。你会发现 VSTO 自动帮你创建了一个配套的 MyAddInSetup 工程。打开这个工程，切换到注册表视图，然后把里面现成的注册表键值设置全部删除（比如那些在 HKEY_CURRENT_USER 里面的）。然后，把下面的注册表信息保存到一个 .reg 文件中，右键单击“Registry on Target Machine”节点，选择“导入（Import）……”，选中你刚才创建的 .reg 文件。这样就把我们需要的注册表信息导入安装程序工程了。如果有必要，你可以调整下面高亮显示的部分，以对应项目的实际情况。

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\MyCompany.MyAddIn\Create\Software\Microsoft\Office\Excel\Addins\MyCompany.MyAddIn]

"Description"="MyAddIn -- an addin created with VSTO technology"
"Manifest"="[TARGETDIR]MyAddIn.dll.manifest"
"FriendlyName"="MyAddIn"
"LoadBehavior"=dword:00000003
"CommandLineSafe"=dword:00000001

　　做完这一步，你的注册表视图看起来应该类似于下图：

　　好了，这样一来，我们就可以保证在卸载 Add-In 的时候，相关的注册表键值会被正确删除。我还建议大家在属性窗口里面把“Create”节点的“DeleteOnUninstall”属性设置成 True，以此保证这个键值会在卸载的时候被删除。

　　请注意，我们还需要在“MyCompany.MyAddIn”节点增加一个“Count”值。但是不能通过“注册表视图”来加。因为我们不但需要在卸载的时候保留这个值，还要将其减小。如果在设计器里面添加，那就会在卸载的时候被删除了。

　　所以我们需要创建一个自定义安装动作（Custom Action），让它来改变 Count 的值，并且在卸载过程中创建一个“Delete”指令。

　　下面我将向大家展示 Darryn Lavery（促成本文的首要功臣）为他的 MSDN 专栏文章编写的代码（这篇即将发布的文章更加详尽地阐述了本文讨论的问题和解决方案），他无私地把代码与我共享，而我就借花献佛，拿来和大家分享。不过还 是要感谢 Darryn。

　　现在我们就来仔细瞧瞧这个 Custom Action 的代码：先定义一个 RegisterOffice2007AddIn 类，添加一些私有方法。

class RegisterOffice2007AddIn {

#region private methods

private const string userSettingsLocation = @"Software\Microsoft\Office\12.0\User Settings";

public void IncrementCounter(RegistryKey instructionKey) {
        int count = 1;
        object value = instructionKey.GetValue("Count");

if (value != null) {
            if ((int)value != Int32.MaxValue)
                count = (int)value + 1;
        }

instructionKey.SetValue("Count", count);
    }

private string GetApplicationPath(string applicationName) {
        switch (applicationName.ToLower()) {
            case "excel":
                return @"Software\Microsoft\Office\Excel\Addins\";

case "infopath":
                return @"Software\Microsoft\Office\InfoPath\Addins\";

case "outlook":
                return @"Software\Microsoft\Office\Outlook\Addins\";

case "powerpoint":
                return @"Software\Microsoft\Office\PowerPoint\Addins\";

case "word":
                return @"Software\Microsoft\Office\Word\Addins\";

case "visio":
                return @"Software\Microsoft\Visio\Addins\";

case "project":
                return @"Software\Microsoft\Office\MS Project\Addins\";

default:
                throw new Exception(applicationName + " is not a supported application", null);
        }
    }

#endregion

　　上面的代码有两个方法：IncrementCounter 负责正确地更新“Count”键值；GetApplicationPath 返回针对某个 Office 应用程序的插件信息注册表键值路径。

　　再看一个在“安装”和“修复”的时候直接被调用的方法：

public void RegisterAddIn(string addInName) {
    RegistryKey userSettingsKey = null;
    RegistryKey instructionKey = null;

try {
        userSettingsKey = Registry.LocalMachine.OpenSubKey(userSettingsLocation, true);

if (userSettingsKey == null) {
            throw new Exception("Internal error: Office User Settings key does not exist", null);
        }

instructionKey = userSettingsKey.OpenSubKey(addInName, true);

if (instructionKey == null) {
            instructionKey = userSettingsKey.CreateSubKey(addInName);
        } else {
            // 删除“Delete”指令
            try {
                instructionKey.DeleteSubKeyTree("DELETE");
            } catch (ArgumentException) { } // “Delete”指令不存在，忽略这种情况下的异常
        }

IncrementCounter(instructionKey);

} finally {
        if (instructionKey != null)
            instructionKey.Close();

if (userSettingsKey != null)
            userSettingsKey.Close();
    }
}

　　在上面的代码中，我们首先保证“Delete”注册表指令不存在，然后增加计数器值（Count 键值）。要注意的是，我们没有用代码创建“Create”指令，因为这个指令已经在之前的“注册表视图”中定义好了，它会被自动写入注册表。

　　最后就是在“卸载”的时候被调用的方法：

public void UnRegisterAddIn(string applicationName, string addInName) {
    RegistryKey userSettingsKey = null;
    RegistryKey instructionKey = null;
    RegistryKey deleteKey = null;

try {
        userSettingsKey = Registry.LocalMachine.OpenSubKey(userSettingsLocation, true);

if (userSettingsKey == null) {
            throw new Exception("Internal error: Office User Settings key does not exist", null);
        }

instructionKey = userSettingsKey.OpenSubKey(addInName, true);

if (instructionKey == null) {
            instructionKey = userSettingsKey.CreateSubKey(addInName);
        } else {
            // 确保“Create”指令被删除
            try {
                instructionKey.DeleteSubKeyTree("CREATE");
            } catch (ArgumentException) { } // “Create”指令不存在，忽略这种情况下的异常
        }

string instructionString =
                        @"DELETE\" +
                        GetApplicationPath(applicationName) +
                        @"\" +
                        addInName;

deleteKey = instructionKey.CreateSubKey(instructionString);

IncrementCounter(instructionKey);
    } finally {
        if (deleteKey != null)
            deleteKey.Close();

if (instructionKey != null)
            instructionKey.Close();

if (userSettingsKey != null)
            userSettingsKey.Close();
    }
}

　　好了，差不多大功告成！只要把这些代码包装进一个 Custom Action DLL（假设你已经有类似的经验），把 CustomActionData 属性设置成 /addinName="MyCompany.MyAddIn" /application="Excel"（具体的值根据你的情况自定义）。在“安装”、“卸载”或者“回滚”的时候调用这些方法，就可以啦。我会在稍后的日志中作一个总结。