Service Tutorial 10 (C#) - Service Documentation

Glossary Item Box

Service Tutorial 10 (C#) - Service Documentation

This tutorial illustrates how to document a service. The tutorial shows how to use a variety of mechanisms including Common Language Runtime (CLR) attribute classes, icons, XML documentation comments, and more. The ways to document a service are explained in more more detail in the topic Documenting Services

This tutorial is provided in the C# language. You can find the project files for this tutorial at the following location under the Microsoft Robotics Developer Studio installation folder:

Samples\ServiceTutorials\Tutorial10\CSharp

Prerequisites

Hardware

This tutorial requires no special hardware.

Software

This tutorial is designed for use with Microsoft Visual C#. You can use:

• Microsoft Visual C# Express Edition
• Microsoft Visual Studio Standard, Professional, or Team Edition.

Overview

Code Comments and Attributes

Visual Studio supports special comments in the code that begin with a triple slash (instead of a double slash). You should add this type of comment before each major component of a service, such as the service class, service state, service operations, etc. There is a compiler option to create an XML documentation file that contains all of these triple slash comments. Other tools are available for processing and formatting these comments.

Robotics Developer Studio has several attributes that can be used to decorate elements of the code. In particular the service class can be tagged with the following attributes:

• DisplayName - Short name for the service (a few words)
• Description - Brief descriptions (usually one sentence)
• DssCategory - Categories that the service belongs to
• DssServiceDescription - URL of the web page that describes the service

These documentation features are shown in the following code snippet:

/// <summary>
/// Implementation class for ServiceTutorial10
/// </summary>
/// <remarks>
/// This tutorial shows how to document a service using several features.
/// </remarks>
[DisplayName("Service Tutorial 10: Service Documentation")]
[Description("This tutorial provides an example of how to document a service.")]
[DssCategory(TutorialCategories.ServiceTutorial)]
[Contract(Contract.Identifier)]
[DssServiceDescription("https://msdn.microsoft.com/library/cc998489.aspx")]
public class ServiceTutorial10Service : DsspServiceBase

The DisplayName and Description are especially important for VPL because this information is displayed as a tool tip when a user hovers over a service in the Services panel. These attributes can be used on various elements in your code including the service state and all of its public members. The information can then be made available via Intellisense and will also be visible when a service is examined using reflection.

Categories are not discussed here but they are implemented in the tutorial code. These can be used to group services together.

The Contract Identifier can also be used as a means to provide additional documentation. Contract Identifiers are in the form of a Uniform Resource Identifier (URI), and one class of URIs is the Uniform Resource Locator (URL) used on the world-wide web. If you want people to be able to look up your service information then you should consider using Contract Identifiers that are real URLs, although this is not a requirement of RDS. Obviously this means that the hostname that you use in the Contract Identifier must be one that you have control over so that you can update the web pages.

Icons

Adding icons to your service is very simple. You need to create two icons and add them as Embedded Resources in your project. These icons must have filenames in the following format:

<ServiceClassName>.Image.type
<ServiceClassName>.Thumbnail.type

The type can be PNG, JPG or BMP. The Image icon must be 32x32 pixels and the Thumbnail must be 16x16 pixels.

The Image icon is used by VPL when it displays the service as an Activity block. The Thumbnail icon is used in the list of services in the Services panel in VPL.

Summary

This tutorial has only briefly discussed the features available for documenting services.

For a detailed of the mechanisms presented in this tutorial, please see the topic Documenting Services.

© 2012 Microsoft Corporation. All Rights Reserved.