Edit

Metadata Files for Analysis Extension Plug-ins

  • Article

When you write an analysis extension plug-in, you also write a metadata file that describes the situations for which you want your plug-in to be called. When the !analyze debugger command runs, it uses metadata files to determine which plug-ins to load.

Create a metadata file that has the same name as your analysis extension plug-in and an extension of .alz. For example, if your analysis extension plug-in is named MyAnalyzer.dll, your metadata file must be named MyAnalyzer.alz. Place the metadata file in the same directory as your analysis extension plug-in.

A metadata file for an analysis extension plug-in is an ASCII text file that contains key-value pairs. Keys and values are separated by white space. A key can have any non-whitespace character. Keys are not case sensitive.

After the key and the following white space, the corresponding value begins. A value can have one of the following forms.

  • Any set of characters to the end of the line. This form works for values that do not contain any newline characters.

    Important  If the last value in the metadata file has a value of this form, the line must end with a newline character.

  • Any set of characters between braces { }. The form works for values that contain newline characters.

A line beginning with # is a comment and is ignored. Comments can start only where keys are expected.

You can use the following keys in a metadata file.

Key Description
PluginId String - Identifies the plug-in.
DebuggeeClass String - Possible values are “Kernel” and "User". Indicates that the plug-in is interested in analyzing only kernel-mode failures or only user-mode failures.
BugCheckCode 32-bit bug check code - Indicates that the plug-in is interested in analyzing this bug check code. A single metadata file can specify multiple bug check codes.
ExceptionCode 32-bit exception code - Indicates that the plug-in is interested in analyzing this exception code. A single metadata file can specify multiple exception codes.
ExecutableName String - Indicates that the plug-in is interested only in sessions where this is the running executable of the process to be analyzed. A single metadata file can specify multiple executable names.
ImageName String - Indicates that the plug-in is only interested only in sessions where the default analysis considers this image (dll, sys, or exe) to be at fault. The plug-in is invoked after analysis has determined which image is at fault. A single metadata file can specify multiple image names.
MaxTagCount Integer - The maximum number of custom tags that the plug-in needs. Custom tags are tags other than the ones defined in extsfns.h.

Example Metadata Files

The following metadata file describes a plug-in that is interested in analyzing bug check code 0xE2. (Recall that the last line must end with a newline character.)

PluginId      MyPlugin
DebuggeeClass Kernel
BugCheckCode  0xE2

The following metadata file describes a plug-in that is interested in analyzing bug checks 0x8, 0x9, and 0xA if MyDriver.sys is considered to be the module at fault.

PluginId      MyPlugin
DebuggeeClass Kernel
BugCheckCode  0x8
BugCheckCode  0x9
BugCheckCode  0xA
ImageName     MyDriver.sys

The following metadata file describes a plug-in that is interested in analyzing exception code 0xC0000005 if MyApp.exe is the running executable of the process being analyzed. Also, the plug-in might create as many as three custom tags.

PluginId        MyPlugin
DebuggeeClass   User
ExceptionCode   0xC0000005
ExecutableName  MyApp.exe

Debugging Tools for Windows has a sample that you can use to build a debugger extension module named dbgexts.dll. This extension module implements several debugger extension commands, but it can also serve as an analysis extension plug-in; that is, it exports an _EFN_Analyze function. Here is a metadata file that describes dbgexts.dll as an analysis extension plug-in.

PluginId         PluginSample
DebuggeeClass   User
ExceptionCode   0xc0000005
ExecutableName      cdb.exe
ExecutableName      windbg.exe
#
# Custom tag descriptions 
#
TagDesc         0xA0000000  SAMPLE_PLUGIN_DEBUG_TEXT    {Sample debug help text from plug-in analysis}
#

See also

Writing an Analysis Extension Plug-in to Extend !analyze

_EFN_Analyze

!analyze