|
This Issue
In this issue we are going to demonstrate how to write to the Event Log, and how to debug an Active Server Object. The big advantage to Active Server Objects, over writing VB Script in an Active Server Pages, is that you can debug the Active Server Object. Since Active Server Pages do not have a debugger, there is no way to step through loops or view variables. This makes it hard to program big Active Server Pages successfully. However, if you write Active Server Objects you can debug them. Before you can debug code you have to have code to debug. So in this issue we are showing you how to write to the Event Log.
Before you Begin
You need to follow the same step to debug Active Server objects as you would to debug ISAPI Server Extensions and Filters. If you have already set your debugging environment for ISAPI Server or Filters you do not need to follow the steps listed below.
Welcome to the second part of a four-part issue on Active Server objects. We are detecating four issues to Active Server objects and ATL because of their usefulness in writing Active Server Pages. As we see it Active Server objects one of the most powerful tools that the developer of web pages has in his/her arsenal. For these reasons: - You can debug Active Server objects using Microsoft Developer Studio. In comparison to Active Server Pages where there currently are no debugging tools. The ability to debug Active Server pages makes big projects easier to do in Active Server objects.
- You can warp databases and tables with Active Server objects and call for the data directly using the objects. Wrapping databases and tables makes for powerful tools since you remove the ADO code from the page Active Server pages and place it within the object.
- You can distribute Active Server objects to run on Microsoft's Transaction server. This allows two (or more) IIS machines that would running the same object to share the object on a third machine.
Being able to log events to the event log is a powerful tool. But, between the message Files, the message compiler and the registry it is no easy programming task. Much of the complication in the programming comes from the complications of internationalization. The Event Log APIs and the Message files are intended to be internationalized. The EvtLog object circumvents that by not compiling messages in the message file but by writing them directly from the Active Server page to the Event Log. We have given enough information about Event Logging so that you can take the code provided and add it to your own Active Server objects and your ISAPI Server Extensions and ISAPI Server Filters. It is very useful to reports errors on low memory, broken SQL Server connections, or starting services. However do not use the Event Log for Web logging since it will consume to many systems resources. We have every intention of using the EvtLog object on our web site and in examples of other technologies in forthcoming issues. Please take a minute to test out the object, read over the programming code and too bookmark our page so that you can read the other two issues on Active Server objects. -Wayne Berry
Editor
The Example Object
In this issue we are going to show you how to write an Active Server object that writes to the event log. This object is useful in many ways. First, it allows the developer of and Active Server page to log to the Event Log, recording all errors to examine later. Second it is an example of how to log to the Event Log, and can be expanded into other Active Server object so that they can log to the event log. Finally, it is example code that we can use for the debugging demonstration.
Simulating the Internet Infromation Server
In order to debug Active Server objects you need to run the Internet Information Service in the Microsoft Developer Studio. The Internet Information Service, like all services, is a special executable that is executed by the operating system. Microsoft Developer Studio allows you to debug executables and DLLs that the executable calls, even if you do not have a debug version of the executable. Since the Active Server objects are instantiated through the Internet Information Service, and are usually DLLs, you can debug the objects by running IIS in Microsoft Developer Studio.
Getting Started
In order to get started you need to create and Active Server object using ATL 2.0. If you do not know how to do this you can get instructions from Mar 08, 1997 - ASP COM Objects with ATL 2.0 issue. In order to use the example you must name the project EvtLog and the Object EvtLogObj. These are the naming conventions that we have assumed in the code example throughout this issue.
Stopping the Running Service
In order to simulate the Internet Information Server, you need to stop the currently running service. You can stop the service through the Internet Service Manager.It is a good idea to debug the Objects on a development machine, and not the live server. Since you might want to test one request at a time to the Object the traffic on the live server would interfere with your debugging.
Project Check List
Follow these steps to create an ATL Active Server object that write to the Event Log.
- Create a project called EvtLog and insert and object called EvtLogObj using the instructions in the Mar 08, 1997 - ASP COM Objects with ATL 2.0 issue of the series.
- Create a message file, compile it and add it to the project (Step 1).
- Add the code to Register the Message File (Step 2).
- Add the Method to do the logging (Step 3).
- Complie the code, which will automatically registers the DLL and the message File.
- Call the object from an Active Server page with a test message. See the ASP section for instructions.
- Debug any problems with Mircosoft Developer Studio (see below).
Understanding IIS's Permissions
The Internet Information Server, running as a Service, runs under the permission of the user that is entered under the general tab of the IIS properties. This user is by default IUSR_MACHINENAME, where MACHINENAME is the name of the machine. The user is created when IIS installs, and the installation sets the permissions. All the DLLs called by IIS have the permissions of this user. This includes all the Active Server Objects. When you run the Internet Information Server from within Microsoft Developer Studio, IIS runs under the permissions of the user that you are logged in as. If you are unaware of this difference it can causes many problems. On of the major problems this cause is that your login many have way more permissions then IUSR_MACHINENAME. This is a problem because it appears that code works in debug mode (running under you login), but doesn't work with the default server (running under IUSR_MACHINENAME). Another problem is that by default a NT service has certain permissions that a typical user doesn't. This means that if you are going to simulate the IIS, you have to change your user permissions.
Debugging
If you went to all the work of creating the Example and it doesn't work then you will need to debug the problem. Here are some places to start.
- Read the section on debugging and run the Internet Information Server from within the Microsoft Development Studio. Place a break point within the WriteError method and request the page again. Make sure that the WriteError method is getting called and there are not errors returned from the Event Log APIs.
- Make sure that the you have registered the object on the machine. If you are working on the same machine that you compiled the project on the object will have registered during compilation. Read the section on the Event Log and Step 2 closely. Open regedit.exe and check the registry settings. Register the DLL and make sure that you get a successful message.
- Compare your code against the code that can be found in the download section. Make sure that you can compile and run our DLL and source found in the download section. Check you Active Server page against the one provided by us.
- Open the OLE Object View from within Microsoft Developer Studio from the Tools menu. Make sure that you can see the object and there is a function called WriteError in the IevtLogObj Interface.
Setting the Permissions
If you are going to simulate the IIS, then you have to give your login these permissions. Here is how: - Make sure that you are logged in as the Administrator of that local machine, or are logging in as a User that belongs to the Administrators Group.
- Click on Start | Programs | Administrative Tools | User Manager for Domains.
- The User Manager appears, in the title bar is the name of the domain that it is currently attached to. You want to select the local machine that the debugging will take place on. If the local machine name is not in the title bar then:
- Select User | Select Domain
- Type in the local machines name and click OK.
- To change the Permissons on the local domain click on Policeis User Rights
- Then check Show Advanced User Rights.
- With Show advanced User Rights Select from the Right: drop down Act as part of the operating system. This will not appear if the Show advanced User Rights is not checked.
- Click on the Add button and the Add Users and Groups will appear
- Click the Show Users button.
- Select the user that you are logged in as (the same user that will be doing the debugging.
- Once Selected Click on Add
- Now click on OK. You have now giving that user permissions to Act as part of the operating system.
- Now you just have to grant one more set of permissions to the user. Select from the Right: drop down Generate Security Audits.
- Click on the Add button and the Add Users and Groups will appear
- Click the Show Users button.
- Select the user that you are logged in as (the same user that will be doing the debugging.
- Once Selected Click on Add
- Now click on OK. You have now giving that user permissions to Generate Security Audits.
- Click on OK to to close the User Rights Policy Dialog.
- Close the User Manager.
You have now changed the permissions of the user that you are going to debug the Internet Information Server with. Now log off and login as that user.
A Little About the Event Log
The Event Log is a way for services and other applications that do not have a GUI interface to write information out to the user. Usually, the event log is used to write error message from a service to a Systems Administrator. The event log consists of message which are written to three different logs, the system log, the security log, and the application log. The System log is for system process and services. The security log is for security issues, and the application log is for applications. Each log breaks down the messages by the source of the message and each source is broken down by category. Each message logged to the Event Log can be one of three severity Error, Warning and Informational.
Createing an IIS Project
In order to run the Internet Information Server from within the Microsoft Developer Studio you will need to create a project workspace for IIS. Opening the IIS executable as a workspace does will create the project workspace. Here is how: - Start Microsoft Developer Studio.
- Click on File | Open Workspace
- Change Files of Type: to Executable Files (*.exe).
- Go to c:\winnt\system32\inetsrv and choose inetinfo.exe
- Click on open.
- Click on File | Save All to save the workspace.
Now that you have created the workspace you need to change the project settings. Here is how: - Click on Build | Settings…
- Click on the Debug Tab.
- In the General Category change Program arguments: to -e W3Svc
- In the Additional DLLs Category add in the DLLs of the Active Server Objects that you want to debug.
- Click on OK to exit the Project Settings Dialog.
- Click on File | Save All to save the workspace.
The Event Viewer
Microsoft Windows NT Server comes with an application to view the Event Log. It is called Event Viewer and can be found in the Administrators Tools. When you open up event viewer you notice that it is organized in a table with every message being a row and the columns consist of : | Severity | This is not really is own row, just a blue, yellow, or red dot indicating the severity. Blue is informational, yellow is warning, and red is error. | | Date | The date the message was written to the Event Log. | | Time | The time the message was written to the Event Log. | | Source | The name of the application or service that. | | Category | The source’’s category for the error. | | Event | The Id of the message | | Users | The user who the application is running under, if the application is running under the system this will appear as unknown. | | Computer | The Computer who filed the error. |
Running IIS
Now all you have to do to run The Internet Information Server from within Mircosoft Developer Studio is: - Click on Build | Execute inetinfo.exe.
- Click on yes when asked "C:\winnt\system32\inetsrv\inetinfo.exe does not contain debugging information. Do you wish to continue?"
How the Strings are Handled
The Event Viewer when opened reads the register and figures out which DLLs have messages files for what sources. When you double click on a row in the Event Log the event log load the DLL and reads the message section of the resource which pertains to the ID of the message. Categories work in much the same way. When the application uses the windows API to write to the Event Log an ID is used. This ID refers to a message contained in the message section in the resource of an application. When the Event Viewer is load it references the registry for all the DLLs of every source that has a row in the table. The Event Viewer then loads the DLLs and reads the Name of the Category from the DLL using the ID as a reference. Usually, the same application is used for both the categories and the messages. Since each application can have only one message section in it's resource the messages and categories end up in the same message section. To distinguish between messages and categories there is also an entry in the registry that indicates the number of categories in the message section. Categories begin with the Id of 0 and continue in increments of one. Messages, on the other hand, may be Id they want as long as they don't conflict with the Id's of the categories. Usually messages start with Id 100 and up. A good trick is to have all messages that go with category one to be in the one hundreds, all messages that go with category 2 to be in the two hundreds and so on.
Creating a Message File
The first thing to do is create a message file that contains the messages that the object will write to the registry. Message files are created with a special Syntax that is specific to the message file. The syntax is simple and must be correct or the message compiler will not be able to compile the message. Since we do not want to hard code the message that we are passing to the event log, we are going to make a single variable message.
The Example Message File
Create a blank text file within the project and add this code: MessageId=1
Facility=Application
Severity=Success
SymbolicName=EVCAT_CATEGORY
Language=English
ASP
.
MessageId=100
Facility=Application
Severity=Success
SymbolicName=EVMSG_MESSAGE
Language=English
%1
.
Save the file as EvtLogMsg.mc.
The Message File Syntax
Each category and message must have an entry like the one above each with a different id. Each message entry must be separated with a . begin on a line by itself. Notice that the MessageId is assigned and that a SymbolicName is given. When the message file is compiled a header file will be produced. You can include the header file in your source code, and reference the id by it's symbolic name.
The Message Compiler
Once you have produced a message file in the correct syntax you need to compile it. The easiest way is to do this is to add a tool to the tool menu drop down. To add the Message Compiler follow these steps: - Open up the Microsoft Developer Studio.
- Click Tool | Customize.
- Click on the Tool Tab.
- Click on the Add Button.
- A new Dialog will appear called Add Tool.
- For the Command: type in c:\msdev\bin\mc.exe. This is the default location of the message compiler call mc.exe. If you have installed Microsoft Developer Studio somewhere else you will need to find mc.exe using the browse option.
- Change the Menu Text from mc to Message Compiler.
- Click on the right arrow next to Arguments and choose File Name from the drop down menu.
- Click on the right arrow next to Initial Directory and choose File Directory.
- Click on the check box that read Redirect to Output Window.
- Click on the Close Button.
Now you are done configuring the Tools Menu to compile Message Files. Click on Tools from the Menu bar and you will notice that the Message Compiler and been added to the drop down menu.
Compling the Message File
To compile the message file:- Open it within the project.
- Making sure that EvtLogMsg.rc is the window in focus.
- Click on Tools | Message Compiler.
The message file should compile with the output going to the output window of Microsoft Developer's Studio. If you get this error message: MC: Compiling EvtLogMsg.mc
EvtLogMsg.mc(15) : error : invalid character (0x2e)
Tool returned code: 1
Then you probable need to add an extra carriage return after the last line.
Add the Message Resource to the Project
Once the Message file is compiled it will produce a EvtLogMsg.rc file that will need to be added to the project. Here is how: - From within the Project Workspace view click on the resource tab.
- Select EvtLog resources so that it is highlighted.
- Right Click on EvtLog resources and choose Resource includes...
- In the read-only symbols directives edit box add another include like that reads:
#include "EvtLogMsg.rc"
- Click on OK to close the Resource Includes dialog.
- Click on OK to get past the warning message
Registering the DLL
Once you have create, compiled, and added the message file you need to register the location of the DLL with the event log.
Modifications to EvtLog.cpp
We need to add the code under DLLRegisterServer in EvtLog.cpp, find that procedure and add this code:
DWORD dwAllocBufferLength=500;
LPTSTR lpszBuffer= new TCHAR[dwAllocBufferLength];
HKEY hKey=HKEY_LOCAL_MACHINE;
HKEY hkResult1;
HKEY hkResult2;
DWORD ulOptions=0;
REGSAM samDesired=KEY_ALL_ACCESS;
DWORD Reserved=0;
DWORD dwTypesSupported=7;
DWORD dwCatagoryCount=1;
// Get DLL File Location
if(!GetModuleFileName(GetModuleHandle("EvtLog.dll"),lpszBuffer,dwAllocBufferLength))
goto Error;
// Event Logging Registry Settings
if (RegOpenKeyEx(hKey,
"SYSTEM\\CurrentControlSet\\Services\\EventLog\\Application", ulOptions,
samDesired,
&hkResult1)!=ERROR_SUCCESS)
goto Error;
if (RegCreateKey(hkResult1,"EvtLog",&hkResult2)!=ERROR_SUCCESS)
{
RegCloseKey(hkResult1);
goto Error;
}
if (RegSetValueEx(hkResult2,
"EventMessageFile",
Reserved,REG_EXPAND_SZ,
(CONST BYTE *)lpszBuffer,
_tcslen(lpszBuffer))!=ERROR_SUCCESS)
{
RegCloseKey(hkResult1);
RegCloseKey(hkResult2);
goto Error;
}
if (RegSetValueEx(hkResult2,
"CategoryMessageFile",
Reserved,REG_EXPAND_SZ,
(CONST BYTE *)lpszBuffer,
_tcslen(lpszBuffer))!=ERROR_SUCCESS)
{
RegCloseKey(hkResult1);
RegCloseKey(hkResult2);
goto Error;
}
if (RegSetValueEx(hkResult2,
"TypesSupported",
Reserved,
REG_DWORD,
(CONST BYTE *)&dwTypesSupported,
sizeof(DWORD))!=ERROR_SUCCESS)
{
RegCloseKey(hkResult1);
RegCloseKey(hkResult2);
goto Error;
}
if (RegSetValueEx(hkResult2,
"CategoryCount",
Reserved,
REG_DWORD,
(CONST BYTE *)&dwCatagoryCount,
sizeof(DWORD))!=ERROR_SUCCESS)
{
RegCloseKey(hkResult1);
RegCloseKey(hkResult2);
goto Error;
}
RegCloseKey(hkResult1);
RegCloseKey(hkResult2);
delete lpszBuffer;
return(S_OK);
Error:
delete lpszBuffer;
return(E_UNEXPECTED);
}
The Event Log and The Registry
Now that we have the message file compiled and added to the project we can write some code that creates an event log registry entry. To have the event log call your DLL you must put an entry in the event logs registry area. To add an application create a key that will hold the DLL information in:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Name
With Name being the name of the application. For the example we created:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\EvtLog
If you want to in the system area you would make an key in:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\System
If you want to in the security area you would make an key in:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Security
The name of the key created will be the source name in the event log. Each key in the registry section of the event log should have 4 name-value pairs no matter if it is under security, application, or system. There should be a DWORD called CategoryCount that holds the number of categories that the application is going to log to the event log. This way when the event log reads the message file starting at 1 it will know how many messages are categories. A name-value pair called TypesSupported with a DWORD data type should be present in the source key with a value on seven. There must also be two name-value pairs that point to the location of the message file. These are called EventMessageFile and CategoryMessageFile. They should be of string type. If you split the Message file in two DLLs, one DLL for categories and one DLL for messages then you will need too assign these values accordingly. These two name-value pairs are how the event log finds the DLL that contains the strings to display.
UnRegistering
Also add this code under DllUnregisterServer, this code removes the registery settings set above.
if (RegDeleteKey(
HKEY_LOCAL_MACHINE,
"SYSTEM\\CurrentControlSet\\Services\\EventLog\\Application\\EvtLog"))
{
return (E_UNEXPECTED);
}
return (S_OK);
Logging to the Event Log
Once you have registered the location of the DLL, you need to write the method that actual logs to the Event Log.
Modifications to EvtLog.idl
First modify the IDispatch interface in EvtLog.idl. It should look like this:
interface IEvtLogObj : IDispatch
{
[id(100)]
HRESULT WriteError([in] BSTR bstrMessage);
};
Modifcations to EvtLogObj.h
Next modify the objects header file (EvtLogObj.h) by adding the new method. Here is how:
STDMETHOD(WriteError)(BSTR bstrMessage);
Modifcations to EvtLogObj.cpp
Finally add the method to EvtLogObj.cpp
STDMETHODIMP CEvtLogObj::WriteError(BSTR bstrMessage)
{
HANDLE hEventLog; // handle returned by RegisterEventSource
PSID lpUserSid=NULL; // user security identifier (optional)
DWORD dwDataSize=0; // size of binary data, in bytes
CHAR *lpStrings[1]; // array of strings to merge with message
LPVOID lpRawData=NULL; // address of binary data
UINT iMessageSize; // The Size of the Message
BOOL bReturn;
iMessageSize=wcslen(bstrMessage)+1;
lpStrings[0] = new CHAR[iMessageSize];
// Change the Message From Unicode to MBCS
if (WideCharToMultiByte(CP_ACP,
0,
bstrMessage,
-1,
lpStrings[0],
iMessageSize,
NULL,
NULL)==FALSE)
{
return(S_FALSE);
}
// Register the Event Source So that we can write to it.
if (!(hEventLog=RegisterEventSource(NULL,"EvtLog")))
{
delete lpStrings[0];
return(S_FALSE);
}
// Write an Event as Error
bReturn=ReportEvent(hEventLog,
EVENTLOG_ERROR_TYPE,
EVCAT_CATEGORY,
EVMSG_MESSAGE,
lpUserSid,
1,
dwDataSize,
(LPCTSTR *) lpStrings,
lpRawData);
// De register the Source
if (!DeregisterEventSource(hEventLog))
{
delete lpStrings[0];
return(S_FALSE);
}
delete lpStrings[0];
return S_OK;
}
Make sure to include EvtLogMsg.h so that the category and message identifiers can resolve.
Debugging Event Logging
A common error in debugging an application that logs to the event log, is to leave the event viewer open. Let's say for instance you made a spelling error in a category. In Microsoft Developer Studio you change the message file and recompile it. Once the message file has compiled you recompile the DLLs resource. Then when you return to the event viewer and the message hasn't changed. Even if you refresh the event viewer the misspelled word doesn't go anyway. The problem here is that the categories load when the event viewer begins, to see the change you will need to close the event viewer and reopen it.
Calling the Method
Once the WriteError method has been added, recomplie the project, and write an Active Server page to call the object.
Registering the Object
If you move the object to another machine you will need to register the object before you can call it with through Active Server. Here is how, from a dos window in the directory that the object is located type:
regsvr32 EvtLog.dll
Simple Active Server Page
Here is a simple Active Server Page that will call the EvtLog Object.
<%
Set Obj = Server.CreateObject("EvtLogObj.EvtLogObj.1")
Obj.WriteError("Test Message")
%>
<HTML>
<BODY>
Done!
</BODY>
</HTML>
Checking the Results
After you have called this page serveral times from a Browser. Open the Event Viewer and view the results. Here is how: - Click on Start | Programs | Administrative Tools | Event Viewer.
- Click on Log | Application.
- Find the Events under the ASP Category, open them and view the Message.
Only the Object
If you do not want to be bothered with Mircosoft Developers Studio, compiling the source code or using Actitve Template Library you can download just the Object and the Active Server Page here. Make sure that you Register the object before calling it. 031697_1.zip (20K).
Only the Source
Here is the source for the EvtLog object and project. http://15seconds.com/files/031697_2.zip (20K).
Registering the Object
Once you download the object to your machine you will need to register the object before you can call it with through Active Server. Here is how, from a dos window in the directory that the object is located type:
regsvr32 EvtLog.dll
|
