Introduction

This article follows on from the Active Script Hosting discussions of Andrew Garbuzov. Before you start on adding debugger support to your active script it's probably a good idea to have active scripts up and running....

Tutorial: UML 2.0 Modeling: Visualize with Rational Software Modeler Using easy-to-follow, step-by-step instructions, you'll learn how to create a variety of different UML 2.0 diagrams, import existing modeling projects, and edit models. On-Demand Webcast: Introduction to UML2 The Unified Modeling Language (UML) is the standard language for visualizing, specifying, constructing, and documenting the artifacts of a software-intensive system. In this session learn the basic UML diagrams, and the notation changes in UML 2.0, the latest version. February 15, 2005 Download: Rational Software Modeler A customizable, UML-based visual modeling and design tool that enables users to clearly document and communicate these system views. Its drag and drop UI components and point and click database connectivity leverages your existing skills, shortens the Java learning curve, and supports team development. Article: Synchronizing UML Models See how the Eclipse-based IBM Rational Systems Developer allows you to easily create and browse models and code using diagrams, create code from UML diagrams, and vice versa. Download: Rational Systems Developer IBM Rational Systems Developer is a design and development tool that enables software architects and model-driven developers to create well-architected C/C++, Java J2SE, and CORBA-based applications that leverage Unified Modeling Language (UML 2). Download: IBM Rational Software Architect V6.0 This integrated design and development tool leverages model-driven development with the UML for creating well-architected applications and services.

The code in this article builds on the Microsoft sample : "MFCAXS.EXE: MFCAXS Implements an Active Script Host Using MFC". This sample on its own is really a very good place to discover lots about how to implement Active Script Hosting. It also contains an excellent extension to CCmdTarget, CCmdTargetPlus, that allows you to easily write automation servers with events without having to use the COleControl class.

To experiment with the debugging interfaces, you will need an Active Script debugger installed like the IE4 one available from Microsoft's scripting site

A reference for the Active Script debugging interfaces was once provided in the online reference but this now seems to have been moved off the Microsoft site. Even with this documentation, implementing script debugging is far from trivial and the main aim of this article is to give you a working sample to play with.

Warning - Because the Active Script Debugging interfaces do not seem to be fully documented yet by Microsoft - in particular they have not provided any header files or type libraries, the sample project attached to this article includes a hand built header file, activscp_plus.h, which should be replaced with an offical MS version as soon as they provide one.

Debugging in Action

Before you start please Download demo project and extract and run mfcaxscrb.exe

To view the debugger in action:

1. Run the debugger
2. Run the sample application. In this application type and run a script
   

   
   BroCon.Navigate ""http://www.codeguru.com%22"
   ??>www.codeguru.com"
   
   MsgBox "Hello World"
   
   Sub AButton_OnClick()
     MsgBox "Button A"
   End Sub
   
   Sub BButton_OnClick()
     MsgBox "Button B"
   End Sub
   

3. The application will appear as:

   

4. In the "Running Documents" view of the IE4 debugger, click down the hierarchy of the "MFC Scripting Documents" application and double-click on the "VBScript - Scripter script block"
5. The IE4 debugger should now display some of the text of your script - in this you can now place breakpoints to test the link between the debugger and the application. For example, set a breakpoint in the AButton_OnClick handler and then click the AButton button in the MFC application
   
6. Feel free to play with the debugger's "commands" window to view and alter values in your script's code. For example, you can use the command window to print the value of the edit control (use '? BroCon.LocationURL') or to set values or call methods (try 'BroCon.Navigate "www.dilbert.com"')

Note: Microsoft have set up the script debugging so that Visual Interdev will always be used in preference to the IE4 debugger. If you have Visual Interdev installed then you can attach to the script using "Debug|Processes" and then choosing the process "mfcaxsrvb.exe" in the dialog. The Interdev debugger gices you the benefits of watchpoints and a watch window, a "Set Next Statement" command, and generally better editing facilites.

Adding debugger support to an Active Script Host

To add debugging support to an Active Script Host, you need to perform the following steps:

1. Before you initialise any of the IActiveScript classes, manually create an IProcessDebugManager - this manager will control the debug process for you.

// Initialise the pdm
hr = CoCreateInstance(CLSID_ProcessDebugManager,
                      NULL,
                      CLSCTX_INPROC_SERVER | /*CLSCTX_INPROC_HANLDER | */CLSCTX_LOCAL_SERVER,
                      IID_IProcessDebugManager,
                      (void**)&m_pdm);

2. Manually create an IDebugApplication, set its name and then add this application to the process manager.

hr = m_pdm->CreateApplication(&m_pDebugApp);
if (!SUCCEEDED(hr))
{
   // ....
}

ASSERT(m_pDebugApp);
hr = m_pDebugApp->SetName(L"MFC Scripting Application");
if (!SUCCEEDED(hr))
{
   // ....
}

hr = m_pdm->AddApplication(m_pDebugApp, &m_dwAppCookie);
if (!SUCCEEDED(hr))
{
   // ....
}

3. For each document (normally each script) you wish to run, create an IDebugDocumentHelper to wrap the document. Define the short and long names of the document and attach the document to your application

hr = m_pdm->CreateDebugDocumentHelper(NULL, &m_pDebugDocHelper);
if (!SUCCEEDED(hr))
{
   // ...
}

hr = m_pDebugDocHelper->Init(m_pDebugApp, L"Doc Name", L"Long Doc Name", TEXT_DOC_ATTR_READONLY);
if (!SUCCEEDED(hr))
{
   // ...
}

hr = m_pDebugDocHelper->Attach(NULL);
if (!SUCCEEDED(hr))
{
   // ...
}

4. Support the IActiveScriptSiteDebug in your script host. This interface provides a number of methods allowing a debugger to get the structure of the scripts in your documents and to get the text of those documents.

BEGIN_INTERFACE_MAP(CMfcaxscrvbDlg, CDialog)
    ...
    INTERFACE_PART(CMfcaxscrvbDlg,IID_IActiveScriptSiteDebug,ActiveScriptSiteDebug)
    ...
END_INTERFACE_MAP()

...

/////////////////////////////////////////////////////////////////////////////
// IActiveScriptSiteDebug Implementation
STDMETHODIMP_(ULONG) CMfcaxscrvbDlg::XActiveScriptSiteDebug::AddRef()
{
   METHOD_PROLOGUE_EX_(CMfcaxscrvbDlg, ActiveScriptSiteDebug)
   return pThis->ExternalAddRef();
}

STDMETHODIMP_(ULONG) CMfcaxscrvbDlg::XActiveScriptSiteDebug::Release()
{
   METHOD_PROLOGUE_EX_(CMfcaxscrvbDlg, ActiveScriptSiteDebug)
   return pThis->ExternalRelease();
}

STDMETHODIMP CMfcaxscrvbDlg::XActiveScriptSiteDebug::QueryInterface(REFIID iid, LPVOID* ppvObj)
{
   METHOD_PROLOGUE_EX_(CMfcaxscrvbDlg, ActiveScriptSiteDebug)
   return pThis->ExternalQueryInterface(&iid, ppvObj);
}

// Used by the language engine to delegate IDebugCodeContext::GetSourceContext. 
STDMETHODIMP CMfcaxscrvbDlg::XActiveScriptSiteDebug::GetDocumentContextFromPosition(
      DWORD dwSourceContext,// As provided to ParseScriptText 
                            // or AddScriptlet 
      ULONG uCharacterOffset,// character offset relative 
                             // to start of script block or scriptlet 
      ULONG uNumChars,// Number of characters in context 
                      // Returns the document context corresponding to this character-position range. 
      IDebugDocumentContext **ppsc)
{
   METHOD_PROLOGUE_EX_(CMfcaxscrvbDlg, ActiveScriptSiteDebug)

   ULONG ulStartPos = 0;
   HRESULT hr;

   if (pThis->m_pDebugDocHelper)
   {
      hr = pThis->m_pDebugDocHelper->GetScriptBlockInfo(dwSourceContext, NULL, &ulStartPos, NULL);
      hr = pThis->m_pDebugDocHelper->CreateDebugDocumentContext(ulStartPos + uCharacterOffset, uNumChars, ppsc);
   }
   else
   {
      hr = E_NOTIMPL;
   }

	return hr;
}

// Returns the debug application object associated with this script site. Provides 
// a means for a smart host to define what application object each script belongs to. 
// Script engines should attempt to call this method to get their containing application 
// and resort to IProcessDebugManager::GetDefaultApplication if this fails. 
STDMETHODIMP CMfcaxscrvbDlg::XActiveScriptSiteDebug::GetApplication(
      IDebugApplication **ppda)
{
   METHOD_PROLOGUE_EX_(CMfcaxscrvbDlg, ActiveScriptSiteDebug)
   if (!ppda)
   {
      return E_INVALIDARG;
   }

   // bugbug - should addref to this ?
   if (pThis->m_pDebugApp)
   {
      ULONG ul = pThis->m_pDebugApp->AddRef();
   }

   *ppda = pThis->m_pDebugApp;

	return S_OK;
}

// Gets the application node under which script documents should be added 
// can return NULL if script documents should be top-level. 
STDMETHODIMP CMfcaxscrvbDlg::XActiveScriptSiteDebug::GetRootApplicationNode(
      IDebugApplicationNode **ppdanRoot)
{
   METHOD_PROLOGUE_EX_(CMfcaxscrvbDlg, ActiveScriptSiteDebug)

   if (!ppdanRoot)
   {
      return E_INVALIDARG;
   }

   if (pThis->m_pDebugDocHelper)
   {
      return pThis->m_pDebugDocHelper->GetDebugApplicationNode(ppdanRoot);
   }

   return E_NOTIMPL;
}

// Allows a smart host to control the handling of runtime errors 
STDMETHODIMP CMfcaxscrvbDlg::XActiveScriptSiteDebug::OnScriptErrorDebug(
      // the runtime error that occurred 
      IActiveScriptErrorDebug *pErrorDebug,
      // whether to pass the error to the debugger to do JIT debugging 
      BOOL*pfEnterDebugger,
      // whether to call IActiveScriptSite::OnScriptError() when the user 
      // decides to continue without debugging 
      BOOL *pfCallOnScriptErrorWhenContinuing)
{
   METHOD_PROLOGUE_EX_(CMfcaxscrvbDlg, ActiveScriptSiteDebug)
   if (pfEnterDebugger)
   {
      *pfEnterDebugger = TRUE;
   }
   if (pfCallOnScriptErrorWhenContinuing)
   {
      *pfCallOnScriptErrorWhenContinuing = TRUE;
   }
   return S_OK;
}

5. Before you parse the script text using IActiveScriptParse, add the script text to the IDebugDocumentHelper and define the script as a text.

hr = m_pDebugDocHelper->AddDBCSText(strScriptText);
if (!SUCCEEDED(hr))
{
   // ....
}

DWORD dw;
hr = m_pDebugDocHelper->DefineScriptBlock(0, strScriptText.GetLength(), m_axs, FALSE, &dw);
if (!SUCCEEDED(hr))
{
   // ....
}

6. When you have finished with the script, be sure to detach and release the IDebugDocumentHelper.

m_pDebugDocHelper->Detach();m_pDebugDocHelper->Release();
m_pDebugDocHelper = NULL;

7. [optional] The sample code included with this article also provides a simple IDebugDocumentHost implementation. This interface does not get used to its full extent by the IE4 debugger, but other Active Debuggers may use it more fully. Among the capabilities of this interface are customisation of script syntax coloring and provision of file path names and methods to react to the debugger changing document text.

Download source and Executable- 86 KB

Webinar : An Introduction to InstallShield 12 for New Users
Fortify Source Code Analysis provides a unique source code security analysis solution. Try it now.
Whitepaper: Learn how effective governance is needed for organizations to fully realize its promise.
Innovate On: A Single Source for Developers and ISVs--Get the latest on upcoming Microsoft products.
Article: Taking a Deeper Dive: Developers Explore the Depths of Interaction Center 7.1