Windows2000 服务器端应用程序开发设计指南－事件记录

事件记录是什么？
　

回报事件
　

在进入自己的事件回报前，先讨论一些关于您的软件应该回报什么事件到事件记录中的内容。然后我们会尝试学习如何去编写回报事件的软件。

什么事件应该被回报？
　

如果您正在开发一个服务应用程序，那么您很可能正想去做一些事件回报的动作。在您这么做之前，无论如何您都必须真正地了解事件记录的内容。记得事件记录是系统管理员从您的服务返回的来源。一个回报无意义事件或太多事件的服务就如同一个显示了太多讯息方块给使用者的应用程序一样，会惹恼系统管理员。

大部份开发者发现决定在哪一种情况下可以授权一个错误事件的记录是件容易的事；而同样的，当您的软件需要发布一个警告事件时，也能容易且适度地被决定。然而，您进入了一个资讯事件的灰色地带。什么软件的活动重要得足以记录一个资讯事件？如果您从系统管理者察看的角度来考虑，那么您通常可以回答这个问题。

没有管理者想在一天结束后还要费力地进行察看几百个或甚至更多资讯事件的动作，只为了找到与她的工作有关的一或两个项目。所以您应该考虑一个「重要性」方面的问题即是在特定情况下的共用问题。一个Web服务器很可能不会为了每个它所接收的连结而记录一个事件。另一方面，它可能会想要为每个因为它太繁忙，无法处理要求而被拒绝存取的连结回报一个事件。然而记录这个事件可能并非必要。如果连结被拒绝时，有一个折衷方案可能是每小时即记录一个事件。该记录可能会包含在一些被拒绝存取连结总数的详细说明中。一个可能性是建立此种回报选项，以使管理者能在被回报的说明中挑挑拣拣。

另一个事件资讯的使用将会回报在您的软件状态中罕见的改变。例如，您可能会想在每次您的服务被暂停或继续执行时便产生一个事件。或者假定您的软件进入了待命模式，释放某些资源就某种时间而言，关系着连结的负载何时是处于较低的情形—这种情形可以允许一个资讯事件的发生。状态改变事件资讯可以是有用的，因为它们给予管理者一个在一个警告或错误事件发生前您的软件完成了什么活动的检测功能。

然而，您要避免将您的应用程序当做一个追踪资讯的储存处并成为考虑事件记录的习惯。这个侦错资讯的型态将会克服管理者与大部份可能会使它忽略每个被您的应用程序所建立之事件。每个事件同样会占用您系统之磁盘空间，所以有效的使用储存媒体也是一个重要的事。如果您的服务器将会回报许多的事件，或者会从许多事件来源回报事件，那些您可能会想要考虑将您的事件记录至一个自订的记录档中。最后在这里必须将一般的常识做个统一；然而您可以依照可能的使用者配置而建立您的应用程序回报机制，以提供使用者最好的记录。

我们已经在关于什么事件应该被回报的内容讨论已经足够。现在让我们进入如何将事件回报的部份。

如何回报事件
　

回报软件事件是一个简单的处理程序，但是在您能够确实利用事件记录前，需要了解如何将它们组合起来。一起拼凑它们之最容易的方法要先看最简单的部份，即是那些回报处理程序。

如果您的处理程序想要开始回报事件至事件记录，它需要使用以下的函数去登录一个事件来源：

HANDLE RegisterEventSource(
PCTSTR pszMachineName,
PCTSTR pszSourceName);

pszMachineName参数为确认您想要将事件项目加入之包含记录档的系统。传递NULL给此参数会在本机中开启记录档。很少有事件会被回报至一个远端机器上的记录文件中。

pszSourceName参数即是事件来源的名称。此名称是被显示在事件检视器嵌入式管理单元中的来源栏位；它不一定是您的可执行程序名称（但是它通常会是）。

说明

我必须提供一个关于安全性的词语：安全性与系统记录档皆是安全的。为了要使您的应用程序加入事件至这些记录文件之一，当它呼叫RegisterEventSource时，您的处理程序必须在拥有安全性内容的权限下执行。它的规则是：安全性记录档只能在使用本机帐户时才可以被写入，而系统记录档则可以在使用本机帐户与管理者帐户时被写入。

如果RegisterEventSource的执行是成功的，它会回传一个有效的handle。您的应用程序即可使用此handle来回报事件。记得所有的handle都一样，当您已完成它时应该让系统知道。您会使用一个呼叫DeregisterEventSource的函数来做这件事：

BOOL DeregisterEventSource(HANDLE hEventLog);

至目前为止一切皆很顺利，对不对？回报一个事件也相当地繁琐，您可以使用一个呼叫至以下的函数：

BOOL ReportEvent(
HANDLE hEventLog,
WORD wType,
WORD wCategory,
DWORD dwEventID,
PSID psidUser,
WORD wNumStrings,
DWORD dwDataSize,
PCTSTR* ppszStrings,
PVOID pvRawData);

hEventLog参数是被RegisterEventSource回传的handle。wType参数则是表6-3所列之五个事先定义类型之一。wCategory和dwEventID参数是您随意选择的值。dwEventID参数将会唯一地识别您的事件来源。事件识别码可以是任意值，并且以任何您想要的顺序来安排。然而，一个指示事件之被定义来源群组的事件类别必须拥有以1启动的值并从那里开始进行。该0值是被保留来指示没有类别时使用的。psidUser参数确认一个使用者，它没有在事件上隐含安全性的限制。NULL时常被传递以说明与任何使用者无关。

ppszStrings参数指向一个与事件关联的文字字串阵列，而wNumStrings是一些阵列中的字串。（我将会在本章之〈建立讯息DLL与Exe〉一节中讨论ppszStrings参数。）最后，pvRawData参数指向一个与事件关联的二进位资料区块。dwDataSize参数指出以位元组为单位之资料区块尺寸。该资料被回报它的应用程序定义，而且它可以是任何您觉得会对使用者或管理者有用的资料。例如，网路驱动程序把原始材料放在被驱动程序所报告的某些事件里。

根据文件所提，刚刚所描述的函数是关于记录事件至事件记录档之所有您需要知道的事情。技术上来说，这是事实；不过，有一些要点被删掉了。如果您把我们使用ReportEvent传递给Event Log服务的资讯与事件检视器嵌入式管理单元所显示的一个典型事件做比较，您将会发现缺少了一些资料。具体而言，我们传递一个类别号码，而事件检视器嵌入式管理单元显示一个文字字串。同样地，并非依照RegisterEventSource或ReportEvent来说明我们想要报告的记录（即应用程序、系统或安全性）。最后，您必须注意ReportEvent缺少了一个对事件详细说明的参数。

依照我曾解释过在应用程序记录档中放置您的事件之预设的方法。记录档包含了详细说明您的事件之一般文字，然后把您的字串资料附加至文字的末端。我们可以在这里停止，但是如果您另外又实作了您自己的详细说明与类别部份，使用者将会非常感谢您，做这件事有助于理解事件记录之设计目标。

讯息文件
　

Windows事件记录的设计者想要建立一个有效的机制以增加语言的独立性。基于这个目标，一个人类可读的事件部分—那就是，类别与详细说明—是从您的应用程序取出到分开的讯息文件中。这些讯息文件被实作成DLL或EXE文件，而它们包含了一个自订之内含您的讯息文字的二进位码资源。本章后面将会解释关于讯息DLL的详细内容，然而现在有几件事是您必须要知道的。

讯息档可以是一个被给定的事件资讯：事件讯息文件、类别讯息文件以及参数讯息文件。一个单一讯息的DLL（或EXE）可以展示它们之中的任何结合，所以您的应用程序可以在一个讯息DLL中储存您的事件讯息文件、类别讯息文件或参数讯息文件；相反的动作也可以成立，例如，可以使用超过一个的讯息DLL为单一事件资源表示事件讯息文件。

说明

通常DLL与EXE文件分别被称为讯息DLL和讯息EXE。为了容易阅读，本章的其馀部份将使用「讯息DLL」来说明，然而，所有资讯皆适用于讯息EXE的部份。

您透过用与您传递给RegisterEventSource的pszSourceName参数相同的名字在子机码下建立少量的登录值使讯息DLL与您的事件来源联系。事件记录档也用它来指定这个新登录机码到您那一些将被记录的来源事件中。一般安装应用程序的软件会将这些项目加到登录中，但是没有说明您的服务不能够加入他们的规则。当该项目已被加入登录时，登录的布局会跟随着以下的阶层而结束：

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
EventLog
Application
Event Source
...
Security
Event Source
...
System
Event Source
...
CustomLog
...

请注意CustomLog机码位于EventLog之下。在预设情形下，在EventLog机码下只有Application、Security与System机码，但是您的程序代码也可以在标准的记录机码中添加另一个机码以采用一个自订的记录至事件记录中。当您呼叫RegisterEventSource时，系统会为了与pszSourceName参数相符的机码而搜寻位于HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Log下的机码。每一个记录皆被依照字母排序而搜寻，直到发现一个符合的来源子机码为止。

所以您可以看到，事件来源的命名空间被所有标准或自订的记录所分享。如果系统下的事件来源在应用程序中与事件来源相匹配，则它将会被忽略。

为了使您的讯息文件与您的事件来源联系，要在您的事件来源机码下建立适当的登录值。支援的登录值定义在表6-4中。

建立讯息DLL与EXE
　

我们还必须回答的问题如下：

本节中将会回答上述的所有问题。图6-3显示了所有的事件记录结构，包含建立一个讯息DLL所需的步骤。您将会在后续的讨论中参考到此图。

您的第一个建立讯息DLL的步骤是为您的讯息来源建立一个文件。此讯息来源一般被称为「MC」文件，而且，可以使用任何您所选择的名称，只要它的延伸档为 .mc。例如，MyMsgs.mc。

您的 .mc文件被架构为一系列的讯息项目，并以任意的顺序安排。请参阅《Platform SDK》文件以取得完整的讯息文件之语法。以下为一个讯息文件的范例：

;/**************************************************************
;Module name:MyMsgs.mc
;**************************************************************/
;//*********************MESSAGE SECTION ***********************
MessageIdTypedef=DWORD
MessageId=0x1
SymbolicName=MSG_DATE
Language=English
Today’s date is %1. %%536871912
.
MessageId=0x2
SymbolicName=MSG_TIME
Language=English
The current time is %1. %%536871912
.
MessageId=
SymbolicName=MSG_SEC
Language=English
The seconds are %1. %%536871912
.
;//****************STRING PARAMETERS SECTION ******************
MessageIdTypedef=DWORD
MessageId=0x100
Language=English
I hope you enjoy today.
.
;//************************END OF FILE ************************

MessageId是与文字关联的识别码。注意到您可以在讯息文件中为这个MessageId栏位省略一个明确的值。这将会导致编译器产生比之前的讯息识别码多的识别码。SymbolicName栏位参考到产生之标头文件中将被使用的已定义巨集。您可以引入被产生的标头档与您的事件回报控制码，并且使用被SymbolicName栏位定义的巨集去确认一个讯息。Language行定义了该讯息使用的语言。您可以使用此方法建立一个为单一讯息识别码鉴定拥有若干语言支援的单一的讯息资源。因为讯息可能是几行长，所以您会在一个单一时期使用一行来指示讯息的结尾。注意此处需要一个延长的期间，而且在您的 .mc文件中的最后一个项目应该在延长期后回传Return键（Carriage Return）。

当您使用ReportEvent记录一个事件时，dwEventID参数指定了事件的识别码。后来事件检视器嵌入式管理单元会使用事件识别码的值搜寻人类可阅读字串之事件讯息文件。同样地，ReportEvent的wCategory参数会与一个在类别讯息文件中识别码相同的讯息关联。

如您所见，讯息文件的语法相当的简单，但是，有些方面需要某些附加的讨论。如前所述，事件记录的主要目的之一即是语言的独立性。讯息资源允许您容易地为了多种语言所包含的讯息。为了达成目的，您只需在被要求的语言内的讯息后面加入一个额外的Language行至每一个讯息的项目即可。它也常被用来将不同的语言编译至相同的讯息DLL中。例如，您的专案可能包含了一个MsgEnglish.dll和一个MsgFrench.dll。只要为您的讯息文件将这二个DLL含入登录项目，事件检视器嵌入式管理单元就可以找到适当的语言所代表讯息。

到目前为止，您可能会认为对于任何给定的事件识别码来说，事件检视器会报告一个不变的细节讯息。如果您认为由编译时期定义的静态字串所组成的一个事件记录机制不是非常有用，那么您是正确的。我们需要对相同的识别码但是为不同文字之回报多个事件的能力。例如，如果您的应用程序回报它无法开启一个文件，您想要使它在事件的说明文字中动态地引入被指定的文件名称。您也许会猜想事件记录的解决方法即是位于ReportEvent内的ppszString参数。

当您建立一个讯息时，该讯息可能包含了指示特定事件字串应被放置在何处的特别字元序列。例如，以下的事件字串指示了二个可置换的字串：

"The file %1 was replaced with the file %2"

如果您使用ReportEvent的ppszStrings传递一个包含二个字串的阵列，事件检视器嵌入式管理单元会使用「%1」取代第一个字串，「%2」则取代第二个字串。

通常，您应该只传递与语言无关的字串值，例如数字、文件名称以及其他资源的名称。尽管您可以传递任何文字而事件检视器嵌入式管理单元会取代它，但是例如传递一个英文片语时，便会破坏事件记录的语言独立性。

可以与扩充的字串一起使用参数代替来从参数讯息文件包含附加的细节字串。当扩充事件字串时，一个「%%」字元序列会被附加在一个指示参数代替的数字后。例如，以下的事件字串指示一个可取代的参数字串：

"This is an example %%237"

当扩充此字串时，事件检视器嵌入式管理单元会搜寻一个识别码为237的字串，且以参数字串取代事件字串的「%%237」之参数讯息文件的讯息表格资源参数。

此外，参数扩充在字串扩充后才被执行，它考虑到复杂的扩充情形。假设讯息字串「Replace with a dynamic parameter %%%1」与一个值为「237」的字串会被传递至ReportEvent。事件检视器嵌入式管理单元会先取代「%1」，然后继续使用在参数讯息文件中有237的识别码取代「%%237」。

如果您将您的事件来源之ParameterMessageFile登录值设定至Kernel32.dll，那么您可以使用从GetLastError回传的值而动态地插入错误讯息文字。例如，假设Kernel32.dll是您的参数讯息文件，而您的讯息字串是「GetLastError() returned the following error: %%%1」。您可以用一个单一字串值「5」呼叫ReportEvent以指示为拒绝存取。事件讯息的结果将会是：

"GetLastError()returned the following error:Access is denied".

能在您的事件说明中插入最后的错误讯息文字，确实是一个有用的特性。

编译您的讯息
　

在您建立 .mc文件后，您需要使用附加在Microsoft Visual Studio中的Message Compiler（Mc.exe）来编译它。以下的文字显示编译器的使用方法：

C:\>mc.exe
Microsoft (R) Message Compiler Version 1.00.5239
Copyright (c) Microsoft Corp 1992-1995.All rights reserved.
用法：MC [-?vcdwso] [-m maxmsglen] [-h dirspec] [-e extension]
[-r dirspec] [-x dbgFileSpec] [-u] [-U] filename.mc
-? - 显示此讯息。
-v - 产生冗长的输出。
-c - 在所有的讯息识别码中设定Customer位元。
-d - 标头档中的FACILTY与SEVERITY值，以十进制值表示。
设定标头中的讯息值为以十进制初始。
-w - 如果讯息文字中包含非OS/2相容之插入物时，发出警告。
-s -  插入符号连结名称以视为每一个讯息的第一行。
-o - 产生OLE2标头档（使用HRESULT定义取代状态控制码定义）。
-m maxmsglen - 如果任何讯息的大小超过maxmsglen所设定之字元数时，产生一个警告。
-h pathspec - 设定建立C含入文件之路径，预设值是 .\。
-e extension - 指定档头文件之延伸名称。
1到3个字元。
-r pathspec - 设定建立RC含入文件与含入之二进位码讯息资源文件的路径。
预设值是 .\。
-x pathspec - 设定建立 .dbg之讯息识别码与符号名称对应的C含入文件路径。
-u - 输入文件为Unicode格式。
-U - 在 .BIN文件中的讯息应为Unicode。
filename.mc - 设定一个用于编译的讯息文字文件名称。
产生的文件使得保存（Archive）位元被清除。

讯息编译器会剖析您的 .mc文件并产生叁个文件：

资源文件
　

在经由讯息编译器执行MyMsgs.mc后，我用一个非常简单的资源指令档（MyMsgs.rc）来结束它，该文件看起来像图6-4所示的内容一样：

您可能已经很熟悉图示、点阵图以及对话方块范本的资源，一个讯息表格不过是资源的另一种型别而已。就像是图示与点阵图，其讯息表格资源是在资源指令中参照的二进位文件，而对话方块范本与功能表范本则嵌入在指令档中。

如果您在Platform SDK中开启WinUser.h标头文件，您将会发现以下被定义之设备符号：

#define RT_CURSOR MAKEINTRESOURCE(1)
#define RT_BITMAP MAKEINTRESOURCE(2)
#define RT_ICON MAKEINTRESOURCE(3)
#define RT_MENU MAKEINTRESOURCE(4)
#define RT_DIALOG MAKEINTRESOURCE(5)
#define RT_STRING MAKEINTRESOURCE(6)
#define RT_FONTDIR MAKEINTRESOURCE(7)
#define RT_FONT MAKEINTRESOURCE(8)
#define RT_ACCELERATOR MAKEINTRESOURCE(9)
#define RT_RCDATA MAKEINTRESOURCE(10)
#define RT_MESSAGETABLE MAKEINTRESOURCE(11) // 看这里！
#define RT_GROUP_CURSOR MAKEINTRESOURCE(12)
#define RT_GROUP_ICON MAKEINTRESOURCE(14)
#define RT_VERSION MAKEINTRESOURCE(16)
#define RT_DLGINCLUDE MAKEINTRESOURCE(17)
#define RT_PLUGPLAY MAKEINTRESOURCE(19)
#define RT_VXD MAKEINTRESOURCE(20)
#define RT_ANICURSOR MAKEINTRESOURCE(21)
#define RT_ANIICON MAKEINTRESOURCE(22)
#define RT_HTML MAKEINTRESOURCE(23)

讯息表格资源已经被指定为号码11。当您加入资源至一个资源指令码（.rc）档时，您必须为每一个资源的类型指定一个唯一的数字。例如，我可以加入一个识别码为53的图示至我的资源指令码中，然后加入另一个识别码为172的图示至我的资源指令码中。这些数字实际上并不重要，因为它们是唯一的。

讯息表格资源与其他资源的工作有些不同。一个资源指令码文件可以只拥有一个讯息表格资源，而且该资源必须被指定识别码为1。如果您指定一个不同的识别码给讯息表格资源，在使用像事件检视器嵌入式管理单元时将无法将事件与类别识别码转换成人类可阅读的字串。

说明

如果您的讯息DLL或EXE包含了附加的资源，只要将被讯息编译器产生的 .rc文件内容复制至您拥有的 .rc文件中即可。然后您可以丢弃被讯息编译器产生的 .rc档。

使用Visual Studio建立一个讯息文件之专案
　

虽然您可以在每一次改变您的讯息时，手动地执行讯息编译器工具，然而那么做会变得麻烦且乏味。我强烈地建议为您的DLL或EXE加入讯息编译的步骤至您的Visual Studio专案中。由于一些未知的原因，Visual Studio环境无法察觉到这个讯息编译器与 .mc文件，所以您需要在专案中加入自订的建立步骤。步骤如下：

1. 将您的 .mc文件加入EXE或DLL专案中。
2. 显示Project Settings对话方块。
3. 在Custom Build页签中选择 .mc文件。
4. 在说明文字方块中设定您想要的说明文字。我通常会使用「Message Compiler」。
5. 在Commands文字方块中设定「mc -s -U -h $(ProjDir) -r $(ProjDir) $(InputName)」与「del $(ProjDir)\$(InputName).rc」。
6. 在Outputs部份，加入二个项目：「$(InputName).h」与「Msg00001.bin」。该对话方块看起来应该像图6-5所示的内容。按下OK按钮。
   　

   图6-5 为 .mc文件加入讯息编译器命令后的Project Settings对话方块

7. 在呼叫ReportEvent函数的原始码文件中含入被产生的标头档。
8. 在您专案的 .rc档中加入一行包含资源数字为1、资源类型为11，以及文件名称为MSG00001.bin的内容。例如：

   1 11 MSG00001.bin

在执行此步骤后，若要产生最后的EXE或DLL，Visual Studio就会知道如何去编译您的讯息文字档与含入的资源。注意到如果您建立了一个只含有资源而没有程序代码的DLL模组，那么您应该使用 /NOENTRY连结器开关来防止连接一个进入点并且减少产生模组的大小。

您必须去编写的唯一程序代码即是对登录的设定部份，因此事件检视器嵌入式管理单元能找到这个讯息EXE或者DLL的位置。

MsgTableDump范例应用程序
　

MsgTableDump范例应用程序（「06 MsgTableDump.exe」）是一个简单的工具程序，它可以开启一个被包含在EXE或DLL中的讯息表格资源并且倾印在表格中的所有字串。此范例应用程序的原始程序代码与资源档存放在随书光碟中的06-MsgTableDump目录中。

这个程序代码非常简单易懂。它把讯息表格资源置于特定的模组并沿着每个存在唯读之编辑控制项中的字串而走。图6-6显示了当MsgTableDump在Kernel32.dll上执行时，其输出的情形。

AppLog范例应用程序
　

AppLog范例应用程序（「06 AppLog.exe」）显示于列表6-1中，它说明从一个应用程序回报事件的内容。它的原始码与资源文件存放在附赠光碟中的06-AppLog目录中。AppLog范例应用程序被实作如同一个标准的应用程序一样，但是如果控制码属于一个服务的话，它便会与回报事件的控制码相同。

当AppLog启动时，它会开启一个本机的应用程序记录并且加入一个指示应用程序己被启动执行的项目。AppLog也会在终止前加入一个项目。在正常的情形下，为了增进执行效能并且不浪费事件记录资料库空间，您不会将这些资讯事件类型回报至事件记录中。

一旦AppLog执行起来，您便可以在编辑控制项中键入一个Win32之错误码并按下Simulate Error按钮。此按钮会使AppLog增加一个事件至系统的应用程序记录档中。当AppLog执行时，您可以依您的喜好而模拟许多Win32的错误。为了察看错误的情形，可以按下Open Event Viewer按钮，以使事件检视器嵌入式管理单元在MMC中显示那些产生错误的原因。

如果您使用事件检视器嵌入式管理单元来看那些项目，您将会看到类别与讯息识别数字与可置换的字串值（被您模拟的错误码数字）。事件检视器无法将类别与讯息识别码对应到它们的英文字串中，直到登录被适当地设定为止。若要将讯息文件模组资讯安装至登录中，可以按下Install Event Message File In Registry按钮。然后回去事件检视器嵌入式管理单元中察看被AppLog加入的事件。此时，您应该会看见识别号码已被转换至适当的字串中。AppLog也允许您按下Remove Event Message File From Registry按钮去删除登录资讯。图6-7显示了AppLog模拟一个错误的情形。