Summary: When to use Alternate Contracts and Alternate Ports

Note: We recently added service tutorial 8 and service tutorial 9 (also described in DSS user guide which show how to declare generic contracts, implementing generic contracts, extending generic contracts, and implementing multi-headed services. The full code is not included in Microsoft Robotics Studio (1.5) but based on the code snippets included in the documentation it should be possible to follow.

When to use Alternate Contracts and Alternate Ports

It is important to understand the different types of services that can be written, and then decide which best fits your situation.


A) Single Service

A new service with its own contract which defines its own state and behavior.

		  [DssNewService] [–s:MyNewService]
	

B) Multiple services in a single assembly

You can combine services by simply creating a separate namespace and contract for each service.

* You can use DssNewService to generate each of your services, then combine the service.cs and servicetypes.cs files from multiple services into a single project (and include the rest of the project files only once).
* Each service can be started independently (by including the contract in your manifest or selected it in VPL).
* One service can start the other service by using the Partner attribute on an instance of the other services’ operation port.


C) An implementation of another service contract

This is a service which implements a different contract but has no additional state or behavior other than that which is defined in the other contract.

This is useful when you have multiple brands of a particular type of device which all work the same but require different code to be accessed. For example, a joystick which has a custom interface, but works like a standard game controller.

		  [DssNewService] [–s:MyGameController] –implement:" GameController.Y2006.M09.dll"
		                –alt:"http://schemas.microsoft.com/robotics/2006/09/gamecontroller.html"
	

* Places AlternateContract on the service class definition
* The main port uses the operation port defined in the alternate contract.
* Operation handlers for every operation are stubbed out for you to implement.


D) An extension of another service contract

A service which implements a different contract but has additional state and/or behavior. An example would be a gaming joystick which implements the GameController contract, but also exposes an extra thumb stick, accelerometer, etc.

This is an advanced service and will require more coding.

* Implement your own OperationPort and Handlers. This will usually be a superset of your alternate contract. Where possible, your operation port should use the same operations as the alternate contract.
* Use AlternateServicePort to expose the alternate GameController contract on a separate url.
* Add new operation handlers for each operation in the alternate GameControllerOperations port.
* In the Start() method, add base.MainPortInterleave.CombineWith(new Interleave(…) and an Arbiter.Receive… for each of the handlers.
* Use shared state between the main port and the alternate port to show a different view of the same state.


E) A multi-function device or service

A multi-function device which exposes possibly related, but different functionality. One example would be a robot which implements a Drive service as well as two Motor services. There are multiple ways to do this, but I would create separate services in the same assembly ( B ), and each service would use ( A ), ( C ), or ( D ) as it’s pattern. In the case of a Drive with two Motors, I would set up each of the motors as a partner to the drive implementation, and mark them with “CreateOnly” which will cause their services to be initialized when the Drive service starts. Additionally you will need to either pre-load the state for each Motor from an InitialStatePartner, or you will need to send a Replace to each instance of the Motor service to configure the motor for your usage. RoboticsCommon has a generic Drive implementation (drive.cs) which does exactly this.

Another example might be a printer which also functions as a fax machine. Since these services really don't overlap their state, you might write two seperate services in the same assembly which expose this functionality.