ReadMe.htm

<!--TO READ THIS HELP FILE, RIGHT-CLICK ON THE FILE NAME IN THE
    SOLUTION EXPLORER PANE AND SELECT "VIEW IN BROWSER"-->

<html><head><title>EEAddIn Sample: Debugging Expression Evaluator Add-In</title></head><body><h1>EEAddIn Sample: Debugging Expression Evaluator Add-In</h1><div id="mainSection"><div id="mainBody"><div id="allHistory" class="saveHistory" onsave="saveAll()" onload="loadAll()"></div><p /><p>The EEAddin sample shows how to extend the native debugger expression evaluator using the Expression Evaluator Add-In API.</p><div class="alert"><table width="100%" cellspacing="0" cellpadding="0"><tr><th align="left">Security Note </th></tr><tr><td><p>This sample code is provided to illustrate a concept and should not be used in applications or Web sites, as it may not illustrate the safest coding practices.</p></td></tr></table></div><h1 class="heading">EE Add-In API</h1><div id="sectionSection0" class="seeAlsoNoToggleSection"><p>The expression evaluator is the part of the debugger that interprets (evaluates) expressions. When you set a breakpoint on an expression or type an expression in a debugger window, the expression evaluator interprets the input. For details, see <MSHelp:link keywords="70F9B531-44C7-4D77-980D-5EDDBF2BFF41" tabindex="0" >Expressions in the Debugger</MSHelp:link>. With the Expression Evaluator Add-In API, you can extend the expression evaluator to handle new types.</p><p>To extend the expression evaluator for a new type, you need to write a function as part of a Win32 DLL (in the same directory as autoexp.dat) and export it by name. You also need to add a line to the <MSHelp:link keywords="9969E9B2-9008-4729-8A14-0D6DEAA61576" tabindex="0" >autoexp.dat</MSHelp:link> file. You can extend the expression evaluator for more than one type by exporting multiple functions from the DLL.</p></div><h1 class="heading">Building and Running the Sample</h1><div id="sectionSection1" class="seeAlsoNoToggleSection"><p>The steps required to build and run this sample fall into three parts.</p><div class="alert"><table width="100%" cellspacing="0" cellpadding="0"><tr><th align="left">Note </th></tr><tr><td><p>If you are running Visual C++ Express Edition, you might need to install the Platform SDK before running this sample. For information on how to do this, see <MSHelp:link keywords="971463b4-7178-42cc-87b4-566295b7ae50" tabindex="0" >How to: Use Visual C++ Express Edition with the Microsoft Platform SDK</MSHelp:link>.</p></td></tr></table></div><h4 class="subHeading">To build and run the sample</h4><div class="subSection"><ol><li><p>Build an expression evaluator Add-In DLL (eeaddin.dll).</p></li><li><p>Edit autoexp.dat to use the expression evaluator Add-In DLL.</p></li><li><p>Test the Add-In by creating a project that uses the custom data type evaluated by autoexp.dat.</p></li></ol></div><p>The following procedures explain these steps in detail.</p><h4 class="subHeading">To build the expression evaluator Add-In DLL</h4><div class="subSection"><ol><li><p>In Visual Studio, open the solution eeaddin.sln.</p></li><li><p>From the <b>Build</b> menu, click <b>Build</b>.</p></li><li><p>Copy the resulting eeaddin.dll to your common7\ide directory (the same directory that contains devenv.exe).</p></li><li><p>From the <b>File</b> menu, click <b>Close Solution</b>.</p></li></ol></div><h4 class="subHeading">To edit autoexp.dat</h4><div class="subSection"><ol><li><p>From the <b>File</b> menu, point to <b>Open</b> and click <b>File</b>.</p></li><li><p>In the <b>Open File</b> dialog box, find the file autoexp.dat (in the common7\packages\debugger directory) and click <b>Open</b>.</p></li><li><p>Edit autoexp.dat to add the following lines: </p><div class="code"><span codeLanguage="other"><table width="100%" cellspacing="0" cellpadding="0"><tr><td colspan="2"><pre>_SYSTEMTIME=$ADDIN(eeaddin.dll,AddIn_SystemTime)
_FILETIME=$ADDIN(eeaddin.dll,AddIn_FileTime)</pre></td></tr></table></span></div><p>Save autoexp.dat. </p></li></ol></div><h4 class="subHeading">To create a project that uses the custom data types</h4><div class="subSection"><ol><li><p>From the <b>File</b> menu, point to <b>New</b> and click <b>Project</b>.</p></li><li><p>In the <b>New Project</b> dialog box, highlight <b>Visual C++ Projects</b>, click <b>MFC Application</b>, enter a name for the project, and click <b>OK</b>.</p></li><li><p>In the <b>MFC Application Wizard</b>, click <b>Finish</b>. The project must be an MFC application because in the next step you will add MFC functions.</p></li><li><p>In the MFC application, add a <MSHelp:link keywords="9AAEF4D6-DE79-4FA1-8158-86B245EF5BFF" tabindex="0" >SYSTEMTIME</MSHelp:link> or <MSHelp:link keywords="E09557E2-B6D7-4DD5-A5B9-6328BCA88595" tabindex="0" >FILETIME</MSHelp:link> object. </p><div class="code"><span codeLanguage="other"><table width="100%" cellspacing="0" cellpadding="0"><tr><td colspan="2"><pre>SYSTEMTIME *s = new SYSTEMTIME();
FILETIME *f = new FILETIME();
GetSystemTime(s);
SystemTimeToFileTime(s,f);</pre></td></tr></table></span></div></li><li><p>From the <b>Build</b> menu, click <b>Build</b>.</p></li><li><p>Start debugging and examine your <b>SYSTEMTIME</b> or <b>FILETIME</b> objects in the watch window.</p></li></ol></div></div><h1 class="heading">How the Sample Works</h1><div id="sectionSection2" class="seeAlsoNoToggleSection"><p>To extend the expression evaluator for a custom data type, you write a custom viewer function in the expression evaluator Add-In DLL. The function uses a pointer to an object in the memory space of the program being debugged (not the memory space of the expression evaluator you are extending). You cannot use normal casts with this pointer. You must read it and the data it points to using a callback function. A callback pointer of type <code>DEBUGHELPER*</code> points to an object with various methods. </p><p>The syntax looks like this:</p><div class="code"><span codeLanguage="other"><table width="100%" cellspacing="0" cellpadding="0"><tr><td colspan="2"><pre>HRESULT WINAPI CustomViewer(
   DWORD dwAddress,       // low 32-bits of address
   DEBUGHELPER *pHelper,  // callback pointer to access helper functions
   int nBase,             // decimal or hex
   BOOL bIgnore,          // not used
   char *pResult,         // where the result needs to go
   size_t max,            // how large the above buffer is
   DWORD dwReserved       // always pass zero
)</pre></td></tr></table></span></div><p>The sample has two implementations of this type of function, <code>AddIn_SystemTime</code> and <code>AddIn_FileTime</code> in timeaddin.cpp. The <code>DEBUGHELPER</code> struct (defined in custview.h) consists of function pointers that can assist you in writing your extension. This pointer is passed to your <code>CustomViewer</code> function, and you can use it to call the helper functions.</p><p>You can get the processor type with <code>pHelper-&gt;GetProcessorType</code>. There are two methods for reading memory, <code>pHelper-&gt;ReadDebuggeeMemory</code> and <code>pHelper-&gt;ReadDebuggeeMemoryEx</code>. <code>ReadDebuggeeMemoryEx</code> handles 64-bit addresses and is supported by the Visual Studio .NET debugger. <code>ReadDebuggeeMemory</code> does not handle 64-bit addresses and is supported by the Visual Studio .NET and Visual C++ 6.0 debuggers. If your Add-In is designed for the Visual Studio .NET debugger only, you can use <code>ReadDebuggeeMemoryEx</code>. If your Add-In needs to work with Visual C++ 6.0 also, you must check the <code>dwVersion</code> field and avoid calling <code>ReadDebuggeeMemoryEx</code> for Visual C++ 6.0. </p><p>The following code works with both debuggers and reads the contents of a <i>localobject</i> (whose type is <code>MyType</code>) from the program being debugged:</p><div class="code"><span codeLanguage="other"><table width="100%" cellspacing="0" cellpadding="0"><tr><td colspan="2"><pre>DWORDLONG qwRealAddress;
DWORD dwGot;
MyType localobject;
if (pHelper-&gt;dwVersion&lt;0x20000)
{
   // Visual C++ 6.0 version
   qwRealAddress = dwAddress;
   pHelper-&gt;ReadDebuggeeMemory( pHelper, dwAddress,
      sizeof(localobject), &amp;localobject, &amp;dwGot );
}
else
{
   qwRealAddress = pHelper-&gt;GetRealAddress(pHelper);
   pHelper-&gt;ReadDebuggeeMemoryEx( pHelper, qwRealAddress,
      sizeof(localobject), &amp;localobject, &amp;dwGot );
}
// TODO: display localobject here</pre></td></tr></table></span></div></div><h1 class="heading">Editing autoexp.dat</h1><div id="sectionSection3" class="seeAlsoNoToggleSection"><p>In the <code>[AutoExpand]</code> section of autoexp.dat, the lines you will add have the following syntax:</p><div class="code"><span codeLanguage="other"><table width="100%" cellspacing="0" cellpadding="0"><tr><td colspan="2"><pre><i>type</i>=$ADDIN(<i>dllname</i>.dll,<i>exportname</i>)</pre></td></tr></table></span></div><p>For example:</p><div class="code"><span codeLanguage="other"><table width="100%" cellspacing="0" cellpadding="0"><tr><td colspan="2"><pre>_SYSTEMTIME=$ADDIN(eeaddin.dll,AddIn_SystemTime)</pre></td></tr></table></span></div><p>or:</p><div class="code"><span codeLanguage="other"><table width="100%" cellspacing="0" cellpadding="0"><tr><td colspan="2"><pre>_FILETIME=$ADDIN(eeaddin.dll,AddIn_FileTime)</pre></td></tr></table></span></div><p>If the DLL is not in the directory containing devenv.exe or on the PATH, you must use a full path name for the DLL. The <i>exportname</i> argument is case sensitive and must exactly match the exported name you got when you ran <code>dumpbin –exports</code> on your DLL.</p><p>To test the debugger with the new Add-In, first stop debugging any program you were debugging when you installed the new DLL, and then start a new debugger session. </p><p><b>Note   </b>The Add-In runs within the debugger, so if your code crashes, you will crash the IDE.</p></div></div><div id="footer"><div class="footerLine"></div>
          © Microsoft Corporation. All rights reserved.  Send <a href="mailto:DevDocs@microsoft.com?subject=Documentation Feedback :EEAddIn Sample: Debugging Expression Evaluator Add-In">comments</a> about this topic to Microsoft.
      </div></div></body></html>