When you want to deploy to a new computer, you first need to install the base RDS DLLs, i.e. the runtime environment. Depending on which edition of RDS you have there are two different ways to do this:

• Express Edition - Install the Express Edition package on the target computer;
• Standard Edition - There is a package located in the Redistributables folder under the RDS installation point that can be installed on the target computer.

This step only needs to be performed once on the target computer. You can then install as many DssDeploy packages as you like. Deploying services directly from within VPL (Standard Edition only) requires this first step to be performed manually.

Additional Dependencies

Although DssDeploy is designed to figure out dependencies for you, sometimes there will be files that it cannot automatically include. One case is source code, which is discussed below. Another case is DLLs that are required, but are not DSS services or maybe not even .NET assemblies. In this case, you must use the Dependencies (/d) option to explicitly specify any required files. Note that DssDeploy lists all the files it is processing as it packages them, so you can see from the console output what is inside the package. (You can also run the package and look at the Contents).

In particular, the Fischer Technik services contain DLLs with common code that are not compiled as DSS Services. To package code that uses these robots, you must explicitly include the necessary DLLs. For example, FTLib.DLL is required for the Fischer Technik robots. These types of DLLs are generally easy to identify because they do not have .Proxy and .Transform versions. In any case, if you deploy a package and it will not run on the target computer, there will be an error message saying that the system could not load the missing DLL.

Version-Specific Deployments

Executable files from one version of RDS cannot be deployed to a different version due to the strong naming of DSS services. In other words, you must deploy to the same version of the runtime that you compiled with. You can used the Current Version (/cv) qualifier to assist you by marking the DssDeploy package with a particular version of RDS. Note that it usually makes sense not to set the Access Control Lists on the files (/s-) when using /cv.

If you need to create a package for a different Edition of RDS from the one that you are running, you can use the Deploy Version GUID (/dvg) option to specify the product GUID (instead of using /cv). The Product GUID for a particular Edition can be found in the file Licenses\VersionInformation.xml under the installation point. Every Edition has a unique GUID (but all installations of a particular Edition are the same), so the GUIDs are not listed here.

If you attempt to unpack a DssDeploy package from the command line that has been created for a specific version, you will get an error. For example, the following sequence of commands:

dssdeploy /p /cv /m:"samples\Config\WebCam.capture.manifest.xml" /s- testpackage.exe
dssdeploy /u testpackage.exe
    

will generate the error message:

*** This package was created to be deployed into a specific version of Microsoft
Robotics Developer Studio. Please use the '/specific' command line option.
    

The /specific command-line option refers to the unpack operation, i.e. the self-extracting DssDeploy package, not the original DssDeploy command that created the package (because /specific is not an option for DssDeploy.exe). If you run the testpackage with the /specific qualifier then the unpack operation will work as expected, provided that you have the same version of RDS installed.

testpackage.exe /specific
    

NOTE: When you run a DssDeploy package from the command line as shown above, it overwrites existing files without warning. If you want to see what a package contains and also have the option of cancelling, then just execute the package and it will display a form before doing the install.

If you execute a DssDeploy package with no command-line options, e.g. testpackage.exe in the example above, then it opens a dialog window similar to the one shown below. This dialog allows you to see the contents of the package (by clicking on the Contents button, which then turns into a list).

DssDeploy Extractor Dialog

Notice that you can run the package, display the contents, and then click on Cancel without installing anything. This allows you to see the contents of a package. Also, in the screenshot, the target folder is greyed out because the package was created using /cv and it will only install into this folder. If you create a package without /cv, then you can select the target folder.

Deploying Source Code

DssDeploy can be used to package any types of files that you like. In particular, if you have source code that you would like to distribute, you can do so using the Dependencies (/d) command-line option. For large amounts of code, it is easier to create a text file containing a series of /d options and then specify the text file on the command line:

DssDeploy @mypackage.txt
    

This approach also allows you to easily specify the Name (/n), Readme (/r), Archive Copyright (/acp), etc. in the text file so that you do not have to always type a very long command-line whenever you re-create the package.

Note that if you want to deploy a VPL program, you must deploy the whole folder. Do not deploy just the .mvpl file. This is the equivalent of the .csproj file for a C# project and does not contain the program. Also be aware that when you import a manifest into a VPL program, it makes an internal copy. Even if the manifest exists in the same folder, you cannot edit it and expect any changes to have an effect. You must re-import the manifest after making changes.

Even with source code, you might want to use /cv to make sure that people do not deploy to other versions of RDS and then find that there are incompatibilies. For instance, deploying RDS 2008 source code to V1.5 does not make sense because V1.5 cannot handle the new features of RDS 2008.

Other Notes

If you use the Delay Sign (/ds) option, then you must also specify the Key File (/k). Otherwise there is no way for DssDeploy to know which key file to use for signing.

You cannot deploy binaries that use the Simulator by requesting that DssDeploy work out the dependencies for you, e.g. with the Manifest (/m) or Contract (/c) options. This is due to issues with licensing as well as the fact that the Simulator requires several other products to be installed, e.g. DirectX, and it uses DLLs that are not services. Your only option for deploying services that use the Simulator are to deploy source code or to explicitly specify all of the binary files using /d in a similar way to source code (as explained above).

When run from a Microsoft Robotics Developer Studio Command Line the following example creates an archive called "ServiceTutorial1.exe" containing everything necessary to run ServiceTutorial1:

dssdeploy /p /m:"samples\config\ServiceTutorial1.manifest.xml" ServiceTutorial1.exe
      

This example creates an archive called "ServiceTutorial1-2.exe" containing everything necessary to run ServiceTutorial1 and ServiceTutorial2:

dssdeploy /p /m:"samples\Config\ServiceTutorial1.manifest.xml" /m:"samples\Config\ServiceTutorial2.manifest.xml" ServiceTutorials1-2.exe
      

This example builds on the previous example but includes an additional Cascading Style Sheet (CSS) file in the package:

dssdeploy /p /m:"samples\Config\ServiceTutorial1.manifest.xml" /m:"samples\Config\ServiceTutorial2.manifest.xml" /d:"documentation\introduction.htm" ServiceTutorial1-2-css.exe
      

DssDeploy can also unpack archives by using the /u command line argument. This example unpacks "ServiceTutorial1.exe" into "%TEMP%\ServiceTutorial1" so that the deployed node is ready to run:

dssdeploy /u /t:%TEMP%\ServiceTutorial1 ServiceTutorial1.exe
      

A simpler way to unpack is just to execute the DssDeploy package itself, e.g. ServiceTutorial1.exe, because it is a self-extracting package. When you are developing and testing a DssDeploy package, this can be useful because there is a drop-down list in the dialog when you run an unpack that allows you to see what files are included in the package. You can cancel the installation if you do not want to overwrite some of the files or if you made a mistake in the packaging, and then try again.

To start the unpacked node (this can be done from a standard comment prompt):

cd /d "%TEMP%\ServiceTutorial1"
bin\dsshost /p:50000 /m:"samples\config\servicetutorial1.manifest.xml"
      

If you have additional files that you wish to deploy to the target computer, you can specify them using the /d command line argument when you build the package. Note that they will be placed onto the target computer in the same location relative to the installation point as they are compared to the source computer's RDS installation point effectively preserving the directory structure.

If you only want to distribute source code, the the best approach is to create an options file containing a series of arguments like:

/d:"myprojects\code\myservice.cs"
/d:"myprojects\config\mymanifest.xml"