Click here to Skip to main content
14,094,971 members
Click here to Skip to main content
Add your own
alternative version


36 bookmarked
Posted 3 Sep 2005


, 3 Sep 2005
Rate this:
Please Sign up or sign in to vote.
A prototype debug tracer with an added dimension.


Traceract is a prototype debug message tracer. The name is a combination of the words "tesseract" and "trace", as it adds "dimension" to the usual debug trace output. In particular, Traceract provides a simple command interface, directing the viewer to output trace messages to a particular window. Although it is still in its infancy, I find it quite valuable simply as is, although there are a myriad of features I would like to add to it over time. One reason to put this in the public domain is that I'd also like to get feedback as to what kind of features other people would like to see.


Traceract features are straightforward:

  • Simple commands embedded as debug output string to direct debug output to specific view windows.
  • Weifen Luo's excellent docking manager is used to enable the user to customize and control the layout of the debug windows.
  • Traceract currently uses a ListView in detail mode to display the debug number, time, and message. This is a bit limiting, especially with regards to line length. Traceract currently wraps lines automatically (and quite dumbly).


Traceract uses the "!" (exclamation) character, positioned as the first character in the debug string, to identify a command. If the remaining portion of the string does not match the required format, Traceract outputs the debug string as normal.


Your application is responsible for defining the output windows to which it will be directing debug strings. This is done with the initialization command:


tag is the shorthand name you will be using in the debug string text to identify that the string is output to the window referenced by the tag. name is the human readable name you are assigning to the output window. By default, all Windows appear on the document tab strip.

For example:

Debug.WriteLine("!!tr=Trans. Rec.");
Debug.WriteLine("!!br=Bus. Rules");

Directing debug strings

A debug string is directed to the appropriate output window using the format:


tag is the shorthand name specified during initialization. msg is the usual debug string.

For example:


Other commands

The only commands that Traceract currently supports are Clear and ClearAll:


This clears the debug strings in the output window specified by the tag name.


This clears all the debug strings in all output windows.

Under the hood

The code that I'm primarily going to illustrate here is the debug message string handling. I will also briefly describe the declarative UI and serialization of the dock panels. However, a full discussion of the dock panel manager that is a wrapper for Weifen Luo's DockPanel Suite will be presented in a separate article, as I'd like to illustrate using both his toolkit and the Infragistics docking manager, and how one writes a wrapper that allows one to use either docking manager in an application without changing the application code.

Debug messages

The Debug Message Monitor

At its core, Traceract intercepts the debug messages in a worker thread. The main loop:

public void Run()

    Events.WaitForSingleObject(ready, -1);

    if (!running)

    if (DbgHandler != null)
      UInt32 nApp=
      long n=sharedAddress.ToInt64()+4;
      string str=
         Marshal.PtrToStringAnsi(new IntPtr(n)); 
      string[] lines=str.Split('\n');

      foreach(string line in lines)
        string l2=line.Trim();
        if (l2 != String.Empty)
          // Ignore completely blank lines, but 
          // if not blank, preserve whitespace.
          DebugDataEventArgs args=
                 new DebugDataEventArgs(nApp, line);
          DbgHandler(this, args);

reads a string, splits it into discrete lines, and invokes the DbgHandler event.

The Event Handler

The event handler does some brute-force decoding of the debug string to check for tags and commands. It then adds a DebugMessageEventArgs instance to a queue that is monitored by a separate worker thread. The reason for this is that the debug monitoring event thread cannot perform a Form.Invoke, nor can it post messages to the Windows message queue. I haven't really looked into why (my knowledge here is ignorant). You will note that a hashtable handlerToContentMap is used to obtain the DebugListView instance that actually handles the display of the debug messages associated with the tag specified in the debug string.

private void OnDebugString(object sender, 
                                 DebugDataEventArgs e)
  long ticks=HiResTimer.Ticks;
  double tick=((double)(ticks - start))/
  string handler=null;
  string[] msgs=e.Data.Split('\r');
  foreach(string m in msgs)
    string msg=m.Replace("\t", 
                       spaces.Substring(0, tabWidth));

    if (msg.Length > 1)
      if (msg[0] == '!')
        if (msg.IndexOf(':') != -1)
          handler=StringHelpers.Between(msg, '!', ':');
          msg=StringHelpers.RightOf(msg, ':');
        else if (msg[1] == '!')
          msg=StringHelpers.RightOf(msg, '!', 2);
          string[] vals=msg.Split('=');

          if (vals.Length==2)
            string tabName=vals[1];
            if (vals[0].ToLower()=="clearall")
            else if (vals[0].ToLower()=="clear")
              string cmd=vals[0];

              if (vals.Length==2)
                if (handlerToContentMap.Contains(vals[1]))
                  Content content=
                  DebugListView dlv=

    if (msg.Length > 0)
      // Uses a queue because we can't do a form.Invoke
      // here (nor does posting a message work).

      int n=0;
      int len=msg.Length;
      DebugMessageEventArgs dmea;

      while (len > 0)
        if (n > 0)
          dmea=new DebugMessageEventArgs(count, tick, handler," "+
                msg.Substring(n, len > maxWidth ? maxWidth : len),
          dmea=new DebugMessageEventArgs(count, tick, handler, 
                msg.Substring(n, len > maxWidth ? maxWidth : len),



Queue processing

As mentioned above, the debug monitor thread cannot directly perform a Form.Invoke or post messages to the application. Instead, the thread adds the messages to a queue. Again, the code implementation is rather brute force--I could have used semaphores but chose a much simpler approach:

public void ProcessMessages()
  while (!stop)
    while (!stop && (queue.Count > 0) )
      DebugMessageEventArgs dmea=
      form.Invoke(new SendMessageDlgt(SendMessage), 
                                      new object[] {dmea});

I can hear the screams already! Sleeping the thread! Well, what can I say. There's definitely room for improvement.

Message processing

The queue worker thread finally gets the debug message posted into the application's thread, from which we can safely update the ListView control:

private void SendMessage(DebugMessageEventArgs dmea)
  if (dmea.Handler != null)
    if (!handlerToContentMap.Contains(dmea.Handler))
      string dwName=Guid.NewGuid().ToString();
      Content content=dockingManager.CreateDockWindow(dwName);
      string contentName=dmea.Handler;
      if (handlerToNameMap.Contains(dmea.Handler))

      DebugListView dlv=(DebugListView)content.Controls[0];

  if (DebugMessage != null)
    DebugMessage(this, dmea);

The above code will create a window on-the-fly when a new tag is encountered. Also, it will set the window's name to a previously specified human-readable caption, otherwise it uses the tag text. Lastly, it invokes the DebugMessage event. This event is hooked by all output windows, and each window gets the opportunity to display the debug message as determined by the filter (the tag). I chose this approach so that in the future, a single window can be told to "watch" for multiple tags. Again, some optimization would be helpful here--only invoking the handler associated with a specific tag.

The DebugMessage handler

The DebugListView class implements the handler:

private void OnDebugMessage(object sender, 
                            DebugMessageEventArgs e)
  bool display=true;

  if (filter != String.Empty)
    display=e.Handler == filter;
    display=(!e.ExcludeFromFullOutput) || (e.Handler==null);

  if (display)
    string count=e.Count.ToString();
    string tick=e.Tick.ToString("#0.00000");
    ListViewItem lvi=new ListViewItem(new string[] 
                                  {count, tick, e.Message});

    if (autoScroll)

which checks if the filter is applicable and correct and if so, displays the debug string.

The user interface

As you can probably guess, the user interface is defined declaratively, using the MyXaml parser (the 2.0 beta version). Before I continue:

MyXaml is generic declarative instantiation engine. It's syntax looks similar to Microsoft's XAML primarily because both directly map XML elements to .NET classes and XML attributes to .NET properties. However, MyXaml is not an emulation of Microsoft's XAML. The two are distinctly different. For example, MyXaml's namespace mapping is different, and MyXaml does not support compound property syntax or implicit collections.

The UI definition consists of four parts:

  • the form
  • the menu
  • the docking manager definition
  • the dock window content templates

A complete discussion of the docking manager and the wrapper that I've written to support Weifen Luo's DockPanel Suite is going to be a separate article, as the article will also illustrate how the wrapper abstracts the docking manager and can be used also for other third party docking managers, such as Infragistic's. In this article, I will only briefly describe the declarative part. As with all declarative XML, it begins with an xmlns to .NET namespace map:


    xmlns="System.Windows.Forms, System.Windows.Forms,






and the "ref" and "def" xmlns tags are internally used by the parser.

The form

The form definition is straightforward:

<mxdm:DockableForm def:Name="AppMainForm"

    Text="Traceract - Trace Viewer"

    ClientSize="800, 600"



This instantiates the DockableForm class and sets a few properties.

The menus

The menu object graph includes wiring up the event handlers. I'm using the MxMenu assembly here so that in the future I can add icons to the menus (the original implementation was written by Chris Becket). As with all MyXaml object graphs, this follows a "class-property-class" parent-child-grandchild format.

      <MenuItem Text="&amp;File">
          <menu:MxMenuItem Text="&amp;Load Layout" 

          <menu:MxMenuItem Text="&amp;Save Layout" 

          <menu:MxMenuItem Text="-"/>
          <menu:MxMenuItem Text="&amp;Test" Click="{app.OnTest}"/>
          <menu:MxMenuItem Text="-"/>
          <menu:MxMenuItem Text="E&amp;xit" Click="{app.OnExitApp}"/>
      <MenuItem Text="&amp;View">
          <menu:MxMenuItem Text="&amp;Clear All" Click="{app.OnClearAll}"/>
        <MenuItem Text="&amp;About" Click="{app.OnAbout}">

Docking Manager definition

The DockableForm class extends Form and adds only one property, a DockManager, which is initialized to an instance of a DockingManager.

  <dm:DockingManager def:Name="dockingManager"


      <mxdm:DockSite def:Name=
               "dockLeft" Edge="Left" Width="300" AutoHide="false"/>
      <mxdm:DockSite def:Name="dockRight" Edge="Right" Width="200"/>
      <mxdm:DockSite def:Name="dockTop" Edge="Top"/>
      <mxdm:DockSite def:Name="dockBottom" Edge="Bottom" Height="200"/>
      <mxdm:DockSite def:Name="document" Edge="Document"/>
      <mxdm:DockWindow def:Name="fullOutput" SiteName="dockBottom" 

                       Caption="Full Output" 


      <mxdm:DockWindow def:Name="newHandler" SiteName="document"



The DockingManager class manages two things--dock sites and dock windows. A DockWindow is docked to a particular site and the content for the window comes from a separate template file, referenced by the properties ContentFile and ContentName. With this information we can construct the initial form layout, which is done imperatively during initialization:

Content content=dockingManager.CreateDockWindow("fullOutput");

When a new debug message window is required, the imperative code copies the "newHandler" template and instantiates a new dock window:

string dwName=Guid.NewGuid().ToString();
dockingManager.CopyDockWindowTemplate(dwName, "newHandler");
Content content=dockingManager.CreateDockWindow(dwName);

Thus, the "newHandler" XML definition determines where the new debug message windows are initially positioned--in this case, in the document tab strip.

Dock window content templates

The templates, which are defined in a separate file, determine the content of the DockWindow instances. Therefore, if you want a different content, you not only define the content template but also an initial DockWindow instance in which that content is displayed. The two templates defined by default are:

<mxdm:Content def:Name="fullOutputContent">
    <tr:DebugListView Dock="Fill" View="Details" 

                      FullRowSelect="true" GridLines="true">
        <ColumnHeader Text="#"/>
        <ColumnHeader Text="Time"/>
        <ColumnHeader Text="Output" Width="600"/>

<mxdm:Content def:Name="newHandlerContent" 

    <tr:DebugListView Dock="Fill" View="Details" 

                 FullRowSelect="true" GridLines="true">
        <ColumnHeader Text="#"/>
        <ColumnHeader Text="Time"/>
        <ColumnHeader Text="Output" Width="600"/>

Application initialization

For those new to declarative programming, I'll describe the application initialization, where imperative and declarative code meet. Here's the initialization code:

                   "MyXaml.WinForms", "WinFormExtender");
parser=new Parser();
parser.AddReference("app", this);
form=(Form)parser.Instantiate("traceract.myxaml", "*");
form.Closing+=new CancelEventHandler(OnFormClosing);

The MyXaml 2.0 parser is "platform neutral", meaning that it doesn't include the System.Windows.Forms namespace, nor does it know about special things that ought to be done during form initialization. This is handled by the MyXaml.WinForms extender which hooks events in the parser. In particular, it implements handlers for the InstantiateBegin and InstantiateEnd methods, which in turn call SuspendLayout and ResumeLayout for any instances of Control type.

In the declarative portion, events were wired up to the "app" instance. The above code illustrates how the parser is told about the "app" instance.

Also, the parser can initialize fields with the instance instantiated during the declarative parsing. In the main application, there is one such field:

[MyXamlAutoInitialize] DockManager dockingManager=null;

The MyXamlAutoInitialize attribute tells the parser that only fields decorated with this attribute expect (and require) to be initialized.


Traceract can save an existing layout and load it (although, this still seems a bit buggy). The layout is serialized to XML as well. For example, if you change the layout to something like this (shrunk so it fits in a screenshot):

The serialization of the form layout (stored in layout.xml) looks something like this:

    <DockSite Name="Bottom1" Edge="Bottom" Width="600"

              Height="200" Location="0, 0" Size="600, 200" />
    <DockSite Name="Left2" Edge="Left" Width="200"

              Height="600" Location="0, 0" Size="200, 600" />
    <DockSite Name="Right2" Edge="Right" Width="200"

              Height="600" Location="0, 0" Size="200, 600" />
    <DockSite Name="Document3" Edge="Document" Width="0"

              Height="0" Location="0, 0" Size="0, 0" />
    <DockWindow Caption="Database" ContentName="newHandlerContent"



                SiteName="Left2" Filter="db" AutoScroll="True" />
    <DockWindow Caption="Full Output" ContentName="fullOutputContent" 


                Name="fullOutput" SiteName="Bottom1" Filter="" 

                AutoScroll="True" />
    <DockWindow Caption="Business Layer" ContentName="newHandlerContent" 



                SiteName="Document3" Filter="bl" AutoScroll="True" />
    <DockWindow Caption="GUI" ContentName="newHandlerContent" 



                SiteName="Right2" Filter="ui" AutoScroll="True" />

You will note that a GUID is used to ensure that a unique name is created for new content windows.

Serialization/deserialization of the window content is complicated. Each docking manager I've worked with is very finicky about deserialization order and how it controls the tiling of the windows. As I've mentioned before, I'll be discussing this in greater depth in an article on docking managers in general.

Upcoming features

The following is a list of features I'm planning to work on as time permits and need requires. Feel free to let me know of other features you'd like.

  • improve the code!
  • replace the ListView with something more decent,
  • colorization,
  • better line wrap handling,
  • automatic positioning of all windows to adjacent debug messages when selecting a debug message,
  • save/restore application screen position and size,
  • automatic reloading of last configuration,
  • MRU list of configurations,
  • file selection for save/load of configurations,
  • automatic configuration selection through debug message string,
  • remote debugging support,
  • copy line/range to clipboard,
  • print,
  • additional configuration options, such as always output to main debug window, line wrap, etc.,
  • layout serialization bug fixes.


Terms and conditions

Traceract is intended to be used for your personal use. You can modify it, borrow from the code, etc., as much as you wish, as long as this is for your own personal use. Traceract or its derivatives cannot be distributed as a stand-alone commercial application or as part of a commercial application without my express permission. Traceract uses the GPL'd MyXaml assemblies. Including the source code and assemblies in the download here does not convey any rights to use the MyXaml assemblies in a commercial application.

Updates and source code

You can obtain the latest code releases, updated source code, and if you wish, contribute to the project by obtaining an account for my CVS server. Anyone interested in this should contact Marc Clifton and I will set you up with an account. I will also be updating the article download, but probably not as frequently.


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Marc Clifton
Architect Interacx
United States United States
Home Page:

All my life I have been passionate about architecture / software design, as this is the cornerstone to a maintainable and extensible application. As such, I have enjoyed exploring some crazy ideas and discovering that they are not so crazy after all. I also love writing about my ideas and seeing the community response. As a consultant, I've enjoyed working in a wide range of industries such as aerospace, boatyard management, remote sensing, emergency services / data management, and casino operations. I've done a variety of pro-bono work non-profit organizations related to nature conservancy, drug recovery and women's health.

You may also be interested in...

Comments and Discussions

QuestionStill current? Pin
roscler25-Aug-14 3:53
professionalroscler25-Aug-14 3:53 
AnswerRe: Still current? Pin
Marc Clifton25-Aug-14 6:05
protectorMarc Clifton25-Aug-14 6:05 
GeneralBroken link Pin
martin_hughes3-Sep-07 6:49
membermartin_hughes3-Sep-07 6:49 
GeneralRe: Broken link Pin
Humble Programmer2-Jul-08 10:17
memberHumble Programmer2-Jul-08 10:17 
QuestionHow do you get it to work? Pin
jonroberts2421-Mar-07 0:49
memberjonroberts2421-Mar-07 0:49 
QuestionTraceract for tracing a service? Pin
AjayVaidya17-Oct-05 18:37
memberAjayVaidya17-Oct-05 18:37 
GeneralThread safety and log4net suggestion Pin
John Rayner6-Sep-05 11:58
memberJohn Rayner6-Sep-05 11:58 
GeneralRe: Thread safety and log4net suggestion Pin
Marc Clifton6-Sep-05 12:07
protectorMarc Clifton6-Sep-05 12:07 
GeneralRe: Thread safety and log4net suggestion Pin
Marc Clifton6-Sep-05 14:32
protectorMarc Clifton6-Sep-05 14:32 
GeneralRe: Thread safety and log4net suggestion Pin
John Rayner7-Sep-05 10:04
memberJohn Rayner7-Sep-05 10:04 
GeneralSuggestions Pin
leppie4-Sep-05 2:05
memberleppie4-Sep-05 2:05 
GeneralRe: Suggestions Pin
Marc Clifton4-Sep-05 2:20
protectorMarc Clifton4-Sep-05 2:20 
GeneralThread.Sleep Pin
leppie4-Sep-05 1:38
memberleppie4-Sep-05 1:38 
GeneralRe: Thread.Sleep Pin
Marc Clifton4-Sep-05 2:16
protectorMarc Clifton4-Sep-05 2:16 
QuestionExcellent Pin
Michael P Butler3-Sep-05 23:10
memberMichael P Butler3-Sep-05 23:10 
AnswerRe: Excellent Pin
Marc Clifton4-Sep-05 2:15
protectorMarc Clifton4-Sep-05 2:15 
QuestionTrace listener? Pin
Ashley van Gerven3-Sep-05 16:04
memberAshley van Gerven3-Sep-05 16:04 
AnswerRe: Trace listener? Pin
Marc Clifton4-Sep-05 2:21
protectorMarc Clifton4-Sep-05 2:21 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web06 | 2.8.190518.1 | Last Updated 3 Sep 2005
Article Copyright 2005 by Marc Clifton
Everything else Copyright © CodeProject, 1999-2019
Layout: fixed | fluid