The basic function of every service is to send and receive messages. This is what enables services to communicate with each other. Messages are strongly typed, and message types are specified within a service. DSS requires that a message must contain the following three elements:

The "Hello World" phrase is returned by something known as a DSS transform file. The transform file, along with the service proxy, is generated when the service assembly is compiled. The state items for a service will pass through calls to the transform before being returned to the service.

The proxy and transform files are generated automatically when you use the Visual Studio template. To see where this is called, on the Project menu, choose project_name Properties. Click the Build Events tab and you see the command line for the DssProxy utility in the post-build event command line. By default, the assemblies generated are stored in the bin subdirectory for the MSRS installation.

Tip

If your service is running on the DssHost, you will not be able to compile your service until the DssHost process has been stopped. You can do this by simply closing the command window that is launched when you run the DSS node.

When compiling a service, MSRS will generate three assemblies: one for the service, one for the proxy, and one for the transform. They will be named using the following naming convention: <service name>.Y<year>.M<month>.<Proxy, Transform, or blank>.dll. For example, the following three files will be generated based on the date the service named DssService1 is compiled:

To understand how MSRS handles sending and receiving messages through DSS ports, let’s take a closer look at the code that is generated when you create a new service using the Visual Studio template. In the DssService1.cs file, there is a declaration for the main port (as shown below):

[ServicePort("/dssservice1", AllowMultipleInstances=false)]
private DssService1Operations _mainPort = new DssService1Operations();

This code indicates that the main port does not allow multiple instances and that the service will be located in a subdirectory named dssservice1. Given this information, you can determine the URL of the service, http://localhost:50000/dssservice1. If the port allowed for multiple instances, each instance would be appended with a globally unique identifier (GUID).

The code also indicates that the port can perform Decentralized Software Services Protocol (DSSP) operations defined in the DssService1Operations class. You might recall from Chapter 1 that DSSP is the SOAP-based protocol used by DSS to handle messages. The DssService1Operations class is located in the DssService1Types.cs file and looks like the following:

[ServicePort()]
public class DssService1Operations : PortSet<DsspDefaultLookup,DsspDefaultDrop, Get>
{
}

The DssService1Operations class defines a PortSet, and this PortSet is used to indicate what types of DSSP or HTTP messages are allowed. All services are required to include the DsspDefaultLoopkup operation, which defines a default message handler for a Lookup message. The Lookup message is used to return the service context, which contains information about how to communicate with the service. DsspDefaultDrop is not required, but it allows the service to support the Drop message. Finally, the Get message allows the service to respond with its current state.

Get is just one of several DSSP operations allowed (refer to Table 2-3 for a list of additional DSSP operations). It will return state in the format of a SOAP message as required by DSSP. To return the state as raw XML, you would need to add an HTTP operation such as HttpGet to the PortSet list. An example of this is provided in Service Tutorial 1 and is available at http://msdn2.microsoft.com/library/bb905437.

Table 2-3 lists the DSSP operations that can be added to a PortSet. The DSS Service Model provides built-in classes that define and implement default code for some of these operations. You can get started by using these defaults instead of adding the code to your service. Ultimately, you will only want to use the defaults when the state for a service is not known or when the implementation is generic. In most cases, you will only use the defaults for the Lookup and Drop operations.

Keep in mind that you can add your own custom messages, which derive from the DsspOperation class. Most services you write will include at least one custom operation implementation. An example of this is seen with the IncrementTick message defined in Service Tutorial 2 (which is available at http://msdn2.microsoft.com/library/bb905437). In addition to the DSSP operations, you can also use HTTP-based operations (as shown in Table 2-4).

A service handler is responsible for handling incoming messages on a port. A service can have more than one service handler, and each one will pertain to a different DSSP, HTTP, or custom operation. The only exceptions to this are the DsspDefaultLookup and DsspDefaultDrop operations because these are typically handled by the DSS runtime but can be overwritten by the service if needed.

The Visual Studio template, which is used to create a new DSS service, provides only one service handler. The service handler (shown as follows) is used to handle DSSP Get messages:

[ServiceHandler(ServiceHandlerBehavior.Concurrent)]
public virtual IEnumerator<ITask> GetHandler(Get get)
{
    get.ResponsePort.Post(_state);
    yield break;
}

The GetHandler does not do much. It simply posts the state as a SOAP message to the response port. The code in this handler could contain additional code that performs computations or sends messages to other services.

Each service handler allows you to define how it will be processed. For example, GetHandler is set to run concurrently. This behavior should be set for handlers that do not modify state. For handlers that modify state, the Exclusive service handler behavior attribute should be used. Other attributes include Teardown, which is executed once and shuts down the service, and DsspOperationDefault, which picks the behavior based on the operation type.