Introduction

This isn't a detailed guide to the Wave Robot API - it's just enough to get you started. For more details, see the official Robot API documentation.

All of this may well change - and in particular there should be fewer hoops to jump through in future.

Prerequisites

To use the .NET Wave Robot API you must have:

• .NET 3.5 or equivalent (I haven't tested it under Mono yet, but I suspect it will work out of the box)
• An accessible ASP.NET server
• A Google AppEngine account
• The Python AppEngine SDK
• A Google Wave account
• Subversion
• A bit of patience

Overview

Currently, the Wave sandbox only allows for robots hosted on AppEngine. AppEngine doesn't host .NET applications, making life a bit trickier. We need to set up a proxying application on AppEngine which forwards requests to an ASP.NET server.

After that, we then need to set up the ASP.NET server to respond appropriately to the proxied Wave requests. This uses a custom HTTP handler, which for convenience we keep on the .ashx extension via a bit of proxy URL rewriting.

Setting up the proxying application

The basis of the proxy is Downy. Ignore the fact that it has anything to do with Mercurial - it's a proxy, which is all we need. Follow these steps:

• Download the three Downy source files in the proxy directory, and put them into a clean directory.
• Create a new AppEngine application
• Make the following changes to the Downy source code:
• Change app.yaml to reflect your AppEngine application name
• Change proxy.py and edit REMOTE_ROBOT to reflect your ASP.NET host and the robot handler you're going to use, e.g. http://demo.robotasp.net/WaveDemo/MyFirstRobot.ashx? - note the ? at the end, because we're going to proxy the main part of the path into the query string, which makes it easier to handle everything with a single HTTP handler on the ASP.NET side.
• Upload the application, following the normal Python SDK procedure. For example, on my box this was a case of running (from a command prompt in the relevant directory):

    python "c:\Program Files\Google\google_appengine\appcfg.py" update .

If you've got appropriate logging turned on at your ASP.NET website, you should now be able to see requests being made appropriately if you put the URL of your AppEngine application into your browser.

Building the Wave Robot API

This bit's easy. Check out the source (read-only is fine) into a new directory. Open the solution in Visual Studio and build it.

Creating your robot

Wave will make requests to three different URLs, relative to the one you specified for REMOTE_ROBOT:

• /_wave/capabilities.xml - defines what events the robot will respond to and the robot version number, as well as the profile information for the robot
• /_wave/profile - possibly old version of the profile information; expect this to be phased out
• /_wave/robot/jsonrpc.ashx - this is where the real work happens.

(The profile information is now available in the capabilities, and can be specified in an attribute, but Wave appears to ignore it at the time of this writing.)

The robot base class handles both the capabilities document and the JSON RPC call, based on the query string.

So, to get started:

• Add references to Google.Wave.Api.dll and Newtonsoft.Json.dll which will both be under the bin directory of the API source tree.
• Create a MyFirstRobot.ashx handler (Add / New Item / Generic Handler) at an appropriate place which matches the URL you used in the Python proxy code.

You can leave the MyFirstRobot.ashx file itself alone, but edit the MyFirstRobot.ashx.cs file.

• Make the new handler class derive from EventDrivenRobotBase. This in turn derives from RobotHttpHandlerBase, but it just means you don't need to explicitly state which events your robot is interested in. Instead, you just override the appropriate OnXxx methods and the API works out what's going on. You perform appropriate operations via the arguments to the methods you've overridden; the details of any changes you've made will then be sent back as JSON.

Here's a complete example based on the Java tutorial.

using Google.Wave.Api;

namespace CSharpInDepth.Wave
{
    /// <summary>
    /// The Parity robot.
    /// Like Parroty, but for .NET... so achieving parity with Java.
    /// </summary>
    public class Parity : EventDrivenRobotBase
    {
        protected override void OnWaveletSelfAdded(IEvent e)
        {
            IBlip blip = e.Wavelet.AppendBlip();
            ITextView textView = blip.Document;
            textView.Append("I'm alive and running in C#!");
        }

        protected override void OnWaveletParticipantsChanged(IEvent e)
        {
            IBlip blip = e.Wavelet.AppendBlip();
            ITextView textView = blip.Document;
            textView.Append("Hi, everybody from C#!");
        }
    }
}

Basically the .NET API is based on the Java one (it's pretty much a direct port with a few name changes to make it more like a normal .NET API) so anything you read about the Java API is worth trying in .NET too.

Testing your robot

To test your robot, you just need to invite it to a wave. Add it as a contact (e.g. demorobot@appspot.com) then create a new wave. When you invite it to the wave, it should respond with (for the demo code above):

• I'm alive and running in C#!
• Hi, everybody from C#!

Congratulations - if you've made it this far, I'd really appreciate it if you'd drop me an email (skeet@pobox.com) to let me know, including any suggestions for improving this little tutorial.