This lose series of articles will cover the implementation of a file system façade that allows transparent remote file system access in VFS.

The series will cover the following topics:

• Introduction and basic concept (this article)
• Implementing a RESTful file system proxy service with OpenRasta (coming soon)
• Unit testing the OpenRasta proxy service (not yet published)
• General tutorial: Streaming binary data in Silverlight
• Implementing VFS client libraries for both .NET and Silverlight (not yet published)

VFS File System Providers

VFS abstracts access to arbitrary file systems through so-called “File System Providers”, which expose a common interface (IFileSystemProvider) that allows you to browse and modify the file system. The interface is not exactly lean, but easy to understand:

Now, common file system providers directly operate on some kind of hierarchical data. Here’s a few examples:

• The “Local File System Provider” allows you to access your local machine, or the contents of a dedicated directory.
• The “ZIP File System Provider” works upon a single ZIP file, and allows you to transparently access and modify its contents.
• An “FTP File System Provider” connects to a given FTP server and gives you access to the server’s files through the VFS API.
• …

So basically, an application uses a VFS provider, which in turn directly accesses the exposed file system:

Tunneling Façades

There is, however, a special family of file system providers that do not access any files. Instead, they forward file system requests to another file system provider, thus creating a tunnel to another file system. Basically, these file system providers are façades to another, arbitrary file system provider.

Here’s an exemplary scenario that uses a façade in order to access a ZIP file that is exposed through a ZIP file provider (click on the UML diagram in order to see it in full size).

The interesting point here: From the client’s perspective, there is no difference in accessing the file system. The façade itself implements the IFileSystemProvider interface – it provides exactly the same API as any other provider.

As you can see from the diagram above, a façade is usually complemented by some kind of proxy that receives the forwarded requests, so in order to implement the pattern, there’s two components to be written:

1. The façade, which implements IFileSystemProvider.
2. The proxy that takes the forwarded requests, forwards them its own file system provider, and eventually returns the requested data. This proxy is not a VFS component, and you don’t have to implement any VFS interfaces.

As you can guess, tunnels come in handy in order to access remote data. Here’s a few scenarios:

• Run a local file system provider on a server that provides a download service. Clients don’t have direct access to the files, but use a tunnel to access the files that are exposed through the provider that runs on the server.
• Allow a Silverlight client to browse the contents of a ZIP file on the server, without having to download the whole ZIP file first (sample coming).
• Host a cloud file system provider within a WCF service, and expose parts of the cloud’s data to clients. Like this, clients don’t have direct access to the cloud data.

A RESTful Façade Implementation

Every façade itself is an independent file system provider – so tunneling is rather a pattern than an API, and you can write your own façade should you wish to (actually, contributions will be most welcome!).

However, VFS 1.0 will ship with a single façade implementation that uses HTTP/REST to create a tunnel to a remote file system. It is built upon the following libraries:

• On the server side, OpenRasta was used to expose file system access as RESTful services. OpenRasta is a lightweight, but powerful framework that comes with a API.
• On the client side, the WCF REST Starter Kit was used for both .NET and Silverlight clients (the Silverlight library hacked together by myself). The starter kit’s client libraries allow for simple access to RESTful resources, even if there is no WCF involved.

The upcoming articles will walk you through the implementation of the both the client and service libraries, and will also be complemented by a preview release of VFS. Stay tuned

Here’s a sample for a simple GET using the HttpClient class:

public User GetUser(string userId)
{
  //init client with base URI
  HttpClient client = new HttpClient(http://localhost:56789/users/);

  //send a HTTP GET request for a given resource
  HttpResponseMessage response = client.Get(userId);

  //parse the received data on the fly
  return response.Content.ReadAsDataContract<User>();
}

Or, in order to send a DTO via HTTP POST:

public void PostUser(User user)
{
  //init client with base URI
  HttpClient client = new HttpClient("http://localhost:56789/");

  //serialize user object
  HttpContent content = HttpContentExtensions.CreateDataContract(user);

  //post to user service
  HttpResponseMessage response = client.Post("/user", content);
}

I have removed a few bits, but most of the functionality should be there, and I added “NOTE” comments to all the sections that I had to modify. I haven’t used this port in-depth but managed to access my RESTful resources as expected so far, and I hope it will work just fine as in most scenarios that are covered in the original Starter Kit. Of course, given the Starter Kit itself is prerelease software, this applies to this release even more.

Blocking vs. Async Operations

If you try to initiate a blocking request to your REST service on the UI thread, an InvalidOperationException is thrown due to synchronization issues. Accordingly, a snippet as the one above should always be invoked on a worker thread (which is a best practice anyway).

However, in order to simplify things, I’ve added a bunch of XXXAsync extension methods for the HttpClient class that allow you to invoke HTTP operations such as GET, POST, PUT etc. directly on the UI thread, and have the result delivered back to you through a simple callback action. Here’s the same snippet as above, this time using the GetAsync method of the HttpClient class:

public void GetFolder()
{
  HttpClient client = new HttpClient("http://localhost:56789/root");

  //you can invoke the GetAsync method on a worker thread
  client.GetAsync(response =>
    {
      VirtualFolder folder = response.Content.ReadAsDataContract<VirtualFolder>();
    });
}

Note that the callback action will be invoked on a worker thread, so you might have to switch back to the UI thread if you want to modify your UI.

Oh yes: Use at your own risk

Download REST Starter Kit for Silverlight

Current Version: 1.0.3, 2010.02.14

This makes sense if the response is requested on the UI thread (otherwise, it would freeze the UI), but it might be a problem in certain scenarios (e.g. if you want to submit multiple requests in an orderly fashion).

However, you can get around the issue by using wait handles, which allow you to easily block a running operation. I encapsulated the required functionality in a simple extension method that brings GetResponse method back into Silverlight.

The usage is simple – you just invoke the GetResponse() extension method with an optional timeout. Here’s a sample that submits five synchronous HTTP requests:

private void RunRequests()
{
  for (int i = 0; i < 5; i++)
  {
    Uri uri = new Uri("http://localhost/users?user=" + i);
    HttpWebRequest request =
      (HttpWebRequest)WebRequestCreator.ClientHttp.Create(uri);

    //get response as blocking operation which times out after 10 secs
    HttpWebResponse response = request.GetResponse(10000);
  }
}

You will run into timeout issues if you run execute this method on the UI thread because internally, the requested response accesses the UI thread (for whatever reasons). Only invoke this extension method on background threads!

Here’s the implementation:

public static class RequestHelper
{
  /// <summary>
  /// A blocking operation that does not continue until a response has been
  /// received for a given <see cref="HttpWebRequest"/>, or the request
  /// timed out.
  /// </summary>
  /// <param name="request">The request to be sent.</param>
  /// <param name="timeout">An optional timeout.</param>
  /// <returns>The response that was received for the request.</returns>
  /// <exception cref="TimeoutException">If the <paramref name="timeout"/>
  /// parameter was set, and no response was received within the specified
  /// time.</exception>
  public static HttpWebResponse GetResponse(this HttpWebRequest request,
                                            int? timeout)
  {
    if (request == null) throw new ArgumentNullException("request");

    if (System.Windows.Deployment.Current.Dispatcher.CheckAccess())
    {
      const string msg = "Invoking this method on the UI thread is forbidden.";
      throw new InvalidOperationException(msg);
    }

    AutoResetEvent waitHandle = new AutoResetEvent(false);
    HttpWebResponse response = null;
    Exception exception = null;

    AsyncCallback callback = ar =>
       {
         try
         {
           //get the response
           response = (HttpWebResponse)request.EndGetResponse(ar);
         }
         catch(Exception e)
         {
           exception = e;
         }
         finally
         {
           //setting the handle unblocks the loop below
           waitHandle.Set();
         }
       };

    //request response async
    var asyncResult = request.BeginGetResponse(callback, null);
    if (asyncResult.CompletedSynchronously) return response;

    bool hasSignal = waitHandle.WaitOne(timeout ?? Timeout.Infinite);
    if (!hasSignal)
    {
      throw new TimeoutException("No response received in time.");
    }

    //bubble exception that occurred on worker thread
    if (exception != null) throw exception;

    return response;
  }
}

Note that this method uses a static int field (seedCounter) when in comes to creating a random seed. This counter is incremented in a thread safe manner every time the method is being invoked. This simple trick is a simple workaround to the notoriously unreliable Random class, and effectively prevents double seeds (and thus: duplicate “random strings”) if the GetRandomString method is being invoked several times immediately. As an alternative, you could also use a static Random field, which would only have to be initialized once. My implementation has the smaller footprint (and integer variable), while a Random field would perform much better (currently, every invocation calculates a seed and creates a new Random instance). The better choice depends on the context I guess:

/// <summary>
/// A counter that is being incremented with every invocation of
/// <see cref="GetRandomString"/>.
/// </summary>
private static int seedCounter = (int)DateTime.Now.Ticks;

/// <summary>
/// Generates a random string of a given length, which consists
/// of characters taken from the UTF-8 table (0x21 - 0x7e).
/// </summary>
/// <param name="length">The length of the random string.</param>
/// <returns>Random characters.</returns>
public static string GetRandomString(int length)
{
  const int lower = 0x21;
  const int upper = 0x7e;

  StringBuilder builder = new StringBuilder();

  //increment thread-safe
  seedCounter = Interlocked.Increment(ref seedCounter);

  //create random with the seed (make sure it's not int.MinValue)
  Random rnd = new Random(seedCounter %int.MinValue);

  for (int i = 0; i < length; i++)
  {
    builder.Append((char) rnd.Next(lower, upper));
  }

  return builder.ToString();
}

Accordingly, invoking the method like this:

string random = GetRandomString(10);

…generates you a string comparable to this one: 2#,R`6>Cz{

Features:

• Simple scheduling and callback mechanisms
• Silverlight compatible
• Lightweight
• Fluent API
• Detection of system time changes with optional rescheduling
• Optional forwarding of exceptions during job execution
• Open Source (Ms-PL)

Download library and sample

Current Version: 1.0.2, 2010.01.12

What Does it Do?

Basically, the library allows you to create a job, and submit that job to a scheduler, along with a callback action. This callback action is invoked as soon (or every time) the job is due.

Before going into the details, here’s a first code snippet that creates a simple Job that is supposed to run repeatedly (every 1.5 seconds) for a minute. Once the job is created, it is submitted to a Scheduler instance which processes the job and makes sure the submitted callback action is being invoked every time the job is due:

private Scheduler scheduler = new Scheduler();

public void RunOnce()
{
  //define a start / end time
  DateTime startTime = DateTime.Now.AddSeconds(5);
  DateTime endTime   = startTime.AddSeconds(60);

  //configure the job
  Job consoleJob = new Job();
  consoleJob.Run.From(startTime)
                .Every.Seconds(1.5)
                .Until(endTime);

  //submit the job with the callback to be invoked
  scheduler.SubmitJob(consoleJob, j => Console.Out.WriteLine("hello world"));
}

Silverlight

The project provides class libraries for .NET 3.5 and Silverlight 3, along with a Silverlight sample application that shows how to add scheduling functionality to your SL application with just a few lines of code.

While long-term scheduling isn’t probably something you need to do in a Silverlight application, the scheduler simplifies the management of periodic jobs, such as polling a server for updates. Below is a snippet from the Silverlight sample application. This job starts immediately, and runs indefinitely with an interval of 2 seconds:

private void CreateJob2()
{
  //create job
  Job<int> job = new Job<int>("Job 2");
  job.Data = 0;
  job.Run.Every.Seconds(2);

  //submit to scheduler
  scheduler.SubmitJob(job, LogJobExecution);
}

private void LogJobExecution(Job<int> job, int data)
{
  //updates user interface
}

Jobs

A job is a simple configuration item for the scheduler. There’s two built-in job types: Job and Job<T>. The only difference between the two is that the latter provides a Data property which allows you to attach state information directly to the job and have it delivered back to you when the job runs.

Creating Jobs

Creating a job is pretty easy, and can be configured through a fluent interface (optional, you can also set the properties the traditional way). Jobs may run once, several times, or indefinitely – you can configure intervals, an optional expiration time, or a maximum number of executions. Here’s a few configuration samples:

//run the job every second until we manually cancel it
Job job = new Job();
job.Run.Every.Seconds(1);

//create a job with an attached FileInfo
Job<FileInfo> job = new Job<FileInfo>();
job.Data = new FileInfo(@"C:\readme.txt");

//run the job 5 times every 1.5 seconds, start immediately
TimeSpan interval = TimeSpan.FromSeconds(1.5);
job.Run.Every.TimeSpan(interval).Times(5);

//create a simple job
Job job = new Job();

//run the job every 1.5 seconds until it expires
DateTime expiration = DateTime.Now.AddMinutes(5);
job.Run.Every.Seconds(1.5).Until(expiration);

The Scheduler Class

Jobs are being submitted to the Scheduler class, which provides a very simple API. Most methods should be pretty self-explanatory, and they are well documented.

Callback Actions

If you add a Job to the Scheduler through one of the SubmitJob overloads, you have to submit a callback action that is being invoked whenever the job runs. Depending on whether you use Job or Job<T>, a different callback delegate may be used:

Here’s a sample that uses two different callback methods:

class Program
{
  private static Scheduler scheduler = new Scheduler();

  static void Main(string[] args)
  {
    Job simple = new Job("simple");
    simple.Run.From(DateTime.Now.AddSeconds(3)).Once();

    Job<int> generic = new Job<int>("generic") {Data = 123};
    generic.StartAt(DateTime.Now.AddSeconds(1)).Run.Once();

    scheduler.SubmitJob(simple, HandleSimpleJob);
    scheduler.SubmitJob(generic, HandleGenericJob);

    Console.ReadLine();
  }

  private static void HandleGenericJob(Job job, int data)
  {
    Console.Out.WriteLine("Job '{0}' submitted data: {1}", job.Id, data);
  }

  private static void HandleSimpleJob(Job job)
  {
    Console.Out.WriteLine("Simple job '{0}' was executed.", job.Id);
  }
}

The sample above produces the following output on the console:

Cancelling or Pausing a Job

If you want to cancel or pause a job, you can do this either via the Scheduler class, or directly on the Job instance that is submitted to you whenever the job runs. Note that canceling the job is a terminal operation – a canceled job cannot be resumed.

private void MyJobCallbackAction(Job job)
{
  //stops execution but keeps the job alive
  job.Pause();

  //resumes operation of a paused job
  job.Resume();

  //terminates the job
  job.Cancel();
}

Actually, doing these operations directly via the Job class is the preferred mechanism – if you use the scheduler’s methods, the scheduler needs to lock its internal list and search for the job itself, which costs you processing power.

Exception Handling

An exception that occurs during the execution of a job does not affect the scheduler – all jobs are being executed on worker threads taken from the .NET thread pool. However, in order not to miss any exceptions, you can instruct the Scheduler class to supervise executing jobs, and forward any unhandled exceptions to a single exception handling routine. All you need to do is registering a callback action to the JobExceptionHandler of the Scheduler class:

private Scheduler scheduler;

private void InitScheduler()
{
  scheduler = new Scheduler();
  scheduler.JobExceptionHandler = LogJobException;
}

private void LogJobException(Job job, Exception exception)
{
  string msg = "Exception occurred while executing job {0}: {1}";
  msg = String.Format(msg, job.JobId, exception.ToString());
  MyLogger.LogError(msg);
}

Performance

The library could surely be tweaked, but it performs pretty well. Running 10000 jobs, each with an interval of 100 ms (that’s around 100 jobs per millisecond) keeps the CPU busy (at around 25% on my machine), but neither eats away your memory nor freezes the PC. Bigger intervals aren’t a problem at all because the scheduler is sleeping most of the time.

Reacting to System Time Change Events

Assume the following:

• The current time is 21:00, your job is scheduled to run at 22:00
• The user changes the computer’s time to 21:30

Now, depending on your needs, you might want the scheduler to adjust itself based on two strategies:

• A: If you want the job to run at a fixed time (22:00), you expect the job to run in 30 minutes. This is the scheduler’s default behavior.
• B: If you want the job to run based on relative times, you still expect the job to run in an hour, so the execution time would have to be change to 22:30.

In order not to miss such an event, the scheduler performs a quick self test with a fixed configurable interval from time to time - even if no jobs are up for execution. Per default, the scheduler’s SelfTestInterval property is set to two minutes, but this can be configured should you need more (or less) accurate re-scheduling.

If you want the scheduler to just readjust its internal schedule and keep fixed times (A), you don’t have to do anything. However, if you want the scheduler to reschedule its jobs if a system time change was detected (B), you can do by setting the SystemTimeChangeRescheduling property of the Scheduler class, which takes an enum value of type ReschedulingStrategy:

As you can see, you can choose not to reschedule at all (default), only reschedule the next execution time (the next time the job runs), or even shift the expiration time of your jobs.

Fixed vs. Relative Rescheduling Depending on Jobs

What if you have a few jobs that should run on a fixed time, while others should be rescheduled?

I decided against making the API more complicated by allowing jobs to be individually configured. As an alternative, I’d suggest to just use two scheduler classes with individual configurations. You could even write a wrapper class that just maintains two schedulers, and forwards all job submissions to the correct one. Here’s a quick but working implementation:

public class MyScheduler
{
  private readonly Scheduler fixedSchedules = new Scheduler();
  private readonly Scheduler relativeSchedules = new Scheduler();

  public MyScheduler()
  {
    //configure relative rescheduling
    var strategy = ReschedulingStrategy.RescheduleNextExecution;
    relativeSchedules.SystemTimeChangeRescheduling = strategy;
  }

  //This method just forwards submitted jobs to one of the schedulers
  public void SubmitJob(Job job, Action<Job> callback, bool hasFixedSchedule)
  {
    if(hasFixedSchedule)
    {
      fixedSchedules.SubmitJob(job, callback);
    }
    else
    {
      relativeSchedules.SubmitJob(job, callback);
    }
  }
}

Persisting Jobs

Persisting jobs is not part of the library, but could be done by subclassing the Scheduler class. The class gives you protected access to all its internals, including its job list. Job is a very simple component, so it should be fairly easy to store and reload all jobs.

However, from an architectural point of view, I’d probably not persist any jobs at all, but rather recreate them during initialization based on persisted business data. A job does execute in a given context, because of “something”. Let’s assume this “something” is a reminder flag in a calendar application:

• User sets a reminder on a calendar entry.
• Calendar application updates database record of the calendar entry, then creates a job with the scheduler.
• User turns off application – the scheduler and running jobs are being disposed.
• User restarts application.
• The application retrieves all reminders from the database and schedules jobs for them.

This approach is simple, and clearly defines the responsibilities of the components in your application. It also minimizes dependencies on the scheduling system.

Implementation Notes

Creating a Fluent Interface

The library provides a fluent API that allows you to chain configuration settings:

//job starts at a given start time, repeats until expiration time
Job myJob = new Job();
myJob.Run.From(startTime).Every.Seconds(1.5).Until(expiration);

The fluent API is optional – a job can also be configured via traditional properties setters. However, the corresponding declaration is more verbose:

//job starts at a given start time, repeats until expiration time
Job myJob = new Job
              {
                Loops = null,
                StartTime = startTime,
                Interval = TimeSpan.FromSeconds(1.5),
                ExpirationTime = expiration
              };

Basically, the implementation of the fluent API is very simple:

• The Run property returns an instance of a helper class called JobSchedule. This helper class provides methods such as From, Until, Every, or Once.
• All methods of the JobSchedule class have a return value of JobSchedule again, which allows the developer to chain the operations as in the sample above.

Below is a part of JobSchedule’s implementation. You can see that the class receives an instance of type Job, and just sets the properties on this class.

public class JobSchedule
{
  private readonly Job job;

  //created with the job that is being configured
  public JobSchedule(Job job)
  {
    this.job = job;
  }

  //all operations just return the schedule itself again
  public JobSchedule From(DateTimeOffset startTime)
  {
    job.StartTime = startTime;
    return this;
  }

  ...

}

DateTime, DateTimeOffset, and SystemTime

SystemTime Pattern

With a scheduler, everything is about time. However, time-related code is very hard to test, which is why the scheduler does not directly access the current system time, but makes use of Ayende’s SystemTime. This is an awesome pattern, and I highly recommend using it whenever timestamps play an important role in code.

DateTimeOffset vs. DateTime

You might have noticed that usually, the code works with DateTimeOffset rather then the commonly known DateTime struct. DateTimeOffset is basically an alternative to DateTime, but operates on UTC which makes it an ideal candidate for most time-related scenarios. You can read more about it at MSDN or at the BCL team blog.

However, you can even still use DateTime in your code if you feel more comfortable with it:

Job job = new Job();

DateTimeOffset expDate1 = DateTimeOffset.Now.AddHours(2);
DateTime       expDate2 = DateTime.Now.AddHours(2);

//the job takes both DateTimeOffset and DateTime values
job.ExpirationTime = expDate1;
job.ExpirationTime = expDate2;

Job List, Timer and Pooled Execution

Job List

Internally, the Scheduler class uses a very simple mechanism: All jobs are being cached in a sorted list, which allows the scheduler to easily determine the next execution time. If a new job is being submitted, the scheduler only has to check whether the new job runs before the next scheduled job or not. If yes, the scheduler adjusts its next execution. If no, the job is just added to the end of the list, and a flag is set that reminds the scheduler to reorder the list once the next job was done. This approach has a big advantage: Even if many jobs are being submitted, reordering takes only place once the next job runs.

public void SubmitJob(Job job, Action<Job> callback)
{
  //[validation omitted for brevity]

  JobContext context = new JobContext(job, callback);

  lock(syncRoot)
  {
    //if this job is going to be the next one, we need to reconfigure
    //the timer. Do not reschedule if the next execution is imminent
    if (NextExecution == null || context.NextExecution <= NextExecution.Value)
    {
      //insert at index 0 –> makes sure the job runs first on next timer event
      jobs.Insert(0, context);

      //only reschedule if the next execution is not imminent
      if (NextExecution == null || NextExecution.Value.Subtract(SystemTime.Now())
                                                .TotalMilliseconds > MinJobInterval)
      {
        //no sorting required, but we need to adjust the timer
        Reschedule();
      }
    }
    else
    {
      //add at end of the list and mark list as unsorted
      //the job will be sorted and rescheduled on the next run (which is before
      //this job's execution time)
      jobs.Add(context);
      isSorted = false;
    }
  }
}

Timer and Rescheduling

In order to trigger the execution, a single Timer is used to wake up the scheduler once jobs are due. The timer is set to one of those values:

• If the scheduler has no jobs at all, the timer is disabled.
• If jobs are pending, the next interval is the execution time of the next pending job.
• If the self test interval is lower than the execution time of the next job, the scheduler will run an evaluation at this time (which ensures that a changed system time does not cause the scheduler to oversleep).

The whole timer logic is encapsulated in the Reschedule method:

/// <summary>
/// Reconfigures the timer according to the
/// next pending job execution time.
/// </summary>
private void Reschedule()
{
  if(jobs.Count == 0)
  {
    //disable the timer if we don't have any pending jobs
    NextExecution = null;
    timer.Change(Timeout.Infinite, Timeout.Infinite);
  }
  else
  {
    //schedule next event
    var executionTime = jobs[0].NextExecution;

    DateTimeOffset now = SystemTime.Now();
    TimeSpan delay = executionTime.Value.Subtract(now);

    //in case the next execution is already pending, add a safe delay
    long dueTime = Math.Max(MinJobInterval, (long)delay.TotalMilliseconds);

    //run at least with the self testing interval
    dueTime = Math.Min(dueTime, SelfTestInterval);

    NextExecution = SystemTime.Now().AddMilliseconds(dueTime);
    timer.Change(dueTime, Timeout.Infinite);
  }
}

Job Execution

“Executing” a job basically means invoking the callback action that was submitted along with the job. This always happens asynchronously through the .NET thread pool:

/// <summary>
/// Invokes the managed job's <see cref="CallbackAction"/> through
/// the thread pool, and updates the job's internal state.
/// </summary>
public void ExecuteAsync()
{
  //only execute if the job is active
  if (...)
  {
    ThreadPool.QueueUserWorkItem(s => CallbackAction(ManagedJob));
  }

  UpdateState();
}

Conclusion

This is a neat little helper library, and its small footprint makes it a viable alternative to handling timers yourself even for small applications. Happy coding

VFS comes with a set of file system providers and clients (including Silverlight support), and allows you to easily write your own providers (e.g. to expose the contents of a ZIP file on a remote server). Additional offerings are flexible security (e.g. to access your Azure blobs via VFS in order to plug-in a custom authorization scheme), auditing and reliable file transfers.

VFS is currently in early Alpha, but I’m working full steam ahead. Comments and wish lists are appreciated! For a more detailed introduction and a few code snippets, visit the project home:
http://vfs.codeplex.com

Thankfully, WCF allows us to communicate errors (or faults) through FaultExceptions. We can just convert internal exceptions into a FaultException, and WCF will take care about everything else. However: This conversion strategy is tedious and error prone, especially if you want to do more sophisticated exception handling. Even a simplified example as the one below mainly consists of exception handling code:

//Simplified example
public string Foo(string userName)
{
  try
  {
     Bar.FooBar(userName);
  }
  catch(ArgumentException e)
  {
    //convert exception into a WCF friendly FaultException
    throw new FaultException("Info about specific error");
  }
  catch(Exception e)
  {
    //convert exception into a WCF friendly FaultException
    throw new FaultException("Info about unspecific error");
  }
}

I’m currently finding myself having to write a set of WCF services, and I didn’t want to go through try/catch blocks all the time just in order to wrap up the same exceptions over and over again. Accordingly, I wrote helper methods that do the exception handling for me.

• SecureAction is used by service methods that do not have a return value.
• SecureFunc<T> is used by service methods that do have a return value.

These helper methods allow me to easily delegate the exception handling from all my service methods, and if anything goes wrong, I can trust that the internal exception is safely converted into a FaultException. Here’s is the rewritten Foo method from above, now remarkably smaller:

public string Foo(string userName)
{
  return SecureFunc(() => Bar.FooBar(userName));
}

Below is the (simplified) snippet with the helper methods. Do note that the above sample methods are just starting points. My productive helper methods provide a more sophisticated exception handling than shown above (they build detailed FaultContracts which are specific to my application) and come with a few overloads.

Furthermore, you might think about adding additional parameters to your helper methods (such as fault IDs) in order to customize the generated faults.

public static void SecureAction(Action action)
{
  try
  {
    action();
  }
  catch (Exception e)
  {
    //productive code provides more specific
    //exception handling, but you should get the idea...
    throw new FaultException(e.Message);
  }
}

public static T SecureFunc<T>(Func<T> func)
{
  try
  {
    return func();
  }
  catch (Exception e)
  {
    //productive code provides more specific
    //exception handling, but you should get the idea...
    throw new FaultException(e.Message);
  }
}

Download and further infos: http://www.hardcodet.net/netdrives

This is an introductory tutorial on SLF, the Simple Logging Façade. This tutorial covers the basics, which will be all you’ll ever need in most projects. I’m planning on writing a second tutorial that will show custom factories and resolvers soon.

Downloading SLF

To get started, visit http://slf.codeplex.com and download the latest release. Source code is available as a Visual Studio 2008 solution, but if you’re working with VS2005, there’s also precompiled binaries for .NET 2.0 available (.NET 1.0 or 1.1 is not supported).

Sample Projects

SLF comes with a lot of samples, all organized as independent projects that discuss a specific use case. As you will see, most scenarios only require a few lines of code. We are planning to extend this section over time, based on your feedback.

ILogger

The central interface in SLF is ILogger. ILogger provides a versatile API to log information to a specific logging framework. You could roughly say there’s three “categories” of loggers:

1. A few simple implementations directly in the SLF core library (e.g. ConsoleLogger or DelegateLogger) that cover common scenarios.
2. Façades for logging frameworks that are currently supported (e.g. log4net). A façade is usually an independent DLL.
3. Custom loggers that you implement yourself. You can do that very easily, usually by extending a simple base class. Creating fancy custom loggers will be covered in the second part of this tutorial.

Here’s a first snippet, that creates a ConsoleLogger, which is part of the core library:

ILogger logger = new ConsoleLogger();
logger.Info("hello world");

This produces the following output

However, rather than creating your loggers all over the place, you will usually use LoggerService to obtain your logger(s):

ILogger logger = LoggerService.GetLogger();
logger.Info("hello world");

Setting up logging with LoggerService is described in a bit further below.

Logging in Categories

As a general guideline on how and when to use logging categories, I recommend Colin Eberhardt’s “The Art of Logging”, which is an excellent introduction to logging in general.

SLF knows 5 logging categories (or log levels), which are covered through a set of methods that allow you to easily submit logging information. 

Every one of these methods provides several overloads, which allow you to submit simple text, exceptions, or even format text on the fly. A few exemplary logging instructions:

ILogger logger = new ConsoleLogger();

logger.Info("Simple Message.");
logger.Info("User {0} logged in at {1}", GetUserName(), DateTime.Now);
logger.Warn(e, "Message for uncritical exception.");
logger.Error(someException);
logger.Fatal(e, "Login exception for user {0}", GetUserName());

Logging a LogItem

Apart from the the above mentioned Info(), Warn(), Error(), Fatal() and Debug() methods, there’s also the Log method, which expects an parameter of type LogItem. LogItem is a simple class that encapsulates information that belongs to a given log entry:

Working with LogItem is not as straightforward as using the other methods, but it may be useful if you want to submit more detailed logging information. Here’s a sample that logs a warning along with an event ID:

public void Login(User user)
{
   //do the login 
   LoginResult result = ...

   //log an Info message with a title and an event ID 
   LogItem item = new LogItem();
   item.LogLevel = LogLevel.Warn;
   item.EventId = 201;
   item.Title = "Invalid login attempted by: " + user.Name;
   item.Message = result.ToDetailedString(); 

   ILogger logger = ...
   logger.Log(item);
}

Setting up Logging in Code

Do it Yourself: Storing a Reference to ILogger

Basically, the simplest possible implementation to use SLF is to just store an ILogger instance somewhere and be on your way. The sample below uses the BitFactory logger façade, which internally forwards log messages to the BitFactory logging framework:

public static class MyApplication
{
  //there’s a static convenience method that creates a logger for a given file 
  private ILogger logger = BitFactoryLogger.CreateFileLogger("log.txt");

  public static ILogger Logger
  {
    get { return logger; }
  }
}

However, we recommend to use LoggerService instead:

LoggerService

LoggerService is a static repository you can use in different ways. It provides support for declarative configurations (taken from app.config), lets you just plug in a single logger, or completely customize and plug in advanced logger resolution strategies.

Lets have a look at a simplistic example: Create the above ConsoleLogger and make it available through LoggerService. Again, this is as simple as it gets:

ILogger logger = new ConsoleLogger();
LoggerService.SetLogger(logger);

With a logger plugged in like this, we can use LoggerService from anywhere in our application to get a hold of the ConsoleLogger we just plugged in:

ILogger logger = LoggerService.GetLogger();
logger.Info("hello world");

Good to Know: LoggerService Never Returns Null

LoggerService guarantees you to always return a valid ILogger instance. If no logger is configured, it will just return you a NullLogger instance. NullLogger is a special implementation of the ILogger interface, which just discards everything you throw at it. You could say that NullLogger switches off logging without requiring any changes in your code.

Thanks to NullLogger, you never have to check for null references when retrieving a logger. Look at the snippet below: This code will not result in an exception, because GetLogger will not return null, but a NullLogger instance:

//you can explicitly assign a null reference… 
LoggerService.SetLogger(null); 

//…and the service will return you a NullLogger 
ILogger logger = LoggerService.GetLogger();

//NullLogger will just discard this message, so no real logging happens
logger.Info("This message will be discarded"); 

Setting up Logging Declaratively (App.config)

Per default, LoggerService analyzes the application’s configuration file (app.config) in order to detect configured loggers. So if you want to go the declarative route, you don’t have to write a single line of code – it just works.

Here’s a sample app.config file that makes SLF write anything to the console through a ConsoleLogger:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="slf" type="Slf.Config.SlfConfigurationSection, slf"/>
  </configSections>

  <slf>
    <factories>
      <!-- log everything through the built-in ConsoleLogger -->
      <factory type="Slf.Factories.ConsoleLoggerFactory, SLF" />
    </factories>
  </slf>

</configuration>

Declarative configurations often make sense in more complex scenarios, especially if you use more powerful logging frameworks such as log4net. Here’s a complete configuration file that makes SLF use log4net. This app.config file contains two sections:

• The slf section tells SLF to forward all logging data to log4net.
• The log4net section is a standard log4net configuration (it has nothing to do with SLF). In this example, log4net is configured to write everything into a single log file.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="log4net"
             type="log4net.Config.Log4NetConfigurationSectionHandler,log4net"/>
    <section name="slf"
             type="Slf.Config.SlfConfigurationSection, slf"/>
  </configSections>

  <slf>
    <factories>
      <!-- configure single log4net factory, which will get all logging output -->
      <factory type="SLF.Log4netFacade.Log4netLoggerFactory, SLF.Log4netFacade"/>
    </factories>
  </slf>

  <!-- configures log4net to write into a local file called "log.txt" -->
  <log4net>
    <appender name="MainAppender" type="log4net.Appender.FileAppender">
      <param name="File" value="log.txt" />
      <param name="AppendToFile" value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date - %message %newline" />
      </layout>
    </appender>
    <root>
      <level value="ALL" />
      <appender-ref ref="MainAppender" />
    </root>
  </log4net>

</configuration>

If you configure SLF through app.config, you don’t have to write any code, because SLF will detect the configuration on its own. Accordingly, just get the logger through LoggerService and log away:

ILogger logger = LoggerService.GetLogger();
logger.Info("Application started at {0}", DateTime.Now);

Do note that if you plug in a custom logger through LoggerService.SetLogger, this will override any declaratively configured loggers. You can, however, always reset LoggerService through the LoggerService.Reset method.

Working With Loggers and Façades

Using the Built-in Loggers

SLF comes with a number of built-in loggers that implement ILogger, which you can use to quickly add logging functionality to your application. There’s the usual suspects such as ConsoleLogger, DebugLogger, or TraceLogger, as well as a few more fancy implementations (e.g. DelegateLogger or DecoratorLogger) and base classes you can use to quickly create your own logger implementations.

There’s a lot of samples that demonstrate the loggers and possibilities, all wrapped into individual projects. However, here’s a few samples:

Delegating Logging through DelegateLogger

DelegateLogger is a simple logger that allows you to quickly plug in some custom logic through a delegate or lambda expression. Here’s dummy sample for a WinForms application, which just shows a message box for every item that is logged to SLF.

DelegateLogger logger = new DelegateLogger(ShowMessage); 

//this message is being invoked by the logger 
private void ShowMessage(LogItem item)
{
  MessageBox.Show("Logged Message: " + item.Message);
}

…or even shorter, with a Lambda Expression:

var logger = new DelegateLogger(item => MessageBox.Show(item.Message));

Combining Logged Output via CompositeLogger

CompositeLogger is a logger that does not log on its own, but forwards all logging information to an arbitrary number of other loggers:

CompositeLogger compositeLogger = new CompositeLogger();

compositeLogger.Loggers.Add(new ConsoleLogger);
compositeLogger.Loggers.Add(new TraceLogger);
compositeLogger.Loggers.Add(new DebugLogger);

compositeLogger.Info("Logging to all three loggers at once!");

You can also submit the underlying loggers directly as constructor parameters:

ILogger consoleLogger = new ConsoleLogger();
ILogger traceLogger = new TraceLogger();
ILogger debugLogger = new DebugLogger();

ILogger composite = new CompositeLogger(consoleLogger, traceLogger, debugLogger);

Formatting Logging Output

The first snippet in this tutorial wrote “hello world” to the console, which looked like this:

Now, a lot of loggers derive from FormattableLoggerBase. This base class provides a Formatter property, which takes an instance of ILogItemFormatter. ILogItemFormatter is a very simple interface, which has only one task: Converting a given LogItem into a string.

Accordingly, if you wanted to change the format of the above message, you could just write a custom formatter and assign it to your logger. Here’s an alternative for a simple XmlFormatter:

public class XmlFormatter : ILogItemFormatter
{
  private XmlSerializer serializer = new XmlSerializer(typeof(LogItem));

  public string FormatItem(LogItem item)
  {
    StringWriter writer = new StringWriter();
    serializer.Serialize(writer, item);
    return writer.ToString();
  }
}

Accordingly, we can plug in this formatter into our ConsoleLogger like this:

IFormattableLogger logger = new ConsoleLogger();
logger.Formatter = new XmlFormatter();
logger.Info("hello world");

The above snippet produces the following output, that renders a LogItem as an XML element:

Directing Trace Output To SLF

If you have an existing codebase that logs through the Trace class, and you would like to make use of SLF, you don’t necessarily have to change the existing code. The SLF core library contains the SlfTraceListener class which just redirects trace messages to SLF.

SLF comes with a sample that shows how to declare SlfTraceListener declaratively via app.config. But you can do this also programmatically:

static void Main(string[] args)
{
  //add SLF listener to Trace 
  Trace.Listeners.Add(new SlfTraceListener()); 

  //write to Trace – this message will be redirected to SLF 
  Trace.WriteLine("We are writing to Trace.");
}

Your own Logger: Extending the Logger Base Classes

If you want to create your own ILogger implementation, you can either create a new class that implements ILogger, or extend either LoggerBase or FormattableLoggerBase.

ILogger is not a complex interface, but there’s a lot of boilerplate code to implement. So in most cases, it’s probably more convenient to extend one of the base classes. Both require you to override just one method:

public class MyCustomLogger : LoggerBase
{
  public override void Log(LogItem item)
  {
     //your implementation goes here 
  }
}

Sample: Implementing a ColoredConsoleLogger

The class below is a custom console logger which writes colored output to the console, depending on the LogLevel of the logged item. The class derives from FormattableLoggerBase in order to allow you to plug in a custom message formatter.

public class ColoredConsoleLogger : FormattableLoggerBase
{
  public override void Log(LogItem item)
  {
    //set console color depending on log level
    switch (item.LogLevel)
    {
      case LogLevel.Info:
        Console.ForegroundColor = ConsoleColor.Green;
        break;
      case LogLevel.Warn:
        Console.ForegroundColor = ConsoleColor.Cyan;
        break;
      case LogLevel.Error:
        Console.ForegroundColor = ConsoleColor.Yellow;
        break;
      case LogLevel.Fatal:
        Console.ForegroundColor = ConsoleColor.Red;
        break;
      default:
        Console.ResetColor();
        break;
    }

    //delegate string formatting to base class 
    string text = FormatItem(item);

    //write the string to the console 
    Console.Out.WriteLine(text);
    Console.ResetColor();
  }
}

If you log through this ColoredConsoleLogger, a logged Info is displayed in green now:

Working with Available SLF Façade Libraries

SLF comes with a few façade libraries you can use to forward to a given logging frameworks. Currently, there is support for the following commonly known frameworks:

• log4net
• NLog
• Enterprise Library
• BitFactory Framework

…and if you would like to use SLF along with a framework that is not listed yet, writing your own façade is pretty easy!

We’ve provided samples and sample configurations for all these façades. Accordingly, you can just find the sample that suits you, and copy/paste the configuration code into your application.

Named Loggers

The “Named Loggers” feature allows you to define several loggers (programmatically or in code), and then access them through their names. You can even direct logging instructions to different logging frameworks based on logger names!

In order to get a named logger, just use the overload of LoggerService.GetLogger that takes a string parameter:

ILogger defaultLogger = LoggerService.GetLogger();
ILogger namedLogger   = LoggerService.GetLogger("LAB-DATA");

Note that the default logger is basically a named logger with a special name (an empty string). The snippets below all return the default logger:

ILogger defaultLogger = LoggerService.GetLogger();
ILogger defaultLogger = LoggerService.GetLogger("");
ILogger defaultLogger = LoggerService.GetLogger(LoggerService.DefaultLoggerName);

The downloadable SLF solution contains sample applications that show how to configure loggers with different names both programmatically or via configuration files.

The Hierarchical Lookup Process

When requesting a named logger, you don’t have to submit a name that exactly matches the name of a configured logger. Instead, named loggers are organized in a hierarchical manner. As soon as a named logger is being requested, SLF will just resolve the closest match and return you a matching logger instance:

In the above sample, SLF was configured with a total of eight loggers. You can see, that the logger names form a hierarchy. With this setup in place, the closest match will be returned on every request.

Accordingly, LoggerService.GetLogger("Foo.AAA") would return a logger of type Foo (closest match). And LoggerService.GetLogger("Foo.XXX.AAA") would return a logger of type Foo.XXX (closest match again).

Here’s some more samples, matching the above hierarchy:

Fallback to Default  Logger

The lookup for a logger will always fall back to the default logger type if no matching named logger was found. This should not come as a surprise. After all, the default logger is just a logger with the name [String.Empty].

And don’t forget – LoggerService always returns a valid logger instance and never a null reference. If no unnamed logger was configured at all, you would just receive an instance of NullLogger.

Exceptions to Named Logger Resolving

Hierarchical lookups work out of the box, but they are not guaranteed if you customize LoggerService:

• If you inject a single ILogger instance into LoggerService via LoggerService.SetLogger, all requests will of course return this specific logger instance, regardless of the requested logger name.
• If you inject a custom resolver into LoggerService by setting the LoggerService.FactoryResolver property, you gain full control over the lookup and logger creation process. Accordingly, you can completely change this behavior.

Configuring Named Loggers in Code or Declaratively

The sample projects show how to set up named loggers in code, or via the application configuration file (app.config).

Filtering

Currently, SLF provides not built-in filtering mechanism, but leaves that to the underlying logging frameworks. The reason for this is that we just wanted to provide a very lean interface to get started with.

However, we’ve already opened a topic on CodePlex’ discussion board, so please express your opinion. If we feel there is a demand for built-in filtering, we will provide the functionality in a matter of days:

http://slf.codeplex.com/Thread/View.aspx?ThreadId=76857

Tutorial Part 2

The next part of this tutorial will discuss Resolvers, Factories, and creating your own logging façades. It will cover simple scenarios (you can plug-in factories with a single line of code) and more complex resolution scenarios for those among you who happen to deal with challenging logging situations. Stay tuned

Release days are good days – Colin Eberhardt and I are very happy to announce SLF 1.0!

SLF is a framework with a simple but ambitious mission: To provide every developer with the means to easily plug in logging functionality into her application. As such, it aims at two fundamental goals:

1. Simplicity: SLF allows you to plug in solid logging functionality into your application with literally one line of code, while providing you with an upgrade path to complex logging scenarios at any time.
2. Flexibility: SLF provides you with a common interface that decouples the logging framework of your choice (e.g. log4net or NLog)  from your code. This eliminates dependencies on a given framework, thus allowing you to switch (or even combine!) frameworks at any time. Furthermore, SLF’s modular architecture allows you to plug-in custom logging strategies very easily.

Features

• Configurable through code or configuration files (app.config).
• Support for named loggers with hierarchical fallback mechanisms.
• Support for common logging frameworks such as log4net out of the box.
• Silverlight support.
• Writing your own pluggable logging strategy is easy.
• You can exchange the underlying logging mechanism at any time, even at runtime.
• Extensible and modular architecture. Writing your own façade can be as simple as overriding one single method, but you can cover complex scenarios, should you have to.
• Robust: In case of invalid configurations or logging instructions, SLF rather outputs debug warnings instead of crashing your application at runtime.
• A ton of copy-and-paste ready samples for different use cases.
• .NET 2.0 compatible binaries.

Related Links

• SLF project page: http://slf.codeplex.com
• The Art of Logging – an excellent introduction to logging in general from SLF co-creator Colin Eberhardt.
• SLF Hands-on Tutorial, Part 1

How does SLF Work?

Here’s a first snippet that shows how to get a logger at runtime via the static LoggerService class. LoggerService is basically a convenient – and optional – repository for your loggers:

//get the default (unnamed) logger 
ILogger logger = LoggerService.GetLogger();

//log an information 
logger.Info("hello world");

When working with SLF, you’re usually dealing with the ILogger interface. There’s a few built-in implementations of this interface directly in the SLF core library (e.g. ConsoleLogger), but in productive environments, your ILogger implementation usually is a class that forwards logging instructions to a proprietary logging framework such as log4net, or a custom logging facility you wrote yourself. Hence the name façade:

From your application’s point of view, there is no dependency on the underlying façade and logging framework – you are always logging through the ILogger interface of the SLF core library. This allows you to easily exchange the underlying proprietary mechanism without having to change any of your code that performs the actual logging.

SLF also allows you to directly control the logger resolution process (the process that eventually leads to an ILogger instance). We will cover this in a later tutorial.

But why should we replace dependencies on logging framework X with dependencies on SLF?

You probably won’t worry about that, as SLF really just forwards logging information, and can be easily adjusted. However: There’s a simple pattern to get rid of that dependency, too. If you download SLF, you will find a sample project that implements a wrapper for SLF itself:

SLF in a Fictitious Sample: The Lifecycle of an Application.

I’ll try to outline the benefits of logging, and the role SLF can play in the context of a fictitious software project. We assume the following:

• The application will contain various modules (plug-ins). The modules will be developed individually by separate teams.
• All modules should log important information. These modules log through SLF, so they have no idea about the underlying logging framework.
• Parts of the logged data should be sent back to the development team as soon as the first beta versions have been deployed.

Week 1: Setting Up Logging

Developers have other things in mind than thinking about logging frameworks. They do, however, set SLF in place with two simple steps:

1. Set a reference to the SLF core library.
2. Configure a logger within the main initialization routine of the application. For starters, all logged data is written to Visual Studio’s debugger by plugging a DebugLogger instance into the global LoggerService:

Actually, the first line of code in the application is related to logging:

private void InitApplication()
{
  //make sure logging is in place 
  LoggerService.SetLogger(new DebugLogger()); 

  [some other code]
}

The application is now officially logging-enabled

(btw: as an alternative, a one-liner in the application’s configuration file would have worked, too)

Week 2: Developing First Modules

The first modules are being developed by individual teams. All module libraries maintain a reference to the SLF core library in order to log information. A typical method in a module looks like this:

private void Foo()
{
  try
  {
    ...
  }
  catch(Exception e)
  {
    ILogger logger = LoggerService.GetLogger();
    logger.Fatal(e, "Some explanation");
  }
}

Note that modules have no idea about the underlying logging strategy that was plugged into SLF (currently the DebugLogger from Week 1). They just know how to request a logger (ILogger interface) from LoggerService. What kind of logger they are dealing with is of no interest to them.

Week 3: Writing Logged Data to a File

There’s a lot of modules by now, which all direct logging information towards SLF. Currently, all this logged messages are being written to the debug window (as configured on Week 1). However, the developers would also like to have the data persisted in a file, while keeping the debug output at the same time.

Accordingly, the initialization routine from Week 1 is slightly altered:

//create two independent loggers 
ILogger debugLogger = new DebugLogger();
ILogger fileLogger = BitFactoryLogger.CreateSingleFileLogger("log.txt"); 

//CompositeLogger will redirect all its logging data to the two loggers… 
ILogger composite = new CompositeLogger(debugLogger, fileLogger);
//…so plug it into LoggerService 
LoggerService.SetLogger(composite);

There’s now 3 loggers in play:

• The initial DebugLogger that logs to the debug window.
• The BitFactory façade was used to quickly set up logging to a file. The BitFactory façade is a library that comes with SLF (just like the NLog façade library or the log4net façade library) and makes use of the BitFactory logging framework. This SLF façade library is now referenced by the main application, but not the independent module libraries.
• CompositeLogger (part of the core library) is then used as a channel that logs output to both the DebugLogger and the new BitFactoryLogger:

These four lines of code changed the logging behavior of the whole application. Even if there are now literally hundreds of logging instructions in various modules, they don’t need to be changed at all. Everything will now be logged to both the file and the debugger.

Week 4: Switching to Declarative Configurations and log4net

The integration team decides to plug in their logging framework of choice, which happens to be log4net. Furthermore, they want to get rid of programmatic initialization, and switch to declarative configuration. This requires two steps:

1. Configuring SLF and log4net in the application’s configuration file (app.config)
2. Remove all the code (initialization of LoggerService) from Weeks 1 and 3.

Here’s the app.config file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
   <section name="slf"
            type="Slf.Config.SlfConfigurationSection, slf"/> 

   <section name="log4net"
            type="log4net.Config.Log4NetConfigurationSectionHandler,log4net"/>
  </configSections>

  <slf>
    <factories>
      <!-- declare a log4net factory -->
      <factory name="l4n"
               type="SLF.Log4netFacade.Log4netLoggerFactory, SLF.Log4netFacade"/>
    </factories>

    <loggers>
      <!-- declare the default logger -->
      <logger factory="l4n" />
    </loggers>

  </slf>

  <log4net>
    <!-- standard log4net settings are here... -->
   </log4net>
</configuration>

Actually, the above SLF configuration could have been written shorter, but the verbose version is recommended for readability. This would be a shorter, but equivalent version of the slf section:

<slf>
  <factories>
    <!-- this default factory is used for every logging instruction -->
    <factory type="SLF.Log4netFacade.Log4netLoggerFactory, SLF.Log4netFacade"/>
  </factories>
</slf>

Week 5: Working with Named Loggers

One of the teams develops a module that logs very important data, and they would like to gather this data separately. It is therefore decided that this output will be logged through a named logger called LABDATA. This LABDATA logger should store this information separately.

Accordingly, a lot of logging instructions in this team’s module use SLF’s capability to work with named loggers:

private void Foo(string someValue)
{
  try
  {
    //get named logger to log this piece of information 
    ILogger labLogger = LoggerService.GetLogger("LABDATA");
    labLogger.Info("Foo was invoked with value {0}", someValue); 

    ...
  }
  catch(Exception e)
  {
    //exceptions are still logged through default logger  
    ILogger defaultLogger = LoggerService.GetLogger();
    defaultLogger.Fatal(e, "Some explanation");
  }
}

This code was written by an independent team, and they haven’t changed the configuration of the main application. Accordingly, the logged information will still be routed through the default logger, because a logger that matches the name “LABDATA” just isn’t available yet.

So currently, “LABDATA” output will be logged to the same file as all other logging information.

But the important thing is: The mechanism is in place and SLF still works without errors!

Week 6: Declaratively Configuring the “LABDATA” Logger

During integration of the new module, SLF’s configuration is changed in order to support custom logging instructions for the LABDATA module.

Because log4net is used, which also supports named loggers out of the box, the SLF configuration does not need to be changed at all! Only the log4net section is being updated:

The adjustments in the application configuration file are specific to log4net:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
   <section name="slf"
            type="Slf.Config.SlfConfigurationSection, slf"/> 

   <section name="log4net"
            type="log4net.Config.Log4NetConfigurationSectionHandler,log4net"/>
  </configSections>

  <slf>
    <factories>
      <!-- declare a log4net factory -->
      <factory name="l4n"
               type="SLF.Log4netFacade.Log4netLoggerFactory, SLF.Log4netFacade"/>
    </factories>

    <loggers>
      <!-- declare the default logger -->
      <logger factory="l4n" />
    </loggers>

  </slf>

<!--
  configures log4net with two loggers:
  - A default logger, which logs to file "log-common.txt"
  - A named logger ("LABDATA"), which logs to file "log-labdata.txt"
-->
<log4net>
  <appender name="CommonAppender" type="log4net.Appender.FileAppender">
    <param name="File" value="log-common.txt" />
    <param name="AppendToFile" value="true" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date - %message %newline" />
    </layout>
  </appender>

  <appender name="LabDataAppender" type="log4net.Appender.FileAppender">
    <param name="File" value="log-labdata.txt" />
    <param name="AppendToFile" value="true" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread] %-5level - %message %newline" />
    </layout>
  </appender>

  <logger name="">
    <appender-ref ref="CommonAppender" />
  </logger>

  <logger name="LABDATA">
    <appender-ref ref="LabDataAppender" />
  </logger>
</log4net>

</configuration>

Week 7: Using Another Logging Framework for the LABDATA Loggers

So far, the generated LabData logging file was manually sent to the development team of the new module, which proved to be tedious (somebody had to manually send a mail every day).

Accordingly, a team developed a simple custom logging façade for SLF. This façade uses WCF to send logged data directly to the team.

As a result, there are now two logging façades in play. We have a new situation:

• Regular logging data should be logged to a file via log4net (same as before).
• Logging data for LABDATA should be handled by the new WcfLogger.

Fortunately, integration of the new façade library is easy! It can be plugged into SLF declaratively through the application’s configuration file:

• log4net configuration: The appender for the LABDATA logger is being removed.
• SLF configuration: The new WcfLogger is declared, and configured to handle all LABDATA output. SLF allows us to inject arbitrary configuration information into the declaration. For the WCF logger, this is address information and credentials.

This is how app.config looks now:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
   <section name="slf"
            type="Slf.Config.SlfConfigurationSection, slf"/> 

   <section name="log4net"
            type="log4net.Config.Log4NetConfigurationSectionHandler,log4net"/>
  </configSections>

  <slf>
    <factories>
      <!-- declare a log4net factory -->
      <factory name="l4n"
               type="SLF.Log4netFacade.Log4netLoggerFactory, SLF.Log4netFacade"/> 

      <!-- the custom factory that logs to a WCF service. -->
      <factory name="wcf"
               type="Acme.Logging.WcfLogger, Acme.Logging.Slf2WcfFacade">
        <factory-data>
          <!-- this factory takes custom configuration settings -->
          <service address="http://www.acme.com:8080/ws/logs"
                   user="foo"
                   password="bar" />
        </factory-data>
      </factory>
    </factories>

    <loggers>
      <!-- the default logger that logs via log4net -->
      <logger factory="l4n" />

      <!-- the named logger that uses the WCF façade -->
      <logger name="LABDATA" factory="wcf" />
    </loggers>
  </slf>

  <!-- log4net configuration for the common log file -->
  <log4net>
    <appender name="CommonAppender" type="log4net.Appender.FileAppender">
      <param name="File" value="log-common.txt" />
      <param name="AppendToFile" value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date - %message %newline" />
      </layout>
    </appender>

    <root>
      <appender-ref ref="CommonAppender" />
    </root>
  </log4net>

</configuration>

Again, only the configuration file was changed – the code in the modules was not touched at all.

Week 8 – Unit Testing Logging Instructions

The developers of the LabData module notice they didn’t cover all code in their unit test: Actually, they don’t know whether their logging instruction are properly executed or not.

In order to unit test their module, they just replace the configured loggers at runtime: They plug in TestLogger classes into LoggerService.  TestLogger is a simple logger which just stores all logging input it receives.

This is how the initialization code of their unit test class looks like:

public class Given_Foo_When_Submitting_Lab_Data
{
  private TestLogger defaultLogger;
  private TestLogger labDataLogger;

  [SetUp]
  public void Init()
  {
    SimpleFactoryResolver resolver = new SimpleFactoryResolver();
    resolver.Factory = new TestLoggerFactory();
    LoggerService.FactoryResolver = resolver;

    //for convenience, already get the two test loggers that we will be used
    defaultLogger = (TestLogger) LoggerService.GetLogger("");
    labDataLogger = (TestLogger)LoggerService.GetLogger("LABDATA");
  }
}

The above snippet installs a TestLoggerFactory. This factory will return TestLogger instances for every logger request that is made through LoggerService. This allows to test whether input was logged through the correct loggers.

Here’s a sample unit test:

[Test]
public void Submitting_Regular_Data_Should_Write_Info_To_Lab_Data_Logger()
{
  string testData = "asl39-23lsd9";
  Foo.FooBar(testData);

  //invoking Foo.FooBar should have logged 1 info to the LABDATA logger
  Assert.AreEqual(1, labDataLogger.LoggedItems.Count);

  //make sure data was logged correctly
  LogItem item = labDataLogger.LoggedItems[0];
  Assert.AreEqual(LogLevel.Info, item.LogLevel);
  StringAssert.Contains(item.Message, testData);

  //make sure nothing was logged to the default logger
  Assert.AreEqual(0, defaultLogger.Count);
}

Conclusion and Further Links

I hope the above scenario gave you an impression about how easily you can set up and adjust your logging environment with SLF. For more information, please visit the project page, check out the tutorials, or leave a feedback. Happy logging

http://wpfdisciples.wordpress.com/resources/

If you invoke the <span class="code">GetData</span> method, ...

Quickly inserting CSS directives is something you can’t easily do with Windows Live Writer. This started to annoy me while writing an article, so I came up with two simple plug-ins that do just that: Formatting selected text through CSS classes.

Plug-in 1: Quick-Insert a Predefined CSS Class

This is a very simple plug-in that stores one (1) single CSS class name, and applies it to the selected text with a single click. This is a fastest possible way to format several junks of your post with the same CSS class.

The simple assignment comes has a price, however: It takes some more work to reconfigure the used CSS class. Therefore, it mainly makes sense if you have quite a lot of similar content to format at once. Otherwise, the second plug-in is probably the better choice.

Using the Plug-in

Once the plug-in is installed (instructions at the end of the article), you’ll notice an additional entry on the side bar and the Insert menu of the tool bar, saying “Quick CSS…”:

All you have to do is selecting the portion of text you’d like to format, and click on the plug-in. The configured CSS class name will be immediately applied to the selected text.

First invocation / configuration

The first time you click on the plug-in, there is no formatting happening. Instead, the plug-in displays its options dialog because no CSS class has been configured yet. This dialog allows you to quickly set the CSS class that should be applied:

Subsequent clicks on the plug-in directly apply the class name you configured – this dialog is only opened automatically the first time.

Changing the Class Name

You can change the name of the used CSS class at any time. This requires a bit of work though, as you’ll have to go through Live Writer’s options dialog:

Plug-in 2: Selecting a CSS Class from a List of Class Names

This is a more flexible plug-in. It takes two clicks to format your text with a given CSS class, but it maintains a configurable list of CSS class names, and allows you to quickly select the class name to be applied from a popup.

Using the Plug-in

Once the plug-in is installed (instructions below), you will find a new entry saying “CSS Format…” on the side bar and Live Writer’s Insert menu. Clicking the plug-in (which causes a short delay the first time) opens a popup that lists your CSS classes in alphabetic order. In order to apply a CSS class to the selected text, just double-click a class name:

Most Recently Used Items

Note that if you have configured 10 or more CSS class names, the popup will display two lists, of which the upper list contains the 5 most recently used class names.

(I could make that feature configurable in a subsequent release, if requested.)

Configuring / Importing CSS Class Names

The plug-in allows you to quickly configure class names through a custom configuration dialog, and also supports importing class names directly from a CSS Style Sheet. You can open the dialog through the Popup by clicking the “Options” button:

Style Sheet Import

Clicking the Import Style Sheet button opens a file dialog that allows you to select a style sheet (probably the one you’re also using on your blog). Once selected, the plug-in imports all new class names from the style sheet.

Live Writer Bug: Reformatting Span-Tags

It appears that Live Writer has a bug when it comes to reformatting already formatted text spans. There’s currently no simple fix for this bug, so keep this in mind:

Imagine you have a preformatted junk of text that looks like this:

<span class="foo">hello</span>

Now, if you select the word “hello”, and try to assign it another CSS class (bar), you’d expect the new markup to look like this:

<span class="bar">hello</span>

Instead, Live Writer just keeps the old span, and wraps it into a second one.

<span class="foo"><span class="bar">world</span></span>

Download and Installation Instructions

Download Links

Plug-in 1: Hardcodet.LiveWriter.QuickClassInsert.dll

Plug-in 2: Hardcodet.LiveWriter.ApplyCss.dll

The second plug-in requires Microsoft .NET Framework 3.5 SP1 (download here)

Installation

In order to install a plug-in:

1. Make sure Live Writer is not running
2. Copy the plug-in DLL into Live Writer’s Plugins folder. Usually, this is the following path: C:\Program Files\Windows Live Writer\Plugins\

Source Code Download for Developers

You can also download the source code of the plug-ins:

css-plugins-for-live-writer.zip

The reason for this issue is buried in the WPF framework, and how it interacts with Windows. Fellow WPF Disciple Andrew Smith pointed me in the right direction:

…because a Popup’s HWND has the WS_EX_NOACTIVATE so the WPF framework will not attempt to actually focus the associated hwnd (because its usually used with a window and you don’t want to deactivate the window when you focus something in the popup).

Accordingly, you’ll have to fiddle with Windows Interop to make things work. Here’s the snippet:

public static class WinApi
{
  /// <summary>
  /// Gives focus to a given window.
  /// </summary>
  [DllImport("USER32.DLL")]
  public static extern bool SetForegroundWindow(IntPtr hWnd);

  public static void ActivatePopup(Popup popup)
  {
    //try to get a handle on the popup itself (via its child)
    HwndSource source = (HwndSource)PresentationSource.FromVisual(popup.Child);
    IntPtr handle = source.Handle;

    //activate the popup
    SetForegroundWindow(handle);
  }
}

• Interactive Popups should now fully support all control types.
• The control can now be used in Windows Forms projects, if you need more functionality than the built-in component.

The solution now comes with an additional WinForms sample project, which shows how to display a WPF user control as an interactive popup.

Download link and further information can be found on the control’s home page:
http://www.hardcodet.net/wpf-notifyicon

Project Page: http://www.hardcodet.net/netdrives

Hardcodet.Commons (C#, .NET 3.5)

Common helper classes and snippets (simple base classes, file management, weak events, extension methods etc.)

Hardcodet.Wpf.Commons (C#, .NET 3.5)

Stuff I commonly use in WPF projects, such as checking for design time, base classes for commands and converters, data binding helpers and other stuff.

I’ll keep these libraries up-to-date, version history will be posted here.

History:

2009.09.14  Initial blog release

Look at this simple project that contains two image files. One file is part of the project (physically stored in the Images folder), the other one added as a link. Both files have the same build action (Resource):

Now, if you declare these two images the same way, everything appears to be fine in the designer (both Visual Studio and Blend):

<Window x:Class="WpfApplication2.Window1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="Window1" Height="150" Width="150">
    <StackPanel VerticalAlignment="Center">
      <Image Source="/Images/Add-Item.png" Stretch="None" />
      <Image Source="/Images/Remove-Item.png" Stretch="None"/>
    </StackPanel>
</Window>

However, as soon as you compile and start your application, the linked image does not appear – obviously, the runtime could not resolve it at runtime:

I was quite surprised about this until I reverted to Reflector, which reveals that the linked image was embedded differently than the other one. Here’s the resource entries of the compiled WPF application:

As you can see, the linked image (Remove-Item.png) was included without the folder name, in lower case. Accordingly, I had to adjust the image source in XAML as follows:

<Window x:Class="WpfApplication2.Window1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="Window1" Height="150" Width="150">
    <StackPanel VerticalAlignment="Center">
      <Image Source="/Images/Add-Item.png" Stretch="None" />
      <Image Source="/remove-item.png" Stretch="None"/>
    </StackPanel>
</Window>

This one works at runtime. BUT it breaks the designer. I’m not too happy about that one – whether a file is linked to or not should not affect the outcome of the compiled build all. I’m not too sure whether this was a conscious decision or a bug, but it sure is a major pain.

Update: Microsoft confirmed this to be a bug, which should be fixed in the upcoming version of the framework / VS2010. So for now, linking is out of the picture for me.

This time, I needed to search the other way: I wanted to find all descendants (direct or indirect childs) of a given element that match a given type. As a result, I came up with a complementary extension method that does the job for me:

//get all TextBox controls within the grid:
Grid container;
IEnumerable<TextBox> editors = container.FindChildren<TextBox>();

Usage Sample

As a sample, let’s use a window dialog which contains several images:

• Images that were pasted into a RichTextBox control.
• Images that are part of the UI, nested within the control hierarchy of a ribbon.

In order to find all these Image elements you can see on the screenshot, this will do:

//start a the root (the window itself)
Window window = this;
foreach (Image img in window.FindChildren<Image>())
{
  Console.WriteLine("Image source: " + img.Source);
}

…the above snippet produces the following output:

Image source: pack://payload:,,wpf1,/Xaml/Image1.png

Image source: pack://payload:,,wpf1,/Xaml/Image2.png

[…]

Accordingly, in order to analyze only the contents of the rich text editor, just start on a lower level of the tree:

//only examine the contents of the editor
RichTextBox editor = this.txtContent;
foreach (Image img in editor.FindChildren<Image>())
{
  Console.WriteLine("Image source: " + img.Source);
}

Implementation

(Download link at the end of the posting)

/// <summary>
/// Analyzes both visual and logical tree in order to find all elements
/// of a given type that are descendants of the <paramref name="source"/>
/// item.
/// </summary>
/// <typeparam name="T">The type of the queried items.</typeparam>
/// <param name="source">The root element that marks the source of the
/// search. If the source is already of the requested type, it will not
/// be included in the result.</param>
/// <returns>All descendants of <paramref name="source"/> that match the
/// requested type.</returns>
public static IEnumerable<T> FindChildren<T>(this DependencyObject source)
                                             where T : DependencyObject
{
  if (source != null)
  {
    var childs = GetChildObjects(source);
    foreach (DependencyObject child in childs)
    {
      //analyze if children match the requested type
      if (child != null && child is T)
      {
        yield return (T) child;
      }

      //recurse tree
      foreach (T descendant in FindChildren<T>(child))
      {
        yield return descendant;
      }
    }
  }
}

/// <summary>
/// This method is an alternative to WPF's
/// <see cref="VisualTreeHelper.GetChild"/> method, which also
/// supports content elements. Do note, that for content elements,
/// this method falls back to the logical tree of the element.
/// </summary>
/// <param name="parent">The item to be processed.</param>
/// <returns>The submitted item's child elements, if available.</returns>
public static IEnumerable<DependencyObject> GetChildObjects(
                                            this DependencyObject parent)
{
  if (parent == null) yield break;
  

  if (parent is ContentElement || parent is FrameworkElement)
  {
    //use the logical tree for content / framework elements
    foreach (object obj in LogicalTreeHelper.GetChildren(parent))
    {
      var depObj = obj as DependencyObject;
      if (depObj != null) yield return (DependencyObject) obj;
    }
  }
  else
  {
    //use the visual tree per default
    int count = VisualTreeHelper.GetChildrenCount(parent);
    for (int i = 0; i < count; i++)
    {
      yield return VisualTreeHelper.GetChild(parent, i);
    }
  }
}

For your convenience, I’ve put together a simple helper class that contains the helper methods to search for both children and parent elements in the tree:

http://www.hardcodet.net/uploads/2009/06/UIHelper.cs

Happy coding

The solution to this very problem is actually pretty simple, and it always takes the same three ingredients:

• A white line
• A black line
• Reduced opacity

Basically, to get an edged line on a green background, you don’t need to fiddle with different shades of green. Just use white and black lines and play with the opacity. Here’s the settings in Blend for one of the white lines in the above screenshot:

…and this is the corresponding XAML for the two vertical lines:

<Grid Background="Green">
  <Path Stretch="Fill" Stroke="#5A000000" Margin="25,62,0,0"
        Width="1" Height="100" Data="M130,176 L130,303.03543"/>
  <Path Stretch="Fill" Stroke="#5AFFFFFF" Margin="26,62,0,0"
        Width="1" Height="100" Data="M130,176 L130,303.03543"/>
</Grid>

Tip: Hiding Blend’s Handles

If you’re trying to format a line, Blend’s handles don’t help much, as the basically hide the whole content:

However - you can easily hide / show them by pressing the F9 button.

Tutorial: Creating a 3D Toggle Button Style

Another usage of white and black lines is a 3D effect for borders. Let’s put this to action and create a reusable style that can be applied to a ToggleButton control:

Rather than joining four lines for each button state, I’ll use two Border controls with the same dimensions for each state, taking advantage that the BorderThickness property can be set independently for every edge. Here’s the borders for the unchecked state:

<Grid x:Name="uncheckedState">
  <Border BorderBrush="#49FFFFFF" BorderThickness="1,1,0,0"/>
  <Border BorderBrush="#49000000" BorderThickness="0,0,1,1"/>
</Grid>

…and here’s the borders for the checked state. Note that its Visibility property of the surrounding grid is set to Collapsed in order to hide the borders:

<Grid x:Name="checkedState" Visibility="Collapsed">
  <Border BorderBrush="#49000000" BorderThickness="1,1,0,0"/>
  <Border BorderBrush="#49FFFFFF" BorderThickness="0,0,1,1"/>
</Grid>  

I put these borders together in a simple style, which uses a trigger to switch the visibility of the two borders as soon as the IsChecked property of the ToggleButton changes:

<Style TargetType="{x:Type ToggleButton}">
  <Setter Property="Template">
    <Setter.Value>
      <ControlTemplate TargetType="{x:Type ToggleButton}">
        <Grid x:Name="mainGrid" Margin="0,0,1,1">

          <Grid x:Name="uncheckedState">
            <Border BorderBrush="#49FFFFFF" BorderThickness="1,1,0,0"/>
            <Border BorderBrush="#49000000" BorderThickness="0,0,1,1"/>
          </Grid>

          <Grid x:Name="checkedState" Visibility="Collapsed">
            <Border BorderBrush="#49000000" BorderThickness="1,1,0,0"/>
            <Border BorderBrush="#49FFFFFF" BorderThickness="0,0,1,1"/>
          </Grid>   

          <!--
            WPF needs a background to toggle IsChecked
            if the ContentPresenter does not fill the whole area
          -->
          <Border Background="#00000000" />

          <ContentPresenter VerticalAlignment="Center"
                            HorizontalAlignment="Center" />

        </Grid>

        <!-- triggers toggle visual appearance -->
        <ControlTemplate.Triggers>
          <Trigger Property="IsChecked" Value="True">
            <Setter TargetName="checkedState"
                    Property="Visibility"
                    Value="Visible" />
            <Setter TargetName="uncheckedState"
                    Property="Visibility"
                    Value="Collapsed" />
            <Setter TargetName="mainGrid"
                    Property="Margin"
                    Value="1,1,0,0"/>
          </Trigger>
        </ControlTemplate.Triggers>
      </ControlTemplate>
    </Setter.Value>
  </Setter>
</Style>

With the style in place, you can easily declare a ToggleButton like this:

<ToggleButton Width="100" Height="24" Content="hello world" />

I feel honored (and a little proud, too) to stand among some of the biggest names in WPF, and I’m looking forward to being part of the discussions within the group. After all, there’s still lots and lots to learn, discover and write about on planet WPF

Apart from the updated control itself, I completely revamped the sample project. It’s no longer just a showcase but contains various standalone samples which cover all aspects of the control. And last but not least, I published a complementary tutorial on the CodeProject. One could say I was quite busy

Further information and download on the project page:
http://www.hardcodet.net/projects/wpf-notifyicon

Accordingly, I didn’t know anything about these controls at runtime. Nonetheless, I wanted to provide a communication channel to inform that UIElement that it is being displayed. And I wanted to do it declaratively.

Attached Events to the Rescue

Enter attached events. Just like the better known attached properties, they can be declared in a static class and attached to arbitrary dependency objects. Accordingly, a control X does not need to declare an event itself in order to raise it.

If you are working with Expression Blend, chances are high that you are already using attached events quite often. As an example, the Mouse.MouseDown attached event that lets you trigger an animation if the user clicks on an arbitrary control. And nothing stops you from defining your own custom events

Creating a Sample Application

Let’s create a simple sample. The scenario is the following:

• Sometimes, some kind of critical event occurs (simulated through a button click).
• Every time this happens, we want a “status control” to show an alarm.

We will implement this status control purely in XAML – an attached event will trigger an animation that displays a warning sign:

(For a real-life usage scenario, have a look at the sample application that comes with the WPF NotifyIcon control.)

Preparing the Status Control

The control below is pretty simple. It just contains two images:

• The regular image shows a star. Its initial opacity is set to 100%.
• The second image is the alarm icon. Its initial opacity is set to 0% so it’s not visible (I changed that a little for the screenshot).

Defining the Attached Routed Event

In order to work with a custom event, it needs to be declared first. In the NotifyIcon library, the NotifyIcon control itself exposes the event. In this sample, however, we will declare an Alarm event in its own class called Monitor. Note that everything is static:

/// <summary>///
 Hosts the <see cref="AlarmEvent"/> attached routed event.
/// </summary>
public static class Monitor{

  /// <summary>
  /// Alarm Attached Routed Event
  /// </summary>
  public static readonly RoutedEvent AlarmEvent =
      EventManager.RegisterRoutedEvent("Alarm",
                                       RoutingStrategy.Bubble,
                                       typeof (RoutedEventHandler),
                                       typeof (Monitor));
}

BTW: I didn’t write the code above on my own - code snippets greatly simplify things here. I’ve used one of Dr. WPF’s snippets which will not only generate the event declarations but also some helper methods to deal with events in code.

Raising the Event

The screenshot below shows a simple form that contains a button and the StatusRenderer user control. In order to keep things simple, we will simply raise the attached routed event on the status control every time the user clicks on the button.

In order to trigger the event, we’ll add a simple static helper method to the Monitor class:

/// <summary>
/// A static helper method to raise the Alarm event on a target element.
/// </summary>
/// <param name="target">UIElement or ContentElement on which to raise
/// the event</param>
internal static RoutedEventArgs RaiseAlarmEvent(DependencyObject target)
{
  if (target == null) return null;

  RoutedEventArgs args = new RoutedEventArgs();
  args.RoutedEvent = AlarmEvent;

  if (target is UIElement)
  {
    (target as UIElement).RaiseEvent(args);
  }
  else if (target is ContentElement)
  {
    (target as ContentElement).RaiseEvent(args);
  }

  return args;
}

We want to raise the event every time the button on the main form is clicked. Accordingly, we invoke RaiseAlarmEvent in the button’s click event handler.

private void btnTrigger_Click(object sender, RoutedEventArgs e)
{
  //raise the attached event on the status control
  Monitor.RaiseAlarmEvent(status);
}

Consuming the Event

The nice thing is – once the event is in place, it can be consumed through XAML only, so there’ no need to write code. Lets complete the sample by adding a simple listener to our user control that triggers an animation. I’m using Blend for that job.

1: Create a new event trigger

Start by clicking on the + Event tab in Blend. You will see that the Monitor.Alarm event is not available through this list. Accordingly, we will just use the Loaded event that is offered for now…

2. Create a storyboard to animate the UI

Next, click on the + button to create a new storyboard. For the sample application, I created a storyboard called ShowWarning that fades in the invisible warning sign and hides the default image.

3: Switch to the Monitor.Alarm event

In the first step, we registered our animation to be triggered whenever the user control’s Loaded event fires. However, we want our animation to be fired upon the attached Monitor.Alarm event. As Blend does not provide attached events through its UI, this needs to be changed XAML. Switch to XAML view and find the following line part.

<UserControl.Triggers>
  <EventTrigger RoutedEvent="FrameworkElement.Loaded">
    <BeginStoryboard Storyboard="{StaticResource ShowWarning}"/>
  </EventTrigger>
</UserControl.Triggers>

Now change the RoutedEvent attribute in order to look like this:

<UserControl.Triggers>
  <EventTrigger RoutedEvent="att:Monitor.Alarm">
    <BeginStoryboard Storyboard="{StaticResource ShowWarning}"/>
  </EventTrigger>
</UserControl.Triggers>

…and of course, you also need to register the namespace prefix in the header of user control:

<UserControl
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:att="clr-namespace:AttachedEventSample"
  ...  >

The Result

That’s it. Now, as soon as you click the button, the attached event is being consumed by the user control and triggers the animation. Without a single line of code on the consumer side

Download Sample Application

In a few words, NetDrives is an open source utility that helps you manage your network shares and mapped network drives. Unlike Windows, it can reconnect to secured shares during startup and provides you quick access to your configured shares.

More information, screenshots, and downloads at the project page:

http://www.hardcodet.net/netdrives

Follow me @ http://twitter.com/phsumi

This is an implementation of a NotifyIcon (aka system tray icon or taskbar icon) for the WPF platform. It does not just rely on the existing Windows Forms component, but is a purely independent control which leverages several features of the WPF framework in order to display rich ToolTips, Popups, context menus, and balloon messages.

I’m planning on doing an introductory article on CodeProject (well, somewhere along the way…) but you’ll probably get along just fine – the control comes with a sample application that shows off most of the control’s features.

Further information and download on the project page:
http://www.hardcodet.net/projects/wpf-notifyicon

Without Extension

Basically, this extension makes your commands immediately available without having to declare them. One "traditional" way to declare a command is directly in XAML:

<Window.Resources>

  <cmd:HelloWorldCommand x:Key="SayHello" />

</Window.Resources>

…and then apply it like this:

<Button Command="{StaticResource SayHello}" />

Using the Markup Extension

The declaration part above can become somewhat tedious, especially if you have quite a few commands (e.g. because you are using a ribbon with lots of buttons on it). Thanks to using a markup extension, you can skip the declaration part altogether and just declare your command.

<Button Command="{cmd:HelloWorldCommand}" />

Implementation and Sample

/// <summary>
/// Basic implementation of the <see cref="ICommand"/>
/// interface, which is also accessible as a markup
/// extension.
/// </summary>
public abstract class CommandExtension<T> : MarkupExtension, ICommand
    where T:class, ICommand, new()
{
  /// <summary>
  /// A singleton instance.
  /// </summary>
  private static T command;

  /// <summary>
  /// Gets a shared command instance.
  /// </summary>
  public override object ProvideValue(IServiceProvider serviceProvider)
  {
    if (command == null) command = new T();
    return command;
  }

  /// <summary>
  /// Fires when changes occur that affect whether
  /// or not the command should execute.
  /// </summary>
  public event EventHandler CanExecuteChanged
  {
    add { CommandManager.RequerySuggested += value; }
    remove { CommandManager.RequerySuggested -= value; }
  }

  /// <summary>
  /// Defines the method to be called when the command is invoked.
  /// </summary>
  /// <param name="parameter">Data used by the command.
  /// If the command does not require data to be passed,
  /// this object can be set to null.
  /// </param>
  public abstract void Execute(object parameter);

  /// <summary>
  /// Defines the method that determines whether the command
  /// can execute in its current state.
  /// </summary>
  /// <returns>
  /// This default implementation always returns true.
  /// </returns>
  /// <param name="parameter">Data used by the command.  
  /// If the command does not require data to be passed,
  /// this object can be set to null.
  /// </param>
  public virtual bool CanExecute(object parameter)
  {
    return true;
  }
}

…and here’s a sample implementation:

public class HelloWorldCommand : CommandExtension<HelloWorldCommand>
{
  public override void Execute(object parameter)
  {
    MessageBox.Show("Hello world.");
  }
}

Of course, nothing prevents you from pimping the base class a little to your needs

codeproject

//ILogger is the facade. Behind the scenes,
//a framework of your choice is used
ILogger logger = LoggerService.Logger;
logger.Log("hello world");

The idea of a logging façade isn’t exactly new, but I thought I’d share this one with you for a few reasons:

• It is dead easy to use.
• It provides quite a few overloads when it comes to logging.
• The core library has no dependencies on other libraries at all.
• There are two façades (separate DLLs) that log through the Enterprise Library Logging block or the BitFactory logger. And hopefully more to come!
• Writing your own façade is as simple as overriding one single method.
• It’s not part of another project (completely standalone), and there is no license attached to it. Do with it whatever you want.
• It is dead easy to use.

(click on image to enlarge)

Here’s one way to create a file-based logger (using the BitFactory façade) and make it globally accessible. This only takes you a few lines of code:

//create a new logger instance
string file = @"C:\logfile.txt";
ILogger logger = BitFactoryLogger.CreateSingleFileLogger(file);

//use the global LoggerService to store the logger
LoggerService.SetLogger(logger);

...

//this will store the info in the log file
LoggerService.Logger.Log("This is an information");

Logging via ILogger

The whole purpose of this project is to shield your libraries from the actually chosen logging framework. Accordingly, you are always logging through the ILogger instance. ILogger provides quite a few overloads of the Log method, here are a few of them:

public void LogData(ILogger logger)
{
  logger.Log("An information");
  logger.Log("Something Happened", TraceEventType.Warning);

  //LogItem is the most verbose version
  LogItem item = new LogItem();
  item.Message = "My Message";
  item.EventId = 999;
  item.Categories.Add("Foo");
  item.Priority = 10;
  logger.Log(item); 

  try
  {
    DivideByZero();
  }
  catch(Exception e)
  {
    logger.Log(e);
    logger.Log("Additional message.", e);
    logger.Log("Additional message.", e, TraceEventType.Critical);
  }
}

Initializing an ILogger Implementation

During the initialization of your application, you will have to specify the the logger implementation that is supposed to be used. This might happen declaratively or directly in code. Here’s the initialization code from NetDrives, which makes a logger available through the AutoFac IOC container.

Note that I’m registering a ConsoleLogger for debug builds, while release builds write into a log file. These are completely different classes, but it doesn’t matter - they both implement the ILogger interface:

//init IOC container builder
var builder = new ContainerBuilder();

//register single logger instance
ILogger logger;

#if (DEBUG)
  logger = new ConsoleLogger();
#else
  logger = BitFactoryLogger.CreateSingleFileLogger(AppUtil.LogFile);
#endif

//register logger
builder.Register(logger).As<ILogger>();

Registration and Access through LoggerService

I prefer to initialize and access my logger through an IOC container, but you can do it however you like. If you’re lacking a place to make your ILogger globally accessible, you can use the static LoggerService class:

public void InitApp()
{
  //create a file logger (use BitFactory facade)
  string logFile = @"C:\MyLogFile.txt";
  ILogger logger = BitFactoryLogger.CreateSingleFileLogger(logFile);

  //register as globally used logger
  LoggerService.SetLogger(logger);
}

private void Foo()
{
  try
  {
    DoSomethingWrong();
  }
  catch(Exception e)
  {
    //get registered logger and log exception
    ILogger logger = LoggerService.Logger;
    logger.Log(e);
  }
}

A nice thing about LoggerService: It guarantees you always a valid ILogger instance. If no logger is set, it just falls back to a NullLogger implementation that does not create any output at all. Here’s the implementation:

namespace Hardcodet.Util.Logging
{
  /// <summary>
  /// Provides a global repository for a given <see cref="ILogger"/>
  /// instance. This class ensures that the <see cref="Logger"/>
  /// property is never nullo - in case no logger is defined, it
  /// automatically installs a <see cref="NullLogger"/>
  /// instance.
  /// </summary>
  public static class LoggerService
  {
    private static ILogger logger = new NullLogger();

    /// <summary>
    /// Gets the installed <see cref="ILogger"/> implementation.
    /// </summary>
    /// <remarks>This property always returns a valid
    /// logger.</remarks>
    public static ILogger Logger
    {
      get { return logger; }
    }

    /// <summary>
    /// Installs a given logger or resets the <see cref="Logger"/>
    /// to a <see cref="NullLogger"/> instance if the
    /// <paramref name="loggerImplementation"/> is a null
    /// reference.
    /// </summary>
    /// <param name="loggerImplementation">The logger to be
    /// used globally, or a null reference in order to reset
    /// the service.</param>
    public static void SetLogger(ILogger loggerImplementation)
    {
      logger = loggerImplementation ?? new NullLogger();
    }
  }
}

Creating a new Logger Façade

In case you want to use another logging framework (e.g. NLog or Log4Net), creating a new façade is very easy. Basically, you create a new project, set a reference to the base library and write a class that either

• implements ILogger directly
• or, even simpler, derives from the abstract LoggerBase class.

Feel like sharing your own façade? Just contact me and I’ll happily include your implementation

As a sample, here’s the code of the ConsoleLogger (part of the core library) and the Enterprise Library façade:

using System;

namespace Hardcodet.Util.Logging
{
  /// <summary>
  /// A very simple implementation of <see cref="ILogger"/>
  /// that outputs all messages to the system console.
  /// </summary>
  public class ConsoleLogger : LoggerBase
  {
    /// <summary>
    /// Logs a given item to the console.
    /// </summary>
    /// <param name="item">The item to be logged.</param>
    /// <exception cref="ArgumentNullException">If <paramref name="item"/>
    /// is a null reference.</exception>
    public override void Log(LogItem item)
    {
      if (item == null) throw new ArgumentNullException("item");
      Console.Out.WriteLine(item.ToLogMessage());
    }

  }
}

using Microsoft.Practices.EnterpriseLibrary.Logging;

namespace Hardcodet.Util.Logging.EntLibFacade
{
  /// <summary>
  /// An implementation of the <see cref="ILogger"/>
  /// interface which outputs logged data using
  /// the <see cref="Logger"/> of the MS Enterprise
  /// Library.
  /// </summary>
  public class EnterpriseLibraryLogger : LoggerBase
  {

    /// <summary>
    /// Writes a log entry to the Enterprise Library's
    /// logging block. Output depends on the logging
    /// block's configuration.
    /// </summary>
    /// <param name="item">An log item which encapsulates
    /// information to be logged.</param>
    public override void Log(LogItem item)
    {
      LogEntry entry = ConvertLogItem(item);
      Logger.Write(entry);
    }

    /// <summary>
    /// Creates a <c>LogEntry</c> instance which can be processed
    /// by the Enterprise Library based on a given log item. 
    /// </summary>
    /// <param name="item">An log item which encapsulates information
    /// to be logged.</param>
    /// <returns>An Enterprise Library item which corresponds
    /// to the submitted <c>LogItem</c>.</returns>
    private static LogEntry ConvertLogItem(LogItem item)
    {
      //assign properties
      LogEntry entry = new LogEntry();
      entry.Message = item.Message;
      entry.Title = item.Title;
      entry.AddErrorMessage(item.ErrorMessage);
      entry.EventId = item.EventId;
      entry.Priority = item.Priority;
      entry.Severity = item.Severity;
      entry.TimeStamp = item.TimeStamp;

      foreach (string category in item.Categories)
      {
        item.Categories.Add(category);
      }

      return entry;
    }

  }
}

The download contains the core library, two external façades (BitFactory, Enterprise Library), and a sample project. Hope you’ll like it

hardcodet-logging.zip codeproject

• Displays a nice looking ToolTip rather than just plain text.
• Optional lookup of strings in a resource dictionary to simplify localization.
• Optional title text.
• Very simple declaration.

Here’s what the XAML looks like:

<Image
  Source="..\Shared\Images\HelpSmall.png"
  ToolTip="{ext:Info Title=ShareNameTitleToolTip, Body=ShareNameInfoToolTip}"
  />

…and this is the output:

Creating the Popup Control

The first step is to create a simple control that contains the ToolTip. Basically, this is a simple UserControl with the following features:

• A grid with two rows. The first row contains just the title and is auto-sized to make sure it collapses if the title is not used at all.
• Two TextBlocks for title and body text.
• An image (I didn’t make that one bindable, I always use the same one).
• Two dependency properties that provide binding capabilities for header and body text.

Here’s what the control looks like in Blend:

Of course, you can easily use this user control through styles and/or directly declared in XAML whenever you need:

<Image Source="..\Shared\Images\HelpSmall.png">
  <Image.ToolTip>
    <MyToolTipControl Header="My Title" Body="This is a ToolTip" />
  </Image.ToolTip>
</Image>

However, this would still take a style to hide the tooltip border and you are lacking resource file lookups. The markup extension makes this way easier…

Implementing the Markup Extension

MarkupExtension is one of the lesser known stars in WPF - it requires a little coding, but once in place, it greatly simplify things for you. A simple yet brilliant example is Dr. WPF’s ValueConverter extension, and I already blogged a few times about other applications.

This Info markup extension basically provides the following:

• Two properties (Title and Body)
• Resource lookup with fallback mechanism (string is used directly if it’s not a resource key)
• ToolTip creation

/// <summary>
/// A markup extension that returns a
/// <see cref="InfoPopup"/> control preconfigured
/// with header and text information according to the
/// <see cref="Title"/> and <see cref="Body"/>
/// properties.
/// </summary>
public class Info : MarkupExtension
{
  /// <summary>
  /// Either a title text or a resource key that can be used
  /// to look up the title.
  /// </summary>
  public string Title { get; set; }

  /// <summary>
  /// Either a tooltips' main text or a resource key that can be used
  /// to look up the text.
  /// </summary>
  public string Body { get; set; }

  /// <summary>
  /// Empty default constructor.
  /// </summary>
  public Info()
  {
  }

  /// <summary>
  /// Inits the <see cref="Info"/> markup extension
  /// with the title and body.
  /// </summary>
  public Info(string title, string body)
  {
    Title = title;
    Body = body;
  }

  /// <summary>
  /// Performs a lookup for the defined <see cref="Title"/> and
  /// <see cref="Info"/> and creates the tooltip control.
  /// </summary>
  /// <returns>
  /// A tooltip control.
  /// </returns>
  public override object ProvideValue(IServiceProvider serviceProvider)
  {
    //create the user control that 
    InfoPopup popup = new InfoPopup();

    if (!String.IsNullOrEmpty(Title))
    {
      //look up title - if the string is not a
      //resource key, use it directly
      var result = Resources.ResourceManager.GetObject(Title) ?? Title;
      popup.HeaderText = (string)result;
    }

    if (!String.IsNullOrEmpty(Body))
    {
      //look up body text - if the string is not a
      //resource key, use it directly
      var result = Resources.ResourceManager.GetObject(Body) ?? Body;
      popup.BodyText = (string)result;
    }

    //create tooltip and make sure only the content is visible
    ToolTip tt = new ToolTip();
    tt.HasDropShadow = false;
    tt.BorderThickness = new Thickness(0);
    tt.Background = Brushes.Transparent;
    tt.Content = popup;

    return tt;
  }
}

Conclusion and Sample

This is only one of several ways to tackle the problem, but I really like that it only takes a single line to have a rich ToolTip in place. The implementation provided here may not completely suit your requirements, but it can easily be tailored to your needs.

The link below points to a sample project that contains both the markup extension and ToolTip control. Enjoy

tooltip-extension.zip

codeproject

<Window ...>
  <Grid>
    <Grid.Resources>
      <r:RibbonCommand
        x:Key="MyCommand"
        Executed="OnRibbonClicked"
        LabelTitle="Click Me" />
    </Grid.Resources>

    <!-- a ribbon that only displays a command in the quick access toolbar -->
    <r:Ribbon>
      <r:Ribbon.QuickAccessToolBar>
        <r:RibbonQuickAccessToolBar>
          <r:RibbonButton
            Command="{StaticResource MyCommand}"
            r:RibbonQuickAccessToolBar.Placement="InToolBar" />
        </r:RibbonQuickAccessToolBar>
      </r:Ribbon.QuickAccessToolBar>
    </r:Ribbon>
  </Grid>
</Window>

…and here’s the event listener that was declared for the RibbonCommand:

private void OnRibbonClicked(object sender, ExecutedRoutedEventArgs e)
{
  MessageBox.Show("Ribbon command executing.");
}

Once opened and closed, this window will not be garbage collected until the application shuts down. The reason is the OnRibbonClicked event handler that doesn’t get deregistered.

There are signs that Microsoft will dump RibbonCommand completely once the ribbon goes live. However: This probably won’t happen too fast, so you will have to solve the issue on your own. On the bright side: It forces a cleaner design on you.

I prefer custom commands anyway, so the natural way to go was to simply implement my own class that derives from RibbonCommand:

///<summary>
/// Base class for custom <see cref="RibbonCommand"/>
/// implementations.
///</summary>
public abstract class RibbonCommandBase : RibbonCommand
{
  /// <summary>
  /// Creates the command and registers weak event listeners.
  /// </summary>
  protected RibbonCommandBase()
  {
    Executed += OnExecute;
    CanExecute += OnCanExecute;
  }

  /// <summary>
  /// Determines whether the command can be executed or not.
  /// The default implementation always allows that.
  /// </summary>
  protected virtual void OnCanExecute(object sender, CanExecuteRoutedEventArgs e)
  {
    e.CanExecute = true;
  }

  /// <summary>
  /// Command implementation - executes command logic.
  /// </summary>
  protected abstract void OnExecute(object sender, ExecutedRoutedEventArgs e);
}

The noteworthy thing here is that this abstract base class registers event listeners for its own events - one virtual, one abstract. Accordingly, a deriving command implementation only has to provide its own OnExecute and OnCanExecute (optional) methods to get going:

public class MessageCommand : RibbonCommandBase
{
  protected override void OnExecute(object sender, ExecutedRoutedEventArgs e)
  {
    MessageBox.Show("Ribbon command executing.");
  }
}

The last thing to correct is the command declaration in XAML - rather than declaring a RibbonCommand with a code-behind event listener, you declare your custom command (MessageCommand in the sample below). As you can see, there is no longer a listener for the Executed event - the command takes care of this on its own. Accordingly, this command can be declared in a resource dictionary without a code-behind file.

<!-- Custom command - can be declared in a resource dictionary -->
<cmd:MessageCommand x:Key="MyCommand"
                    LabelTitle="Click Me"
                    SmallImageSource="About.png"
/>

Sample Project

The attached sample project shows the two variants and the missing garbage collection of the standard ribbon commands.

I wasn’t sure about licensing restrictions, therefore I did not include the WPF ribbon assembly in the downloadable sample - you’ll have to add the reference yourself before compiling. Sorry for the inconvenience :/

Download: ribbon-commands.zip

Laurent Bugnion has posted a great tutorial where he walks you through the various aspects of a magnifying glass behavior, and Jeremiah Morrill generates eye candy through a behavior that adds glass effects to your visuals.

Last but not least, the Expression team created a new section on the Expression Gallery that is dedicated to behaviors. I sure like shiny new toys