Registering a Custom Debug Engine

  • Article

Note

This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

The debug engine must register itself as a class factory following COM conventions as well as register with Visual Studio through the Visual Studio registry subkey.

Note

An example of how to register a debug engine can be found in the TextInterpreter sample, which is built as part of the Tutorial: Building a Debug Engine Using ATL COM.

DLL Server process

Typically, a debug engine is implemented in its own DLL as a COM server. This means that the debug engine must register the CLSID of its class factory with COM before Visual Studio can access it. Then the debug engine must register itself with Visual Studio itself in order to establish any properties (otherwise known as metrics) the debug engine supports. The choice of metrics that are written to the Visual Studio registry subkey for the debug engine depends on the features the debug engine supports.

SDK Helpers for Debugging describes not only the registry locations necessary to register a debug engine; it also describes the dbgmetric.lib library, which contains a number of useful functions and declarations for C++ developers that make manipulating the registry easier.

Example

The following is a typical example (from the TextInterpreter sample) showing how to use the SetMetric function (from dbgmetric.lib), to register a debug engine with Visual Studio. The metrics being passed are also defined in dbgmetric.lib.

Note

TextInterpreter is a basic debug engine; it does not implement—and therefore does not register—any other features. A more complete debug engine would have a whole list of SetMetric calls or their equivalent, one for each feature the debug engine supports.

// Define base registry subkey to Visual Studio.  
static const WCHAR strRegistrationRoot[] = L"Software\\Microsoft\\VisualStudio\\8.0";  
  
HRESULT CTextInterpreterModule::RegisterServer(BOOL bRegTypeLib, const CLSID * pCLSID)  
{  
    SetMetric(metrictypeEngine, __uuidof(Engine), metricName, L"Text File", false, strRegistrationRoot);  
    SetMetric(metrictypeEngine, __uuidof(Engine), metricCLSID, CLSID_Engine, false, strRegistrationRoot);  
    SetMetric(metrictypeEngine, __uuidof(Engine), metricProgramProvider, CLSID_MsProgramProvider, false, strRegistrationRoot);  
  
    return base::RegisterServer(bRegTypeLib, pCLSID);  
}

See Also

Creating a Custom Debug Engine
SDK Helpers for Debugging
Tutorial: Building a Debug Engine Using ATL COM