Writing Your First Add-in

To create an add-in for Messenger, you need to create a new Class Library project in Visual Studio (C# or VB, it doesn't matter). Be sure to use the same name that you want your Add-In's user to see. Messenger requires two names — the assembly name and the class name identifying your add-in; they must be the same, to prevent spoofing. In our case, we create a new Class Library with the name of "FirstAddin".

Next, we need to add a reference to the Messenger API. The API is contained in a single assembly in the Windows Live Messenger installation directory. By default, Messenger still uses the old MSN Messenger Directory, C:\Program Files\MSN Messenger.

You should add a reference to the MessengerClient.dll assembly, which contains several types that you will use to implement your add-in. Once you add the reference to the MessengerClient assembly, you can include or import the Microsoft.Messenger namespace into your main class. So your class should look like this, so far:

' VB
Imports Microsoft.Messenger

Public Class FirstAddin

End Class

// C#
using Microsoft.Messenger;

public class FirstAddin 
{
}

Inside the MessengerClient assembly is an interface that defines what an Add-In is required to implement. This interface is called IMessengerAddIn. This interface looks like so:

' VB
Public Interface IMessengerAddIn
  Sub Initialize(ByVal messenger As MessengerClient)
End Interface

// C#
public interface IMessengerAddIn
{
  void Initialize(MessengerClient messenger);
}

The interface specifies only a single method that needs to be implemented called Initialize that takes a MessengerClient object. To make your new class an add-in, implement the IMessengerAddin interface. Your code should looks something like this now:

' VB
Imports Microsoft.Messenger

Public Class FirstAddin
  Implements IMessengerAddIn

  Public Sub Initialize(ByVal messenger As MessengerClient) _
    Implements IMessengerAddIn.Initialize

  End Sub
End Class
// C#
using Microsoft.Messenger;

public class FirstAddin : IMessengerAddIn
{
  public void Initialize(MessengerClient messenger)
  {
  }
}

Figure 5: MessengerClient (VB)

This MessengerClient object is the entry point into writing your add-in. The MessengerClient object supports a number of methods, properties, and events to access different pieces of Messenger. Below is a class diagram of the MessengerClient class (Figure 5 is for VB, Figure 6 for C#):

Figure 6: MessengerClient (C#)

Now that we have implemented the Initialize call, we have an instance of the MessengerClient class. What can we do with it? First, keep a reference to the MessengerClient class in the class, so that we can use it later. We do this by adding a field for the MessengerClient object and store it in the Initialize method, like so:

' VB
Imports Microsoft.Messenger

Public Class FirstAddin
  Implements IMessengerAddIn

  Private _client As MessengerClient

  Public Sub Initialize(ByVal messenger As MessengerClient) _
    Implements Microsoft.Messenger.IMessengerAddIn.Initialize

    _client = messenger

  End Sub
End Class

// C#
using Microsoft.Messenger;

public class FirstAddin : IMessengerAddIn
{
  MessengerClient _client = null;

  public void Initialize(MessengerClient messenger)
  {
    _client = messenger;
  }
}

We should also set some properties on the MessengerClient object to tell Messenger a little about our add-in. We can do this by setting properties of the MessengerClient.AddInProperties property, which includes properties for FriendlyName, Creator, Description and URL of the add-in. You can set them like so:

' VB
_client.AddInProperties.FriendlyName = "FirstAddin"
_client.AddInProperties.Creator = "InformIT Reader"
_client.AddInProperties.Description = "This is a test of my first Addin"
_client.AddInProperties.Url = New Uri("http://adoguy.com")

// C#
_client.AddInProperties.FriendlyName = "FirstAddin";
_client.AddInProperties.Creator = "InformIT Reader";
_client.AddInProperties.Description = "This is a test of my first Addin";
_client.AddInProperties.Url = new Uri("http://adoguy.com");

The creamy center of the MessengerClient class is the events you can register for. For the purpose of this example, let's register for the IncomingTextMessage event to allow us to do something interesting when a new message comes in. In VB you would do this by adding the WithEvent keyword to the _client field, then adding a handler for the IncomingTextMessage event. In C#, you would do this by adding a handler in code to the event. Your code should look something like this now:

' VB
Public Class FirstAddin
  Implements IMessengerAddIn

  Private WithEvents _client As MessengerClient

  Public Sub Initialize(ByVal messenger As MessengerClient) _
    Implements Microsoft.Messenger.IMessengerAddIn.Initialize

    ' ...

  End Sub

  Private Sub _client_IncomingTextMessage(ByVal sender As Object, _
                                          ByVal e As IncomingTextMessageEventArgs) _
    Handles _client.IncomingTextMessage

  End Sub
End Class
// C#
public class FirstAddin : IMessengerAddIn, IDisposable
{
  MessengerClient _client = null;

  public void Initialize(MessengerClient messenger)
  {
    // ...

    // Subscribe to the events.
    _client.IncomingTextMessage +=
      new EventHandler(_client_IncomingMessage);
  }

  void _client_IncomingMessage(object sender, IncomingTextMessageEventArgs args)
  {
  }
}

When I use Messenger and I go to a full-screen application (e.g. Virtual PC, or World of Warcraft), Messenger marks me as busy by default. I like this behavior, but I don't want people that write to me in Messenger to think I am ignoring them; I can't see the messages because the full-screen program).

To address this, I wanted an add-in that would reply to a message with an apology if I was marked as Busy. We can do this because, when the incoming message is sent, we can ask the MessengerClient what our status is. We accomplish that by checking the LocalUser property of the MessengerClient. If we are marked as busy, then we can send a message back by using MessengerClient's SendTextMessage method. Your code might look something like this in the event handler:

' VB
Private Sub _client_IncomingTextMessage(ByVal sender As Object, _
                                    ByVal args As IncomingTextMessageEventArgs) _
  Handles _client.IncomingTextMessage

  ' If I am marked as Busy
  If _client.LocalUser.Status = UserStatus.Busy Then

    Dim msg As String
    msg = String.Format("Sorry {0}, I have a full-screen program running", _
                       args.UserFrom.FriendlyName)

    _client.SendTextMessage(msg, args.UserFrom)

  End If

End Sub

// C#
void _client_IncomingMessage(object sender, IncomingTextMessageEventArgs args)
{
  // If I am marked as Busy
  if (_client.LocalUser.Status == UserStatus.Busy)
  {
    String msg = string.Format("Sorry {0}, I have a full-screen program running",
                     args.UserFrom.FriendlyName);

    _client.SendTextMessage(msg, args.UserFrom);
  }
}

Figure 7: Personal Settings

Now that we have the functionality, we need to install our add-in. Open up Messenger, and look at your personal settings, which will look something like figure 7.

In the Add-Ins tab, pick "Add to Messenger," as seen in Figure 8:

Figure 8: Personal Settings

Navigate to your new project's bin directory, and pick the newly created add-in's DLL file. Once you do. the Add-Ins tab changes to what you see in Figure 9.

With the Add-In loaded, you can close this dialog. You should now be able to turn on the add-in through your personal menu. To test the add-in, set your status to "Busy" and have someone IM you.

Figure 9: Add-ins Tab with an Add-in Loaded

I used the Web Messenger to test it. When I send a message to my messenger window when I am busy, I get the response.

Figure 10 shows the add-in working.

Figure 10: The add-in in action

Note that the add-in reports that the add-in is the one actually responding. That can create a problem. If the other user is not using Windows Live Messenger (such as an older version of messenger, Yahoo Messenger, Web Messenger, or an open source solution like Trillian), it does not report that the add-in is the one replying. That isn't a big deal here, but it may be relevant to the add-ins you want to create.

The events that you can handle from Messenger are shown in Table 1:

Table 1: MessengerClient Events

Event	Description
IncomingTextMessage	Fired with a new message is received.
OutgoingTextMessage	Fired when a new message is sent.
StatusChanged	Fired when the status of the user (whether automatically or manually) changed.
ShowOptionsDialog	When the "Settings" button is selected for the add-in on the Add-ins Tab of the Personal Settings dialog.
Shutdown	When messenger is either being closed or when the current logged in user is logged out.

The example code includes examples for all these events.

Download the code for this project here.

With just a little work, you can make Windows Live Messenger do a lot of interesting things. By writing a simple .NET class library you can wrestle control from Messenger and get back in charge of your own instant messages.

For more information: Katie Blanch's MSDN Weblog discusses Messenger's programmability.

Discuss Writing Windows Live Messenger Add-ins with .NET   Vet man:O:D I use the following VB.net code within a addin class: Dim web As New... >>> Post your comment now!

>>> More Using VS Articles          >>> More By Shawn Wildermuth