Debugging & Diagnostics

By their nature, Shell Extensions can be difficult to debug. Whether running in Explorer (as most extensions do) or a COM Surrogate Host (as extensions such as Preview Handlers do), servers can be complex to attach to and diagnose.

In earlier versions of SharpShell, all logging was done to the Event Log, under the 'SharpShell' source. This is not suitable for diagnostics in many scenarios, as writing to the event log requires certain administrative privileges. SharpShell now supports a variety of ways to configure logging.

Table of Contents

Logging APIs
Configuration

SharpShell Logging APIs

You can log messages and errors when referencing SharpShell with the commands:

Logging.Log("This is a message.");
Logging.Error("This is an error.");
Logging.Error("This is an error with exception details.", someException);

However, if you are in a method in a class which derives from SharpShellServer (i.e. in your extension class), you can use:

Log("This is a message.");
LogError("This is an error.");
LogError("This is an error with exception details.", someException);

In this case, the name of your server is added to the log information, making it easier to diagnose which server is the source of the error message.

Configuring Logging

SharpShell logs in both Debug and Release mode, however, by default there are no loggers registered. To enable a logger, set the following Registry key:

HKEY_LOCAL_MACHINE\Software\SharpShell\LoggingMode

The values supported are:

Flag	Mode
0	Disabled
1	Debug
2	EventLog
4	File

You can use any combination of flags. Rather than setting the flags manually, you can use the srm tool:

srm config LoggingMode Debug
srm config LoggingMode "EventLog, File"

You can show the logging mode for the machine with:

srm config

Each of the logging modes are detailed below.

Debug

This is the safest logging mode to use as it requires no administrative privileges. Messages are written to the Windows Debug Log, and can be viewed with the free DebugView app or the command line version dbmon.exe.

EventLog

This mode will only work with when the process runs with elevated privileges. All messages are logged to the Windows Application Event Log.

File

Logging to a file may require administrative privileges, depending on the location of the file. Set the file location by setting the registry key:

HKEY_LOCAL_MACHINE\Software\SharpShell\LogMode

Or by using the srm:

srm config LogPath "%TEMP%\SharpShell.log"

The path will be expanded, so you can use environment variables. The %temp% location is recommended as no special permissions are required to write to this location.