级别： 初级 贾 春丽, 软件工程师, IBM
魏 洪涛, 高级软件工程师, IBM
2009 年 9 月 25 日 Windows Installer 服务提供了应用程序的安装日志，为我们查找问题的根源提供了有力的帮助。但这些安装日志文件有特定的格式，而且文件大、内容多，也不适合一般开发和测试人员阅读。本文演示了如何利用工具对 Lotus Notes 客户端的安装日志文件进行处理，一方面可以增加对应用程序安装过程的理解，同时也可以更有效地筛选出需要的信息，为定位问题提供帮助。
为什么安装部署日志是重要的？
日志作为一种记录信息的方式，一直是我们检查错误、查找问题根源的有利工具。操作系统有日志，安全系统有日志，同样应用程序也有日志。安装部署日志就是按照某种规范来表达应用程序安装部署行为的，是一个系统的重要组成部分。这里我们简单介绍一下 Windows installer 服务及其是如何提供日志功能的。
微软开发的 Windows Installer 就是由操作系统提供的一个用于程序安装和部署的服务。这个服务是通过两个进程以 Client/Server 的方式工作的，但它们不同于我们常说的网络中的 Client/Server 方式，而是和组件中的 Client/Server 方式类似。通过该服务用户可以比较容易地安装卸载软件和在公司网络中部署软件。直观地，我们可以通过 任务栏 > 任务管理器 找到该服务所依附的进程 – MSIEXEC.EXE。如果想使用这个服务，那么在定制开发安装程序时就必须遵循 Windows Installer 服务的规则，同时安装程序也应该是基于 Windows Installer API 的。
Lotus Notes 客户端的安装程序是基于 Windows Installer API 的。在安装 Notes 客户端的过程中，我们使用特定的参数，就可以得到它的详细的安装日志，包括用户的在安装过程中所做的选择，后台执行的安装动作，每个动作是否成功等细节。
如何获得安装日志？
这里提供两种途径来获得 Notes 客户端应用程序的详细安装日志。
第一种方法是通过命令行的方式。当安装 Notes Client 时，在命令行窗口输入如下命令行 :
Setup.exe /s /v” /L*v C:\temp\installlog.txt /qb+”
|
当程序安装结束后您就可以得到一个安装日志文件 installlog.txt. 这里关键的部分是参数 /L*v C:\temp\installlog.txt。它告诉 Windows Installer 服务记录详细的安装日志到 C:\TEMP 下的 installlog.txt 文件中。
第二种方式是通过注册表设置 Windows Installer 服务提供的日志记录策略。按照以下步骤进行设置：
- 打开注册表
- 找到如下注册表项 HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer
- 按照下表设置两个选项
表 1. 注册表设置项
| 名称
| | 类型
| | Logging
| REG_SZ
| voicewarmupx
| | Debug
| DWORD
| 0000000
|
设置完成后，结果如图 1 所示 :
图 1. 设置后的注册表信息
通过注册表的设置，当 Notes Client 安装完成后，您可以从下列位置找到对应的安装日志文件。
在 Windows XP 系统上，您可以从 C:\Documents and Settings\<user name>\Local Settings\Temp 目录下找到。而在 Windows Vista 系统上，您可以从 C:\Users\<user name>\AppData\Local\Temp 目录下找到。
安装日志的格式及其特点
打开 Notes Client 的安装日志时，您会发现它是按照一定的规则记录的。这里通过几个例子来说明它的一些基本规则。
C/S 规则
正如前边所述，程序的安装过程是通过 Client/Server 的交互来完成的。在安装日志中，关于交互的部分，它的每一行都是按照如下格式记录的。
MSI(client/server process mark)[processID:ThreadID][time stamp]:[Description]
|
其中每个部分如图 2. 所示：
图 2. 记录格式说明
MSI 三个字符作为 开头部分 是固定不变的。C/S 标识部分 指出了记录者，如果是 Client, 就用字符‘c’，如果是 Server，就是字符‘s’表示；同时在 进程，线程 ID 部分标注具体的 ID, 记录的时间在 记录时间 部分标注；而最后的具体内容在 描述部分 标注。下面用两个例子来具体解释这种记录格式。
MSI (c) (08:18) [00:22:02:916]: Validating transform
'C:\Users\admin\AppData\Local\Temp\1465d48a.mst'
with validation bits 0
|
在这个例子中，‘(c)’表明这个记录是由 Client 进程生成的。‘(08:18)’ 是进程、线程的标识。时间发生在’00:22:02:916’。
MSI (s) (98:68) [00:22:22:665]: SOFTWARE RESTRICTION POLICY: Verifying transform
-->
'E:\build\8.5.1\AllClient.msi.w32.prod\1033.MST' against software restriction policy
|
在这个例子中，‘(s)’ 表明这个记录是由 Server 进程生成的。‘(98:68)’ 是进程、线程的标识。时间发生在 ‘00:22:22:665’。
错误代码
在安装程序过程中会涉及到很多安装动作，有标准内置的，也有定制的。当这些动作发生错误时，需要给用户返回详细的信息，让用户知道错误是关于哪个方面的。为了方便在日志中表示错误，微软对错误代码做了一定的编码，所以您在日志中看到的是错误代码，而不是实际的错误信息。下面是几个例子说明。详细的错误代码可以参考 Windows Installer Error Messages。
MSI (c) (08:18) [00:22:02:916]: Note: 1: 2262 2: Patch 3: -2147287038
MSI (s) (98:68) [00:22:22:665]: Note: 1: 2262 2: DigitalSignature 3: -2147287038
|
在以上两行记录中，都有错误代码 2262，我们并不能直观地知道它所代表的含义，只能通过微软的网站查找具体的定义。为了便于本文所述工具的处理，我们把这些错误代码整理后保存到了一个叫 ErrorCode.txt 文件中。
返回值
在日志中，每个标准的和定制的动作都有一个返回值。这里列举了主要的返回值及其它们各自的描述，如表 2 所述。完整的返回值及其描述请参考 Logging of Action Return Values
表 2. 返回值及其描述
| 返回值 | 描述 | 注释 |
|---|
| 0 | A function could not be executed. | 该动作没有被执行。 | | 1，5 | An action completed successfully.
| 这是我们期望的返回值 | | 2 | A user canceled installation.
| 如果用户取消了安装，返回值为 2 | | 3 | A fatal error. | 应该关注的问题，特别是一些定制动作，更容易引起返回值为 3 的错误。 | | 4 | The installation suspended, incomplete. | |
同样地，我们通过例子来说明有关每个动作执行后返回值的规则。请看下面的例子。
Action start 0:22:03: CheckLaunchConditions.
MSI (c) (08:18) [00:22:03:477]: Creating MSIHANDLE (441)
of type 790542 for thread 2072
MSI (c) (08:14) [00:22:03:477]: Invoking remote custom action.
DLL: C:\Users\admin\AppData\Local\Temp\MSID883.tmp,
Entrypoint: CheckLaunchConditions
MSI (c) (08:14) [00:22:03:477]: Closing MSIHANDLE (441)
of type 790542 for thread 2072
Action ended 0:22:03: CheckLaunchConditions. Return value 1.
|
以上六行安装日志记录是一个动作执行的情况。记录主要反映了动作 - checkLaunchConditions 的执行，并且它的返回值是 1，由此知道这个动作的执行是成功的。
引入工具来处理
当从安装日志中按照以上规则去理解或搜索需要的信息时，我们发现是很不方便的。一是日志文件本身内容多，一个文件的大小大概在 10M 或更多。二是虽然日志按照一定规则记录的，但我们阅读和理解时很费力，不直观。它需要我们去查找错误代码，需要我们搜索特定的动作，可我们并不知道它有哪些动作。在这里，我们针对日志的上述规则编写了一个处理工具，您可以从参考链接中下载该工具。
借助工具对安装日志文件做特殊处理，只提取安装过程中的动作及其返回值，同时对于您感兴趣的一些关键字也可以通过工具一起得到。对于一个安装部署过程，如果每个动作都执行正确，一般来讲这次安装部署是成功的。如果发现有您感兴趣的返回值，比如返回值为 3 的动作，那您可以对实际的安装日志进行分析，查看具体的错误原因，或者提交问题报告给相关人员。
首先我们向您介绍该工具对安装日志做了哪些处理以及如何使用它。
工具的特点
- 对错误代码进行了翻译。根据微软提供的错误代码参考，我们在处理日志时，对不直观的错误代码翻译成了比较直观的错误信息。示例如下：
原始的安装日志记录：
MSI (s) (98:68) [00:24:15:563]: Note: 1: 2318 2:
C:\Program Files\IBM\Lotus\Notes\kppicrdr.dll
|
工具处理后的结果：
Line: 70983 MSI (s) (98:68) [00:24:15:563]: Note: File does not exist:
C:\Program Files\IBM\Lotus\Notes\kppicrdr.dll.
|
- 提供对安装日志多个关键字的搜索，特别是支持正则表达式的搜索。
- 对安装日志标注了行号，这样方便您阅读和查找。
工具的使用方法
在命令行窗口中运行命令：MsiLogTranslator.exe。
您将会得到它的具体的命令帮助。其具体运行方式如下所示：
MsiLogTranslator.exe <LOG FILE NAME> ["Strings list"]
|
这个工具带有两个参数，第一个参数是我们要处理的安装日志文件，是必选的；第二个参数是我们需要搜索的关键字符串，是可选的。注意：请保证上节提到的 错误代码文件 和该工具在同一目录。
例如命令：
MsiLogTranslator.exe MSI5d488.LOG
|
在工具运行结束后，会生成两个文件。一个叫 result.txt 的文件，该文件保存和原安装日志文件一样的内容，不同的是这个文件每行都有行号，同时它的错误代码已经被实际的错误信息所取代。这样您可以比较直观地阅读这些日志信息，同时利用行号信息可以知道错误是从哪里开始的。另一个叫 summary.txt 的文件，该文件主要提取了安装过程的每个动作的开始和结束以及它们的返回值，通过这个文件您可以很快知道安装过程的整体情况，而不需要去查看原始的安装日志。这个文件的另外一个作用是保存您需要的额外信息。比如您想要了解在安装过程中是否有部分安装错误发生，那么执行如下命令：
MsiLogTranslator.exe MSI5d488.LOG "(Dialog created|Partial|Rollback|Error [1-9])"
|
该命令要处理日志文件 MSI5d488.LOG ，同时它会把安装日志文件中有关字符串 “Dialog created”、“Partial”、“Rollback”和“Error x”的信息保存到文件 summary.txt 中。这样如果安装过程有部分安装错误发生或者有回滚发生或者其他有关的 Error，您从这个 summary.txt 中就可以看到。
工具的实际使用案例
安装成功
我们首先来看一下一个安装成功的例子，看它的安装日志是如何记录的。使用工具对成功安装日志进行分析，您可以从 summary.txt 文件中获得如下的重要信息。
Line: 4 MSI (c) (E8:78) [11:11:42:234]: ******* RunEngine:
Line: 5 ******* Product:
C:\HannoverPackage\8.5.1\AllClient.msi.w32.prod\Lotus Notes 8.5.1.msi
Line: 6 ******* Action:
Line: 7 ******* CommandLine: TRANSFORMS="1033.MST"
SETUPEXEDIR="C:\HannoverPackage\8.5.1\AllClient.msi.w32.prod"
Line: 186 Action start 11:12:12: INSTALL.
…
Line: 92367 Action ended 11:22:06: INSTALL. Return value 1.
Line: 93597 === Logging stopped: 7/25/2009 11:22:07 ===
Line: 93599 MSI (c) (E8:78) [11:22:07:250]: Product:
Lotus Notes 8.5.1 -- Installation operation completed successfully.
|
从以上日志记录的片段，您可以清楚看到动作 INSTALL的返回值是 1，说明这次 Notes Client 的安装是成功的
用户取消了安装过程
下边的例子说明了用户取消安装后的日志记录。您可以看到动作 INSTALL的返回值是 2，表明用户取消了这次安装。
Line: 4 MSI (c) (54:1C) [11:09:21:343]: ******* RunEngine:
Line: 5 ******* Product:
C:\HannoverPackage\8.5.1\AllClient.msi.w32.prod\Lotus Notes 8.5.1.msi
Line: 6 ******* Action:
Line: 7 ******* CommandLine: TRANSFORMS="1033.MST"
SETUPEXEDIR="C:\HannoverPackage\8.5.1\AllClient.msi.w32.prod"
Line: 186 Action start 11:09:52: INSTALL.
......
Line: 7542 Action ended 11:10:13: INSTALL. Return value 2.
Line: 8763 === Logging stopped: 7/25/2009 11:10:13 ===
Line: 8765 MSI (c) (54:1C) [11:10:13:578]: Product:
Lotus Notes 8.5.1 -- Installation operation failed.
|
安装过程中出现部分安装错误，但并没有影响整个的安装过程。
这里例子相对来说要复杂一点。从安装动作 INSTALL和它的返回值来判断，这次安装是成功的。但我们仔细搜索安装日志发现，其中几个功能并没有安装成功。从下面的记录信息可以看到在动作 InstallFinalize开始执行之后，有几个功能模块的安装失败通过关键字 Partial installation and setup occurred反映了出来。请参考下面记录的黑体字部分。
Line: 4 MSI (c) (08:18) [00:22:02:448]: ******* RunEngine:
Line: 5 ******* Product:
E:\build\8.5.1\AllClient.msi.w32.prod\Lotus Notes 8.5.1.msi
Line: 6 ******* Action:
Line: 7 ******* CommandLine: TRANSFORMS="1033.MST"
SETUPEXEDIR="E:\build\8.5.1\AllClient.msi.w32.prod"
…Line: 49246 Action start 0:22:51: InstallFinalize.
Line: 109588 Action 0:27:29: 4999856. Partial installation and setup occurred.
|Below are details about the features that failed to set up.
|CWPPR0503I: The installation of feature
com.ibm.commons.feature_8.5.1.20090516-1630 was cancelled.
|CWPPR0503I: The installation of feature
com.ibm.commons.jdbc.feature_8.5.1.20090516-1630 was cancelled.
|CWPPR0503I: The installation of feature
com.ibm.designer.domino.runtime.core.feature_8.5.1.20090516-1630
was cancelled.
|CWPPR0503I: The installation of feature
com.ibm.designer.domino.runtime.feature_8.5.1.20090516-1630
was cancelled.
|CWPPR0503I: The installation of feature
com.ibm.xsp.core.feature_8.5.1.20090516-1630 was cancelled.
|CWPPR0503I: The installation of feature
com.ibm.xsp.feature_8.5.1.20090516-1630 was cancelled.
|CWPPR0503I: The installation of feature
com.ibm.designer.domino.api.feature_8.5.1.20090516-1630 was cancelled.
|CWPPR0503I: The installation of feature
com.ibm.jscript.feature_8.5.1.20090516-1630 was cancelled.
|CWPPR0503I: The installation of feature com.ibm.designer
…Line: 109960 Action ended 0:29:49: InstallFinalize. Return value 1.
Line: 109961 MSI (s) (98:68) [00:29:49:340]: Skipping action:
RemoveAddons.5F3129E8_3AD4_4346_AEE6_A314E2DE64D9 (condition is false)
…
Line: 109980 Action start 0:29:49: ISSelfRegisterFinalize.
Line: 109998 Action ended 0:29:49: ISSelfRegisterFinalize. Return value 1.
Line: 110001 Action start 0:29:49: CopyInstallManifest.
Line: 110035 Action ended 0:29:49: CopyInstallManifest. Return value 1.
Line: 110038 Action start 0:29:49: CopyExtrasFolder.
Line: 110060 Action ended 0:29:49: CopyExtrasFolder. Return value 1.
Line: 110061 MSI (s) (98:68) [00:29:49:574]: Skipping action:
CopyInstallLog (condition is false)
Line: 110062 Action ended 0:29:49: INSTALL. Return value 1.
Line: 111311 Action ended 0:29:50: ExecuteAction. Return value 1.
Line: 111314 Action start 0:29:50: SetupCompleteSuccess.
Line: 111316 Action 0:29:50: SetupCompleteSuccess. Dialog created
Line: 111319 Action start 0:29:51: CopyInstallLog.
Line: 111329 Action ended 0:29:51: CopyInstallLog. Return value 1.
Line: 111330 Action ended 0:29:51: SetupCompleteSuccess. Return value 2.
Line: 111331 Action ended 0:29:51: INSTALL. Return value 1.
Line: 112557 === Logging stopped: 3/2/2009 0:29:52 ===
Line: 112559 MSI (c) (08:18) [00:29:52:132]: Product:
Lotus Notes 8.5.1 -- Installation operation completed successfully.
|
这个例子提示我们在通过安装动作来判断安装是否成功，一般来说是正确的，但并不是说一定就是正确的。您需要对可能的错误信息关键字进行搜索。这也正是这个工具的一个功能特点。
安装过程中发生了严重错误，安装发生了回滚。
您从下面的这个例子中可以看到在安装过程中发生严重错误时安装日志是如何被记录的。从日志记录的的黑体部分您可以看到安装动作 INSTALL 的返回值是 3，是一个严重错误的提示。
经过进一步的查找，原来错误是由于对目录的访问权限引起的，通过关键字 Error 1926 反映了出来，同时安装动作 Rollback 也被执行。
结论
通过工具对安装日志的处理和提取，我们对 Lotus Notes 客户端产品及其安装部署的过程有了更深入的了解，对于在安装部署过程中出现的问题更能提供有力的解释。同时这些知识和工具也适用于其它基于 WINDOWS Installer API 的产品安装日志的处理和分析。
下载 | 描述 | 名字 | 大小 | 下载方法 |
|---|
| 本文示例工具 | msiTranslatorTool.zip | 23 KB | HTTP |
|---|
参考资料 学习
获得产品和技术
作者简介  | | | 贾春丽是一名软件工程师，具有多年的产品测试经验，目前负责产品的安装和部署测试，对自动化测试技术感兴趣 。 |
| | | 魏洪涛是一名高级软件工程师，具有多年的产品开发测试经验，对软件测试方法与实践感兴趣。 |
对本文的评价
| 
