Service Tutorial 11 (C#) - DSS Manifest Editor
Glossary Item Box
Writing an application using DSS is a simple matter of orchestrating the input and output between a set of services. These services can reside in different instances of DSS nodes which may be distributed across multiple computers.
Connections between services in different DSS nodes can be set up programmatically or by specifying the URL in the manifests. DSS provides tools that help you to create manifests for multiple nodes and run them.
This tutorial describes how to create two distributed applications with existing services using the Microsoft DSS Manifest editor.
This tutorial teaches you how to:
This tutorial uses the services written in Service Tutorial 4 (C#) - Supporting Subscriptions and Service Tutorial 5 (C#) - Subscribing.
This tutorial requires no special hardware.
This tutorial is designed for use with the DSS Manifest Editor which is part of DSS.
You will also need Microsoft Internet Explorer or another conventional web browser.
Step 1: Create a Distributed Application Project
Start the Microsoft DSS Manifest Editor and choose New from the File menu to create a new project.
The Microsoft DSS Manifest Editor supports two different project types. You can edit a Microsoft DSS Manifest for a single node directly. In order to create a distributed application select Microsoft DSS Distributed Application.
The Microsoft DSS Manifest Editor now shows two pages. The Application page shows the list of all services in your application independent of the node they run on. The Nodes page shows all DSS nodes and the services that they run.
By default a new project has one node (Windows) and no services. In case you close any of the pages accidentally, you can reopen them by double-clicking on the respective entry in the Project toolbox.
Step 2: Add and Configure Nodes
A node is an instance of the DSS runtime. In order to build a distributed application, you need at least two nodes. Add a second node using the Add button (or the right-click context menu). For this tutorial choose Microsoft Windows (this includes all desktop and server versions of Microsoft Windows that are capable of running Microsoft DSS). If you develop services for Microsoft Windows CE or Microsoft Windows Mobile, you can choose Microsoft Windows CE instead.
The application now has two nodes. They are currently configured to run at the same computer using the same port number. Select the first node (Windows) by clicking on its title bar. In the Properties toolbox change its name to A (or any other name you are comfortable with). Now select the second node change its name to B. Also change the ports of node B's transports to 50004 and 50005 so that they are different from A. In this tutorial you run both nodes on the same computer. However, you can easily change this by replacing localhost in the transport configuration of your node to the DNS names or IP addresses of the computers you want to use.
Ports for the HTTP transport must be reserved by an administrator before they can be used. You can used the httpreserve commandline tool, e.g. httpreserve /p:50004 /u:<username>.
Step 3: Add and Partner Services
This tutorial uses the services written in Service Tutorial 4 (C#) - Supporting Subscriptions and Service Tutorial 5 (C#) - Subscribing. Service Tutorial 4 implements a simple clock service that sends tick notifications. Service Tutorial 5 subscribes to the clock service and synchronizes its own state with that of the clock.
Locate the Service Tutorial 5 service in the Services toolbox, drag it onto node A, and drop it there. This adds a new instance of the service to your application (If you switch to the Application page, you will see the instance there, too.)
Notice that the service you just added requires a partner called Clock. Select this partnership. This will automatically reduce the Services toolbox down to the list of services that can be used for this partnership (you may have to clear the search box). In this tutorial the only possible partner service is Service Tutorial 4. Drag it from the Services toolbox to the Clock partnership. This will add a new instance of the service and will also set up the Clock partnership to use this instance.
At this point the names of the instances are a bit confusing. Select the first service (ServiceTutorial) and rename it to ClockSubscriber in the Properties toolbox. Rename the second service (ServiceTutorial0) to Clock.
Both service instances are still in the same node. So it is technically not a distributed application yet. Drag the Clock service from node A to node B and drop it there. The application is now distributed.
Step 4: Create Manifests and Deploy Packages
In order to be able to run your application you need to create DSS manifests and DSS deploy packages for each node. Luckily in the Microsoft DSS Manifest Editor this boils down to a couple of mouse clicks.
From the Deploy menu select Create Deployment Package. This will prompt you to save the project (this tutorial uses ServiceTutorial11 as file name) and to select the output directory where you want the manifests and packages to be created. (You have to repeat this step after you make changes to the project in order to guarantee that the changes are reflected in manifests and packages.)
Please note that the output directory must not be the installation directory of DSS or any of its subdirectories. (This limitation only applies to the Microsoft DSS Manifest Editor and the Microsoft Visual Programming Language.)
The output directory now has the following contents.
For each node in the project there are three files. The .exe file is a self extracting DSS deploy package that contains all necessary files to run the node, this includes DSS Runtime and all its dependencies. You can use this package to install the node on a different computer. The .manifest.xml specifies the list of service that need to be started for the node. The .cmd file is a sample script that shows how to start the node manually. Both the manifest and the cmd script are included in the DSS deploy package.
The DSS deploy packages will contain the node configuration (dsshost.exe.config) that is on the computer on which the Microsoft DSS Manifest Editor was used to create the packages. This includes whatever security settings that were made in this file. If you want to change the security settings in the generated package, you can either change the original settings before creating the deployment packages or change the configuration after you have deployed the packages.
Step 5: Run the Distributed Application
You can run the application manually by starting the individual nodes using the provided manifests. Please consult the DSS documentation for instructions on how to do that.
Prior to running the application, you need to deploy the package(s). See the DSS User Guide for information on DssDeploy and how to distribute applications. In the following steps you deploy the packages on your existing PC for testing purposes.
To run the package from a command line, follow these steps:
- Open a DSS Command Prompt window and navigate to the directory that you wrote the deployment package to.
- Deploy the A node by running A.exe. This will unpack the files used by the A node into the current directory.
- Deploy the B node by running B.exe. This will unpack the files used by the B node into the current directory. Note that you will be prompted to overwrite a set of files that are shared between the services. Press OK at this prompt.
- Start the B node with the command: "start B.cmd". Note that you must use "start" because this starts the new DSS node in the background without tying up the command prompt. Alternatively, you can run "B.cmd" and then open a new DSS Command Prompt window to run the other service.
- Start the A node (which depends on B to be already running) with the command: "start A.cmd".
Now use a web browser to examine the state of each of the services as shown at the end of the next step.
Step 6: Run the Distributed Application via the Manifest Editor
The Microsoft DSS Manifest Editor provides a more convenient way of running your application. Select Run on distributed Nodes from the Run menu.
This will prompt you to make sure that the Package Deployer service is running on each of the computers on which you want to run the nodes (in this case only localhost).
The package deployer is a helper service that the Microsoft DSS Manifest Editor uses to deploy and run packages on remote computers. You have to make sure that the service is running and that you have permissions to access it (please consult the security documentation on how to change permissions). The package deployer service is a service like any other and can be started like any other service. DSS ships with a sample script bin\rundeployer.cmd that shows how to do this. (By default the package deployer service is expected to run on TCP port 55555 but you can change this in the properties of your distributed application. The port number must not conflict with the ports used by the other services in this example.)
IMPORTANT NOTE: If you are distributing a package to another computer, you must first start the Package Deployer service on both computers. This example uses a single computer so the instructions only tell you to start the service once.
Click OK. The Microsoft DSS Manifest Editor will use the package deployer service to copy the DSS deploy packages to the remote nodes and run them.
The application is now running. You can inspect the nodes using a web-browser.
Click Stop to stop the application and terminate the nodes.
© 2012 Microsoft Corporation. All Rights Reserved.