Customize IntelliTrace to Collect Enums

This Guillaume Rouchon's post illustrates how to add a custom IntelliTraece event. Mine is to complement it with an enum type and updates in Visual Studio 2015 Update 2.

Let me summarize how to add a custom IntelliTrace event. The file you have to change is in a sub folder of Visual Studio installation folder, <VS installation folder>\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace\14.0.0\en\collectionplan.xml. You need to have admin privilege to do that. This file only affect F5 debugging in Visual Studio. If you are using IntelliTrace standalone collector, you have to pass the collection plan file to the command line. So you can modify default one that comes with the standalone collector or write your own one.

What you need to do to add a custom event is

Add a category under TracepointProvider/Categories
Add an assembly under TracepointProvider/ModuleSpecifications
Add your own diagnostic event specification under TracepointProvider/DiagnosticEventSpecifications

There are two ways of querying parameter values and returned values. The first is DataQuery. It's a simple declarative way using dot notation to get values of the parameter or the field in the parameter. It only supports primitive types. The other way is ProgrammableDataQuery. You have to provide your own IProgrammableDataQuery implementation to query a complex type.

For enum, we're going to use DataQuery.

We need to specify a type in the data query for enum. Intuition tells us we can use the enum type. But that's not working. The right type should be the underlying integral type. For example, int. The value is also an integral value too.

Let me illustrate it here.

I create a sample console application

using System;
namespace ConsoleApplication1
{
    enum Color
    {
        Red,
        Green,
        Blue
    }
    class Program
    {
        static void Main(string[] args)
        {
            PrintColor(Color.Blue);
        }
        static void PrintColor(Color color)
        {
            Console.WriteLine("Color: " + color);
        }
    }
}

Let's change the collection plan.

1. Add a new category.
<Category Id="enumSample" _locID="category.enumSample">Enum Sample</Category>
2. Add a new module
<ModuleSpecification Id="sample">ConsoleApplication1.exe</ModuleSpecification>
3. Add a diagnostic event specification
We're going to query the parameter color in the method PrintColor.

<DiagnosticEventSpecification>
    <CategoryId>enumSample</CategoryId>
    <SettingsName _locID="settingsName.ConsoleApplication.PrintColor">PrintColor (Color)</SettingsName>      
    <SettingsDescription _locID="settingsDescription.ConsoleApplication.PrintColor">
       Print the color
    </SettingsDescription>
    <Bindings>
        <Binding>
            <ModuleSpecificationId>sample</ModuleSpecificationId>
            <TypeName>ConsoleApplication1.Program</TypeName>
            <MethodName>PrintColor</MethodName>
            <MethodId>ConsoleApplication1.Program.PrintColor(System.Int32):System.Void</MethodId>
            <ShortDescription _locID="shortDescription.PrintColor.Color">Print Color "{0}"</ShortDescription>
            <LongDescription _locID="longDescription.PrintColor.Color">
                Going to print the color in integral value "{0}"
            </LongDescription>
            <DataQueries>
                <DataQuery index="0" type="Int32" name="color" query=""
                    _locID="dataquery.PrintColor.Color" _locAttrData="color"></DataQuery>
            </DataQueries>
        </Binding>
    </Bindings>
</DiagnosticEventSpecification>

Save the file and restart VS. The custom event shows in Tools/Options/IntelliTrace/IntelliTrace Events

IntelliTrace Event Options screenshot

When I debug the program, the custom event appears in the Events table. Look at the description! It shows me the integral value of the enum value. VS Events tab screenshot

How simple it is to add a custom IntelliTrace event! This is helpful to diagnose a piece of code path that're prone to error in changes. When you have your own collection plan for the program, you can just debug the program and let it run, and spot the error from the Events table.

Customize IntelliTrace to Collect Enums

Leave a comment

Cancel reply