Extending Mole 2010’s Reach – Mole Type Loader

Since the first version of Mole was released in December 2007, the number one support question has been, “I installed Mole but I can’t start it; how do I start Mole?” With the launch of Mole 2010, this has not changed.

When are Types are Listed in a Data Tip?

An important distinction that causes some confusion with visualizers is, “Mole can visualize any type, however not all types are registered with Visual Studio to launch the Mole visualizer.”  In order for Visual Studio to launch a visualizer, the visualizer must be listed in a Data Tip for a type at a break point.

All versions of Mole have been able to visualize any .NET type.  Internally, Mole works with System.Object.  It’s this capability of Mole that allows it to drill around the managed heap, displaying information at debug-time about your application’s types because all types are internally treated equally.

When a debugging sessions begins, Visual Studio reflects all .dll assemblies located in the two well known visualizer folders and builds a cache of types specified in the DebuggerVisualizer attributes that decorate these  assemblies.

The well know visualizer folder locations are:

• {Visual Studio 2010 install location}\Microsoft Visual Studio 10.0\Common7\Packages\Debugger\Visualizers
• {User Documents folder}\Visual Studio 2010\Visualizers

Visual Studio uses the type and visualizer specified the DebuggerVisualizer attribute to build a cache of types and the visualizers that can visualizer specified types.  In many cases, registering a base type using the DebuggerVisualizer attribute will cause Visual Studio to associate the base type and all super types, but not in all cases.

The below code snippet shows how the generic List<T> or List(Of T) is registered with Visual Studio, specifying Mole as the visualizer.  This attribute, along with many others decorates the Mole 2010 visualizer assembly.

[assembly: System.Diagnostics.DebuggerVisualizer(
        typeof(Mole.EntryPoint),
        typeof(Mole.BackEnd.MoleVisualizerObjectSource),
        Target = typeof(System.Collections.Generic.List<>),
        Description = "Mole 2010")]

When at a breakpoint, hovering over a variable will bring up the Data Tip and any visualizers that have registered for this type will be listed as in the image below.

Selecting the Mole 2010 visualizer will launch Mole pictured below.

As you can see, there is a direct correlation between the types registered in visualizer assemblies and the types that have a visualizer listed in the Data Tip.

Mole 2010 version 1.2 ships with 1801 DebuggerVisualizer attributes decorating the Mole visualizer assembly.  All of the 1801 types registered with Mole 2010 are all .NET Framework types.

So the question is, how can a developer launch Mole for a type that does not have a specified type?

System.WeakReference Wrapper Technique

The below screen shot is taken from the Mole 2010 Read Me page.

Extending Mole 2010’s Reach by Registering Your Types With Visual Studio

Using the above WeakReference technique is a good solution for one-off types you would like to visualize.  But what about types you need to visualize on a daily basis that are not part of the 1801 types pre-registered by Mole?  For example Prism types, Enterprise Library types or types in frameworks that you develop.

I have been thinking about this problem for a while now and did a spike last week to prove that an assembly could register types for another visualizer assembly.

The below image shows the installation location for my copy of Mole 2010 that has the 1801 DebuggerVisualizer attributes.

The below image shows the location of an assembly that has many DebuggerVisualizer attributes that specify types that I want to have a Data Tip for that lists the Mole 2010 visualizer.

The below image shows the Mole Type Loader UI.  This utility program allows developers to select .NET assemblies and have their types used to create the above custom type loader .dll.  From the list on the left, you can see I’ve elected to load up the Prism and Ocean assemblies and have their types registered with Visual Studio. 

The reason the custom type loader .dll file is under the Documents folder instead of the Visual Studio installation folder is because of write permissions.  Users have write permissions under their Documents folder but not under Program Files without changing permissions.  Also, I didn’t want to have the executable in a different folder than the data file.  Of course, you can modify the code to change the location of the data file if you want.

The below code snippet is from the generated custom type loader assembly.

[assembly: System.Diagnostics.DebuggerVisualizer(
    "Mole.EntryPoint, Mole.Visualizer.VS2010, Version=1.2.0.0, ...",
    "Mole.BackEnd.MoleVisualizerObjectSource, Mole.Visualizer.VS2010, Version=1.2.0.0, ...",
    TargetTypeName = "Ocean.DataGeneration.DataGenerator, Ocean",
    Description = "Mole 2010")]

As you can see in the below image, Visual Studio displays a Data Tip for the Mole 2010 visualizer when hovering over an Ocean DataGenerator variable while at a break point.

This was made possible by the above custom type loader .dll having the assembly decorated with a DebuggerVisualizer attribute that specified the DataGenerator and pointed to the Mole 2010 visualizer.

The Fine Print

Ok, it’s time for the fine print. 

First, although we have tested this utility program, this is an experiential technique for registering additional types (your types) with Visual Studio.  This is not part of the Mole 2010 offering nor is it supported by Molosoft.  If you have a question or issue, please leave a comment on this blog post.

Second, in order for this to work, Mole 2010 and associated assemblies must be installed in the GAC. See Requirements below.

Mole 2010 Type Loader

Purpose

Provides a utility application that can discover types in an assembly, store those types in a local data tile and then create a custom type loader .dll that contains DebuggerVisualizer attributes for each type that has been loaded.

Setup

I recommend that your perform a Release build of the Mole.TypeLoader project and then copy the files to a folder under your Documents folder structure.  This will allow the application to write its data file without a permissions issue.

Next, add the Mole.TypeLoader.exe application to your start menu for quick access.

Requirements

Important: You can’t have any active debug sessions running when running the Mole.TypeLoader.exe application.  Visual Studio locks the Mole.TypeLoader.exe output file during debugging sessions and you will not be able to create a new one while a debugging sessions is running.

There are four requirements or actions that must be followed otherwise you’ll get unexpected results. 

• Requires Mole 2010 version 1.2 or later.  See Molosoft news.
• All Mole 2010 assemblies must be installed into the GAC
• Each time a new version of Mole 2010 is installed you must:
  • Edit the Mole.TypeLoader.exe.config and update two settings
  • Run Mole.TypeLoader and execute the “Create Mole Types assembly” menu command

While not required by the Mole.TypeLoader application, all Mole 2010 .dll’s must be installed into the GAC so that when the Mole.Visualizer.VS2010.CustomTypeLoader.dll is created and the Mole visualizer is specified as the visualizer for the types, Visual Studio will be able to start the Mole 2010 visualizer.

This requirement is part of the above, “fine print.”  Despite the fact that that the Mole.Visualizer.VS2010.CustomTypeLoader.dll is located in a well known visualizers folder, its DebuggerVisualizer attributes specify an assembly by strong name, but not by the full path name.  Unless the Mole 2010 assemblies are in the GAC, the .NET Framework will not be able to locate and load the assemblies at debug time.  This is why the Mole 2010 assemblies must be installed into the GAC.

To install Mole 2010 assemblies into the GAC:

• Open a Visual Studio 2010 command prompt, be sure to “Run as administrator”
• Navigate to the folder where the Mole 2010 assemblies are installed and execute the following commands:
  • gacutil /i Mole.Visualizer.VS2010.dll
  • gacutil /i Microsoft.Licensing.Permutation_0e3eb_2.0.dll
  • gacutil /i Microsoft.Licensing.Runtime2.0.dll
  • gacutil /i Microsoft.Licensing.Utils2.0.dll

To uninstall Mole 2010 assemblies from the GAC:

• Open a Visual Studio 2010 command prompt, be sure to “Run as administrator”
• Navigate to the folder where the Mole 2010 assemblies are installed and execute the following commands:
• gacutil /u Mole.Visualizer.VS2010
• gacutil /u Microsoft.Licensing.Permutation_0e3eb_2.0
• gacutil /u Microsoft.Licensing.Runtime2.0
• gacutil /u Microsoft.Licensing.Utils2.0

Each time you install a new version of Mole 2010, you must update two settings in the Mole.TypeLoader.exe.config file, MoleAssemblyName and MoleObjectSource. 

You must ensure that the Version in the .config file matches the version of Mole 2010 you have installed.  The version can be viewed in the Mole 2010 About dialog, can be obtained by viewing the Mole 2010 visualizer assembly file properties in Windows Explorer, or can be viewed in Reflector.

<setting name="MoleAssemblyName" serializeAs="String">
    <value>Mole.EntryPoint, Mole.Visualizer.VS2010, Version=1.2.0.0, Culture=neutral, …
</setting>
<setting name="MoleObjectSource" serializeAs="String">
    <value>Mole.BackEnd.MoleVisualizerObjectSource, Mole.Visualizer.VS2010, Version=1.2.0.0, …
</setting>

The below Mole 2010 About dialog displays the version of Mole 2010 that is installed.

You can also right click on the Mole 2010 visualizer assembly and view the File version.  This matches the above Mole assembly Version.

If you forget to update the .config file or don’t run the Mole.TypeLoader.exe and create a new Mole Types assembly after updating the .config file, you’ll get an error dialog when you attempt to view a custom type that was loaded by the Mole.TypeLoader utility.

Mole.TypeLoader Command Line Mode

The Mole 2010 Type Loader can be used in two modes; command line or as a normal WPF application.

When used as a command line application the following command line parameter are supported:

• Mole.TypeLoader /?
  • This will display the command line usage in a console window
• Mole.TypeLoader {folder to load}
  • This command line will load types from all .dll and .exe files in the specified folder.  This feature is useful when you are developing a custom framework or custom application and you want all types in the framework or application to automatically be available to start Mole 2010.
  • This can easily be accomplished by adding a Post-build event like so:
    • {folder where Mole.TypeLoader.exe is}\Mole.TypeLoader $(TargetDir)
    • The $(TargetDir) is a Visual Studio build event macro that returns the output folder

The Mole Type Loader does not load types so re-running of the Mole.TypeLoader.exe as a post-build event will not cause any problems.

When used in command line mode, the Mole.TypeLoader will inspect each .dll and .exe assembly in the specified folder, load its types, save the data file and then create a new Mole.Visualizer.VS2010.CustomTypeLoader.dll.

If an error occurs during this processing, a MessageBox will display with the error information.  Using a MessageBox as opposed to outputting information to a console window allows a developer to see any problems when the application is being run as a post-build task in Visual Studio.

Mole.TypeLoader WPF Application Mode

When Mole.TypeLoader.exe is executed without any command line arguments the WPF version of the application executes.

If you select an assembly from the left side list box, the data grid will be filtered to only display types from that assembly.

When opened, types in the right side data grid will be sorted by AssemblyName and TypeName.  You can change sorting by clicking or SHIFT clicking on the data grid column headers.

The initial status bar message displays the version information from the .exe.config file so that you know what version of Mole the outputted assembly will be targeting.

You can also click on the hyperlink in the lower right corner to visit the Molosoft.com web site.

To remove one or more types, select the row in the data grid and press the Delete key.  To remove all types from a single assembly, select the assembly name in the left side list box, then select all types in the data grid and press the Delete key.

To add one or more assemblies, use the File menu and select, “Select assemblies to load.”  When the files dialog appears, navigate to the desired folder and select one or more .dll or .exe files to load types from.

To create a new Mole.Visualizer.VS2010.CustomTypeLoader.dll assembly, use the File menu and select, “Create Mole Types assembly.”

If you add or remove types and forget to create the assembly, it will automatically be created for you.

Application Settings in Mole.TypeLoader.exe.config

LastFolder – this saves the last folder that assemblies were load from.  No reason to change this value.

OutputAssemblyName – this is the name of the assembly that will created that contains the DebuggerVisualizer attributes for all loaded types.  No reason to change this value.

OutputFolderName – this is the folder name where the assembly is outputted.  If this setting is blank (the default) the Mole.Visualizer.VS2010.CustomTypeLoader.dll will be outputted to {Documents}\Visual Studio 2010\Visualizers folder. 

If you change this setting to output to the {Visual Studio 2010 install location}\Microsoft Visual Studio 10.0\Common7\Packages\Debugger\Visualizers folder, you must ensure that you set write permissions on the file, otherwise write errors will occur.

MoleAssemblyName – this is the entry point and the Mole 2010 assembly strong name.  This value will need to be updated each time a new version of Mole 2010 is installed.  You should only have to update the Version as described above.

MoleObjectSource – this is the object source and the Mole 2010 assembly strong name. This value will need to be updated each time a new version of Mole 2010 is installed. You should only have to update the Version as described above.

MoleDescription – this is the visualizer name that will appear in the Data Tip. No reason to change this value.

DataStoreFileName – this is the name of the file that the Mole.TypeLoader.exe saves its data to.   No reason to change this value.

Downloads

Mole Type Loader Source (295KB) can be downloaded from my Sky Drive.

Close

I realize there are a few moving parts to this solution.  However, once set up, its very easy to maintain and easily add and remove types from the custom types assembly that is created.

Feedback welcome.

Have a great day,

Just a grain of sand on the worlds beaches.