The Windows Communication Foundation (WCF) is Microsoft’s approach to service-oriented architectures and allows you to easily built client/server and distributed applications with .NET. SmartInspect can be used to debug applications that make use of WCF and this article (and the attached demo project) explains how to do this. The demo application is based on Microsoft’s WCF tutorial, so if you haven’t worked with WCF before, the tutorial is a good way to start.

The service application

The service application that is part of the demo project exposes a simple service that offers various calculation methods (add, subtract, multiply, and divide). We use SmartInspect to log the method execution, parameters and results:

class CalculatorService : ICalculator
{
	public double Add(double n1, double n2)
	{
		SiAuto.Main.EnterMethod(this, "Add({0},{1})",
			new object[] {n1, n2});
		double result = n1 + n2;
		SiAuto.Main.LogValue("Result", result);
		SiAuto.Main.LeaveMethod(this, "Add");
		return result;
	}

	// [..]
}

The client application

The client application connects to the service and uses the exposed methods to calculate various results. The client application is also instrumented with SmartInspect log calls and logs the calculation results returned from service:

static void Calculate(CalculatorClient client)
{
	SiAuto.Main.EnterMethod("Program.Calculate");

	// Call the Add service operation
	double value1 = 100.00D;
	double value2 = 15.99D;
	double result = client.Add(value1, value2);
	SiAuto.Main.LogMessage("Add({0},{1}) = {2}", value1, value2, result);

	// [..]

	SiAuto.Main.LeaveMethod("Program.Calculate");
}

Debugging with the SmartInspect Console

When you launch both demo applications, the SmartInspect Console automatically receives the log messages via named-pipes (make sure to start Visual Studio as administrator, as this is required by WCF to register the service). You can also redirect the logging data to log files or other protocols by setting the connection string accordingly.

The SmartInspect Console makes it easy to see the log messages and data in context or to separate the log messages of the client and service. The Console also helps with tracking the involved threads and processes (e.g. you can see in the screenshot that .NET starts and recycles two threads to serve the four service calls).

Log messages of the client and service in the SmartInspect Console

Tracing WCF

WCF also has some tracing and logging capabilities of its own. This allows you to trace the messages and packets WCF sends and receives. Inspecting the exchanged messages is especially useful if you need to debug interoperability issues with other platforms and frameworks. WCF uses .NET’s built-in tracing API to log messages and packets.

Fortunately, SmartInspect makes it easy to receive .NET debug messages as it comes with a custom trace listener. To redirect WCF diagnostic messages to SmartInspect, simply add the Gurock.SmartInspect.DebugTrace assembly as a reference to your project and add the following code to the App.config (the demo projects already come with all the required bits pre-configured; you just need to uncomment the config settings):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.diagnostics>
    <sources>
      <source name="System.ServiceModel.MessageLogging" >
        <listeners>
          <clear />
          <add name="SmartInspect"
              type="Gurock.SmartInspect.DebugTrace.SmartInspectTraceListener,        Gurock.SmartInspect.DebugTrace" />
        </listeners>
      </source>
    </sources>
  </system.diagnostics>
  <system.serviceModel>
      <diagnostics>
        <messageLogging
             logEntireMessage="true"
             logMalformedMessages="true"
             logMessagesAtServiceLevel="true"
             logMessagesAtTransportLevel="true"
             maxMessagesToLog="3000"
             maxSizeOfMessageToLog="2000"/>
      </diagnostics>
    </system.serviceModel>
</configuration>

The full demo application will be included in the next SmartInspect release, but you can also download a copy of the demo project from this site in the meantime.

Michael Baarz recently emailed us as he was a looking for a modern .NET logging tool for his company’s complex telecommunication and PBX software. Michael was about to redesign his company’s flagship product and was planning to use Microsoft’s dependency injection framework Unity.

He told us that he really enjoyed working with SmartInspect and because Unity also supports some aspect oriented programming features, Michael decided to write an unofficial library to integrate SmartInspect with Unity so he could benefit from this useful combination. This posting introduces Michael’s library and will explain how to get started with the extension to integrate and benefit from SmartInspect and Unity.

Unity, a dependency injection container

Unity is Microsoft’s dependency injection container and framework and is part of their Patterns & Practices initiative. If you are new to dependency injection in general, I recommend taking a look at this article by Martin Fowler that explains the basic concepts and benefits. Besides common dependency injection features, Unity also supports aspect oriented programming by allowing you to intercept and wrap method calls.

The big difference between dependency injection (DI) frameworks and classic AOP tools such as PostSharp is that DI frameworks are configured at run-time, whereas PostSharp injects and builds its aspects at compile time. Both approaches have their pros and cons, so it really depends on the circumstances which one you should use (DI frameworks are usually more flexible as you can change the behavior at run-time, whereas ‘classic’ AOP tools support more features and are usually faster).

Using the SmartInspect Unity Interception Extension

Michael’s library to integrate SmartInspect and Unity is called the SmartInspect Unity Interception Extension and can be downloaded from CodePlex. To get started with the library, either check out the source code via Subversion or download one of the releases (there wasn’t a release at the time of this writing yet).

To use the library in your solution, you first need to add a few assembly references to your projects. First of all, you need to reference the Microsoft.Practices.Unity and Microsoft.Practices.Unity.Interception assemblies; these are part of Unity and are automatically installed and registered when you download and install Unity. The next assembly reference you need to add is Gurock.SmartInspect, as this is required to use SmartInspect logging. Last but not least you need to add Michael’s SmartInspect.Extensions.Unity assembly as a reference to your project, either by adding a reference to the compiled DLL or by adding the project to your solution and using a project reference.

Tracing method execution

One of the more useful aspects (no pun intended) of AOP is the capability to easily trace method execution, so this is the first thing I’m going to demonstrate. Unity is a dependency injection framework so we will need to properly register and instantiate all classes we want to intercept for logging. The first thing we need to do is to define the interface for the class we want to instantiate through Unity. Because one of the design goals of DI is that we can easily replace the actual implementation for an interface, using interfaces is mandatory here. For our Hello, World example, I’ve defined an interface and implementation class:

interface IHello
{
	int Count { get; set; }
	void SayHello(string name);
	string SayGoodbye(string name);
	void RaiseException(string name);
}

The actual implementation already makes use of SmartInspect to log various messages:

class Hello : IHello
{
	public int Count { get; set; }

	public void SayHello(string name)
	{
		SiAuto.Main.LogMessage("Hello, {0}.", name);
	}

	public string SayGoodbye(string name)
	{
		string msg = String.Format("Goodbye, {0}.", name);
		SiAuto.Main.LogMessage(msg);
		return msg;
	}

	public void RaiseException(string name)
	{
		SiAuto.Main.LogMessage("Hello, {0}.", name);
		throw new Exception("This is a test exception");
	}
}

Now to intercept and trace the method calls, we first need to make sure that we register and instantiate the interface and implementation with Unity. To do this, we use an instance of UnityContainer and add and configure the Interception extension. Here’s the full Main method of our example program:

static void Main(string[] args)
{
	// Enable SmartInspect logging
	SiAuto.Si.Enabled = true;

	// Create the Unity dependency injection container,
	// register the Interception extension and register our
	// our example class
	IUnityContainer container = new UnityContainer();
	container
		.AddNewExtension<Interception>()
		.RegisterType<IHello, Hello>();

	// Now tell Unity how to intercept IHello method calls
	container.Configure<Interception>()
		.SetInterceptorFor<IHello>(new TransparentProxyInterceptor());

	// Instead of creating our Hello class directly, we ask
	// Unity to resolve the dependency for the IHello interface
	IHello hello = container.Resolve<IHello>();

	// Call The IHello methods and assign property values
	hello.SayHello("World");
	hello.SayGoodbye("World");

	Random r = new Random();
	for (int i = 0; i < 10; i++)
	{
		hello.Count = r.Next(100);
		Thread.Sleep(1000);
	}

	hello.RaiseException("Hello World");
}

Now to actually use the the SmartInspect Unity extension and trace method calls, we just need to add a single attribute to the interface, namely the [SiMethodCall] attribute (which can be found in the SmartInspect.Extensions.Unity namespace):

[SiMethodCall]
interface IHello
{
	// [..]
}

The attributes come with various properties to influence the behavior of the log calls, such as changing the log level, adding name prefixes/suffixes and so on. For a complete list of properties just see the Intellisense help within Visual Studio. Once we launch the example application, we see the following output in the SmartInspect Console (also take a look at the viewer toolbox at the bottom right of the window, it shows the method arguments of the selected log entry):

Log messages and method tracing in the SmartInspect Console

Logging exceptions

Logging occurred exceptions is another useful thing you can automate with AOP. The SmartInspect Unity extension comes with its own attribute to log exceptions, namely the [SiException] attribute. The attribute doesn’t handle the exceptions (it just logs them) so it doesn’t change the behavior of your code. To use the attribute, just specify it for an interface or method like this:

[SiException(LogArgumentsToViewer = true)]
interface IHello
{
	// [..]
}

The resulting log messages in the SmartInspect Console look like this:

Logged exception in the SmartInspect Console

Watching property values

SmartInspect allows you to easily log and watch field and property values. The SmartInspect Unity extension comes with an attribute to automatically log changes of properties as they occur. To benefit from this, simply add the [SiWatch] attribute to the set method of your properties:

interface IHello
{
	int Count { get; [SiWatch]set; }
}

This blog posting is intended to give you an overview of the capabilities the SmartInspect Unity extension library provides, but it cannot explain all the useful options and features that the library comes with. So to get started with the library and learn about all its capabilities, I recommend downloading it and start playing with it.

Please also note that the SmartInspect Unity extension introduced here is not a Gurock Software product and is not official supported by us. To send feedback and to contribute to the project, please take a look at the CodePlex project page. Thanks Michael for writing the library and for contributing to the SmartInspect ecosystem!

Our PostSharp aspect library has a new home: SmartInspect for PostSharp

There are various AOP frameworks available for each of the three platforms SmartInspect supports, so why did we decide to start with PostSharp for the first part of this blog series about apsect-oriented logging? PostSharp has become the de-facto standard AOP framework for .NET and there are many things to like about PostSharp:

• PostSharp is really easy to use. It integrates nicely with MSBuild (and therefore Visual Studio) and you just need to complete the PostSharp setup and are good to go.
• It provides different APIs depending on what you are trying to accomplish. You can use a low-level API for injecting snippets of MSIL code for complexer tasks (PostSharp.Core) or a very simple high-level API (PostSharp.Laos) to develop aspects with custom .NET attributes.
• It’s very well documented. The APIs are fully documented and there are getting started tutorials, videos, a plugin repository and lots more. Can’t get a lot better than that.
• It’s a compile-time AOP framework. Unlike other tools which inject the AOP code at runtime, it post-processes the assemblies directly after compliation which is more efficient and allows for more flexibility.
• Last but not least, some SmartInspect customers were already successfully using PostSharp in their applications and told us that they liked the combination of both tools (that’s how we became aware of PostSharp in the first place).

We will be using the simpler Laos API for our SmartInspect PostSharp aspects, as we found it sufficient for all our needs. The resulting library is able to automatically trace method execution, log exceptions and watch changes of field variables. The library comes with three aspects for the different tasks, each implemented as a custom .NET attribute.

Using the SmartInspect aspects

The general procedure of using a PostSharp aspect is to install the PostSharp framework and to add the PostSharp.Public and PostSharp.Laos assembly references to your application. PostSharp injects itself into the MSBuild build process and automatically processes all assemblies that reference PostSharp.

For our logging aspects, you further need to add references to the Gurock.SmartInspect and Gurock.SmartInspect.PostSharp assemblies (the logging library and PostSharp aspects, respectively). The logging library is included in the SmartInspect trial download and the SmartInspect AOP plugin can be downloaded from the SmartInspect resources page.

Tracing method execution

The first aspect I am going to demonstrate is for tracing method execution. This aspect makes it really easy to generate a complete call trace of your application, showing you the entire application flow and letting you inspect stack traces at each execution point. It automatically generates two log messages for each method call: one for entering a method and one when a method exits. You can also log the passed method arguments (when entering a method) and the method result (when exiting a method), respectively.

To use this aspect, simple add the SiTrace custom attribute to your application as follows (note how you can continue to use SmartInspect for complementary log messages, of course):

using System;
using Gurock.SmartInspect;
using Gurock.SmartInspect.PostSharp;

[assembly:SiTrace(SessionName="Main")]

namespace Gurock.SmartInspect.PostSharp.Samples
{
	class Program
	{
		static void Main(string[] args)
		{
			SiAuto.Si.Enabled = true; // Enable logging
			Hello("World");
			Goodbye("World");
		}

		static void Hello(string name)
		{
			SiAuto.Main.LogMessage("Hello, {0}.", name);
		}

		static string Goodbye(string name)
		{
			string msg = String.Format("Goodbye, {0}.", name);
			SiAuto.Main.LogMessage(msg);
			return msg;
		}
	}
}

The attribute can be specified on a per-class/per-method basis or, like in our example, for the entire assembly. You can further specify filters for including/excluding certain modules/classes (called attribute targets in the PostSharp terminology), set aspect priorities (useful with nested aspects) and much more.

Our aspects have a few additional SmartInspect-related options. First, as you can see in the example above, you can set the session name used for sending log messages. If you do not want a hard-coded session name, you can tell the aspect to make use of the logging context and automatically adjust the name based on the current namespace or class. You can do so by setting a so called session policy. For example, to automatically use a session name that equals the name of the current class context, you can use a session policy of SessionPolicy.TypeName and omit the session name:

...
[assembly:SiTrace(SessionPolicy=SessionPolicy.TypeName)]
...

There are additional options for including the method arguments (IncludeArguments) and method return value (IncludeReturnValue). With both options enabled, the resulting log looks as follows in the SmartInspect Console (SmartInspect’s viewer application). Note how the automatic enter/exit messages are mixed with the manual log messages:

The SiTrace sample log shown in the SmartInspect Console

Logging exceptions

Another typical use-case for logging is recording all occurring exceptions and this is usually done by adding log calls to your exception handlers. Adding log statements to all your exception handlers can get tedious and error-prone though (e.g., you could forget to rethrow the exception after logging it), so we’ve added an aspect to automate this task for you. To use it, just add the SiException attribute to your code:

using System;
using Gurock.SmartInspect;
using Gurock.SmartInspect.PostSharp;

...

[assembly: SiException(SessionName="Main")]

...

		static void Hello(string name)
		{
			SiAuto.Main.LogMessage("Hello, {0}.", name);
			throw new Exception("This is a test exception");
		}

...

Note how the exception is now automatically included in the resulting log (within the expected method context):

The SiException sample log shown in the SmartInspect Console

Watching field values

Arguably the most advanced aspect in this library is the SiField attribute. This attribute lets you automatically record any changes to values of object or class fields. The aspect gets notified whenever the value of a field changes and then logs the name of the field along with its old and new value. You can configure whether the aspect should send the name and values as normal log messages or as SmartInspect watches (for showing the latest values of a variable in the watches toolbox or for displaying its history as a chart in the watches graph). By default, both watches and normal messages are logged.

Let’s have a look at the following example which demonstrates SiField in practice. Note how we use SiField as an attribute for the entire assembly again. We could also limit it to individual classes or fields, either by writing the attribute above the classes/fields we want to inspect or by specifying filters/attribute targets for the global attribute.

using System;
using Gurock.SmartInspect;
using Gurock.SmartInspect.PostSharp;

[assembly: SiField(SessionName = "Main")]

namespace Gurock.SmartInspect.PostSharp.Samples
{
	class Program
	{
		public static int FIELD;

		static void Main(string[] args)
		{
			SiAuto.Si.Enabled = true; // Enable logging
			Counting();
		}

		static void Counting()
		{
			Random r = new Random();

			for (int i = 0; i < 10; i++)
			{
				FIELD = r.Next(100);
				Thread.Sleep(1000);
			}
		}
	}
}

And here’s the generated log in the SmartInspect Console:

The SiField sample log shown in the SmartInspect Console

As you can see, every field change is automatically logged and shown in the Console. The watches toolbox in the lower left of the Console displays the latest value of FIELD in addition to the normal log messages in the main view. Also note the watches graph on the right that displays the field’s history as a chart (with its values over time). I believe an upcoming version of PostSharp will also be able to watch properties and we will update our library accordingly when this feature is available.

The nice thing about these aspects is that they can be freely combined as you like. You can mix and match the aspects as needed. If you plan to use our aspects and library, I also recommend taking a look at the PostSharp documentation for more details about aspects, AOP and PostSharp in general as well as how to configure PostSharp for more complex scenarios.

Feel free to send me an email or leave a comment on this blog in case you have any questions about this plugin.

Unfortunately, Delphi never had good (built-in) run-time support for stack traces. The features for stack traces during debugging in the IDE are/were okay, but there were nothing in the language or framework which helped you to find out programmatically where an exception occurred at run-time and, more importantly, how it got passed to your exception handler (besides the original exception address, maybe). So, I was happy to see that Delphi 2009 finally introduced a new StackTrace property which, I hoped, would return a full-blown stack trace when you caught an exception.

The initial happiness soon wore off when I realized that the StackTrace property was really just a placeholder to return a stack trace from a possible stack trace provider rather than a real stack trace implementation. So, without such a provider (and there’s none that comes directly with Delphi), there is still no way to get a stack trace for your exceptions. Though a bit disappointing, the good thing is that there’s now finally a standardized way to get a stack trace, even if it’s not implemented by default.

Exception reporting tools such as Eurekalog or madExcept or debug helpers such as the JclDebug unit can register themselves as providers and use their engines to return a stack trace when an exception is raised. I’ve built a small unit which demonstrates this with the Jcl in combination with our logging tool SmartInspect and I’ve heard Fabio of Eurekalog is working on a similar feature for his component:

unit StackTrace;

interface

uses
  SysUtils, Classes, JclDebug;

implementation

function GetExceptionStackInfoProc(P: PExceptionRecord): Pointer;
var
  LLines: TStringList;
  LText: String;
  LResult: PChar;
begin
  LLines := TStringList.Create;
  try
    JclLastExceptStackListToStrings(LLines, True, True, True, True);
    LText := LLines.Text;
    LResult := StrAlloc(Length(LText));
    StrCopy(LResult, PChar(LText));
    Result := LResult;
  finally
    LLines.Free;
  end;
end;

function GetStackInfoStringProc(Info: Pointer): string;
begin
  Result := string(PChar(Info));
end;

procedure CleanUpStackInfoProc(Info: Pointer);
begin
  StrDispose(PChar(Info));
end;

initialization
  // Start the Jcl exception tracking and register our Exception
  // stack trace provider.
  if JclStartExceptionTracking then
  begin
    Exception.GetExceptionStackInfoProc := GetExceptionStackInfoProc;
    Exception.GetStackInfoStringProc := GetStackInfoStringProc;
    Exception.CleanUpStackInfoProc := CleanUpStackInfoProc;
  end;

finalization
  // Stop Jcl exception tracking and unregister our provider.
  if JclExceptionTrackingActive then
  begin
    Exception.GetExceptionStackInfoProc := nil;
    Exception.GetStackInfoStringProc := nil;
    Exception.CleanUpStackInfoProc := nil;
    JclStopExceptionTracking;
  end;
end.

The unit merely starts and stops the exception tracking of the Jcl, implements a minimal stack trace provider and registers for the Exception provider events. The GetExceptionStackInfoProc and CleanUpStackInfoProc functions are automatically called by the RTL to give the provider the opportunity to initialize and cleanup the stack trace after an exception occurred. GetStackInfoStringProc is called indirectly when you access the StackTrace property and is responsible for returning the actual stack trace.

So, how do you use this unit? Let’s have a look at the following example:

...

uses
  ..., StackTrace;

type
  TForm1 = class(TForm)
    Button1: TButton;
    procedure Button1Click(Sender: TObject);
  private
    procedure SomeMethod;
  end;

implementation

procedure TForm1.Button1Click(Sender: TObject);
begin
  try
    SomeMethod;
  except
    // Log the exception: We use SmartInspect here because it has
    // built-in support for Exception.StackTrace but you could also
    // access the StackTrace property here directly.
    SiMain.LogException;
  end;
end;

procedure TForm1.SomeMethod;
begin
  raise Exception.Create('A test exception');
end;

...

As you can see, using this unit is just a matter of adding it to our uses clause. It won’t get any simpler than that. The unit will take care of registering/unregistering itself as a stack trace provider and when you now access the StackTrace property of an Exception object, you will get a detailed stack trace. To include the method names and line numbers in the stack trace, make sure to let the linker include debug symbols into your application and to enable the ‘Use debug .dcus’ option in case you also want line numbers from the VCL and RTL methods.

The SmartInspect Console showing the stack trace of an exception

Now, when you use SmartInspect for logging and have a stack trace provider registered, all your logged exceptions automatically include the exception’s call stack. Pretty useful, isn’t it?

SmartInspect SQLite log viewed in SQLiteSpy

The logging protocol automatically creates and initializes a new SQLite database on its first use, making it very easy to deploy application with it. All SmartInspect packets such as log entries, watches and process flow entries are supported and stored in the resulting SQLite database. Please note that the protocol has been written for Delphi 2009, but there are only a few changes required if you want to use it with an older Delphi version. Update: The protocol works with multiple Delphi versions out of the box, including Delphi 2007 and Delphi 2009.

Until our upcoming new website with a more useful SmartInspect resources section has been launched (scheduled for next month), you can download David’s protocol here:

Download (5 KB)

The example project demonstrates how to attach an event handler to madExcept and add a SmartInspect log file to madExept’s crash report whenever an unhandled exception occurs:

uses
  madExcept;

// [...]

procedure ExceptionHandler(const ExceptIntf: IMEException;
    var Handled: Boolean);
const
  ZIPFILE = 'CrashReport.zip';
var
  LStream   : TFileStream;
  LTempPath : array[0..MAX_PATH+1] of Char;
  LFileName : String;
begin
  Handled := False;

  { Get a temporary filename }
  if GetTempPath(MAX_PATH, LTempPath) = 0 then
    Exit;

  // Save madShi's bug report information in the log.
  SiMain.LogException(Exception(ExceptIntf.ExceptObject),
    'Madshi Exception Handler');
  SiMain.LogString('BugReport', ExceptIntf.BugReport);

  ExceptIntf.AdditionalAttachments.Clear;

  { Put everything in a zip file }
  ExceptIntf.ScreenShotZip := ZIPFILE;
  ExceptIntf.BugReportZip  := ZIPFILE;

  { Just some extra optional information }
  ExceptIntf.AdditionalFields.Add('Application',
    Application.Title);

  LFileName := IncludeTrailingPathDelimiter(LTempPath) +
    'CrashLog.sil';
  { Save the log file }
  LStream := TFileStream.Create(LFileName, fmCreate);
  try
    Si.Dispatch('mem', 0, LStream);
  finally
    LStream.Free;
  end;

  { Attach the file to madShi's crash report }
  ExceptIntf.AdditionalAttachments.Add(LFileName, '', ZIPFILE);
end;

initialization
  RegisterExceptionHandler(ExceptionHandler,
    stTrySyncCallOnSuccess);
end.

The resulting madExcept email and crash report zip file includes a SmartInspect log file with the recent user actions and application data, along with madExcept’s error report and screenshot:

If you are already using madExcept and are planning to integrate it with SmartInspect (or the other way around), Jeremy’s example code is a great starting point and should get you up and running in a few minutes. You can download the example code here and learn more about the used techniques in the related EurekaLog article.