Building your own Windows Live Messenger Events Agent

	This articles shows how to build a Windows Live Messenger Add-in that connects to Windows Sharepoint Services.
Paul-Valentin Borza Paul's Blog Difficulty: Intermediate Time Required: 1-3 hours Cost: Free Software: Visual Basic or Visual C# Express Editions, Windows Live Messenger, Windows Sharepoint Services 2.0 with Service Pack 2 Hardware: None Download: Download

Summary

The guide takes you on your new text-based adventure, as you'll learn to build a little gadget that will answer questions instead of you. This pretty piece of software is nothing more than a Windows Live Messenger Add-In that will register people for events that are tracked using Windows SharePoint Services. In the end, you'll be able to activate an agent on your messenger that will interact with your friends in live scenarios using text messages.

Introduction

Microsoft Windows SharePoint Services is a versatile technology that people can use to increase the efficiency of business processes and improve team productivity. Let's see how we can extend this wonderful technology: you are probably spending almost all your time online and using Windows Live Messenger to talk to your friends; more, you may be a very organized person that keeps track of every event (e.g. movie nights, snowboarding weekends etc.), so why not let your friends register for your events in a totally unique way. Sounds good? You'll even be able to supervise the conversation and supply answers to questions that your agent is not prepared to answer.

Prerequisites

Please download Windows Live Messenger and install it on your computer if you have not done so already. With Windows Live Messenger version 8, you can even talk with your Yahoo! friends; we'll talk about Windows Live Messenger and Yahoo! Messenger later on.
I hope you are already using Visual Studio Express C# or VB since you're on the Coding4Fun web site (you're ok with any choice, as the sample is available is both languages).
You'll also need a place to set up your Windows SharePoint Services; depending on your mood, two options are available:

1. You have Windows Server 2003 on your developer or on a near-by networked machine: just download Windows SharePoint Services with Service Pack 2 and go with the default installation.
2. You just don't want to install something new, or your machine is not running Windows Server 2003: you are lucky, because Microsoft and its partners offer you a Hosted Windows SharePoint Services 2.0 Trial, which is more than enough to get you started.

I personally tried them both and the project worked properly, so it's up to you. Now that you have everything up and ready, let's get started: it's Coding4Fun time!

Getting Started with Windows Live Messenger Add-Ins

From a developer's perspective, Windows Live Messenger delivers a great instant messaging platform that provides support for custom add-ins through its Messenger Add-In API. However, this is not available out of the box; to take advantage of this feature, we must explicitly tell Windows Live Messenger that we want to use add-ins by tweaking a registry key.
Open the Registry Editor and set HKEY_CURRENT_USER\Software\Microsoft\MSNMessenger\AddInFeatureEnabled to a DWORD entry with the value equal to 1. It's time to check whether the change in the registry caused the desired effect in your Personal Settings, as illustrated in [Fig. 1]. A new tab called Add-ins should be visible to you.

[Figure 1]

Getting Started with Windows SharePoint Services

Here, I'll try to make you understand how Windows SharePoint Services works. Please excuse me in case you find these obvious, or I'm repeating myself; it's better to clear things out from the early stages than getting into code and not understanding the basic concepts. Windows SharePoint Services is designed as a platform to support different types of sites, also named templates. Natively installed unique types in Windows SharePoint Services include the STS type, which defines the Team Site, Blank Site, and Document Workspace configurations, and the MPS type, which defines the Basic Meeting Workspace, Blank Meeting Workspace, Decision Meeting Workspace, Social Meeting Workspace, and Multipage Meeting Workspace configurations; throughout the tutorial, we are going to work only with Team Web Site and Basic Meeting Workspace.
Let's organize your default Team Web Site to be ready for use in the upcoming custom add-in; navigate to your default web site location, as shown in [Fig. 2].

[Figure 2]

Notice that the page contains several panels named Announcements, Events and Links; in SharePoint terms, these are called lists. We are going to work only with the Events list; you are not constrained to work only with these predefined lists, you can create your own or use other predefined lists at anytime; just needs a little more investigation from your side.

Adding a New Event to the Events List

It's simple to add a new event; just click Add new event below the Events list. You'll have to complete a three-page process in order to create a valid event.

1. Be sure to populate every field, regardless of what the red star character tells you; the Windows Live Messenger Add-In that we are building is going to use all of them. I have designed the add-in so that it works only with non-recurrent events. You are welcome to extend it to also work with recurrent events; I'll even tell you where you should modify the code to achieve that. Please consider special attention to the bottom Workspace check box.

   
   [Figure 3]

   You have to create a Meeting Workspace web site that associates with the event that you are currently adding. It's the only way you can keep track of attendees and other details. If you don't do this, you won't be able to register people for events or view attendees. Click Save and Close.
2. Since you checked the Workspace box, you will be taken to the second page where you can specify details (web site title, web site location etc.) for the Meeting Workspace. Leave everything as it is and click Ok. Notice that the Meeting Workspace that you are creating will be a sub-site of the site where the Events list is located. You are now starting to understand how Windows SharePoint Services works.
3. You are now going to select the template for this Meeting Workspace. Go with the Basic Meeting Workspace; this way, the predefined lists are already created for you, instead of a blank web site. Click Ok.

That's it! A new event that uses a Meeting Workspace should take you to the new workspace web site, like in [Fig. 4]. Again, you can see that the page contains several panels named Objectives, Attendees, Agenda and Document Library; these again are lists. At this point you got the idea: Windows SharePoint Services is made up from different types of sites (or sub-sites), and that each site (or sub-site) contains different types of lists depending on the template it's using.

[Figure 4]

The Attendees list already contains the email of the user who created it (that's me). When a friend of yours registers for an event (e.g. Microsoft Academic Tour), you should be able to see its email together with its response here. Every event has its own Meeting Workspace, so don't expect to see emails for all events here. Return to the Team Web Site Home (by clicking the Up to Team Web Site link located in the top-right corner) and repeat these steps as many times it's necessary. For example, you should add movie nights and snowboarding weekends as events; be sure to set up the occurrence date correctly as this is quite important when querying for events that occur within a week, month or year time.

Building the Windows Live Messenger Add-In

The current version of messenger provides only text message support for add-ins, although you have probably already seen that it's more than capable of handling sound and video when communicating with your friends; nevertheless it's enough for what we intend to build. Fire up your code editor, we're a step closer from writing code!
The add-in will be able to:

• Say hello to a contact with whom you have not talked with since the add-in was started.
• Detect the status (e.g. busy) of a contact.
• Show upcoming events based on predefined time intervals: week, month, year and all.
• Show details for events.
• Register contacts for events.
• Unregister contacts for events.
• Change your personal status message according on how many contacts have been registered. We won't change it when a contact unregisters; we don't want to make bad commercial.

Several basic requirements need to be met in order for an add-in to function as expected. Please note that they are already done and included in the sample. However, it's better for you to understand how it actually works and not just find them somewhere in the sample and wonder why did I do that:

• The add-in needs to use the MessengerClient.dll binary, so add a reference that points to it; it can be found in the default installation location %ProgramFiles%\MSN Messenger\MessengerClient.dll.
• Add-ins run under Code Access Security (CAS) and are not allowed to call any web service. Since our primary purpose is to work with Windows SharePoint Services web services, we need to override this behavior. We can achieve that by installing the assembly in the Global Assembly Cache (GAC); assemblies deployed in GAC must be Strong-Named Assemblies.
  • To digitally sign the assembly, go to Project Properties > Signing > Sign the assembly and check the box; choose or create a new strong name key file.
  • To install the assembly in the GAC you should use the developer tool named gacutil which is easily available in the Visual Studio 2005 Command Prompt. I used the build events to automatically install my assembly: go to Project Properties (in C#) or Project Properties > Compile (in VB) > Build Events > Post-build event command line and enter "$(DevEnvDir)..\..\SDK\v2.0\Bin\gacutil.exe" /i "$(TargetPath)". From now on, every time there is a successful build, the output assembly is automatically installed in the GAC for you; be sure to compile the project at least once before using the add-in with the messenger.
• The add-in is an assembly that contains a class that implements the Microsoft.Messenger.IMessengerAddIn interface. The messenger must know exactly what class to use, so the assembly name must be in Namespace.ClassName.dll format, where ClassName is the class that we talked about.

Exchanging Text Messages

By this time, it's clear that we are going to work with many text messages; it's always better to keep text that you're probably going to modify in the near future (you may even want to localize the messages in your language) in resources. We have several types of text messages, which all are located in Resources.resx:

1. The 1st table displays the commands that make the add-in take action; call them incoming text messages:

   Name	Value	Details
   ITextMessage_AllEvents	show events	Request to see all upcoming events.
   ITextMessage_YearEvents	show year events	Request to see all upcoming events in a year time.
   ITextMessage_MonthEvents	show month events	Request to see all upcoming events in a month time.
   ITextMessage_WeekEvents	show week events	Request to see all upcoming events in a week time.
   ITextMessage_EventDetails	show details for event [event_id]	Request to see details for a selected event.
   ITextMessage_RegisterForEvent	register for event [event_id]	Request to register for a selected event.
   ITextMessage_UnregisterForEvent	unregister for event [event_id]	Request to unregister for a selected event.
   ITextMessage_Help	help	Request to help.

   
   
2. The 2nd table displays the responses that the add-in will send back in reply to the previous incoming text messages; call them outgoing text messages:

   Name	Value	Details
   OTextMessage_Welcome	Hy {0}, I'm the Events Agent (*). Please ask me something like "show events", "show month events" or "help" etc.	Show that the add-in is alive and your friend is welcome to use it. {0} - your friend's name.
   OTextMessage_EndWelcome	I can see that you are not busy, so why not register for one of the events...	When your friend's status is other than busy.
   OTextMessage_BeginEvents	You are welcome to participate in {0} event(s):	{0} - number of events that matched your friend's query.
   OTextMessage_EventDescription	Event {0} - {1};	{0} - event id; {1} - event title.
   OTextMessage_EndEvents	You can view details and register for any event by saying something like "show details for event 2" and "register for event 2". Hope you register!	Show a tip to remind your friend how it can register for events.
   OTextMessage_ZeroAvailableEvents	I'm sorry , but no event matched your query... Please try to enlarge the time span.	When there is no event available that matched your friend's query.
   OTextMessage_EventDetails	Event {0} - {1} takes place on {2} in {3}.	{0} - event id; {1} - event title; {2} - event date; {3} - event location.
   OTextMessage_Help	You can talk to me by saying: show events, show year|month|week events, show details for event 2, register for event 1, unregister for event 2, help.	Show all available commands that the add-in is prepared to answer.
   OTextMessage_RegisteredForEvent	You have been successfully registered for event {0} - {1}.	{0} - event id; {1} - event title.
   OTextMessage_NotRegisteredForEvent	You don't seem to be registered for event {0} - {1}.	{0} - event id; {1} - event title.
   OTextMessage_UnregisteredForEvent	:-O It's a great event! I'm sorry you do not wish to attend anymore. You have been unregistered for event {0} - {1}.	{0} - event id; {1} - event title.
   OTextMessage_InvalidEvent	Sorry, you wanted to perform an action on an invalid event. Try to query for events first, like "show events" etc.	When your friend uses an invalid event.
   OTextMessage_Exception	Ooops! something unexpected happened while processing your request. The action was not completed. Use "help" in case you have any questions. Please try again later.	When an exception occurred; it can happen.

   In case you've seen awkward group of characters like :-O etc. and are wondering what they are, I'll tell you that they are emoticons; and yes, the messenger translates them into cool pictures.
   
3. The 3rd table displays Windows Live Messenger related customization:

   Name	Value	Details
   MessengerAddIn_Description	Windows Live Messenger + Windows SharePoint Services Events	The description of the add-in.
   MessengerAddIn_FriendlyName	Events Agent	The friendly name of the add-in.
   MessengerAddIn_PersonalStatusMessage	Register For Events Now!	Your default personal status message when the add-in starts.
   MessengerAddIn_PlusOnePersonalStatusMessage	+ {0} Person(s) Registered! Registration Is Open!	Your personal status message when you have at least one person registered. {0} - number of registered friends.

   
   
4. The 4th table displays Windows SharePoint Services related customization:

   Name	Value	Details
   SharePoint_AttendeesListName	Attendees	No need to change in case you went with the default installation.
   SharePoint_EventsListName	Events	No need to change in case you went with the default installation.
   SharePoint_MeetingSeriesListName	Meeting Series	No need to change in case you went with the default installation.
   SharePoint_ServerName	http://sharepoint.borza.ro	Modify to target your Windows SharePoint Services server name or web site that contains the Events list.

The following rule applies to all text messages that are sent in and out the network: a text message can have only 400 characters; in case a reply exceeds this limit, it won't send the text message, and you'll just wonder what happened. Take into account that a large number of events may increase the size of a query reply considerably. In case you have many events, you'll have to create a paging mechanism that meets your needs.

Consuming Windows SharePoint Services Web Services

There are many web services that can be used to work remotely with a deployment of Windows SharePoint Services: Administration, Alerts, Document Workspace, Forms, Imaging, List Data Retrieval, Lists, Meetings, Permissions etc; we are going to learn how to use Lists and Meetings web services, since these are the only ones we need. When adding web references to the web services, make sure you enter the URLs like these: http://ServerName/_vti_bin/Lists.asmx?WSDL and http://ServerName/_vti_bin/Meetings.asmx?WSDL. I know that you are eager to write some code; hang on, we are just one paragraph away from coding.

Looking at the Windows Live Messenger Add-In Code

I thought I would never reach the coding stuff... we'll start by looking at the way the add-in comes to life. In MessengerAddIn.cs or MessengerAddIn.vb, the class MessengerAddIn (to remind you, the assembly name is EventsAgent.MessengerAddIn.dll) is implementing the Microsoft.Messenger.IMessengerAddIn.

Visual C#

Visual Basic

Any class that implements this interface must also implement its Initialize method. The Initialize method is the first one which gets called when you click Turn on "Events Agent", as in [Fig. 5]; and receives the Windows Live Messenger client as an argument, which is saved in a local variable for use later on. One should use the initialization to properly change the friendly name, description and personal status message. The project only uses one messenger event, which is fired up each time a new text message arrives; in case you decide to use other events, just uncomment them.

Visual C#

Visual Basic

For handling incoming text messages, I have written and registered my own event handler. The event is raised regardless who sent the text message, so we need a way to track users: have we talked with a user before, what kind of query has the user previously made etc.; this is achieved using a dictionary having the user's unique id as key, and an instance of the Conversation class as value. On line 58 (in C#) or 52 (in VB) you can see how easy it is to detect the user's status - nothing complicated. Take care at: Windows Live Messenger Add-Ins ca only send a (one) text message as a reply to a (one) incoming text message, that's why I always use a return statement after I send a message (an exception is raised when you try to send multiple messages). I don't like this issue, you don't like it, but it keeps me and you secure from malicious add-ins.

Visual C#

Visual Basic

What happens when a friend of yours sends you a show events text message and the add-in intercepts it? When a text message validates the condition from line 78-79 (in C#) or 72-73 (in VB), SharePointWrapper.GetEvents (we'll talk about this later on) is called and used to complete the request; plus, a friendly text message that reflects the previous call is built and sent back. You must always send the reply to the user from which the request came from; otherwise, an exception will be thrown.

Visual C#

Visual Basic

The code that is executed when a user requests help, show events that occur in a week, month or year time is either similar with the previous code, or too simple and I'm not going to display it here. Instead, I'll show you what happens when a user requests to register for an event. A text message that would trigger the code looks like register for event 2; all I did was get the id from the incoming message and processed the request; the rest you'll understand as it looks almost the same. When a user wants to perform an action on an invalid event, the add-in notifies him or her of the mistake.

Visual C#

Visual Basic

Requests to unregister for events and show details for an event are similar and there is no reason to talk about them. Each task (request) uses its own method to create its reply - that's were many conditions are checked and a proper response is built. Be sure to download the sample, which is available in both languages and discover the hidden aspects for yourself.

Looking at the Windows SharePoint Services Wrapper Code

Most Windows SharePoint Services web services use as arguments Collaborative Application Markup Language (CAML), so they're quite flexible. In case you want to do more with SharePoint than I have done here, you'll have to learn CAML. It's important to notice that the authentication to the web service, located on line 46 (in C#) or 43 (in VB), is made through the GetSharePointCredentials method; don't forget to supply your credentials as described within the body of the method.

Depending on the time span, the appropriate CAML query is built - it checks for a greater date than now and a less date than the one specified in the query span.
Right now I can think of three methods to process the response from the web services: navigate your way using xpaths, work with datasets or... deserialize the response into objects. Although you have to write more code, deserialization brings a huge benefit - it's easier to work with later on; three classes were used to achieve that: SharePointListRoot, SharePointListData and SharePointListItem.

Visual C#

Visual Basic

When you want to add a new attendee, you basically need to add a new item to the Attendees list. A trick to notice: every site has its own web services, so you'll need to change the URL of the web service to target the web service of the workspace site that contains the Attendees list you want to modify; otherwise, a null reference exception will be raised. For example, a Team Web Site is not a Meeting Workspace and does not have a meetings web service. Always take care at this issue when you work with SharePoint web services.

Visual C#

Visual Basic

When a user wants to re-register for an event, we won't add it again to the Attendees list, because we would have duplicate items; instead, we are going to use the Meetings web service to set its response back from Declined to Accepted, or from Accepted to Declined, in the unregister case. Again, the URLs targeting the web services are set as they should be. This is one of the places you need to modify in order to make it work with non-recurrent events; check the comments within the code for more details.

Visual C#

Visual Basic

This concludes our overview of the code. Not every line of code is displayed here, but the number preceding each line of code is the actual line number from the sample code files; so, if you have any questions about the code you'll be able to find it in a snap.

It Works on Windows Live Messenger Network

Although you can talk with your Yahoo! friends using text messages, Windows Live Messenger Add-Ins do not work with Yahoo! contacts; in other words, the add-in won't receive the text messages from them, although you see them, so it does not have how to send text messages back. You'll have to find another suitable alternative for them to register for your events.
The usual way of testing a messenger add-in is to ask a friend of yours to send you text messages. Of course, you can have multiple Windows Live Ids and use Virtual PC to install and run more messengers; but hey, I did not want to do that. So, at one moment I had an interesting idea: why not make Encarta Instant Answers (which is a BOT) make it send me some text messages that matched my patterns (e.g. show events). In case you say to Encarta Instant Answers show events, it will respond with something like: Why must I show events? (the response you get may differ). It should have worked, but unfortunately it's the same as in the Yahoo! case.
The good news is that it works with your friends that are connected to the Windows Live Messenger Network using Pocket MSN. I was curious and tried MSN Messenger on a device running Windows Mobile 5.1 Pocket PC Phone Edition and it worked fine; I was able to interact with the add-in. Do not get me wrong, add-ins can be loaded only on a Windows Live Messenger, and not on a Pocket MSN.
And a dummy remark: people who use Windows Live Messenger have no problems using Windows Live Messenger Add-Ins.

Demo

In the end, I just want to show you how it works, because so far we have only talked around the subject without seeing it in action. Return to your Personal Settings > Add-ins, as illustrated in [Fig. 1] and click Add to Messenger; navigate to your sample installation folder and select the EventsAgent.MessengerAddIn.dll assembly. After completing this, the combo should have the Events Agent value; optionally, you may want to check the Automatically turn on this add-in when my status is anything other than Online or Appear Offline box. By clicking Turn on "Events Agent", like in [Fig. 6] you are activating your add-in and allowing it to interact with your friends, and this is what we expect it to do!

 
[Figure 5]

Before I give it a spin, please check my sample events that will be used to demonstrate the project. In [Fig. 6] you can see that I am using three events that occur at different time intervals, and all of them are using meeting workspaces to allow people to enroll in events as attendees.

[Figure 6]

It's spinning... in [Fig. 7] you can watch my conversation with one of my friends. A golden bar tells us that we have almost reached our goal; you'll be able to recognize text messages sent by the add-in when a message begins with a Paul-Valentin Borza's add-in "Events Agent" says: text.

[Figure 7]

Oh, you're right it's not my conversation - I haven't written a single word, or character: our project, the Windows Live Messenger Add-In Events Agent has done all the work for me. And that's great because that means my work here is done! Don't forget to look at the result: there are two attendees now.

[Figure 8]

Conclusion

I'm happy that you learned how to use and combine two powerful technologies: Windows Live Messenger Add-Ins and Windows SharePoint Services. You have built your own events agent that will serve you every time you start your favorite messenger. You'll now be able to show it to your friends while talking to them, from the same windows you have always did before! I'm sure they'll be quite surprised... mine were. You can try my events agent on my Windows Live Messenger Id windowslive@borza.ro; you'll even be able to talk with me in case you need any assistance.
Being at my second Coding4Fun article, I feel great when I can help people achieve a greater potential that has always been within their reach; and all of these happening while simply coding for fun. Thanks to the Microsoft Academic Program Team Romania for support.

Improvements

I encourage you to extend my work by:

• Making it say "Happy New Year!" in addition to the welcome message.
• Making it work with recurrent events.
• Using Credentials Management with .NET Framework 2.0 together with the project.
• Using the Messenger Activity SDK to further extend the agent, like Encarta Instant Answers does.
• Making it work with Windows SharePoint Services 3.0; please check the Windows SharePoint Services Version Comparison before.

Bio

Paul-Valentin Borza is in its second year of study at the Babes-Bolyai University of Cluj-Napoca, Faculty of Mathematics and Computer Science. Since 2005, he is involved in the Microsoft Student Partners - Microsoft Academic Program Romania. He can be reached through his web site at www.borza.ro.