A quick overview of how Windows Forms work with DSS services is appropriate at this point. In a normal Windows Forms application, all of the relevant code is often included directly in the form. However, for use with MRDS, "control" of the service is done in the main service implementation code and not the form.

Windows Forms operate off the main Win32 message queue for the application. They handle events such as MouseMove, ButtonClick, KeyDown, and so on. These events need to be sent back to the main DSS service (possibly after some pre-processing, or perhaps not at all if they only affect the internal state of the form).

Therefore, a port is created by the main service to allow the WinForm to send messages back to the main service. The message types have to be defined in the same way as they would for any service. In this sense, the WinForm acts something like an internal partner service, but it does not have a Proxy.

When it is necessary to execute some code in the context of the WinForm, the main service has to use an approach that is similar to PlatformInvoke for calling unmanaged code. This is done by sending a FormInvoke message to the WinFormsServicePort specifying a delegate to execute.

Windows Forms are in a sense "legacy" code. (Eventually, WinForms might disappear and be replaced by the new Windows Presentation Foundation, WPF. However, as of V1.5 of MRDS the WPF is not supported.) WinForms run in a Single-Threaded Apartment model and do not fit nicely into the multi-threaded model of the CCR. Because WinForms have thread affinity—i.e., they store state information into the thread's local store—they require special treatment. Therefore, Microsoft defined a WinFormsServicePort in the DsspServiceBase class that is used to control Windows Forms.

Following is a summary of the steps for adding a WinForm to your service (steps 2-4 are similar to setting up a new service):

This might seem like a daunting task, but once you get the hang of it you will find that it is not that complicated. These steps are explained in more detail in the following sections.

Creating a Windows Form and then setting it up to interact with your main service is a fairly involved process. However, once you have done it a couple of times you should not have any trouble.

As you saw in the last section, you need to add a reference to System.Windows.Forms to your project, and a using statement at the top of your code.

You create a new Windows Form for your service in exactly the same way as you do for any Visual Studio project, i.e., click Project Add Windows Form. Figure 4-5 shows the Add New Item dialog for adding the DriveControl Form to the TeleOperation project.

Figure 4.5. Figure 4-5

The TeleOperation service has two forms, each of which is associated with a source file where you place the event handlers:

For the DriveControl Form, then, at the top of the main service, you declare a variable to hold a handle (a reference to the class instance) for the Form, _driveControl, as well as a port for messages from the Form, _eventsPort:

// Handle to the main WinForm UI
DriveControl _driveControl;
// Port for the UI to send messages back to here (main service)
DriveControlEvents _eventsPort = new DriveControlEvents();

The DriveControlEvents class is discussed in the next section and is defined in DriveControl.cs. For now, you only need to know that it is a PortSet that enables the DriveControl Form to send information back to the main service.

There is nothing magical about these classes or variables. You can name them whatever you like, and you can change the messages that are accepted by the DriveControlEvents PortSet. This is just one example of how to implement communication between a service and a WinForm. Other samples in MRDS use different approaches. However, the authors believe this is a consistent and manageable approach.

In the Start method, you have to create a new instance of the DriveControl Form. (The WebCamForm is created only after a Webcam service has been found). This is done as follows:

// Create the WinForm UI
WinFormsServicePort.Post(new RunForm(CreateForm));

The RunForm message specifies a delegate to execute to create the new Form. This delegate should return a handle to the Form as follows:

System.Windows.Forms.Form CreateForm()
{
     // NOTE: Modify the constructor in the Form to pass these parameters
     return new DriveControl(_eventsPort, _state);
}

This routine is trivial and could be specified as an anonymous delegate in the RunForm message instead of as a separate method. If you are an experienced Windows Forms programmer, you might have noticed that the code does not save the handle to the new Form instance. It can be done here, but for illustrative purposes it is done later.

Note that when the DriveControl Form is created it is passed two parameters. Normally the constructor for a WinForm does not take any parameters. You must modify the automatically generated code for the Form to accept these parameters (in DriveControl.cs):

public partial class DriveControl: Form
{
    // This port is passed across to the constructor
    // It allows messages to be sent back to the main service
    DriveControlEvents _eventsPort;
    // This is part of the main service State
    GUIOptions options;

public DriveControl(DriveControlEvents EventsPort,
            TeleOperationState state)
    {
        InitializeComponent();

        // Remember the port to use to send back messages
        _eventsPort = EventsPort;

        // Copy the option settings
        options = state.Options;

All the constructor needs to do is copy the parameters to variables inside the Form. Other code within the Form can then use these variables as necessary. Clearly, the EventsPort is required so that the Form can post back messages to the main service. The reason for passing across the service state is not so obvious—it enables the Form to access the option settings that are stored in the config file.

You have not entirely finished with Form creation because you still need the Form handle. This last step is covered in the next section.

Information needs to be passed in both directions between the main service and the WinForm. This section discusses how to pass information in each of these directions and the different approaches required:

What FormInvoke does is execute code from the main service in the context of a WinForm. It does this by posting a message to the WinFormsServicePort, which means that the delegate executes asynchronously with respect to the caller. In other words, any code that follows a FormInvoke in the same routine cannot assume that the FormInvoke has completed execution.

A good example is the handler for axes updates from the game controller. This handler sends the new axes information to the DriveControl Form so that the onscreen trackball and the associated X, Y, and Z values can be updated:

IEnumerator<ITask> GameUpdateAxesHandler(game.UpdateAxes update)
{
      if (_driveControl != null)
      {
          WinFormsServicePort.FormInvoke(

delegate()
          {
               _driveControl.UpdateGameControllerAxes(update.Body);
          }
      );
  }
  yield break;
}

Note the following regarding the preceding code:

If you only want to read data, you can also extract information from the Form by grabbing the values of public properties in the Form. (Technically, you can also write to public variables, but then you might have concurrency issues). Visual Studio creates all controls on a Form as private properties, so you cannot access the controls directly. However, you can declare your own public properties, and many properties at the Form level are public.

The following code snippet is from the handler that saves the state to a config file:

// Grab the current window location
if (_driveControl != null)
{
    _state.Options.WindowStartX = _driveControl.Location.X;
    _state.Options.WindowStartY = _driveControl.Location.Y;
}

The Location.X and Location.Y properties are the screen coordinates of the top-left corner of the window. This enables the window to be started at the same position the next time the service is run. Note that gathering data this way is an on-demand approach, rather than an event-driven approach.

The basic process for communication from the Form back to the main service is via the Form's event handlers, which generate messages that are posted to the _eventsPort. Some events in the Form might not result in a message being sent, but instead set internal variables inside the Form, so there is no one-to-one correspondence between events and messages sent to the _eventsPort.

Strictly speaking, the _eventsPort is not necessary. You could define the requests that the DriveControl Form requires as additional operations on the main operations port for the service. However, it makes sense to separate WinForm interactions from the operations that the service provides because you don't want to expose these operations via the service Proxy. It also helps to make the WinForm handling code reusable.

Windows Forms often have dozens of controls. If you defined a message type for each possible event that could occur on the Form, it would quickly get out of hand. A better approach is to define a general class to handle WinForms interaction and then subclass this as necessary for message types that are specific to particular Forms. It is also advisable to try to group messages together to share message types.

Look in TeleOperationTypes.cs in the General Form Operations region at the bottom of the file:

#region General Form Operations
// This is the base class for all Form event messages
public class FormEvent
{
    private Form _theForm;

    public Form Form
    {
        get { return _theForm; }
        set { _theForm = value; }
    }

    public FormEvent(Form form)
    {
        _theForm = form;
    }
}

public class OnLoad: FormEvent
{
    public OnLoad(Form form)
        : base(form)
    {
    }
}

public class OnClosed: FormEvent
{
    public OnClosed(Form form)
        : base(form)
    {
    }
}

#endregion

The class called FormEvent is the base class for any event information that is passed back from a WinForm to the main service. This base class contains a property that identifies the WinForm by its handle. In the TeleOperation example, there are two WinForms.

Two other subclasses are also defined: OnLoad and OnClosed. These events are common to all WinForms so it is sensible to define them here. In the code for a WinForm, you add event handlers similar to the following. Notice that these handlers simply post a message of the appropriate type to the _eventsPort for the WinForm:

private void DriveControl_Load(object sender, EventArgs e)
{
    _eventsPort.Post(new OnLoad(this));
}

private void DriveControl_FormClosed(object sender, FormClosedEventArgs e)
{
    _eventsPort.Post(new OnClosed(this));
}

If you are not familiar with adding event handlers, follow these steps:

For buttons and other controls on the Form, you don't need to go to this much trouble because you can simply double-click the control in the Design View and the default event handler is added automatically. However, the keypress events cannot be added this way because there are no controls to click for keypress.

The OnLoad handler in the main service for OnLoad messages from the DriveControl Form is as follows (there is a different OnLoad handler for the WebCamForm):

/// <summary>
/// On Load Handler for completion of Form Load
/// </summary>
/// <param name="onLoad"></param>
/// <returns></returns>
IEnumerator<ITask> OnDriveControlLoadHandler(OnLoad onLoad)
{
    // Save a handle to the form
    _driveControl = (DriveControl)onLoad.Form;

    LogInfo("Drive Control Form Loaded");

    // Subscribe to the joystick
    yield return Arbiter.ExecuteToCompletion(Environment.TaskQueue,
        Arbiter.FromIteratorHandler(SubscribeToGameController));
}

This handler saves the Form handle at last. It is not necessary to do this here—it could have been saved when the Form was initially created, but it is done here as an example.

Then the handler tries to subscribe to a game controller. Other initialization can also be included at this point, such as updating labels or textbox controls on the Form with initial information. The main point to note is that this handler is not executed until the OnLoad message has been received, which is an indication that the Form has been created and is running.

The OnClosed event fires if the user clicks the Close button in the Form's title bar. There is no need to provide an Exit button on the Form, but one has been included as a convenience. The Exit button handler simply closes the Form, which fires the OnClosed event anyway, and this causes an OnClosed message to be sent to the main service.

The OnClosed handler in the main service attempts to shut down by posting a Drop message to itself. (The Drop handler is not discussed here).

/// <summary>
/// Form Closed Handler for when Drive Control Form has closed
/// </summary>
/// <param name="onClosed"></param>
void OnDriveControlClosedHandler(OnClosed onClosed)
{
    if (onClosed.Form == _driveControl)
    {
        LogInfo("Main Form Closed");

        // Send a Drop message to ourselves
        _mainPort.Post(new DsspDefaultDrop(DropRequestType.Instance));
    }
}

Notice here that the code checks the handle in the message against the handle in the Form to ensure that the message has been received from the correct Form. This isn't actually necessary, but it illustrates the point that one handler can potentially handle multiple Forms by using the Form handle to identify the Form.

If you refer back to Figure 4-6 you can see that there are event handlers for the KeyDown and KeyUp events. These handlers are used to enable you to drive the robot using the arrow keys on the keyboard. However, there are a couple of tricks involved in setting this up.

The keyboard handlers are in a region called Keyboard Handlers toward the bottom of the Form code, DriveControl.cs. Note that the event handlers were first created in the Properties panel by double-clicking the events, and then the code was added to each of the routines.

Start by looking at the KeyDown event handler:

#region Keyboard Handlers

// NOTE: The arrow keys will not normally appear in a KeyDown event.
// This is because they will be pre-processed. However, the operation
// under CF seems to be different and it does no harm to leave them
// in here anyway.

private void DriveControl_KeyDown(object sender, KeyEventArgs e)
{
    switch ((Keys)e.KeyValue)
    {
        case Keys.Up:
            Forward();
            e.Handled = true;
            break;

        case Keys.Down:
            Backward();
            e.Handled = true;
            break;

case Keys.Left:
            TurnLeft();
            e.Handled = true;
            break;

        case Keys.Right:
            TurnRight();
            e.Handled = true;
            break;

        default:
            break;
     }
  }

It turns out that this code is not responsible for the movements of the robot, even though it looks like it should be. It is called for keypresses in general, but not for the arrow keys. You could add other case statements to the switch to use alternative keys. For example, the A, S, D, and W keys are commonly used in first-person shooter games to move around.

Are you being misled? No. When you get to Chapter 16, you will find that Windows Mobile operates a little differently. In that case, the preceding code is called. The "arrow keys" on a PDA correspond to the "rocker switch" that is used to move the cursor around.

With desktop operating systems, you have to take a different approach to process the arrow keys. You first need to set the KeyPreview property on the Form to True. This indicates that you want to handle the "special" keys, rather than use the default handling. The arrow keys are normally used to move from one control to another, or to move side to side in a TextBox. By setting the KeyPreview flag, your code can take over.

Next, you must create a handler to override the default ProcessDialogKey method. Your handler can do whatever it likes with incoming keystrokes before they are passed on to the Form. If you wanted to be really nasty, you could throw away all "2" keystrokes and the poor users would think they had a broken key. Let's not do that.

ProcessDialogKey has to process the keys that it is interested in and return true to indicate that the keystrokes have been used up. Any keys that it is not interested in can just be passed to the original ProcessDialogKey handler, where they are processed as usual. In other words, you are intercepting keystrokes before they arrive at the Form:

// Overriding ProcessDialogKey allows us to trap the arrow keys
protected override bool ProcessDialogKey(Keys keyData)
{
    switch (keyData)
    {
        case Keys.Up:
            Forward();
            return true;

        case Keys.Down:

Backward();
            return true;

        case Keys.Left:
            TurnLeft();
            return true;

        case Keys.Right:
            TurnRight();
            return true;

        default:
            break;
    }

    return base.ProcessDialogKey(keyData);
}

Notice that the last step in the code is to pass the keyData back to the normal ProcessDialogKey handler and return whatever result it gives you. It is quite likely that the original ProcessDialogKey handler won't do anything with the keystroke (because it is not a special character), in which case it returns false and the keyData is sent to the Form for processing.

The functions that are called in response to each of the arrow keys are trivial, so only the Forward function is shown here:

void Forward()
{
    _eventsPort.Post(new OnMove(this,
      (int)options.MotionSpeed, (int)options.MotionSpeed));
}

It is worth noting here that MotionSpeed is an option setting. This is part of the service state, so it is saved in the config file. The Form doesn't have direct access to the service state, but the state is passed to the Form when it is created.

OnMove messages are processed in the main service by the following handler. As you would expect, it issues a SetDrivePower request to the differential drive:

/// <summary>
/// Handle basic moves (motor power settings)
/// </summary>
/// <param name="onMove"></param>
/// <returns></returns>
IEnumerator<ITask> OnMoveHandler(OnMove onMove)
{
    if (_drivePort != null)
    {
        // Create a drive request
        // There is a more concise syntax, but we need to access some
        // additional properties

drive.SetDrivePowerRequest request =
                new drive.SetDrivePowerRequest();
        request.LeftWheelPower =
                (double)onMove.Left * MOTOR_POWER_SCALE_FACTOR;
        request.RightWheelPower =
                (double)onMove.Right * MOTOR_POWER_SCALE_FACTOR;
        drive.SetDrivePower sdp = new drive.SetDrivePower(request);
        // Set a timeout so that this does not wait forever
        sdp.TimeSpan = TimeSpan.FromMilliseconds(1000);
        _drivePort.Post(sdp);

        yield return Arbiter.Choice(
                sdp.ResponsePort,
                delegate(DefaultUpdateResponseType response)
                {
                    //Console.WriteLine("Power updated");
                },
                delegate(Fault f)
                {
                    // Log an error (most probably a timeout)
                    LogError(f);
                    if (f.Code.Subcode.Value ==
                                DsspFaultCodes.ResponseTimeout)
                        Console.WriteLine("Timeout on Move");
                    else
                        Console.WriteLine(f.Detail);
                }
        );
    }
}

Another point to note about the SetDrivePower request is that a timeout is set on it. All DSS requests have a TimeSpan property. If you use a shorthand method for sending a request, rather than explicitly creating the request object, then you do not have the opportunity to set the TimeSpan. The code is therefore a little more involved.

It is important to have a timeout here so that the TeleOperation service doesn't hang. Some robot services are not well-behaved when something goes wrong with the robot. For example, try turning your robot off and see whether your service stops responding to requests.

The last point about this code is that the motor power settings from the Form are scaled by the MOTOR_POWER_SCALE_FACTOR, which is 0.001. This is because the Game Controller service sends axis values in the range −1000 to +1000. However, the SetDrivePower request must use values in the range −1.0 to +1.0.

At this point, the code gets the robot moving, but you also need to stop it. The simplest way to do this is to stop the robot as soon as the user releases the key. This means that as long as the arrow key is held down, the robot continues to move in that direction, which is intuitively easy to use.

The KeyUp event handler therefore calls Stop and is trivial:

private void DriveControl_KeyUp(object sender, KeyEventArgs e)
{
    Stop();
}

A KeyUp event occurs when any key is released. The handler for KeyUp immediately sends a Stop command without even determining which key was released.

While you are holding a key down, the keyboard automatically repeats the keystroke, typically a few times per second. These additional "keystrokes" simply execute the same KeyDown code, but they are not necessary for the process to work—the first KeyDown event starts the robot moving, and the key release stops it.

As noted above, if you are working with a PDA running Windows Mobile, only two event handlers (KeyDown and KeyUp) are required provided that you change the KeyPreview property for the Form to true. The ProcessDialogKey method is not required for Windows Mobile.

There are arrow buttons on the DriveControl Form for controlling the robot. The way that these work is actually quite simple: The event handlers for the buttons post messages to the main service, and the service posts appropriate messages to the differential drive.

Consider the event handler for the "Forward" button (the up arrow):

private void btnForward_Click(object sender, EventArgs e)
        {
            if (chkFixedMoves.Checked)
                _eventsPort.Post(new OnMotionCommand(this,
MOTION_COMMANDS.Translate, options.DriveDistance / 1000, options.MotionSpeed));
            else
                Forward();
        }

The code first checks whether the Fixed Moves checkbox is enabled or not. If it is, then DriveDistance and RotateDegrees are used to control the robot. These functions are handy because they only move the robot by a fixed amount and it can't run away from you. However, some robot services don't implement these functions, which would make the buttons useless.

Notice that there is another message type for the fixed motions called OnMotionCommand. The enum called MOTION_COMMANDS has three possible values: Translate, Rotate, and Stop. The second parameter to this request is a double that is either a distance or an angle (depending on the request type) and the last parameter is the drive power.

If the Fixed Moves checkbox is not clicked, the Forward method shown earlier is called. This just turns on the motors; you have to click the Stop button to stop the robot. In this mode, the buttons behave like they do in Robotics Tutorial 4, but they are much prettier buttons.

When you enter a URL that refers to a service into the address bar of a web browser, DssHost gets the state information from the service on your behalf and sends back a web page. You will see either some raw XML code or a nicely formatted web page.

If the service does not implement the HttpGet request type, then DssHost makes a Get request. If you have declared the HttpGet message type in your main operations port but you did not supply a handler, then the handler in the DsspServiceBase class is used instead.

*** Dssp Operation handler has been marked with the ServiceHandlerAttribute but
its operation type is not on the operations
port.Method:System.Collections.
Generic.IEnumerator`1[Microsoft.Ccr.Core.ITask] HttpGetHandler(Microsoft.Dss.Core.Dss
pHttp.HttpGet) [01/16/2008 17:42:56][http://koala:50000/teleoperation]

To see the difference between a formatted page and raw XML, follow these steps:

This displays the state as an XML file without using the XSLT file to format it. (It is the same as clicking the orange XML button in the top right-hand corner of the window in Figure 4-7). The XML code is as follows:

<?xml version="1.0" encoding="utf-8" ?>
<TeleOperationState
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
    xmlns:d="http://schemas.microsoft.com/xw/2004/10/dssp.html"
    xmlns="http://www.promrds.com/contracts/2008/01/teleoperation.html">
  <Host>localhost</Host>
  <Port>50001</Port>
  <Connected>true</Connected>
  <DriveService>dssp.tcp://koala:50001/simulateddifferentialdrive/ 

68d363c7-39a9-41b2-b90d-2e24a966015b/drive</DriveService>
  <WebCamService>dssp.tcp://koala:50001/simulatedwebcam/53f5c3a7-3f08- 

4f64-800f-8edddeabe68a/webcamservice</WebCamService>
  <Options>
    <WindowStartX>78</WindowStartX>
    <WindowStartY>51</WindowStartY>
    <WebCamStartX>415</WebCamStartX>
    <WebCamStartY>11</WebCamStartY>
    <DeadZoneX>200</DeadZoneX>
    <DeadZoneY>200</DeadZoneY>
    <TranslateScaleFactor>0.75</TranslateScaleFactor>
    <RotateScaleFactor>0.5</RotateScaleFactor>
    <MotionSpeed>500</MotionSpeed>
    <DriveDistance>300</DriveDistance>
    <RotateAngle>45</RotateAngle>
  </Options>
</TeleOperationState>

Which of these two versions, a formatted web page or raw XML, would you prefer to see as a user of the TeleOperation service? Obviously, a nicely formatted screen gives a more professional look to your service and is much easier to use.

Now that you have seen both the raw state information and a formatted web page, here is a summary of the steps for using a Web Form:

If you are an experienced web developer, you should find this process easy to follow. If not, please keep reading.

If you don't have a background in web development, then you might find this section useful. If you are already an experienced web developer, skim through to the next section (and ignore the little "white lies").

As you know, data is transferred in messages between services using XML (Extensible Markup Language). This is a much stricter language than HTML (Hypertext Markup Language), which is used for writing web pages. In particular, XML is case sensitive. It is assumed that you have some basic familiarity with HTML.

An XSLT file defines how to take an XML file as input and reformat it to create a new output file. Note that the output does not have to be HTML, although this is usually the case. In theory, XSLT can be used to create a PDF file, a Word document, and so on. The definition of XSLT can be found on the World Wide Web Consortium website at www.w3.org/TR/xslt.

A lot of the code in an XSLT file is just HTML, which is destined to be displayed on the output page. Embedded in this are <xsl> elements that control what information from the XML data stream is displayed, such as the <xsl:value-of> element, which displays a value by name.

Visual Studio understands XSL syntax, so when you open an XSLT file you can use IntelliSense and the online help. For example, when you enter <xsl:, Visual Studio pops up a list of available XSL elements (as soon as you press the ":" key).

XSL includes logic and repetition elements, such as <xsl:if>, <xsl:choose>, and <xsl:for-each>. You can even create variables in XSL. Place the cursor over one of these commands in the editor in Visual Studio and press F1 to view the online help.

Before you start working with XSLT, you should follow the instructions provided in this section. They will help you to set up your environment, and they explain a little bit about how XSLT is used by MRDS.

By saving these files to your hard drive, you avoid some other error messages that appear if you try to edit an XSLT file. This step is not essential, but it gets rid of some annoying errors.

If you are interested, there are other embedded resources for MRDS that you can examine using a web browser:

http://localhost:50000/resources/dss/Microsoft.Dss.Runtime.Home.Styles.Common.css
http://localhost:50000/resources/dss/Microsoft.Dss.Runtime.Home.JavaScript
.Common.js

There are also some images that are not listed here, but you don't need them. Unfortunately, you cannot simply browse /resources/dss to view the available embedded resources. In order to see an embedded resource, you must know its full URI. Otherwise, DssHost presents you with a blank page.

To use an XSLT file to display your service state you have two options:

From here on, the examples use embedded resources because this is the authors' preferred approach. The format of the URI for embedded resources is as follows:

/resources/Assembly-Name/Default-Namespace.Path.Filename

You can open the project properties for your service and look on the Application tab to find the assembly name and the default namespace. If your XSLT file is in the same folder as the rest of your source files, then there is no Path. The Filename is just the name of the XSLT file. The URI is not case sensitive.

It is common practice to locate XSLT files in a Resources subfolder under your source directory. The TeleOperation service follows this convention, so the full URI for the XSLT file is as follows (ignoring the wrap-around):

/resources/TeleOperation.y2008.m01/ProMRDS.Robotics.TeleOperation.

Resources.TeleOperation.xslt

To create a new XSLT file you have two options:

Obviously, this section covers building the XSLT file from scratch; the next section discusses using the MRDS template. If you want to start with a blank file and embed it in your service assembly, proceed as follows:

The service contract identifier is listed as one of the xmlns (XML namespace) parameters at the top of the file using the alias svc so that you can easily refer to it throughout the rest of the file. In the <xsl:template> element, the match attribute specifies the ServiceState. This must be the actual class name of your service state. Remember that the XML file output by your service is a serialized version of the service state.

Inside the template section is a complete HTML page. Property values are displayed from the state using the <xsl:value-of> element. All properties must be referred to using a full URI. This is why they are shown as svc:property1 and svc:property2. If you use nested structures within your state, then you cannot just use the "dot notation" that you use in C#. For example, the state for the TeleOperation service contains a class called Options, which in turn contains a number of other properties. To access Options.MotionSpeed you must write the following:

<xsl:value-of select="svc:Options/svc:MotionSpeed"/>

Notice that a slash (/) replaces the dot (.) in the property name and that the contract identifier (svc:) is repeated. If you make a mistake in the syntax of the select attribute, the value quietly disappears. No errors are reported—the value is just missing from the web page.

In addition to formatting the layout of your state properties using XSLT, you can use a Cascading Style Sheet (CSS) file to control the formatting of the HTML tags, i.e., the appearance of the elements on the page.

A CSS file can be embedded in your service in exactly the same way as an XSLT file. (Add it to your project and then mark it as an embedded resource). Then you just need to know the appropriate URI. In the preceding example, the built-in MRDS Cascading Style Sheet is used for formatting. The full URI for this is in the href attribute of the <link> tag. This MRDS CSS file defines the odd and even classes that are used on the table rows to make them easier to read by changing the background highlighting.

If you want to save yourself some time and promote page uniformity, instead of building an XSLT file from scratch as shown in the last section, you can always create one using the MRDS template. To use the MRDS template, follow these steps:

Notice that the TeleOperation service displays an icon in the page header (in the preceding code) by adding an image to the serviceName variable. (Ignore the wrap-around in the URI).

In the MRDS template, you can either define CSS styles directly (between the <style> tags) or include a style sheet file. Look at the comments carefully. They indicate that the head parameter is placed in the HTML <head> section of the web page, and there is also a comment showing where to insert style definitions directly.

In the following example, an embedded style sheet file is used:

<!-- The contents of head param will be placed just before the </head> tag in 

html. -->

<xsl:with-param name="head">

   <link rel="stylesheet" href="/resources/teleoperation.y2008.m01/ProMRDS.Robotics 

.TeleOperation.Resources.TeleOperation.css" type="text/css" />
    <style type="text/css">
       /* Service-specific stylesheet goes here */
    </style>

Using your own style sheet means that your page might not have the same appearance as other MRDS pages. Notice here that the CSS file is also an embedded resource in the Resources folder of the project. The standard MRDS style sheet is automatically included by the master page.

At the bottom of the first template is another <xsl:template> section. You need to change the match criterion from /svc:Template to use the correct name for your service state class. This is shown in the following example (ignore the <form> tag for now, as it is discussed later):

<xsl:template match="/svc:TeleOperationState">
   <form name="DssForm" method="post" onsubmit="return checkform(this);">
     <div class="Content">
   <table width="100%" border="0" cellpadding="5" cellspacing="5">
     <tr>
       <th>Host:</th>
       <td>
         <xsl:value-of select="svc:Host"/>
       </td>
     </tr>
     <tr>
       <th>Port:</th>
       <td>
         <xsl:value-of select="svc:Port"/>
       </td>
     </tr>
     <tr>
       <th>Connected:</th>
       <td>
         <xsl:choose>
           <xsl:when test="svc:Connected = 'true'">
             Connection established
           </xsl:when>
           <xsl:otherwise>
             Not connected
             (<b>Tip:</b>
             <span class="greyText">
               Enter a Host name and a Port and click on Connect
             </span>)
           </xsl:otherwise>
         </xsl:choose>
       </td>
     </tr>
...
     <tr>
       <th colspan="2">Option Settings</th>

</tr>
          <tr>
            <th>Main Window Start Position</th>
            <td><xsl:value-of select="svc:Options/svc:WindowStartX"/>,

 <xsl:value-of select="svc:Options/svc:WindowStartY"/> (Saved automatically)
          </td>
        </tr>
      <tr>
 ...
    </table>
    </div>
    </form>
  </xsl:template>
</xsl:stylesheet>

For this code, note the following:

The best way to learn how to create XSLT code is probably to look at existing files. Search the MRDS samples folder for XSLT files.

You are not finished yet. To display your state using XSLT, you must create a handler for HttpGet requests and add this message type to your main operations port (if it is not there already). The handler specifies the XSLT file when it returns the state.

To refer to your embedded XSLT file in the HttpGet handler, you define a string variable at the top of the source file. It is usually called _transform, but it doesn't have to be. You can use the [EmbeddedResource] attribute to construct the full URI for the XSLT file as shown here for the TeleOperation service:

/// <summary>
    /// Embedded XSLT file for formatting State on a web page
    /// </summary>
[EmbeddedResource("ProMRDS.Robotics.TeleOperation.Resources.TeleOperation.xslt")]
    string _transform = null;

The appropriate prefix is added to the URI and the resulting string is assigned to _transform when you compile the code.

The code for the HttpGet handler is quite simple:

/// <summary>
/// HttpGet Handler
/// </summary>
/// <param name="get"></param>
/// <returns></returns>
[ServiceHandler(ServiceHandlerBehavior.Concurrent)]
public virtual IEnumerator<ITask> HttpGetHandler(HttpGet httpGet)
{
    // Format the response using a transform
    httpGet.ResponsePort.Post(new HttpResponseType(
        HttpStatusCode.OK,
        _state,
        _transform)
    );
    yield break;
}

The response posted back is created using _state and _transform.

That's all there is to formatting your state information. However, if you make a mistake in the URI of your XSLT file in the [EmbeddedResource] attribute, you might see an error like the one shown in Figure 4-8.

Figure 4.8. Figure 4-8

You can check whether your embedded XSLT file is present in your assembly by entering the full URI into the address bar of the web browser. If it is not found, a blank page is displayed. In that case, you need to double-check your spelling, the path, and the placement of dots. The URI is not case sensitive, so that cannot be the problem.

Creating a Web Form is not much different from what you have already seen except that you wrap your HTML code in a <form> tag and put the property values into <input> tags. You also have to add a Submit button; otherwise, there is no way to post the Form! If you are familiar with web development, then you should not have any trouble:

The Submit (Save) button is visible at the very bottom of Figure 4-9.

Figure 4.9. Figure 4-9

Notice in Figure 4-9 that the values above the Option Settings heading cannot be edited; they are for informational purposes only. The window positions cannot be edited either. They are obtained directly from the windows, so you just need to position the windows where you want them before you save the state.

All of the remaining properties have textboxes for entering new values. It is possible to make them right-aligned, but this has not been done. It is simply a matter of changing the TextBox style in the CSS file.

You can have more than one <form> tag on a web page, and you can have more than one Submit button in a Form (with different names). In that case, the code in your HttpPost handler needs to check the Form name and/or the Submit button name.

After you click Save, the data is sent in an HttpPost request to your handler. Before looking at the handler though, you need to add some support utilities. At the top of the service, add the following statement:

DsspHttpUtilitiesPort _httpUtilities;

This port can be used to request support services for processing HTTP forms. Do not be tempted to create a new port like this:

DsspHttpUtilitiesPort _httpUtilities = new DsspHttpUtilitiesPort();

Using new does not work. The new port must be created in the Start method:

// Needed for HttpPost
_httpUtilities = DsspHttpUtilitiesService.Create(Environment);

The TeleOperation HttpPost handler begins like this:

/// <summary>
/// Http Post Handler for Web Form inputs
/// </summary>
[ServiceHandler(ServiceHandlerBehavior.Concurrent)]
public virtual IEnumerator<ITask> HttpPostHandler(HttpPost httpPost)
{
    string ErrorMessage = String.Empty;
    Fault fault = null;
    NameValueCollection parameters = new NameValueCollection();

    // Use helper to read form data
    ReadFormData readForm = new ReadFormData(httpPost.Body.Context);
    _httpUtilities.Post(readForm);

    // Wait for result
    yield return Arbiter.Choice(
        readForm.ResultPort,
        delegate(NameValueCollection col)
        {
            parameters = col;
        },
        delegate(Exception e)
        {
            fault = Fault.FromException(e);
            LogError(null, "Error processing form data", fault);
            ErrorMessage += e.Message;
        }
    );

    if (fault != null)
    {
        httpPost.ResponsePort.Post(fault);
        yield break;
    }

The first thing the handler does is send a ReadFormData request to the HTTP utilities. Because the utilities operate like a service, you have to wait for a response and be prepared to handle a Fault.

There is an alternative to using these utilities: You can write your own code to extract the form parameters. The following code is not seriously proposed as a replacement, but it shows how the parameters are obtained. The code performs no error handling, and it fails if the total amount of data exceeds 10K:

NameValueCollection parameters = new NameValueCollection();
            // Extract the parameters from the Request data stream
            int length = 0;
            byte[] data = new byte[10240];
            length = httpPost.Body.Context.Request.InputStream.Read(

data, 0, 10240);
            StringBuilder sb = new StringBuilder();
            for (int i = 0; i < length; i++)
                sb.Append((char)data[i]);

            string request = sb.ToString();
            char[] ampersand = { '&' };
            char[] equals = { '=' };
            string[] pairs = request.Split(ampersand);
            for (int i = 0; i < pairs.Length; i++)
            {
                 string[] namevalue = pairs[i].Split(equals);
                 parameters.Add(namevalue[0], namevalue[1]);
            }

Each of the parameters is checked in turn to see if it is valid. You must do this even if you use client-side validation in JavaScript because users can turn off JavaScript in their web browsers. For example, the following code confirms that the user entered a valid number for MotionSpeed:

double MotionSpeed = _state.Options.MotionSpeed;
bool validValue = false;

if (!string.IsNullOrEmpty(parameters["MotionSpeed"]))
{
    try
    {
        MotionSpeed = double.Parse(parameters["MotionSpeed"]);
        validValue = true;
    }
    catch (Exception e)
    {
        string msg = "Could not parse Motion Speed: " + e.Message;
        LogError(msg);
        ErrorMessage += msg;
    }
}

if (validValue && MotionSpeed >= 10 && MotionSpeed <= 1000)
{
    _state.Options.MotionSpeed = MotionSpeed;
}

The code also checks whether MotionSpeed is within a reasonable range, and finally assigns the new value to the property in the state. (Because it modifies the state, the HttpPost handler should be Exclusive. However, most implementations mark it as a Concurrent handler. Make sure that you mark it as Exclusive if it changes the state.)

Similar checks are performed for the rest of the properties. Notice that any error messages are appended to the ErrorMessage variable. Once all of the updates have completed, it is a simple matter to determine whether the ErrorMessage is empty and call the appropriate routine to post success or failure:

// Finally, process the result
    if (ErrorMessage == string.Empty)
    {
        HttpPostSuccess(httpPost);
    }
    else
    {
       HttpPostFailure(httpPost, ErrorMessage);
    }

    yield break;
}

The HttpPostSuccess routine does not require much comment. Just note that it saves the option settings back into public variables in the WinForms if they are active. In effect, it passes information from the main service to the WinForms. Then it saves the state to a config file:

/// <summary>
/// Send Http Post Success Response
/// </summary>
private void HttpPostSuccess(HttpPost httpPost)
{
    // Grab the current window location
    if (_driveControl != null)
    {
        _state.Options.WindowStartX = _driveControl.Location.X;
        _state.Options.WindowStartY = _driveControl.Location.Y;
    }
    if (_cameraForm != null)
    {
        _state.Options.WebCamStartX = _cameraForm.Location.X;
        _state.Options.WebCamStartY = _cameraForm.Location.Y;
    }

    // Update the Forms with the new option settings
    // This is another implicit method of communication with WinForms
    if (_driveControl != null)
        _driveControl.options = _state.Options;
    if (_cameraForm != null)
        _cameraForm.options = _state.Options;

    // Post a response
    HttpResponseType rsp =
        new HttpResponseType(HttpStatusCode.OK, _state, _transform);

httpPost.ResponsePort.Post(rsp);

    // Save the state now because it might have changed
    SaveState(_state);
}

Conversely, the HttpPostFailure routine does require some explanation. If it simply posts back a Fault (as in the code that is commented out), then XML code is displayed on the screen. Instead, it posts a Fault response but specifies an XSLT file (_faultTransform):

/// <summary>
        /// Send Http Post Failure Response
        /// </summary>
        private void HttpPostFailure(HttpPost httpPost, string failureReason)
        {
            // Create a new Fault based on the error message
            Fault fault = Fault.FromCodeSubcodeReason(FaultCodes.Receiver, 

DsspFaultCodes.OperationFailed, failureReason);

            //HttpResponseType rsp = new HttpResponseType(fault);
            //httpPost.ResponsePort.Post(rsp);

            // Post it back but use the Fault Transform
            httpPost.ResponsePort.Post(new HttpResponseType(
                HttpStatusCode.OK,
                fault,
                _faultTransform
                )
            );
        }

The Fault.xslt file isn't covered here. It formats a standard SOAP fault (which is an XML message) and provides a couple of buttons so that users are not left at a dead end with nowhere to go. You can examine this file yourself.

A Web Forms approach whereby all the data on the Form is sent to the web server for validation does not result in a good user experience. It is much better to have JavaScript code in the Form to do validation prior to submitting the Form.

If you do not already know JavaScript, it might be a good investment in your job skills because it is a key component of web development. Numerous websites on the Internet offer tutorials on JavaScript, such as www.w3schools.com/js/default.asp. Because it is a C-like language, you should not have trouble learning enough to do basic validation. There are also websites that provide JavaScript code for a variety of tasks, such as www.dynamicdrive.com.

The position in the XSLT file where you place your JavaScript code is indicated quite clearly in the comments in the template. You can either enter the code directly into the XSLT file or create another embedded resource and add your own <script> tag to reference it as follows:

<script language="javascript" type="text/javascript" src="URI-for-JS-file" />

In TeleOperation.xslt you can see the validation code, which is split across two routines. The first routine, simply called validate, is used to confirm that a value is numeric and falls within a specified range:

// Check that a value is numeric and within a specified range
// Returns a string which is either empty or an error message
function validate(val, fieldname, minval, maxval)
{
   var msg = "";
   var num;
   if (val.length == 0)
   {
       msg += "Please enter a value for " + fieldname + "
";
   }
   else
   {
     num = parseFloat(val);
     if (isNaN(num))
       msg += fieldname + " must be a number
";
     else if (num < minval || num >= maxval)
      msg += fieldname + " is out of range (" + minval + " to " + maxval +")
";
   }
   return msg;
}

The validate function returns an error message if there is one, or an empty string. It is called by the checkform routine:

// Check the form before submission
// NOTE: Return true if OK to proceed, or false if there are errors
function checkform(f)
{
   var msg = "";

   // Accumulate all of the error messages (if there are any)
   msg += validate(f.DeadZoneX.value, "Dead Zone X", 0, 900);
   msg += validate(f.DeadZoneY.value, "Dead Zone Y", 0, 900);
   msg += validate(f.TranslateScaleFactor.value, "Translate Scale Factor", 

0.01, 100);
   msg += validate(f.RotateScaleFactor.value, "Rotate Scale Factor", 0.01, 100);
   msg += validate(f.MotionSpeed.value, "Motion Speed", 10, 1000);
   msg += validate(f.DriveDistance.value, "Drive Distance", 10, 2000);
   msg += validate(f.RotateAngle.value, "Rotate Angle", 5, 360);

   // If there were any errors at all, display them
   if (msg != "")
   {
     // Pop up a dialog to tell the user what is wrong
     alert(msg);
     return false;
   }

   // If we got here, then the data is OK
   return true;
}

In addition, you need to modify the <form> tag so that the validation routine is called prior to the Form being submitted. To do this, add the onsubmit attribute to the tag:

<form name="DssForm" method="post" onsubmit="return checkform(this);">

Note the syntax used in the onsubmit attribute—you must return the Boolean value from checkform so that the Form submission can either proceed or be suppressed. In addition, note that JavaScript is case sensitive, so if you write "return CheckForm(this);", you will receive an error when you try to submit the Form.

Validating Form data this way cannot catch every possible type of error. There might still be errors that occur only after the Form has been submitted and the service has had a chance to process it. In any case, the user can turn off JavaScript in the web browser, so you always have to check on the server side. This is just basic Web Development 101.

OnConnectHandler searches the directory on the specified remote host (it does not have to be localhost) for generic Differential Drive and Webcam services. It is possible that there are no matching services, so this must be taken into account:

/// <summary>
        /// Connect Handler
        /// </summary>
        /// <param name="onConnect"></param>
        /// <returns></returns>
        IEnumerator<ITask> OnConnectHandler(OnConnect onConnect)
        {
            if (onConnect.Form == _driveControl)
            {
                string ErrorMessage = null;

                // The service here is the Directory on the specified host:port
                UriBuilder builder = new UriBuilder(onConnect.Service);
                builder.Scheme = new Uri(ServiceInfo.Service).Scheme;

                ds.DirectoryPort port = 

ServiceForwarder<ds.DirectoryPort>(builder.Uri);
                ds.Get get = new ds.Get();

                port.Post(get);
                ServiceInfoType[] list = null;

                yield return Arbiter.Choice(get.ResponsePort,
                    delegate(ds.GetResponseType response)

{
                    list = response.RecordList;
                },
                delegate(Fault fault)
                {
                    list = new ServiceInfoType[0];
                    LogError(fault);
                }
        );

If you did not have to allow for the possibility of remote hosts, then it would not be necessary to create a ServiceForwarder for the directory service. Instead, you could just use the DirectoryPort, which is defined in the DsspServiceBase class.

A simple Get request to the directory service returns an array of ServiceInfoType records. The code extracts the host name and port number from the first record, although this is not really necessary. It also handles the situation where no services are found:

ServiceInfoType driveInfo = null;
ServiceInfoType webcamInfo = null;

try
{
    if (list.Length > 0)
    {
        UriBuilder node = new UriBuilder(list[0].Service);
        node.Path = null;
        string nodestring = node.Host + ":" + node.Port;
        LogInfo(nodestring);
    }
    else
    {
        LogError("No services found!");
        ErrorMessage = "No services found!
";
        _state.Connected = false;
    }

Next, the code loops through all of the services in the list, comparing the Contract ID with the IDs for the Differential Drive service and the Webcam service. If either of these is found, the service info is remembered:

string driveUriPath = null;
                    string webcamUriPath = null;
                    foreach (ServiceInfoType info in list)
                    {
                        if (driveInfo == null && info.Contract == 

drive.Contract.Identifier)
                        {
                            driveInfo = info;
                        }

                        if (webcamInfo == null && info.Contract == 

webcam.Contract.Identifier)

{
                            webcamInfo = info;
                        }

                        if (driveInfo != null && webcamInfo != null)
                            break;
                    }
               }
               catch (Exception ex)
               {
                   string msg = "Service search error: " + ex.Message;
                   LogError(msg);
                   ErrorMessage += msg + "
";
                   _state.Connected = false;
               }

An error message is constructed based on the outcome of the search. If either or both of the services were not found, a MessageBox displays. The MessageBox is invoked via a public method in the DriveControl Form. The ShowErrorMessage method is trivial—it contains a single statement, which displays a MessageBox using the string parameter it was given. This illustrates one way to display message boxes from within a service:

if (driveInfo == null)
    ErrorMessage += "No Drive service found
";
if (webcamInfo == null)
    ErrorMessage += "No WebCam service found
";

if (ErrorMessage != null)
{
    if (_driveControl != null)
    {
        WinFormsServicePort.FormInvoke(
            delegate()
            {
                _driveControl.ShowErrorMessage(ErrorMessage);
            }
        );
    }
}

Lastly, the appropriate connect routine is called for each of the services (if found):

if (driveInfo != null)
      SpawnIterator<string>(driveInfo.Service, ConnectDrive);

  if (webcamInfo != null)
      SpawnIterator<string>(webcamInfo.Service, ConnectWebCam);

  // We are "connected" if either service was found
  if (driveInfo != null || webcamInfo != null)
      _state.Connected = true;
  }
}

Before looking at the ConnectWebCam routine, there are several global variables declared at the top of TeleOperation.cs that are used in this routine:

// Ports for the Web Camera
webcam.WebCamOperations _webCamPort;
webcam.WebCamOperations _webCamNotify = new webcam.WebCamOperations();
Port<Shutdown> _webCamShutdown = null;
// Form to display the video in
WebCamForm _cameraForm;
// Port for the WebCam Form to communicate on
WebCamFormEvents _webCamEventsPort = new WebCamFormEvents();
// Flag to indicate that the form is loaded and ready
bool _webCamFormLoaded = false;

For this code, note the following:

The rest of the code is in the Camera region at the bottom of TeleOperation.cs.

ConnectWebCam takes the name of the service as a string. If a connection is already open to a camera, then it unsubscribes:

// Handler for connecting to WebCam
IEnumerator<ITask> ConnectWebCam(string camera)
{
    //ServiceInfoType info = null;
    Fault fault = null;
    SubscribeResponseType s;
    //String camera = Opt.Service;

    // Already connected?
    if (_webCamPort != null)
    {

// Unsubscribe
    if (_webCamShutdown != null)
        yield return PerformShutdown(ref _webCamShutdown);
}

Next, it creates a new operations port and subscribes to the webcam:

// Create a new port
_webCamPort = ServiceForwarder<webcam.WebCamOperations>(camera);

// Subscribe to the webcam
webcam.Subscribe subscribe = new webcam.Subscribe();
subscribe.NotificationPort = _webCamNotify;
subscribe.NotificationShutdownPort = _webCamShutdown;

_webCamPort.Post(subscribe);

yield return Arbiter.Choice(
    //_webCamPort.Subscribe(_webCamNotify),
    subscribe.ResponsePort,
    delegate(SubscribeResponseType success)
    { s = success; },
    delegate(Fault f)
    {
        fault = f;
    }
);

if (fault != null)
{
    LogError(null, "Failed to subscribe to webcam", fault);
    yield break;
}

If the subscription is successful, then the state is updated with the full URI of the Webcam service and a new Webcam View Form is created:

// Put the service URI into the state for visibility
_state.WebCamService = camera;
LogInfo("Connected WebCam to " + camera);

// Now that we have found the service and subscribed,
// create a form to display the video
RunForm runForm = new RunForm(CreateWebCamForm);

WinFormsServicePort.Post(runForm);

yield return Arbiter.Choice(
    runForm.pResult,
    delegate(SuccessResult success) { },
    delegate(Exception e)
    {
        fault = Fault.FromException(e);
    }

);

    if (fault != null)
    {
        LogError(null, "Failed to Create WebCam window", fault);
        yield break;
    }

    yield break;
}

At this stage, the TeleOperation service is waiting for messages to arrive from the webcam and a new WinForm should be visible on the screen, as shown in Figures 4-3 and 4-4.