xFx How-To #2: creating a simple xFx plugin

[Stuart Booth]

Here's something for the curious. I've been asked a few times recently
how to go about creating a xFx-based xAPplication, e.g. one that sits
in a GUI like the xAP SlimServer Connector does:

<<a href="http://www.xapframework.net/modules.php?name=Sections&op=viewarticle&artid=9";>http://www.xapframework.net/modules.php?name=Sections&amp;op=viewarticle&amp;artid=9</a>>

This is reasonably straight-forward I think (but then I would do I
suppose!). So here's the start of a new technical note on an aspect of
xAPFramework that may be of interest to some. There are lots more
features you can make use of (which the SlimServer Connector does
extensively) but they're not needed right now (for example, how you
can 2x click an event message and display detailed information
including the actual xAP message if appropriate).

In this example I'm written a very, very simple xAPplication called
"xAP Echo Target" that echoes any xAP messages targetted directly
at
it back to the sender.

So if I sent out a message such as the following (note the Target
address):

xap-header
{
v=12
Hop=1
UID=FF123400
Class=xAP-OSD.Display
Source=KCSoft.Send.Anya
Target=KCSoft.EchoTarget.Anya
}
{ ... the body ... }

It will swap the Source/Target address around so as to send it from
the xAP Echo Target application back to its original source. This
conveniently avoids infinite network traffic.

xap-header
{
v=12
Hop=1
UID=FF123400
Class=xAP-OSD.Display
Source=KCSoft.EchoTarget.Anya
Target=KCSoft.Send.Anya
}
{ ... the body ... }

The C# code to achieve this, implemented as a xFx-based Plugin DLL is
as follows. The end results can be viewed here:

<a href="http://www.xapframework.net/xAPImages/SimplePlugin.jpg";>http://www.xapframework.net/xAPImages/SimplePlugin.jpg</a>

I was hoping to say you could compile this code up and drop it into
the SlimConnector's "Plugins" directory, but I discovered a
slight
buglette in the GUI plugin runtime. It's easily fixed with a few extra
lines of code here, but as they're unnecessary for the example I
decided to omit them.


using System;

using KCS.xAP.Framework.Message;
using KCS.xAP.Framework.Transport;
using KCS.xAP.Framework.Plugins;

namespace KCS.xAP.Applications.EchoTarget
{
[xAPPluginMessageHandler]
[xAPPluginDisplayName("xAP Echo Target")]
[xAPPluginServiceName("xAPEchoTarget")]
[xAPPluginServiceDisplayName("xAP Echo Target")]
[xAPPluginServiceDescription("Echoes messages targetted at the
application back
onto the xAP network.")]
[xAPPluginAppConfigSettingAttribute("xAPHeaderSourceVendor",
xAPHeaderSource.DEFAULT_SOURCE_VENDOR)]
[xAPPluginAppConfigSettingAttribute("xAPHeaderSourceDevice",
"EchoTarget")]
public class EchoTargetPlugin : xAPPluginModuleBase
{
protected override void MessageReceived (object sender,
xAPMessageEventArgs event_args)
{
try
{
if (event_args.Message.Header.Target != null &amp;&amp;

event_args.Message.Header.Target.CompareAddressTo(Heartbeat.Source))
{
OutputMessage(event_args.Message.Header.Class.ToString(),
event_args.Message.Header.Source.ToString());

xAPTargetAddress target = new xAPTargetAddress
(event_args.Message.Header.Source);
event_args.Message.Header.Target = target;
event_args.Message.Header.Source = Heartbeat.Source;

xAPSender.ApplicationSender.Send(event_args.Message);
}
}
catch (Exception exc)
{
OutputMessage(event_args.Message.Header.Class.ToString(),
exc.Message);
}
}
} // End of class EchoTargetPlugin
} // End of namespace

That's all that is required to achieve something as simple as this:

<a href="http://www.xapframework.net/xAPImages/SimplePlugin.jpg";>http://www.xapframework.net/xAPImages/SimplePlugin.jpg</a>

This can be loaded by the Console, GUI or Windows Service runtimes, so
you can deploy your application any way you wish. Multiple plugins can
even be combined together under the one 'shell' application.

A lot of common boilerplate code is implemented in the
xAPPluginModuleBase class, from xAPUtilities.DLL in xAPFramework.
Technically you just need to implement the IxAPPluginModule interface
on your plugin class, but I find it easier to inherit
xAPPluginModuleBase, which implements the IxAPPluginModule interface,
and then override MessageReceived() as you can see above.

The interesting stuff is probably the attributes that decorate the
class declaration above. I'll trot through them:

[xAPPluginMessageHandler]

This is the real magic flag as it identifies this class as a plugin
class to be loaded by the plugin manager. Add this attribute to your
IxAPPluginModule implementing class and you're more or less away.

[xAPPluginDisplayName("xAP Echo Target")]

This is just a pretty presentation name for the plugin when it gets
loaded. You can see how it gets used as the application title when the
plugin runtime engine detects only the single plugin.

[xAPPluginServiceName("xAPEchoTarget")]
[xAPPluginServiceDisplayName("xAP Echo Target")]
[xAPPluginServiceDescription("Echoes messages targetted at the
application back
onto the xAP network.")]

These are used when the plugin DLL is installed as a Windows Service
and should be fairly self explanatory. You can see these in the
Service Control Manager in Control Panel/Administrative Tools/Sevices
of your Windows OS.

[xAPPluginAppConfigSettingAttribute("xAPHeaderSourceVendor",
xAPHeaderSource.DEFAULT_SOURCE_VENDOR)]
[xAPPluginAppConfigSettingAttribute("xAPHeaderSourceDevice",
"EchoTarget")]

These two fix down the Vendor and Device addresses of your plugin
application. I've talked in the past about how to do this in code for
a standalone application to configure its own Vendor name, and an
appropriate device name. These achieve the same for plugins.

That's it really. The code in the MessageReceived() function should be
pretty clear I hope. This is exactly how the root of the SlimServer
Connector is implemented, although it's a whole lot more complicated
than the echo application above!

Any further queries/comments, fire away.

S
--
Stuart Booth <<a
href="/group/xAP_developer/post?postID=6-_Sfrsrr4DZGPKTdM2RJi2sgaI5CyQe9wMSEReED4TQbqu_I6HDKDywzaZbLQg3TD8QLYaejiPF8NCa8e2izxQ">stuart@x...</a>>
xAPFramework.net - a xAP software development framework for .net

<a href="http://www.xapautomation.org/";>http://www.xapautomation.org/</a>
<a href="http://www.xapframework.net/";>http://www.xapframework.net/</a>