A contract identifier is used to uniquely identify different services. When you create a new service, as explained next, a contract identifier is created for you. For example, here is the contract identifier from the Dance service in Chapter 14:

/// <summary>
/// Dance Contract class
/// </summary>
public sealed class Contract
{
    /// <summary>
    /// The Dss Service contract
    /// </summary>
    public const String Identifier =
            "http://www.promrds.com/contracts/2007/10/dance.html";
}

Every service must have a class called Contract, and it must contain a field called Identifier. MRDS uses URIs in the following format:

http://somehost.domain/path/year/month/servicename.html

This looks like a valid URL, but it does not have to exist on the Internet. By default, the host name is www.promrds.com, but most of the Microsoft services use the host and path schemas.microsoft.com/robotics. The convention of using the year and month in which the service was created helps to keep the URIs unique and enables new versions of the same service to be built.

The important point to note is that the URI must be unique. You can use any host name or/path directory, that you want. This book uses a real web prefix, www.promrds.com/contracts/. Be aware, however, that the URI should be all lowercase or there can be problems with case sensitivity.

The programmatic interface to a service is defined as part of the contract via a set of classes that describe the types of messages to which a service can respond. The objective is to keep this interface clean by only using data structure definitions, and no methods. In particular, there must be at least one PortSet that is public and contains ports for all of the available message types. (Remember that messages are just data types, i.e., classes).

For example, here is the main operations port for the Dance service (although it is called a port, it is actually a PortSet):

/// <summary>
/// Dance Main Operations Port
/// </summary>
[ServicePort()]
public class DanceOperations: PortSet<DsspDefaultLookup, DsspDefaultDrop, Get>
{
}

Notice that this PortSet is "decorated" with the [ServicePort] attribute, which marks it is as an operations port. MRDS makes extensive use of such attributes to help build the necessary infrastructure for services declaratively. The compiler takes care of generating any code that might be necessary, so you don't have to worry about it.

DanceOperations contains ports for three types of messages: DsspDefaultLookup, DsspDefaultDrop, and Get. A Lookup operation enables other services to find out information about this service; Drop is used to shut down the service; and Get is used for retrieving a copy of the service's state. This is the set of message types created automatically when you create a new service.

The internal state of a service is a class containing properties that are important to the operation of the service. Some properties are effectively constants for the duration of the service execution. This can include parameters such as the COM port that is used to communicate with a robot. By making this available externally, it is possible to reconfigure the service without recompiling it.

Other state properties change over the lifetime of the service. For example, you might implement a finite state machine (FSM) to control a robot as it wanders around (see Chapter 16). Then you can define the current state of the robot as Drive Straight, Turn Right, Back Up, and so on, and store this in a variable in the service state. (Do not confuse "state" in the FSM with the "state" of a service. In general, the FSM state is a small subset of the overall service state.) In this case, the state changes in response to external events, such as detecting an obstacle in the path of the robot.

Lastly, some properties in the state can represent things happening in the real world, e.g., values obtained from sensors, user input, and so on.

Here is the state from the Stinger Drive By Wire service in Chapter 16:

[DataContract]
public class StingerDriveByWireState
{
    // The Headless field indicates if we should run without a GUI
    private bool _headless;

    [DataMember]
    public bool Headless
    {
        get { return _headless; }
        set { _headless = value; }
    }

    // Can run with the Motor disabled for testing
    private bool _motorEnabled;

    [DataMember]
    public bool MotorEnabled
    {
        get { return _motorEnabled; }
        set { _motorEnabled = value; }
    }

private bool _wanderEnabled;

    [DataMember]
    public bool WanderEnabled
    {
        get { return _wanderEnabled; }
        set { _wanderEnabled = value; }
    }

    private WanderModes _wanderMode;

    [DataMember]
    public WanderModes WanderMode
    {
        get { return _wanderMode; }
        set { _wanderMode = value; }
    }

    private int _wanderCounter;

    [DataMember]
    public int WanderCounter
    {
        get { return _wanderCounter; }
        set { _wanderCounter = value; }
    }

    private double _irLeft;

    [DataMember]
    public double IRLeft
    {
        get { return _irLeft; }
        set { _irLeft = value; }
    }

    private double _irFront;

    [DataMember]
    public double IRFront
    {
        get { return _irFront; }
        set { _irFront = value; }
    }
    private double _irRight;

    [DataMember]
    public double IRRight
    {
        get { return _irRight; }
        set { _irRight = value; }
    }
 }

The StingerDriveByWireState class defines the internal state of the service. Notice that it is also part of the service contract because it has the [DataContract] attribute. When another service issues a Get request, it knows from the contract exactly what information it will receive in the response message.

DSS nodes implement a web server so you can use a web browser and enter the URL for a service to see its state. Requesting a web page from the service executes an HttpGet operation, which returns an XML file. Being able to examine the state of a service remotely using a web browser gives you some insight into the service without having to run it in the debugger.

The state can be stored in a saved state or config file, which is an XML file. This can be reloaded the next time that the service is run so it "remembers" parameter settings. An example of a config file is shown here for the Stinger Drive By Wire service:

<?xml version="1.0" encoding="utf-8"?>
<StingerDriveByWireState xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlsn:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlsn:d="http://schemas.microsoft.com/xw/2004/10/dssp.html"
xmlsn="http://schemas.tempuri.org/2007/11/stingerdrivebywire.html">
  <Headless>false</Headless>
  <MotorEnabled>true</MotorEnabled>
  <WanderEnabled>false</WanderEnabled>
  <WanderMode>None</WanderMode>
  <WanderCounter>0</WanderCounter>
  <IRLeft>61.3</IRLeft>
  <IRFront>80</IRFront>
  <IRRight>79.8</IRRight>
</StingerDriveByWireState>

The state has values that are supposed to be set by editing the saved state file: Headless, MotorEnabled, and WanderEnabled. It also contains internal information that provides some insight into how the Wander behavior is running: WanderMode and WanderCounter. The last three fields are the IR sensor values, obtained from other services but included here to make them easier to see.

The WanderMode controls the internal FSM during wandering. It uses an enum that is also part of the contract (because it has a [DataContract] attribute too):

// Modes that the robot can be in while wandering
[DataContract]
public enum WanderModes
{
    None,
    DriveStraight,
    VeerLeft,
    VeerRight,
    TurnLeft,
    TurnRight,
    BackUp
}

When the state is serialized (into XML), the WanderMode appears as one of the names in the enum. There is no need to memorize "magic" numbers so you can tell what is happening when you view the state. In your code, you simply use the symbolic values, such as WanderModes.DriveStraight.

You can poll a service by requesting its state on a regular basis using a Get operation. This places the responsibility on your service to request the updates (and wait for them to arrive). Determining an appropriate polling interval is one of the challenges of robotics. If you poll too fast, you might overload the other service, or simply receive the same old stale information. If you don't poll often enough, you might miss important information, such as a looming wall, and then crash!

One of the key features of DSSP is that messages can be sent asynchronously, i.e., unsolicited. These are referred to as notifications. Services can offer subscriptions to their state information, so you can avoid polling. (Subscriptions are covered in Chapter 4).

For example, a laser range finder (LRF) produces range scans about once a second. Services that are interested in this data can subscribe to the LRF service and receive notifications when new range scan data becomes available. (The LRF data is part of the service's state, so the LRF service is sending state update notifications.) These updates continue to arrive until one of the services is shut down or the subscriber decides to unsubscribe.

Note that the LRF service sends the range data as part of the notification message. However, a Webcam service simply sends a message to say that a new frame is available because of the large amount of data involved. It is then up to the recipient to request the frame. If the recipient is slow and misses a couple of updates, very little bandwidth is wasted because the images are not sent in notifications anyway.

Putting this all together, the diagram shown in Figure 3-3 depicts a sequence of messages passing between hypothetical services.

Figure 3.3. Figure 3-3

In Figure 3-3, note the following:

Note two distinct patterns in Figure 3-3. One is the classic request/response pattern. You have the option to wait for the response or ignore it. The response could be a Fault if the other service encountered an error processing the request. You can also explicitly set the request's TimeSpan property so that it times out if the other service doesn't respond.

The other pattern is asynchronous notifications to multiple subscribers. The subscribers first request notifications (these messages are not shown in Figure 3-3) and then they continue to receive updates whenever they become available. No acknowledgment is required for notifications.

Service behavior describes what the service actually does. Behavior includes the algorithms that a service uses to achieve its purpose, such as wandering around without bumping into obstacles. Orchestration is a form of behavior. Behavior also includes simple functions such as returning the state when it is requested.

All services implement a certain minimum set of operations that are defined when you create a new service (as shown earlier in "Contracts"), so even an "empty" service has some behavior. An operation is a function that a service can perform. Operations are defined by the ports that represent them, and ports use particular classes (or data types) for their messages. This is discussed in more detail below.

This terminology gets a little messy. Sometimes operations are also referred to as requests or responses—a request occurs when a message is sent to a service (using a specified data type associated with a port), and a response is sent back by the service (using another data type).

Note that operations are not required to send a response; it is up to you as the programmer to define whether or not a response is sent. At runtime, you can also set ResponsePort to null in the request—that is, you can explicitly say that you don't want a response. DSSP uses TCP/IP or HTTP, both of which are reliable transports, so there is no need to acknowledge every message.

However, if you anticipate that a request might fail and you want to know about it, then you must specify a response port (and set up a receiver to read from the port) or set up a causality. Causalities are like structured exception handling on steroids. They allow exceptions that occur anywhere along the execution path of a message sequence to be posted back to a single port. These exceptions might even occur concurrently due to the multi-threaded nature of the CCR.

Internally, a service uses handlers to process operations. Handlers operate asynchronously and possibly in parallel. Most handlers are controlled by a CCR Interleave (called MainPortInterleave), which is created automatically for you. As shown in the previous chapter, the handlers attached to an interleave can belong to the Exclusive or Concurrent groups (or the special case called TearDown, which is usually just for Drop messages).

Here is a handler for a Get operation that retrieves the state from a service:

/// <summary>
/// Get Handler
/// </summary>
/// <param name="get"></param>
/// <returns></returns>
[ServiceHandler(ServiceHandlerBehavior.Concurrent)]
public virtual IEnumerator<ITask> GetHandler(Get get)
{
    get.ResponsePort.Post(_state);
    yield break;
}

This is a very simple handler—it just sends back a copy of the service state. It is annotated with the [ServiceHandler] attribute, which specifies that it belongs to the Concurrent group. This handler is allowed to execute simultaneously with other Concurrent handlers, but it is not allowed to execute while an Exclusive handler is running.

In effect, operations are the APIs that can be used to query and manipulate a service, e.g., retrieve (Get) or change (Replace, Update) the state. In a traditional programming environment, you link your code against a library of subroutines and use local procedure calls (the APIs for the library) to execute the functions in the library. In MRDS, operations are executed via SOAP requests, which means that they are similar to remote procedure calls and can therefore be executed on another computer anywhere in the network.

If an unhandled exception occurs during the execution of a handler, then DSS automatically creates a Fault and returns it as the response. However, if you are running the code in the debugger, it catches the exception and suspends execution. You can simply continue executing the code so DSS gets a chance to handle it.

Note that the contract is embodied in a Proxy DLL that is created automatically when you compile your service by a program called DssProxy. (Because .NET assemblies are self-describing, you can find out about the contract using reflection, but that is another topic.) You do not make calls directly to the service DLL; instead, you call routines with the same signatures in the Proxy DLL.

If you understand web services, then you know that parameters that are passed to and from services have to be marshaled, i.e., converted to a neutral format that both the client and the server understand. For web services, this format is XML. Because DSSP is based on SOAP, it also uses XML for requests over HTTP. However, for direct communication using TCP/IP, a binary serialization is used that is 10 to 20 times faster. (When you get to the "Running a DSS Node" section, you will see that two ports are specified when you start DSS: one for HTTP requests and one for direct TCP/IP connections.)

The context of a service includes all of its partners. These are other services that it relies on to do its job. The obvious examples for a robot are the motors that drive the wheels, infrared sensors, and so on. A service can have as many partners as it likes, and the partnerships can be dynamic.

By design, partners do not have to be on the same computer. Each computer runs an instance (or possibly multiple instances) of a DSS node. A service directory is maintained in each DSS node. As you have already seen, one of the possible operations on a service is a lookup.

In most cases, partnerships last for the duration of the service execution. Therefore, they are often established declaratively in the code (using attributes). However, MRDS has a concept of generic contracts. These types of contracts specify the operations that a conforming service must support. At runtime, any service that complies with the generic contract can be used as a partner. The association between the actual service and the generic service is done using a manifest, which is an XML file that uses a schema defined by Microsoft.

A common example is the generic differential drive service for two-wheeled robots. The manifest can connect a service to the drive on a Boe-Bot, or a LEGO NXT Tribot, or a Stinger, and so on, and the service should have no idea what type of robot it is talking to.

One case where partnerships are established on demand is when you use the Dashboard (which is described in Chapter 4). In order to do this, the Dashboard must query the service directory to find services that implement generic contracts that it understands, such as the differential drive, game controller, laser range finder, webcam, and so on. The execution context of the Dashboard, therefore, changes over time.

The following manifest starts a Boe-Bot and the Dashboard. It runs the BASICStamp2 service, which is the "brick" or "brain" on the robot; the BSDrive service, which controls the wheels; and the Dashboard:

<?xml version="1.0" encoding="utf-8"?>
<Manifest
     xmlns="http://schemas.microsoft.com/xw/2004/10/manifest.html"
     xmlns:dssp="http://schemas.microsoft.com/xw/2004/10/dssp.html"
     >

  <CreateServiceList>

     <!—Start BasicStamp2 Brick—>
     <ServiceRecordType>
       <dssp:Contract>http://schemas.microsoft.com/robotics/2007/06/basicstamp2.html
       </dssp:Contract>
       <dssp:PartnerList>
         <!—Initial BasicStamp2 config file—>
         <dssp:Partner>
           <dssp:Service>Parallax.BoeBot.Config.xml</dssp:Service>
           <dssp:Name>dssp:StateService</dssp:Name>
         </dssp:Partner>
       </dssp:PartnerList>
     </ServiceRecordType>

     <!—Start the BoeBot drive service—>

<ServiceRecordType>
       <dssp:Contract>http://schemas.microsoft.com/robotics/2007/06/bsdrive.html
       </dssp:Contract>
       <dssp:PartnerList>
         <!—Initial Drive Configuration File—>
         <dssp:Partner>
           <dssp:Service>Parallax.BoeBot.Drive.Config.xml</dssp:Service>
           <dssp:Name>dssp:StateService</dssp:Name>
         </dssp:Partner>
       </dssp:PartnerList>
     </ServiceRecordType>

     <!—Dashboard—>
     <ServiceRecordType>
       <dssp:Contract>http://schemas.microsoft.com/robotics/2006/10/dashboard.html</dssp:Contract>
     </ServiceRecordType>

   </CreateServiceList>

</Manifest>

You can clearly see each of the services listed inside a ServiceRecordType. The BASICStamp2 and BSDrive also partner with the StateService, which is responsible for loading the initial state from the specified config file.

Don't worry about manifests at this stage. MRDS includes a Manifest Editor that makes creating them relatively easy. This is discussed later in the chapter.

The DSSP service model defines many operation classes. Luckily, most of these you will never use in an MRDS service. (If you are interested, you can read the full DSSP specification, available at http://download.microsoft.com/download/5/6/B/56B49917-65E8-494A-BB8C-3D49850DAAC1/DSSP.pdf).

The full list of DSSP operations is shown in the following table. You do not need to know all of these operations, but they are included here for completeness.

The only mandatory operation according to the DSSP specification is Lookup. However, for practical reasons, MRDS always creates services with Lookup, Drop, and Get. A service that only implemented Lookup would be pretty useless.

The DSS runtime provides a wrapper, CreateService, for the Create operation. Lookup operations are a little more complicated, but can be handled by requests to the Directory service.

All of the operations are based on the generic DsspOperation class:

public class DsspOperation<TBody, TResponse>

To define your service operations, you subclass one of the standard DSSP operations and supply your own body type (which is the request) and a PortSet for the response.

An example will help to clarify this. The Hemisson services in Chapter 16 have a request to read the IR sensors. It is defined as follows:

[DisplayName("GetSensors")]
[Description("Gets the state of the infrared sensors")]
public class QueryInfraRed: Query<SensorsRequest, PortSet<Sensors, Fault>>
{
}

[Description("Requests sensor data")]
[DataContract]
public class SensorsRequest
{
}

This new operation type, QueryInfraRed, is based on the Query class because it only retrieves part of the state. When a new instance is created, the Body field contains a variable of type SensorsRequest, and the ResponsePort field is a PortSet that returns either a Sensors object or a SOAP Fault. (The Sensors class is not shown here. It contains all of the IR sensor values.)

A key point to note is that the request type must be unique among all of the types in the main operations PortSet. If you tried to implement requests using an int for several of them, only the first one in the PortSet would ever get any messages.

This new class must be added to the main operations port for the Hemisson services, and then a handler can be written as follows:

/// <summary>
/// QueryInfraRed Handler
/// </summary>
/// <param name="query"></param>
/// <returns></returns>
[ServiceHandler(ServiceHandlerBehavior.Concurrent)]
public virtual IEnumerator<ITask> QueryInfraRedHandler(QueryInfraRed query)
{
    query.ResponsePort.Post(_state.Sensors);
    yield break;
}

Notice that this handler returns only the Sensors portion of the state. How this sensor information is updated is irrelevant here. It is the responsibility of the service to obtain this data from the robot and make it available.

The [ServiceHandler] attribute flags this method as being a handler, and the QueryInfraRed parameter indicates what type of operation it handles. The attribute also specifies which interleave group the handler should be in.

This behavior is in the Concurrent interleave group. This means that it is allowed to execute in parallel with other Concurrent handlers. However, it cannot execute while an Exclusive handler is running.

The third group of handlers are TearDown handlers. Usually this group only contains the Drop handler. TearDown handlers are not only exclusive; they also prevent further execution of any other handlers. The last thing that a service must do when it receives a Drop request is to post back a response.

The QueryInfraRed example shows a request that basically has an empty body and returns some information. The opposite is a request that sends information but does not expect any information in the response. The PlayTone operation from the Boe-Bot (see Chapter 14) is an example:

[DisplayName("PlayTone")]
[Description("Plays a tone on the speaker on the Boe-Bot.")]
public class PlayTone: Update<Tone, PortSet<DefaultUpdateResponseType, Fault>>
{
}

The PlayTone operation sends a Tone object as the request body, but it only receives a DefaultUpdateResponseType to indicate success (or a Fault for failure). There are pre-defined classes for the default responses to most of the operation classes so that you do not have to bother defining response types for all of your operations.

The Tone class is marked as part of the data contract. It also specifies two data members as the parameters for a constructor, Frequency and Duration:

[Description("Sound a Tone on the Speaker.")]
[DataContract]
public class Tone
{
    // Parameters
    private int _frequency;
    private int _duration;

    [DataMember, DataMemberConstructor(Order = 1)]
    [Description("Frequency in Hz (rounded to nearest 50Hz).")]
    public int Frequency
    {
        get { return this._frequency; }
        set { this._frequency = value; }
    }

    [DataMember, DataMemberConstructor(Order = 2)]
    [Description("Duration in Milliseconds (rounded to nearest 50ms).")]
    public int Duration
    {
        get { return this._duration; }
        set { this._duration = value; }
    }
}

As a convenience, the Proxy generator (discussed later in the section "Proxy Assemblies") will create appropriate helper methods on the proxy operations port so that you can write the following command (assuming _stampPort is already set up as the operations port):

_stampPort.PlayTone(3000, 500);

This constructs a new Tone object and sends it to the Boe-Bot.

Because the PlayTone operation returns a PortSet, you can also use it in a Choice:

yield return
      Arbiter.Choice(
          _stampPort.PlayTone(3000, 500),
          delegate(DefaultUpdateResponseType d)
          { },
          delegate(Fault f)
          {
              Console.WriteLine("Play Tone failed: " + f.Reason);
          }
      );

This has the added benefit that execution will not continue until the PlayTone request has been completed, and of course it is also defensive programming because it explicitly flags errors.

LogInfo(LogGroups.Console, "some message");

A generic contract is similar to an abstract class, but MRDS does not implement class inheritance in the usual sense. Generic contracts have no implementation of their own. They consist solely of the type definitions required for the contract identifier, the state, and the main operations port.

To implement a generic service, you must build a service based on the generic contract. This can be done most easily using the /alt qualifier to DssNewService to specify the generic contract that should be used. This is covered in more detail in Chapter 4.

The implementation service has two operations ports: one for the new service itself and one that receives requests based on the generic contract. In your source code for the new service, you must implement handlers for all of the operations defined in the generic service contract. There is no requirement to add more handlers to the new service (apart from Lookup, Drop, and Get, which all services have). The simplest implementation, therefore, consists only of handlers for the generic operations, in which case you do not need your own operations port.

The reason for defining generic contracts is to try to make MRDS services hardware-independent in the same way that device drivers hide hardware details from an operating system.

The layout of a DSS node is as follows:

Root directory (or Mount point)
    Bin
    Store
        Logs
        Media
        Styles
        Transforms

When you deploy the MRDS runtime to another computer, this is the minimal directory structure that is created. If you have a full installation of MRDS on your computer, then there are many more directories but they are not required to run MRDS.

In a web browser, you can go to the Service Directory (as explained below) and click on the mountpoint service to see the local path where MRDS is installed, which is referred to as the root directory or the mount point. The mountpoint service can be used in your code to access local files, but it only allows you to access files below the MRDS root directory.

You can find out where your local DSS node is in your C# code using the LayoutPaths static class, as shown in this example:

string logdir = LayoutPaths.RootDir + LayoutPaths.LogDir;

This will give you the full path to the Logs directory if you want to write your own log file.

Open an MRDS Command Prompt window by clicking Start

C:Microsoft Robotics Studio (1.5)>DssHost /?

Now start DssHost on its own (with no services) using the following command:

C:Microsoft Robotics Studio (1.5)>DssHost /p:50000 /t:50001

The output from DssHost should look like Figure 3-4, which shows that the Directory and Constructor services started, but no manifest was supplied (so nothing else started).

Figure 3.4. Figure 3-4

DssHost @myoptions.txt

DssHost requires you to specify at least the port parameter (abbreviated to /p). In the example in Figure 3-4, the tcpport is also specified with /t. At first glance this is a little confusing. The "port" numbers you give to DssHost have nothing to do with CCR ports, and why do you need two ports?

The port parameter supplies what might more appropriately be called the HTTP port, and the tcpport parameter is the SOAP port. DssHost includes a web server that can be used to examine and control services. This web server uses the port parameter. In addition, a service receives requests (SOAP messages) through its service port, which is the tcpport parameter.

There is nothing magical about the numbers 50000 and 50001 other than the fact that they are above the range of "well-known" TCP/IP ports. In fact, in the early days of MRDS, the documentation used 40000 and 40001 in many cases.

Once DssHost is running, start up a web browser and enter the following URL in the address bar: http://localhost:50000.

Because you will make frequent use of a web browser to examine services, it is a good idea to save a shortcut (or favorite) for this web page once it is displayed. Notice that the port number in the URL is the (HTTP) port that you specified on the command line when you started DssHost.

You should see something like what is shown in Figure 3-5. Notice that there are several options in the menu at the left-hand side of the window. Each of these options is explained briefly below. Try them all out for yourself. You can investigate the Developer Resources and About Microsoft Robotics Studio sections of the menu on your own.

Figure 3.5. Figure 3-5

The Control Panel

The Control Panel displays all of the available services. When you select the Control Panel, it might take a little while before anything is displayed because it initiates a refresh of the directory cache. Eventually, the Control Panel displays a list of all the available services. You can manually start services from this list.

You can narrow down the list of services by typing in a search string. Figure 3-6 shows the results of entering "cam," which indicates all services with "cam" in their name or description, which are obviously cameras.

Figure 3.6. Figure 3-6

In the drop-down list beside each service, you can find a list of all of the manifests that DSS found that refer to the service. You can either select one of these manifests or just leave the drop-down set on <<Start without manifest>> and click the Create button to start a new instance of the service. If you have a web camera, make sure that it is plugged into your PC and click the Create button beside the Webcam service. (Don't select a manifest.)

The Service Directory

A new Webcam service will be started on your computer. You can verify this by selecting Service Directory from the menu (see Figure 3-7).

Figure 3.7. Figure 3-7

Every DSS node has a service directory that lists the currently running services. Two Webcam services are listed (the second one is cut off a little at the bottom of the window in Figure 3-7) because there is a generic Webcam contract and the service implements both the generic contract and its own contract. Notice that there are several other services as well, such as the manifest loader, console output, and the Control Panel.

Click the Webcam service in the Service Instance list to see what the output from the service looks like. An example is shown in Figure 3-8. If you look carefully in the address bar, you might be able to see that the URL is http://localhost:50000/webcam/c7354581-c28f-4b4c-b419-d5b7ea06aab9. Before you panic, assuming you have to know these magic numbers, it should be pointed out that they change every time you run a service—they are only there to make service URIs unique. The main point is that the Webcam service can be accessed just by appending its name to the end of the DSS node URL; the numbers are not necessary unless there are multiple instances of a service.

Figure 3.8. Figure 3-8

The Webcam service formats its output when you make a HttpGet request to the service and presents it as a Web Form. The form enables you to set the camera parameters, including refresh interval, display format, and capture format (image resolution). You can also select from several cameras if you have more than one connected to your PC. Finally, you can run the viewer continuously or refresh the image manually using the Start, Stop, and Refresh buttons. This is an advanced example of a web interface to a service.

The Debug and Trace Messages Page

Select Debug and Trace Messages from the menu. You should see something like what is shown in Figure 3-9.

Figure 3.9. Figure 3-9

The Console Output, as it is known (the URL is http://localhost:50000/console/output), lists all of the informational and error messages that are generated by services running in the DSS node. You can use this to assist you with debugging.

Don't be confused by the name "console output" because any messages that you write using Console.WriteLine do not appear on this page.

Notice that you can select the level of messages in the Filters section. This is one of the advantages of using LogInfo and the other methods: You can select at runtime what level of messages you want to see. Another advantage is that you can expand the information available by clicking the small, downward-pointing arrow in the View column beside each message. This shows you information from the stack, including the name of the source file and the line number. You might find this useful if you can't remember where a particular message comes from.

The default trace levels are set in the DssHost application configuration file, which is in the MRDS bin folder and is called dsshost.exe.config. (This is really a .NET feature, not MRDS.) Recall that the config file is an XML file, so you can open it in Notepad. It contains some helpful comments.

You can also enable timeout tracking on all messages in the config, so that you can detect services that are not responding to messages. You can also log all message traffic if you really want to!

The Manifest Load Results option is covered shortly because there is no manifest loaded at the moment.

The Contract Directory

Next, click the Contract Directory menu option. This displays a screen like the one shown in Figure 3-10. This is not very exciting; it just tells you where the services reside on the local hard drive.

Figure 3.10. Figure 3-10

The Security Manager Page

Select the Security Manager from the menu. This displays a Web Form. If you click the Edit button, the screen should look like the one shown in Figure 3-11.

Figure 3.11. Figure 3-11

Some users have experienced problems running DssHost due to firewall or security settings on their computers. This is most likely to happen if you are not logged in as an Administrator on your PC.

The Security Manager page shows the contents of the file storeSecuritySettings.xml, which you can edit if you wish. (If you cannot find the file, then the default security settings will be in force.) However, there is another part to the puzzle: The name of the security settings file is set in the .NET application configuration file for DssHost (which was mentioned above)—namely, bindsshost.exe.config. If you look in this file you should find a key called Security:

<!--Comment the line below to disable security-->
<add key="Security" value=".storeSecuritySettings.xml"/>

Security is discussed in more detail in the online documentation. You can also search the Discussion Forum if you have problems.

Resource Diagnostics

The last menu option is Resource Diagnostics. This page shows information about each of the dispatchers (and their queues) running in the DSS node. You might find this information helpful when trying to diagnose a problem. An example is shown in Figure 3-12.

When you have finished exploring DSS in the web browser, enter Ctrl+C in the MRDS Command Prompt window or simply close down the window. This is a nasty way to shut down DssHost, but it works.

Figure 3.12. Figure 3-12

To run a robot service, you need to supply a manifest on the command line. Several manifests are supplied for you in the MRDS samplesConfig folder. After you have installed the code that comes with this book, you will also have a folder called ProMRDSConfig.

You will no doubt find yourself typing the same DssHost command over and over again as you test your services. You might want to create batch files to run various services. If you place them into the MRDS bin folder, then they will be on the search path and will be found automatically when you type a command in an MRDS Command Prompt window. These files are fairly simple, but they save you a lot of time.

For example, here is a batch file that runs a Boe-Bot (called RunBoeBot.cmd):

@ECHO ON
REM Run a Parallax Boe-Bot
REM Type Ctrl-C in this window when you want to stop the program.
dsshost -port:50000 -tcpport:50001 

-manifest:"../ProMRDS/Config/Parallax.BoeBot.manifest.xml" 

-manifest:"../ProMRDS/Config/Dashboard.manifest.xml"

Two manifests are specified on the command line: the Boe-Bot and the Dashboard. This is because the two services are not directly related—the Dashboard connects to other services dynamically.

Notice that the paths to the manifests are relative to the location of the batch file. If you place the batch file into a different folder, i.e., not the bin folder, then you will need a relative path to DssHost.exe, and the relative paths to the manifests will be different as well.

To run this batch file, you can just double-click it in Windows Explorer. Alternatively, to run it from an MRDS Command Prompt window, enter the following command:

C:Microsoft Robotics Studio (1.5) >RunBoeBot

Manifest Load Results

Once you have the Boe-Bot running (or your particular robot), start a web browser again and browse to the DSS node at http://localhost:50000. Select Manifest Load Results in the menu; the result should look similar to what is displayed in Figure 3-13. You can expand each manifest to see additional information. Notice that the Boe-Bot manifest loaded the BASICStamp2 and BSDrive services, each with a StateService partner (an initial config file).

Figure 3.13. Figure 3-13

Now select the Service Instance Directory (see Figure 3-14).

Figure 3.14. Figure 3-14

Viewing Service State

Figure 3-14 indicates that many different services are running. Click the basicstamp2 service to view its state. This output should look like the window shown in Figure 3-15.

Figure 3.15. Figure 3-15

Notice in Figure 3-15 that the right infrared sensor specifies true, which indicates an obstacle in the immediate vicinity of the Boe-Bot. This page is nicely formatted because it uses an XSLT (Extensible Stylesheet Language Transform) file to format the XML output from the service.

The state information on the page does not update automatically—you need to keep clicking on the browser's refresh button.

Go back to the Service Directory and click the bsdrive service. The output should look like Figure 3-16. This is raw XML code. If you look back at Figure 3-15, you will see an XML button in the window's top-right corner. You can click this to see the raw XML behind a formatted state page.

Figure 3.16. Figure 3-16

The BSDrive service does not have an associated XSLT file to format its output. However, the output is still intelligible. This is one of the advantages of XML—it is human-readable.

That completes the pictorial overview of DSS. It is hoped that the many pages it took to show the screenshots were worth more than several thousand words.

In this section you build a brand-new service. It is advisable to keep your code separate from the MRDS distribution. The Service Tutorials suggest creating new services under the samples folder, but this results in your code being intermixed with the Microsoft code. All of the code for the book is under the ProMRDS folder, which makes it much easier to pick up and move elsewhere. Furthermore, there is no chance of a conflict if you update your MRDS installation, such as with the MRDS V1.5 Refresh.

If you have not done so already, create a new folder called Projects. In Windows Explorer, browse to the Microsoft Robotics Studio (1.5) folder and make a new folder under it called Projects.

Alternatively, open an MRDS Command Prompt window by running the Command Prompt option from the Microsoft Robotics Studio (1.5) folder in the Start menu. Create a new folder called Projects:

C:Microsoft Robotics Studio (1.5)>md Projects

This is where you should create your own MRDS projects.

Using Visual Studio

The previous chapter explained how to create a new service using Visual Studio. Now you need to create another service. The New Project dialog is shown in Figure 3-17.

Figure 3.17. Figure 3-17

To summarize the steps involved:

1. Open Visual Studio and select File

   

2. Select the Robotics project type and the Simple Dss Service (1.5) template.

3. Make sure that the location is your Projects folder.

4. Give the service the name ServiceA.

When Visual Studio has finished creating your project, you will find the following source files listed in the Solution Explorer panel:

• AssemblyInfo.cs: This is a standard file that contains information about the output assembly (DLL). You do not need to be concerned with it here, so you can ignore it.

• ServiceA.cs: This is the main source file for the new service. Most of the work of creating a new service is done in this file.

• ServiceA.manifest.xml: This is the manifest that is used by DSS to load the service.

• ServiceATypes.cs: This contains a set of classes, also called types, that are used by the service and other services that wish to communicate with it.

(There are several more files that Visual Studio uses to manage the solution: ServiceA.csproj, ServiceA.csproj.user, ServiceA.sln and ServiceA.suo. You can ignore them; they don't show up in the Solution Explorer anyway.)

The source files are explained in more detail later in this chapter. In the meantime, it is instructive to look at the Visual Studio Project Properties.

Open the Project Properties and step through each of the tabs to look at the settings. The important points on each of the tabs are highlighted here:

• Application tab: The application type is Class Library (DLL). All MRDS services are dynamic link libraries (DLLs). Notice that the Assembly name is ServiceA.Yyyyy.Mmm, where yyyy is the current year and mm is the current month. Using the date is a simple way to create different versions of a service with the same name. Recall from earlier in the chapter that contract identifiers also contain a year and a month. The assembly name and the contract identifier should match. (It is possible to have a different assembly name, but that can become a source of confusion!)

  The default namespace is Robotics.ServiceA. There is no need to change this unless you want to create assemblies for a particular organization.

• Build tab: The output path should be ....in. All MRDS services are placed into the bin folder under the MRDS root directory.

• Build Events tab: There is a post-build event command that is only executed after successful compilation:

  "C:Microsoft Robotics Studio (1.5)indssproxy.exe" 
  
  /dll:"$(TargetPath)" /proxyprojectpath:"$(ProjectDir)Proxy " 
  
  /keyfile:"$(AssemblyOriginatorKeyFile)" $(ProxyDelaySign) 
  
  $(CompactFrameworkProxyGen) /binpath:". " 
  
  /referencepath:"C:Microsoft Robotics Studio (1.5)in " 
  
  /referencepath:"C:Microsoft Robotics Studio (1.5)in "

  You do not need to know what this command does for now, and you certainly should not change it. Its purpose is to create a proxy for your service. If you are familiar with web services and SOAP requests, then you know what a proxy is. Otherwise, it is explained later in the section "Proxy Assemblies."

• Debug tab: When you run the debugger, it automatically starts an external program: C:Microsoft Robotics Studio (1.5)indsshost.exe.

  DssHost.exe runs a DSS node, which is effectively the MRDS runtime environment. Your service(s) run within this node. Although it is possible to start a DSS node from within your own application program, it isn't done that way for the examples in this book.

  Notice that the working directory is the MRDS root directory and some command-line options are passed to DssHost:

  -port:50000 -tcpport:50001 
  
  -manifest:"C:Microsoft Robotics Studio (1.5)projects 
  
  ServiceAServiceA.manifest.xml"

• Reference Paths tab: There should be two directories in the list of reference paths. The first directory is where all of the service DLLs reside, as well as the components that make up MRDS. This enables you to easily reference other services. The second directory is the V2.0 .NET Framework, which is required to run MRDS V1.5.

  c:microsoft robotics studio (1.5)in
  c:windowsmicrosoft.netframeworkv2.0.50727

You can ignore the Resources, Settings, and Signing tabs because they are not important at this stage. For now, just leave Visual Studio open while you create another service from the command line as an alternative to using Visual Studio. We want two services so that they can interact with each other.

C:Microsoft Robotics Studio (1.5)>DssNewService /?

This section examines the various files that are generated when you create a new service. The source code for a new service is split into two files: the main code and the "types." You are not limited to using only these two files—you can split the code up any way you like. In fact, in the early days of MRDS, it was common to also have a "state" file that contained only the definition of the service state. This is now rolled into the types file, but you can still see many state files in the samples supplied with MRDS.

namespace Robotics.ServiceA
{
    /// <summary>
    /// ServiceA Contract class
    /// </summary>

public sealed class Contract
    {
        /// <summary>
        /// The Dss Service contract
        /// </summary>
        public const String Identifier = 

"http://schemas.tempuri.org/2008/01/servicea.html";
    }

/// <summary>
/// The ServiceA State
/// </summary>
[DataContract()]
public class ServiceAState
{
}

/// <summary>
    /// ServiceA Main Operations Port
    /// </summary>
    [ServicePort()]
    public class ServiceAOperations: PortSet<DsspDefaultLookup, 

DsspDefaultDrop, Get>
    {
    }

/// <summary>
    /// ServiceA Get Operation
    /// </summary>
    public class Get: Get<GetRequestType, PortSet<ServiceAState, Fault>>
    {
        /// <summary>
        /// ServiceA Get Operation
        /// </summary>
        public Get()
        {
        }

        /// <summary>
        /// ServiceA Get Operation
        /// </summary>
        public Get(Microsoft.Dss.ServiceModel.Dssp.GetRequestType body):
            base(body)
        {
        }

        /// <summary>
        /// ServiceA Get Operation
        /// </summary>
        public Get(Microsoft.Dss.ServiceModel.Dssp.GetRequestType body, 

Microsoft.Ccr.Core.PortSet<ServiceAState,W3C.Soap.Fault> responsePort):
                base(body, responsePort)
        {
        }
   }

using W3C.Soap;

namespace Robotics.ServiceA
{
     /// <summary>
     /// Implementation class for ServiceA
     /// </summary>
     [DisplayName("ServiceA")]
     [Description("The ServiceA Service")]
     [Contract(Contract.Identifier)]
     public class ServiceAService: DsspServiceBase
     {

/// <summary>
/// _state
/// </summary>
private ServiceAState _state = new ServiceAState();

/// <summary>
/// _main Port
/// </summary>
[ServicePort("/servicea", AllowMultipleInstances=false)]
private ServiceAOperations _mainPort = new ServiceAOperations();

/// <summary>
/// Default Service Constructor
/// </summary>
public ServiceAService(DsspServiceCreationPort creationPort):
        base(creationPort)
{
}

/// <summary>
/// Service Start
/// </summary>
protected override void Start()
{
    base.Start();
    // Add service specific initialization here.
}

/// <summary>
/// Get Handler
/// </summary>
/// <param name="get"></param>
/// <returns></returns>
[ServiceHandler(ServiceHandlerBehavior.Concurrent)]
public virtual IEnumerator<ITask> GetHandler(Get get)
{
    get.ResponsePort.Post(_state);
    yield break;
}

<?xml version="1.0" ?>
<Manifest
    xmlns="http://schemas.microsoft.com/xw/2004/10/manifest.html"
    xmlns:dssp="http://schemas.microsoft.com/xw/2004/10/dssp.html"
    >
    <CreateServiceList>
        <ServiceRecordType> <dssp:Contract>http://schemas.tempuri.org/2008/01/servicea.html</dssp:Contract>
        </ServiceRecordType>
    </CreateServiceList>
</Manifest>

You don't need to do anything special to compile a service—just select Build Solution from the Build menu. If it is not open already, open ServiceA in Visual Studio. Locate the Start method in ServiceA.cs and add a line of code to announce the startup of the service, as shown here:

protected override void Start()
{
     base.Start();
     // Add service specific initialization here.
     Console.WriteLine("ServiceA starting");

Now compile ServiceA. It should compile without errors. You can run it if you want, but it just displays a message indicating that it is starting, which is not very exciting.

Open ServiceB in Visual Studio and add a Console.WriteLine command in ServiceB.cs, except obviously the message should say "ServiceB starting."

When you compile, you might notice in the Output panel that some other DLLs are created as well. These are the Proxy DLLs discussed later in the section "Proxy Assemblies."

In Visual Studio for ServiceA, expand the References in the Solution Explorer panel. References are inserted automatically for Ccr.Core, DssBase, and DssRuntime when the service is created. In almost all services, you will also require RoboticsCommon.Proxy. You can add this reference to your services if you want, but because they do not involve a real robot, it is not necessary.

You also need to add references to other services that you intend to use. In the example in this chapter, ServiceA partners with ServiceB, so ServiceA must have a reference to the ServiceB proxy. (See "Proxy Assemblies," later in the chapter). This is why you compiled both of the services in the previous section.

When you add a reference, it might take a little while before the dialog is displayed. Eventually you should see a list of DLLs. Scroll down to ServiceB, as shown in Figure 3-18. Make sure you select the Proxy assembly. (The year and month in the assembly name will be different for you.)

Figure 3.18. Figure 3-18

Note that ServiceB does not need a reference to ServiceA because it never calls ServiceA—it only responds to requests from ServiceA.

At the top of ServiceA.cs underneath the existing using statements, add another one:

using serviceb = Robotics.ServiceB.Proxy;

You can now recompile ServiceA with the new reference. Clearly, you have to compile ServiceB before ServiceA so that the correct reference is used.

When you compile a service, a post-build event is triggered after a successful compilation. This runs DssProxy, which generates a Proxy DLL. You can see the command in the Project Properties on the Build Events tab, as mentioned earlier.

Service operations are executed "over the wire" by sending messages. These messages must first be serialized, i.e., converted to XML, so that they can be sent. This is necessary because the service that you are communicating with might not be on the same computer. It is not simply a matter of passing across a pointer reference to a location in memory—this will not work across the network!

This is an important point: You can't allocate a chunk of memory, e.g., create a new class instance, and send a pointer to it to another service. The contents of the area of memory have to be converted to XML, and then sent.

The Proxy DLL is responsible for performing the serialization and deserialization of messages. When you post a message, you pass a handle to the request message body (a pointer reference) to the Proxy and it creates an XML message from that. When a response message is returned, the Proxy converts the XML back into its binary representation and gives you a handle to a response message.

Therefore, the reference that you add to ServiceA is to the ServiceB proxy. You do not call ServiceB directly.

Now that you have compiled the services, you can try running each of them using whatever method you normally use: press F5; click the Start Debugging icon in the toolbar; or click Debug Start Debugging.

This starts DssHost and runs the manifest that was generated for you when you created the service. The command that is executed can be found in the Project Properties on the Debug tab in the Start External Program textbox, and the command-line options are in the Command Line Arguments textbox.

The first time you run ServiceA, you should see something like what is shown in Figure 3-19. Notice that the message "ServiceA starting" is displayed but then nothing else happens. You must stop debugging or close the MRDS Command Prompt window to terminate the service.

Figure 3.19. Figure 3-19

Because this is a new service that has not been run before, DSS rebuilds the contract directory cache, as you can see from the message:

Rebuilding contract directory cache. This will take a few moments .
Contract directory cache refresh complete

The contract directory cache is populated using reflection on all of the DLLs in the MRDS bin folder. It consists of two files in the store folder:

You can open these files and have a look at them if you like, but you will never need to edit them. If you want to force the cache to be refreshed, you can delete these two files. The next time DssHost starts, it will recreate them.

Also in Figure 3-19, you can see that the Manifest Loader starts up and then loads the ServiceA manifest. When you are creating your own manifest (explained below), you might make mistakes. If you do, this is where the errors will appear.

Now add some behavior to ServiceB. Open it in Visual Studio and then open ServiceB.cs. Scroll down in ServiceB until you find the Start method. Add the following code (shown highlighted):

/// <summary>
/// Service Start
/// </summary>
protected override void Start()
{
    base.Start();
    // Add service specific initialization here.

    SpawnIterator(MainLoop);
}

private IEnumerator<ITask> MainLoop()
{
    Random r = new Random();
    while (true)
    {
        // Generate a random number from 0-100 and write it out
        Console.WriteLine("B: " + r.Next(100));

        // Wait a while
        yield return Arbiter.Receive(
            false,
            TimeoutPort(1000),
            delegate(DateTime time)
            { }
        );
    }
}

The SpawnIterator in the Start method kicks off an infinite loop called MainLoop. ServiceB then displays a random number from 0-100 on the console, waits for a second, and then repeats forever (or until you shut it down). The point of this code is that it continually generates new random numbers that are used to simulate sensor readings.

Compile ServiceB and run it. You should see output like that in Figure 3-20.

Figure 3.20. Figure 3-20

Debugging services is just like debugging normal code—assuming that you normally debug multi-threaded code! You can set breakpoints and step through code just as usual. Try it out by setting a breakpoint inside MainLoop and running ServiceB again.

Figure 3-21 shows the debugger stopped at a breakpoint. Notice in the bottom-left corner that the Threads window is visible. Select it from the menu using Debug Windows Threads. This menu option is only available while the debugger is running. Two threads are assigned to the User Services Common Dispatcher. This dispatcher is set up for you by DssHost.

Figure 3.21. Figure 3-21

Be careful about where you set breakpoints. You can set breakpoints inside a delegate if you want to. If you try to single-step through the code, you might encounter strange behavior when you hit a yield return. Instead of stepping through a yield return, set a breakpoint on the statement after it and tell the debugger to continue execution.

If you are calling other services, you can debug them too. Simply open the relevant source file from another project in the current Visual Studio window. Set breakpoints in this "external" source file as required, and then run the debugger.

For example, later in the chapter you will be running ServiceA with ServiceB as a partner. You can open ServiceA in Visual Studio and set breakpoints in ServiceA.cs. Then, from the menu, click ? File Open ? File and browse to ServiceB.cs and open it. You can set breakpoints inside ServiceB as well. That way, as you send messages backward and forward, you stop in the code on both sides.

To load an initial state from a config file, you need to specify where it should come from. DSS can obtain a name for a config file in two ways:

/// <summary>
/// _state
/// </summary>
// Set an OPTIONAL initial state partner
// NOTE: If the config file is NOT specified in the manifest, then the
// file will be created in the MRDS root directory. If it is listed in the
// manifest, then it will be created in the same directory as the manifest.
[InitialStatePartner(Optional = true, ServiceUri = "ServiceB.Config.xml")]
private ServiceBState _state = new ServiceBState();

private const string InitialStateUri = ServicePaths.MountPoint + @"/ProMRDS/Config/Dashboard.Config.xml";

     // shared access to state is protected by the interleave pattern
     // when we activate the handlers
     [InitialStatePartner(Optional = true, ServiceUri = InitialStateUri)]
     StateType _state = null;

<?xml version="1.0" ?>
<Manifest
    xmlns="http://schemas.microsoft.com/xw/2004/10/manifest.html"
    xmlns:dssp="http://schemas.microsoft.com/xw/2004/10/dssp.html"
    >
    <CreateServiceList>
        <ServiceRecordType>
    <dssp:Contract>http://schemas.tempuri.org/2008/01/serviceb.html</dssp:Contract>
            <dssp:PartnerList>
              <dssp:Partner>
                <dssp:Service>ServiceB.Config.xml</dssp:Service>
                <dssp:Name>dssp:StateService</dssp:Name>
              </dssp:Partner>
            </dssp:PartnerList>
        </ServiceRecordType>
    </CreateServiceList>
</Manifest>

protected override void Start()
{
     base.Start();
     // Add service specific initialization here.
     Console.WriteLine("ServiceB starting");

     // Make sure that we have an initial state!
     if (_state == null)
     {
         _state = new ServiceBState();
     }
     // Sanity check the values (or initialize them if empty)
     if (_state.Interval <= 0)
         _state.Interval = 1000;

     // Save the state now
     SaveState(_state);

     SpawnIterator(MainLoop);
}

Saving the current state of a service is actually quite trivial—just call the SaveState helper function in DSS. However, you need to set up the name of the config file first, as explained in the previous section.

The following code from the previous code snippet saves the state each time the service runs:

// Save the state now
SaveState(_state);

SaveState is just a helper function that posts a Replace message to the Mount service. Because this happens asynchronously, you cannot assume when it returns that the state has been saved, or even that it was successful! However, SaveState returns a PortSet, so you can use it in a Choice to determine whether it returns a Fault. More important, if you are saving the state in your Drop handler, then you can wait until the save has completed before finally shutting down the service. The simplest way to wait is as follows:

yield return (Choice)SaveState(_state);

This assumes that you are inside an iterator.

In V1.5, the default output directory for saved config files was changed to the MRDS root directory (if no path is specified in the Partner attribute). For this reason, it is preferable to supply the filename in the manifest file. Then the file will be saved to the same directory as the manifest. Alternatively, as explained in the last section, you can specify an explicit path.

Saved state files are in XML format. In the case of ServiceB, the first time the state is saved it should look like the following:

<?xml version="1.0" encoding="utf-8"?>
<ServiceBState 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://schemas.tempuri.org/2008/01/serviceb.html">
  <Interval>1000</Interval>
  <SensorValue>0</SensorValue>
</ServiceBState>

You can edit the saved state and change the Interval. The file is in the MRDS root directory and is called ServiceB.Config.xml. Open this file in Notepad and change Interval to 200. Save the file.

Rerun ServiceB. The output should appear a lot faster. What you have done is to change the configuration of ServiceB without modifying the code and recompiling. Even though ServiceB rewrites the config file every time it runs, it simply propagates what is already there.

A Replace message supplies a completely new copy of the state. Because the Body of the message contains an instance of the state that is specific to this service, you must define a Replace class in your service types file (where xxx is the service name):

public class Replace: Replace<xxxState, 

PortSet<DefaultReplaceResponseType, Fault>>
    {
        public Replace()
        {
        }

public Replace(xxxState body)

: base(body)
        {
        }
    }

A basic Replace handler might look like the following:

[ServiceHandler(ServiceHandlerBehavior.Exclusive)]
public IEnumerator<ITask> ReplaceHandler(Replace replace)
{
    _state = replace.Body;
    replace.ResponsePort.Post(DefaultReplaceResponseType.Instance);
    yield break;
}

Notice that the handler is declared in the Exclusive group. This guarantees that the state is not updated by two different handlers at the same time, which could lead to an inconsistent state.

However, note also that the code does no checking of the incoming state. Most of the samples in the MRDS distribution are like this (if they have a Replace operation). It would be better to check crucial values in the state before making the replacement.

The handler sends an acknowledgment message to the ResponsePort when it has finished. It uses a pre-defined message called DefaultReplaceResponseType.Instance that makes your life easier because you don't need to create a response type. (Similar instances are available for other types of operations; use IntelliSense to look for them.) If the partner service cannot continue until the replacement is complete, then it can wait for this response message to arrive.

You use the Update messages when only a portion of the state needs to change. You need to define an appropriate class to hold all the information you want to update, and then write a handler to perform the update. This must be an Exclusive handler to avoid potential conflicts.

/// <summary>
/// ServiceB Set Interval Operation
/// </summary>
public class SetInterval: Update<SetIntervalRequest,
            PortSet<DefaultUpdateResponseType,Fault>>
{
    public SetInterval()
    {
    }
}

/// <summary>
/// Set Interval Request

/// </summary>
[DataContract]
[DataMemberConstructor]
public class SetIntervalRequest
{
    [DataMember, DataMemberConstructor]
    public int Interval;
}

_servicebPort.SetInterval(1500);

/// <summary>
/// Set Interval Handler
/// </summary>
/// <param name="request">SetIntervalRequest</param>
/// <returns></returns>
[ServiceHandler(ServiceHandlerBehavior.Exclusive)]
public virtual IEnumerator<ITask> SetIntervalHandler(SetInterval request)
{
    if (_state == null)
        // Oops! Return a failure
        request.ResponsePort.Post(new Fault());
    else
    {
        // Set the interval
        _state.Interval = request.Body.Interval;
        // Return a success response
        request.ResponsePort.Post(DefaultUpdateResponseType.Instance);
    }
    yield break;
}

/// <summary>
/// Get Handler
/// </summary>
/// <param name="get"></param>
/// <returns></returns>
[ServiceHandler(ServiceHandlerBehavior.Concurrent)]
public virtual IEnumerator<ITask> GetHandler(Get get)
{
    if (_state == null)
        // Oops! Return a failure
        // This can happen due to race conditions if another service
        // issues a Get before the Initial State has been defined
        get.ResponsePort.Post(new Fault());
    else
        // Return the state
        get.ResponsePort.Post(_state);
    yield break;
}

// Create a new Fault based on the error message
Fault fault = Fault.FromCodeSubcodeReason(FaultCodes.Receiver,
        DsspFaultCodes.OperationFailed, "Some error message");

In most cases, you do not need to explicitly start or stop a service because all the services you require will be started when the manifest is loaded. However, this section explains the procedure. The next section ("Using the Partner Attribute") shows you an easier approach.

Remember that ServiceA is the one that is in charge. It partners with ServiceB and makes requests to ServiceB. Therefore, open ServiceA.cs in Visual Studio.

// Create a port to access Service B,
// but we don't know where to send messages yet
serviceb.ServiceBOperations _servicebPort = null;

/// </summary>
protected override void Start()
{
    base.Start();
    // Add service specific initialization here.
    Console.WriteLine("ServiceA starting");

    // Start the main task on a separate thread and return
    SpawnIterator(MainTask);
}

private IEnumerator<ITask> MainTask()
{
      Port<EmptyValue> done = new Port<EmptyValue>();

      SpawnIterator<Port<EmptyValue>>(done, CreatePartner);

      // Wait for a message to say that ServiceB is up and running
      yield return Arbiter.Receive(
          false,
          done,
          EmptyHandler
      );

      // Check that we have a forwarder
      if (_servicebPort == null)
      {
          LogError("There is no ServiceB");
          yield break;
      }
      else

{
          SpawnIterator<Port<EmptyValue>>(done, MainLoop);
          yield return Arbiter.Receive(
              false,
              done,
              EmptyHandler
          );
      }

      // We no longer require ServiceB so shut it down
      // NOTE: This is not necessary—it is just here to illustrate that
      // other services can be shut down
      LogInfo(LogGroups.Console, "Dropping ServiceB .");
      _servicebPort.DsspDefaultDrop();

      Console.WriteLine("ServiceA finished");
      // Wait a while for ServiceB to exit
      yield return Arbiter.Receive(
          false,
          TimeoutPort(500),
          delegate(DateTime time)
          { }
      );

      // Pause for user input—
      // This is just so that the DSS node stays up for the time being
      Console.WriteLine("Press Enter to exit:");
      Console.ReadLine();
      // Shut down the DSS node
      ControlPanelPort.Post( 

new Microsoft.Dss.Services.ControlPanel.DropProcess());

            yield break;
        }

private IEnumerator<ITask> CreatePartner(Port<EmptyValue> p)
{
     // Create ServiceB instance
     Console.WriteLine("Creating new ServiceB");
     yield return Arbiter.Choice(CreateService(serviceb.Contract.Identifier),
         delegate(CreateResponse s)

{
                     // Create Request succeeded.
                     LogInfo(LogGroups.Console, "ServiceB created: " + s.Service);

                     Uri addr;
                     try
                     {
                          // Create URI from service instance string
                          addr = new Uri(s.Service);

                          // Create forwarder to ServiceB
                          _servicebPort = 

ServiceForwarder<serviceb.ServiceBOperations>(addr);
                     }
                     catch (Exception ex)
                     {
                         LogError(LogGroups.Console, 

"Could not create forwarder: " + ex.Message);
                    }
                },
                delegate(W3C.Soap.Fault failure)
                {
                    // Request failed
                    LogError(LogGroups.Console, "Could not start ServiceB");
                }
           );

           // Signal that the create is finished
           p.Post(EmptyValue.SharedInstance);

           yield break;
     }

private IEnumerator<ITask> MainLoop(Port<EmptyValue> p)
{
         // Issue several Gets to ServiceB
         yield return Arbiter.ExecuteToCompletion(Environment.TaskQueue,
             Arbiter.FromIteratorHandler(GetData));

         // Change the update interval on ServiceB
         _servicebPort.SetInterval(1500);

         // Do some more Gets to see the effect of the changed interval
         yield return Arbiter.ExecuteToCompletion(Environment.TaskQueue,
             Arbiter.FromIteratorHandler(GetData));

         // Finally, post a message to say that we are finished
         p.Post(EmptyValue.SharedInstance);

         yield break;
}

// Request "sensor" data from ServiceB
        private IEnumerator<ITask> GetData()
        {
            for (int i = 0; i < 10; i++)
            {
                // Send a Get request to ServiceB
                yield return Arbiter.Choice(_servicebPort.Get(),
                    delegate(serviceb.ServiceBState s)
                    {
                        // Get request succeeded
                        LogInfo(LogGroups.Console, 

"ServiceB Sensor: " + s.SensorValue);
                    },
                    delegate(W3C.Soap.Fault failure)
                    {
                        // Get request failed
                        LogError(LogGroups.Console, 

"Get to ServiceB failed" + failure.Reason);
                    }
                );

                // Wait for 1 second
                yield return Arbiter.Receive(
                    false,
                    TimeoutPort(1000),
                    delegate(DateTime time)
                    { }
                );
            }

            yield break;
      }

/// <summary>
/// Drop Handler
/// </summary>
/// <param name="drop"></param>
/// <returns></returns>
[ServiceHandler(ServiceHandlerBehavior.Teardown)]
public virtual IEnumerator<ITask> DropHandler(DsspDefaultDrop drop)
{
    // Tell the main loop to stop
    _shutdown = true;

    Console.WriteLine("ServiceB shutting down");

    // Make sure you do this or the sender might be blocked
    // waiting for a response. The base handler will send
    // a response for us.
    base.DefaultDropHandler(drop);

    // That's all folks!
    yield break;
}

_servicebPort.DsspDefaultDrop();

Running the Services Together

Recompile both ServiceA and ServiceB. Then run ServiceA in the debugger. If you have done everything properly, then Service B should also start up, as shown in Figure 3-22.

Figure 3.22. Figure 3-22

If you read through the output in Figure 3-22, you will see that ServiceB is created by ServiceA, but the first Get response from ServiceB is before it has output any "sensor" readings, and consequently the value is zero. (The first "reading" is when ServiceB displays B: 64).

After 10 iterations, the timer interval for ServiceB is changed by ServiceA. Then you see sensor readings doubling up because ServiceA continues to poll ServiceB at the same rate as before. This is now too fast for the incoming "sensor data" at the ServiceB end.

Lastly, ServiceA tells ServiceB to shut down by sending a Drop message.

Rather than create services explicitly, you can create a service partner declaratively using the [Partner] attribute. This is the usual approach. However, sometimes you do not know ahead of time what services you will have to partner with—for example, the Dashboard dynamically partners with Differential Drive services, Laser Range Finder services, and Webcam services. When it starts, it doesn't know which of these services might be available. More to the point, it doesn't know which DSS node you are going to point it at.

To specify a partner at compile time, go back to the top of ServiceA.cs and change the declaration of _servicebPort as follows:

// Partner with ServiceB
[Partner("ServiceB", Contract = serviceb.Contract.Identifier,
    CreationPolicy = PartnerCreationPolicy.CreateAlways, Optional = false)]
private serviceb.ServiceBOperations _servicebPort =
    new serviceb.ServiceBOperations();

Notice that the contract identifier for ServiceB is specified as a parameter to the [Partner] attribute. In addition, ServiceB is not optional. The CreationPolicy is set to CreateAlways. This causes the constructor service to create a new instance of ServiceB for you. It doesn't matter whether you create a new instance of the service operations port or leave it null if the config file exists because the State service will take care of it.

Four service creation policies are available:

The simplest approach is CreateAlways. This is equivalent to creating the service explicitly but requires only a couple of lines of code. In some cases this makes sense, such as when a service uses another service that is never called directly by anyone else, i.e., there is a one-to-one partnership.

Now that you have declared the partnership with ServiceB, there is no longer any need to call the CreatePartner routine. However, for the purposes of illustrating a point, you will insert some different code.

The FindPartner routine replaces CreatePartner:

private IEnumerator<ITask> MainTask()
{
     Port<EmptyValue> done = new Port<EmptyValue>();

     SpawnIterator<Port<EmptyValue>>(done, FindPartner);

FindPartner issues a DirectoryQuery to try to find ServiceB, but with the default long timeout:

private IEnumerator<ITask> FindPartner(Port<EmptyValue> p)
        {
            // Find ServiceB in the local directory
            Console.WriteLine("Finding ServiceB in the Directory");
            yield return Arbiter.Choice(
                DirectoryQuery(serviceb.Contract.Identifier, 

DsspOperation.DefaultLongTimeSpan),
                delegate(ServiceInfoType s)
                {
                    // Request succeeded
                    LogInfo(LogGroups.Console, "Found ServiceB: " + s.Service);

                    Uri addr;
                    try
                    {
                         // Create URI from service instance string
                         addr = new Uri(s.Service);

                         // Now create service forwarder to ServiceB
                         _servicebPort = 

ServiceForwarder<serviceb.ServiceBOperations>(addr);
                    }
                    catch (Exception ex)
                    {
                        LogError(LogGroups.Console,
"Could not create forwarder: " + ex.Message);
                        _servicebPort = null;
                    }
                },
                delegate(W3C.Soap.Fault failure)
                {
                     // Request failed
                     LogError(LogGroups.Console, "Could not find ServiceB");
                     _servicebPort = null;
                }
            );

            // Signal that the find is finished
            p.Post(EmptyValue.SharedInstance);

            yield break;
     }

Basically, FindPartner waits until ServiceB does a DirectoryInsert and becomes visible in the service directory. The rest of the code is the same as CreatePartner. This is one way to synchronize service startup. For it to work successfully, services must not call base.Start until they have completed all of their initialization. Otherwise, they appear in the directory prematurely. If you run this revised version of the code, there is not very much difference, so no screenshot is provided.

You can change the partner creation policy to UseExistingOrCreate, but you won't see any difference in this scenario because the "Or Create" option causes ServiceB to be created. In other words, ServiceA uses an existing instance of ServiceB if one exists; if not, it simply goes ahead and creates one anyway.

When you create a new service, a manifest is automatically created for you. This section steps you through the process of modifying a manifest using a text editor. However, as you will see later in "Modifying Manifests Using the DSS Manifest Editor," it is preferable to use the appropriate tool for this task. The purpose of this section is to give you some understanding of what manifests look like and how they work. It is not suggested that you always edit manifests by hand.

Use Existing Partner

In Visual Studio for ServiceA, open ServiceA.manifest.xml. It should have a single service record for ServiceA. Leave it alone for the moment.

Change the partner creation policy in ServiceA.cs to UseExisting:

// Partner with ServiceB
[Partner("ServiceB", Contract = serviceb.Contract.Identifier,
    CreationPolicy = PartnerCreationPolicy.UseExisting, Optional = false)]
private serviceb.ServiceBOperations _servicebPort = 

new serviceb.ServiceBOperations();

This specifies that there must be a ServiceB running on the DSS node before ServiceA can start up properly. You can see from the ServiceA manifest that there is no mention of ServiceB.

Recompile the code and run ServiceA. Be patient—very patient! In fact, be patient for up to two minutes. Eventually, an error message will appear (displayed in red), as shown in Figure 3-23.

Figure 3.23. Figure 3-23

This error says, "Partner enumeration during service startup failed." Quite clearly, the error occurred because you asked for ServiceB but did not create a new instance of it. This is easy to fix.

Open the ServiceB.manifest.xml in Visual Studio and copy the Service Record. Then go to ServiceA.manifest.xml and paste it in there. The resulting ServiceA manifest should look like the following:

<?xml version="1.0" ?>
<Manifest
    xmlns="http://schemas.microsoft.com/xw/2004/10/manifest.html"
    xmlns:dssp="http://schemas.microsoft.com/xw/2004/10/dssp.html"
    >
  <CreateServiceList>
    <ServiceRecordType>
    <dssp:Contract>http://schemas.tempuri.org/2008/01/servicea.html</dssp:Contract>
    </ServiceRecordType>
    <ServiceRecordType>
    <dssp:Contract>http://schemas.tempuri.org/2008/01/serviceb.html</dssp:Contract>
      <dssp:PartnerList>
        <dssp:Partner>
          <dssp:Service>ServiceB.Config.xml</dssp:Service>
          <dssp:Name>dssp:StateService</dssp:Name>
        </dssp:Partner>
      </dssp:PartnerList>
    </ServiceRecordType>
  </CreateServiceList>
</Manifest>

Be very careful when you copy and paste pieces of code between XML files. If you end up with mismatched tags, the manifest won't work at all and you will just get a syntax error. This is one reason why it is better to use the Manifest Editor (discussed in "Modifying Manifests Using the DSS Manifest Editor"), rather than edit manifests manually.

Remember that in the section "Specifying a Configuration File in a Manifest" you added a state service partner to ServiceB. This is part of the Service Record as well. However, when you run ServiceA now, a new config file is created in the ProjectsServiceA folder because that is where the manifest is. It all gets a little confusing after a while.

This is the brute-force approach to partnering—it simply specifies two services in the manifest and they are both created. Save the manifest and run ServiceA again. The services should now run successfully.

Contract Identifiers and Case Sensitivity

If you have plenty of time and nothing better to do, edit the manifest again by changing the names of the services in the contract identifiers to ServiceA and ServiceB, i.e., capitalize them so that they look pretty. Run ServiceA. What happens? Look at Figure 3-24.

Figure 3.24. Figure 3-24

First, the contract directory cache is rebuilt because you requested two services that DSS has not seen before. However, this doesn't help and you get two error messages saying that there was an error creating the service, with a Fault.Subcode of UnknownEntry.

This is a small trap for beginners—contract identifiers are case-sensitive.

<?xml version="1.0" ?>
<Manifest
    xmlns="http://schemas.microsoft.com/xw/2004/10/manifest.html"
    xmlns:dssp="http://schemas.microsoft.com/xw/2004/10/dssp.html"
    xmlns:this="http://schemas.tempuri.org/2008/01/servicea.html"
    >
  <CreateServiceList>
    <ServiceRecordType>
    <dssp:Contract>http://schemas.tempuri.org/2008/01/servicea.html</dssp:Contract>
    <dssp:PartnerList>
      <dssp:Partner>
        <dssp:Name>this:ServiceB</dssp:Name>
      </dssp:Partner>
    </dssp:PartnerList>
    <Name>this:ServiceA</Name>

</ServiceRecordType>
  <ServiceRecordType>
    <dssp:Contract>http://schemas.tempuri.org/2008/01/serviceb.html</dssp:Contract>
      <dssp:PartnerList>
        <dssp:Partner>
          <dssp:Service>ServiceB.Config.xml</dssp:Service>
          <dssp:Name>dssp:StateService</dssp:Name>
        </dssp:Partner>
      </dssp:PartnerList>
      <Name>this:ServiceB</Name>
    </ServiceRecordType>
  </CreateServiceList>
</Manifest>

The DSS Manifest Editor was introduced in MRDS V1.5 as a tool to help make the creation and editing of manifests easier. We do not intend to provide a tutorial on the Manifest Editor here, but you should be aware that it exists and read up on it in the online documentation. (Actually, the Manifest Editor is not a separate program but part of VPL. A batch file called dssme.cmd in the MRDS bin directory executes VPL in Manifest mode.)

To try out the Manifest Editor, use the very last manifest from the previous section. You can start the Manifest Editor by clicking Start ? Microsoft Robotics Studio (1.5) ? Microsoft DSS Manifest Editor. It might take a little while to start, because it is listing all of the available services.

When the Manifest Editor main screen appears, click File ? Open and browse to the ServiceA manifest to open it. Once the manifest has been loaded, it should look like what is shown in Figure 3-25.

Figure 3.25. Figure 3-25

You can select ServiceB and add an initial configuration if you want. This will add a state partner with a nominated config file.

Apart from that, just play around in the Manifest Editor until you are comfortable with it. You will find it is much easier to use than editing XML files. It is the recommended method for editing manifests, rather than opening them in a text editor.

You can get information about contracts and the operations that a service supports using the DssInfo tool. For example, the following command displays information about the Dashboard service that is included with the code for Chapter 4:

C:Microsoft Robotics Studio (1.5)>dssinfo bindashboard.y2007.m10.dll

You can control the amount of information displayed using command-line qualifiers. The default information level shows the contract, partners, the operations that are supported, and so on, as shown here:

Reflecting:                         Dashboard.Y2007.M10.dll
DSS CONTRACT
Verbosity                           ShowWarnings
Assembly:                           c:microsoft robotics studio (1.5)indashboar
                                    d.y2007.m10.dll

Service:                            DashboardService
   DssContract:                     http://www.promrds.com/2007/10/dashboard.html
   Namespace:                       ProMRDS.Robotics.Services.Dashboard
   ServicePrefix:                   /dashboard
   Singleton:                       False
   Partner(s):
     [InitialStatePartner]          /mountpoint/ProMRDS/Config/Dashboard.Config.xml
     UseExistingOrCreate            http://schemas.microsoft.com/robotics/2006/09/g
                                    amecontroller.html
   ServicePort                      DashboardOperations
     Lookup:                        DsspDefaultLookup
     Drop:                          DsspDefaultDrop
     Get:                           Get
     Replace:                       Replace

If you run DssInfo and specify RoboticsCommon.dll, you will see several generic contracts and some actual service implementations.

At this stage, you do not need to migrate any services because all your code is on one computer and you have not upgraded MRDS. However, it is worth mentioning the DssProjectMigration tool so that you can file away it in the back of your mind for later use. This tool can be very useful in a couple of circumstances:

For more information, you can refer to the online documentation when you need to use DssProjectMigration.

If you are interested in sharing your code, you can package it so that other people can install it into their MRDS environment. This is what the authors have done with the ProMRDS code. In this case, the DssDeploy package contains only the source code for the relevant services and the compiled DLLs. All of the object files, debug symbol tables, and so on, are left behind because they can be recreated by compiling the source code.

To build a package for one of the chapters in this book, following these steps:

When you get to Chapters 16 and 17, you will be deploying services to a PDA running Windows Mobile or an eBox embedded PC running Windows CE. These environments run the .NET Compact Framework, so they are referred to as CF services for short.

In this situation you do not want to install the full MRDS environment. (In fact, you can't do this anyway.) What you want is a runtime-only environment.

The batch script to create the package, called BuildStingerCFPackage.cmd, contains the following commands:

REM Create a DssDeploy package
setlocal
call "......sdkenv.cmd"
cd "%~dp0"
DssDeploy /p /cf /n:"ProMRDS Stinger CF Example" /d:"../../BatchFiles/CF/*"
/m:../../Config/StingerCFDriveByWire.manifest.xml StingerCF.exe
pause

This DssDeploy command creates a package for the Compact Framework due to the /cf qualifier. It explicitly adds all the files from the BatchFilesCF folder to the package, and then uses a manifest to collect all of the necessary services. DssDeploy analyzes the manifest and walks down the dependency tree looking for service DLLs. The MRDS runtime DLLs are automatically included.

Deploying a runtime version of MRDS in this fashion is not restricted to just CF platforms. You can also create a package without the /cf qualifier and deploy it to Windows XP or Vista.

There is one restriction on the runtime-only version, however, and it is related to the simulator. In order to run Simulation services, you need to have the AGEIA PhysX engine installed, as well as the latest versions of Microsoft DirectX and XNA. In short, you must have MRDS installed on the target machine if you want to deploy a simulation.

A tool called ViewDssDeployContents, written by Paul Roberts at Microsoft, is available from the Channel 9 website (http://channel9.msdn.com/ShowPost.aspx?PostID=368096), and you should definitely download a copy of it. Perhaps this tool will be included in MRDS V2.0.

This tool shows, in an Explorer-like tree, what files are included in the package. This is particularly handy if you want to check out a package before installing it. Otherwise, you might have no idea what files are going to be replaced. DssDeploy only lists the files that will be replaced if there are less than about 20 of them, but beyond that, it simply asks you something like "72 files will be replaced, OK?".