How Does Script Debugging Work Internally?

Every now and then someone will ask me how the behind-the-scenes magic works that allows you to debug scripts.

Darned if I know.  While the rest of the script team was busy implementing the debugging interfaces, I was working on the engines.  I understand only a little of the specifics.  But I can give you an overview.

The debugging architecture has five parts:

  • the host (IE, ASP, WSH, other third party hosts)
  • the engine (VBScript, JScript)
  • the process debug manager (PDM.DLL)
  • the machine debug manager (MDM.EXE)
  • the debugger (Visual Studio, Visual Interdev, the Script Debugger)

There are two kinds of hosts: “smart” and “dumb”.  Smart hosts know how the debugger architecture works, dumb hosts do not.  The script engine can detect whether it is running in a smart or dumb host.  (It asks the host “are you smart?” and if the answer is “Huh?” then obviously its not.  🙂 )  If it’s running in a dumb host, then the script engine takes care of the debugging plumbing.  If it is running in a smart host, then the engine and the host each have a part in the plumbing. 

The reasoning behind this is that we wanted to enable script developers to debug their scripts even if they were running in third party “dumb” hosts, but we also want smart hosts to be able to do things like provide context.  When you debug a script in a web page, the script engine knows nothing about the HTML in which it is embedded — it needs the cooperation of IE to tell the debugger what HTML file to display.  Similarly, ASP and WSH are smart; they provide information about the context in which the script is running.

The script engine and the host do not talk to the debugger directly.  Instead, they talk to an in-process component, aptly named the Process Debug Manager.  The PDM knows how to talk to the Machine Debug Manager, which runs as its own process.  The MDM acts as a dating service to hook up willing debuggers with willing debugees.

To sum up the story so far:

  • The (smart) host knows how to talk to the engine and the PDM. 
  • The engine knows how to talk to the host and the PDM. 
  • The PDM knows how to talk to the MDM.
  • The MDM knows how to talk to the PDM and the debugger.
  • The debugger knows how to talk to the MDM.

As you can see, the debugging architecture was designed for extensibility and abstraction.  A debuggee need know nothing about the debuggers, and vice-versa.  The debuggee need know nothing about what debuggers are installed on the machine, etc.  It just talks to the process debug manager, the PDM contacts the MDM, and everyone gets hooked up.

And now you know everything that I know about how script debugging works.  (OK, maybe I know a little bit more than that.  Someday I might do a blog entry on how to turn a dumb host into a smart host.)

Want to know more?  See the MSDN documentation here.

Comments (10)

  1. Michael Harris says:

    A blog entry on how to debug a broken "debugger dating service" situation would be interesting.

    When a scripter posts that they are unable to debug a script, there are numerous questions asked that revolve around two fundamental requirements:

    – do you have a debugger installed?

    – did you enable debugging (question/answer are generally specific to the host)?

    Now assume the poster provides all the right answers to all the right questions, yet are still unable to debug a script.

    The problem then appears to that something in host/engine/pdm/mdm/debugger chain has gone south. At that point, everyone tends to throw in the towel since there is no guide on how to debug the plumbing that makes the "debugger dating service" work…

  2. Ivana Mandic [MSFT] says:

    So its not cheese inside?

  3. Lucas Arnold says:


    Great Info!! Now I’m guessing if there is some way that I could hook up to the jscrip engine or debugger to actually peek at some internals (ie. # of time the GC has run, logging every time it runs, etc). Is this even possible? Do you have some pointers where to start looking at?


  4. John Stanhope says:

    I know there is KB article that includes the generated headers but are there any plans to distribute the IDL files used to generate the script debugging interfaces?

  5. Eric Lippert says:

    Hooking up the script debugger doesn’t debug the actual implementation of the script engine. None of the details of the garbage collector are exposed by the script engine.

    I continue to maintain that if you need to know details about how the garbage collector works, you are using the wrong language in the first place. The whole point of automatic storage languages is that you don’t have to think about that stuff. Why do you care what the GC is doing?

  6. Brian R. James says:

    I’m having no luck at all getting Script Debugger / Visual Studio to debug DHTML behaviors. I keep getting the "Script Unavailable" dialog. Normal .js scripts debug just fine. Anyone have any suggestions?

  7. Dan Shappir says:

    > Why do you care what the GC is doing?

    In most cases you are correct. But in some cases you really do want to know. At the very least, you want to be able to affect the behavior. This is why Java exposes System.gc, even it recommends not to use it. I assume JScript provides CollectGarbage for the same reason.

    For example, I’ve written a browser extension that uses Word to do spell-checking on text entered in forms. For obvious reasons, I want to release the Word instance as quickly as possible. CollectGarbage is the only way to enforce that (short of switching to VBScript).

  8. Paul Enfield says:

    Thank you so much for this. With this info I was able to resolve a debugging problem in our environment that stemmed from mis-matched versions of MDM and PDM.

    As an FYI for others out there, VS6 installs its support files in %windir%system32 while VS7(.Net) installs in Program FilesCommon FilesMicrosoft SharedVS7Debug

    Simply removing PDM.dll and MDM.exe from the System32 dir resolved our issues.

  9. 247Blogging says:

    Every now and then someone will ask me how the behind-the-scenes magic works that allows you to debug scripts. Darned if I know. While the rest of the script team was busy implementing the debugging interfaces, I was working on the engines. I understan