Introduction
n order to run this example, you will need an MS Agent agent installed. Note that if you are using Windows 2000, this is installed by default.
Other operating systems will need it specifically installed.
MainWindow.cs
The simple Windows Form contains nothing revolutionary. It is a simple window with a help menu. The menu contains only one option - " Agent Help". The helpMenuItem_Click method triggers what we are really interested in.
private void helpMenuItem_Click(object sender, System.EventArgs e)
{
new AgentActivator();
}
AgentActivator.cs
This Class is essentially the workhorse of the program. Note the "using" statements we require for the MS Agent to function.
using System.Runtime.InteropServices;
using System.Threading;
using AgentServerObjects;
using AgentObjects;
The no-parameter constructor calls the StartAgent() method, which is responsible for creating the MS Agent. So let's walk through it.
Firstly, we need an object that will be used to hold our actual Agent character.
IAgentCharacterEx CharacterEx = null;
Now its time to create 3 ints to hold the Character ID, Request ID Sink ID, and an instance of the AgentServer, and return if this cannot be completed for whatever reason; otherwise, it will continue.
int dwCharID = 0, dwReqID = 0, sinkID = 0;
AgentServer Server = new AgentServer();
if (Server == null)
{
Console.WriteLine("STOP: The Agent Server could not start");
return;
}
Console.WriteLine("Agent Server created!");
Once we have the server object, we cast it to an IAgentEx interface that allows our application to load characters, receive events, and determine the state of the Agent Server. You would never do this in a real application, but I have hard-coded the specific Agent character I want to use. in this case, Peedy. However, feel free to change it to any of the others and give them a try.
genie.acs, Robby. acs, peedy.acs, merlin. acs are the four characters that are supplied by default. Toolkits, however, are available to create your own.
Once we have specified the character, we call the Load method on the Server Interface to load the character passing in the ints for the character and request IDs that the COM object expects; and catch any exceptions that are thrown.
Example. using an invalid character name.
IAgentEx SrvEx;
SrvEx = (IAgentEx)Server;
try
{
string CharacterFile = "peedy.acs";
SrvEx.Load(CharacterFile, out dwCharID, out dwReqID);
}
catch (Exception ex)
{
Console.WriteLine("Failed to load Agent character! Exception details:");
Console.WriteLine(ex);
}
Now that we have loaded a character, it's time to register an event handler (more on that later) and show him, her, or it to the world!! This is done simply by calling the GetCharacterEx method on the server, passing in the dwCharID and our previously defined CharacterEx holder object. Now we can simply call the show method on our CharacterEx object!
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.