DSS Service Projects Overview

Glossary Item Box

DSS User Guide: Creating DSS Service Projects | Choosing Programming Language | DSS Service Contracts

Microsoft Robotics Developer Studio

Send feedback on this topic

DSS Service Projects Overview

As described in Creating DSS Service Projects, service projects can be created using Microsoft Visual Programming Language (VPL) or various .NET languages. However, regardless of how a service project is created, it contains a common set of components as described below.

Service Project Files

For illustration look at a basic sample C# project using DSS New Service Generation Tool (DssNewService.exe). The same parameters apply to other supported programming languages. Note also that you can also create a new service project directly using a Wizard within Microsoft Visual Studio by selecting, New Project, and then selecting the appropriate Microsoft Robotics Developer Studio project template. See Creating DSS Service Projects.

From a Decentralized Software Services (DSS) command prompt, type the following to create the sample C# service project:

DssNewService.exe /s:SimpleSample

This creates a new directory called SimpleSample which contains the service code. Note that DssNewService does not create a Solution file (.sln), so you will have to open the Project file (.csproj) in Visual Studio first to create the Solution file. You can open the .csproj file as follows:

cd SimpleSample
start SimpleSample.csproj

Once you have done this, exit from Visual Studio and save the Solution file. You can examine the contents of the folder at the command prompt by typing the following:

dir

The resulting output looks similar to this. Note that time stamps and sizes will be different.

06/03/07  10:00               674 AssemblyInfo.cs
06/03/07  10:00             2,229 SimpleSample.cs
06/03/07  10:00             5,048 SimpleSample.csproj
06/03/07  10:00             1,233 SimpleSample.csproj.user
06/03/07  10:00               398 SimpleSample.manifest.xml
06/03/07  10:00               909 SimpleSample.sln
06/03/07  10:00             5,375 SimpleSampleTypes.cs

The service project files fall into three categories: Visual Studio files, source code files, and manifests as described below:

Visual Studio Files

The files SimpleSample.csproj, SimpleSample.csproj.user, and SimpleSample.sln are used by Visual Studio to manage the service project. Visual Studio provides two types of containers named solutions and projects. These containers are used for managing items necessary for developing services such as references, folders, files, and dependencies. In addition, Visual Studio provides solution folders to organize related projects into groups and perform actions on those groups of projects. Solution Explorer, an interface for viewing and managing these containers and their associated items, is part of the Visual Studio Integrated Development Environment (IDE).

To open the service project within Visual Studio you can either start Visual Studio from the Start menu or type the name of the project or solution on the command line of a DSS command prompt, for example

SimpleSample.sln

If you are not already familiar with the Visual Studio IDE, projects and solutions, refer to the Visual Studio documentation within the MSDN Library for details.

Source Code Files

The source code files SimpleSample.cs, SimpleSampleTypes.cs, and AssemblyInfo.cs represent a starting point for actual service implementation. While the service project, at this point already contains some code, it is only a template for how to build a complete service implementation. The AssemblyInfo.cs file contains some project wide attributes that you do not normally have to modify.

The SimpleSample.cs file contains the core of the DSS Service Components consisting of initialization and termination code, service handlers, and event notification handlers. The SimpleSampleTypes.cs file contains contract identifier as well as a definition of the service state and which messages are allowed on the main port. See DSS Service Components for details.

Manifest Files

Manifests are XML files that can be read by the Manifest Loader Service indicating a set of services that are to be started. While manifests can be loaded at any time during the life time of a DSS Node, they are typically used during start-up of a node indicating which services to start. Manifests can be indicated on the command line when starting a DSS Node using DSS Host Tool (DssHost.exe), or as part of the static DssEnvironment class. They can also be loaded using the Control Panel service which is one of the DSS System Services. They can also be loaded programmatically by accessing the Manifest Loader Service directly.

Compiling a Service Project

Visual studio projects and solutions can be compiled from within Visual Studio or directly from the DSS command prompt using MSBuild. MSBuild is part of the .NET Framework. For details on how to use MSBuild from the command line, refer to the MSBuild documentation within the MSDN Library for details.

If you opened the solution above in Visual Studio it can be compiled by selecting Build Solution, commonly also available by pressing F6. This causes three assemblies to be generated:

1. A service implementation assembly based on the source code included in the service project.

2. A DSS Proxy assembly exposing the contract of a service so that it programmatically can be used with other services. The proxy assembly contains the public operations and state types exposed by the service. When services partner with each other they link with proxy assemblies rather than directly with each other.

3. A DSS Transform assembly providing a mapping between the typed defines in the service implementation assembly and the proxy assembly. The service transform assembly is loaded automatically by the DSS runtime and is only relevant to the service implementation. It is not relevant to other services using the service proxy.

All three assemblies are copied into the common bin folder which allows them to be loaded and instantiated by the DSS runtime. See Running DSS Services for how to start a service and interact with it from a Web browser.

The name of the service implementation assembly can be controlled using command line options in connection with the DSS New Service Generation Tool (DssNewService.exe), or by changing the project settings in Visual Studio. The default assembly name form is,

<ServiceName>.Yyyyy.Mmm

where yyyy is a four digit year and mm is the two digit month. By convention, the proxy and transform assemblies are named similar to the service implementation. However, proxy and transform are appended respectively.

Extending a Service Project

Service projects are not limited to containing the source code files listed above. Typical extensions of a service project include XSLT files for generating HTML from the service state as well as images, audio files, scripts, etc. Such additional files can either be copied directly to the output folder which makes them accessible to other services using the Mount Service or they can be embedded into the service implementation assembly as embedded resources served using the Embedded Resource Service.

Managing Multiple Service Projects

When you create a service project, by default, it contains a single service within a single Visual Studio project contained within a single Visual Studio solution:

However, a project can contain multiple services and a solution can contain multiple projects. This becomes more and more useful as the number of services grow, both for managing cross service dependencies and also to limit the number of service Dynamically Linked Libraries (DLLs).

Adding Multiple Projects to a Solution

Service projects can easily be added to the same solution enabling you to explicitly set the dependencies between multiple service projects. First we create a second service project exactly as we did before from a DSS Command Prompt

cd %MRI_INSTANCE_DIR%
DssNewService.exe /s:SimpleSampleTwo

Similar to before you will find a folder called SimpleSampleTwo containing the new service project. Now, open the SimpleSample.csproj project file, then exit from Visual Studio. It will ask if you want to create a Solution file, so answer yes so that a Solution file will be created. Now open the SimpleSample.sln solution file from the first service project and in the Visual Studio Solution Explorer select Add Existing Project and add SimpleSampleTwo to the solution so that it contains both projects:

Service implementations do not link against each other directly but rather use their associated proxy assemblies as this allows service implementations to evolve and be deployed independently. Because proxy assemblies are not exposed directly in the Solution Explorer, however, you should indicate dependencies between service projects using the Project Dependencies wizard in Visual Studio. For example, if SimpleSampleTwo depends on SimpleSample then use the Project Dependencies wizard to set the build order so that SimpleSample is built before SimpleSampleTwo.

Adding Multiple Services to a Project

When compiling the solution above with two service projects the result is two sets of service assemblies. One assembly for the SimpleSample service and one assembly for the SimpleSampleTwo service. However, as the number of services grow, it often makes sense to incorporate multiple services into a single set of assemblies.

When combining multiple services into the same assembly, each service must be in a separate Common Language Runtime namespace.

Inspecting Service Assemblies

Service assemblies can be inspected using the DSS Contract Information Tool (DssInfo.exe). This allows you to determine which services are implemented as well as their contract. As an example, to inspect the assembly generated above, type the following from a DSS command prompt:

cd %MRI_INSTANCE_DIR%\bin
DssInfo.exe /v:m SimpleSample.*.dll

DSS User Guide: Creating DSS Service Projects | Choosing Programming Language | DSS Service Contracts

© 2012 Microsoft Corporation. All Rights Reserved.