Using Microsoft Agent With C#

SrvEx.GetCharacterEx(dwCharID, out CharacterEx);
// Set event handler
Sink = new AgentEventHandler();
SrvEx.Register(Sink, out sinkID);
// Show the character.
// The first parameter determines whether or not the character is
// displayed by showing an animation.
CharacterEx.Show(0, out dwReqID);

This makes the character appear on the screen... so now let's make it do something more useful. The Speak method will make him speak (obviously), and the Play method will animate it in. In this case, it plays the "Greet" animation. For a complete list of animations, please refer to the MS Agent SDK documentation.

// Make the character speak
CharacterEx.Speak("Hello C-sharp world!", null, out dwReqID);
CharacterEx.Play("Greet", out dwReqID);
Position = new Point(100, 300);
Thread.Sleep(5000);

Included a "Position" Point object to make moving the Agent Character around the screen a little easier! Simply pass in the new coordinates, and off it goes.

// This object is can be used to move the character around the screen
public Point Position
{
    get
    {
        int x, y;
        CharacterEx.GetPosition(out x, out y);
        return new Point(x, y);
    }
    set
    {
        int nReqID;
        CharacterEx.MoveTo((short)value.X, (short)value.Y, 1000, out nReqID);
    }
}

it is also possible to directly modify the Character's speech bubble! This requires getting the IAgentBallonEx object for the Character and then calling the setter methods for the appropriate property such as Font, Style, etc.

// This object can be used to set the font, style, etc. of the speech bubble
public IAgentBalloonEx Balloon
{
    get
    {
        return (IAgentBalloonEx)CharacterEx;
    }
}

And that is essentially it! However, the Agent is not much use if it cannot respond to events. So as promised, here is how to make an event handler.

AgentEventHandler.cs

The main events handled by an Agent Character are via its IAgentNotifySink interface. We must first create a class that implements this interface, define all the methods, and then expand the events we are interested in catching.

using System;
using AgentServerObjects;
namespace AgentWindow
{
    /// <summary>
    /// Handles Events for the Agent
    /// </summary>
    public class AgentEventHandler : IAgentNotifySink
    {
        // Your code for the AgentEventHandler class goes here
    }
}

There are many methods in this interface, but by way of illustration, I expanded on the Click method that listens to see when a user performs a single mouse click on the Agent Character. In response to the event, I decided to simply show a message box.

public void Click(int dwCharID, short fwKeys, int x, int y)
{
    System.Windows.Forms.MessageBox.Show("You clicked on the agent", "Event");
}

The last but not least part of the exercise is to register the EventHandler. This is done in the AgentActivator class. Firstly by creating a new instance of the AgentEventHandler and then by calling the Register method on the server interface passing in the sinkID we defined earlier on.

public void Click(int dwCharID, short fwKeys, int x, int y)
{
    System.Windows.Forms.MessageBox.Show("You clicked on the agent", "Event");
}

And that is all there is to it! Of course, this example is not a very useful implementation of the Agent, but it illustrates how to form the basic requirements needed to include them in your applications.

Summary

This article explains how to include MS Agent into a simple Windows Form-based application using C#. The code is compiled using Visual Studio .Net and the released Microsoft (R) Visual C# Compiler Version 7.00.9466 [CLR version v1.0.3705] and tested on Windows 2000 Server SP2.