Service Tutorial 8 (C#) - Generic Service Declaration

Glossary Item Box

Service Tutorial 8 (C#) - Generic Service Declaration

This tutorial demonstrates how to define a generic service contract without an actual service implementation. Generic service contracts provide a level of abstraction that can be implemented by many different services that want to share a common service declaration but differ in how they are implemented. Consumers of generic contracts do not have to worry about the different service implementations as they all have the same service state and behavior as defined by the generic contract.

While the analogy is not perfect you can loosely think of generic contracts as interfaces. That is, the concept of a generic contract is a service abstraction that is similar to interfaces in object oriented programming. However, as we will see in Service Tutorial 9 (C#) - Implementing and Extending Service Contracts, generic contracts manifest themselves in different ways than traditional interfaces.

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\Tutorial8\CSharp

This tutorial teaches you how to:

• Create a Generic Service Project.
• Set the ServiceDeclaration attribute.
• Define the Generic Service Contract.
• Define the Generic Service State.
• Define the Generic Service Operations.
• Compiling the Generic Service.

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.

You will also need Microsoft Internet Explorer or another conventional web browser.

Step 1: Create a Generic Service Project

Start by creating a service project called "ServiceTutorial8" following the process described in Service Tutorial 1 (C#) - Creating a Service. In this case you will only need the file ServiceTutorial8Types.cs as there is no service implementation so you can remove the file Servicetutorial8.cs from the service project. Because there is no service implementation it is not possible to run a generic service declaration directly; it must first be implemented by an actual service as illustrated in Service Tutorial 9 (C#) - Implementing and Extending Service Contracts.

Step 2: Set the ServiceDeclaration attribute

In the file AssemblyInfo.cs, use the ServiceDeclaration attribute to indicate to the Decentralized Software Services (DSS) infrastructure that this assembly contains a generic contract without an implementation:

[assembly: ServiceDeclaration(DssServiceDeclaration.DataContract)]

It is possible to have both generic contract declarations as well as service implementations within a single assembly as long as they are defined in different CLR namespaces. You can indicate this using the ServiceDeclaration attribute by doing a bit-wise OR between the arguments DssServiceDeclaration.ServiceBehavior and DssServiceDeclaration.DataContract as follows:

[assembly: ServiceDeclaration(DssServiceDeclaration.ServiceBehavior | DssServiceDeclaration.DataContract)]

Step 3: Define the Generic Service Contract

The service contract of a generic service is defined in exactly the same way as any other service contract. For the case of this tutorial, the definition is as follows:

/// <summary>
/// Generic Service without service implementation
/// </summary>
[DisplayName("Service Tutorial 8: Generic Service Contract")]
[Description("This is a generic contract without an actual service implementation. See Service Tutorial 9 for various ways to use this contract.")]
[DssServiceDescription("https://msdn.microsoft.com/library/bb727256.aspx")]
public sealed class Contract
{
    /// <summary>
    /// The Dss Service contract
    /// </summary>
    [DataMember()]
    public const String Identifier = "https://schemas.microsoft.com/2007/08/servicetutorial8.html";
}

Step 4: Define the Generic Service State

The service state of a generic service is also defined in exactly the same way as any other service. That is, you define the state types and mark them using the DataContract, DataMember and DataMemberConstructor attributes. Here the definition looks as follows:

/// <summary>
/// State for the generic service
/// </summary>
[DataContract]
[DisplayName("Generic Service State")]
[Description("Specifies the state of the generic service.")]
public class GenericState
{
    string _firstName;
    string _lastName;

    [DataMember]
    [Description("Specifies the first name of a person.")]
    [DisplayName("First Name")]
    public string FirstName
    {
        get { return _firstName; }
        set { _firstName = value; }
    }

    [DataMember]
    [DisplayName("Last Name")]
    [Description("Specifies the last name of a person.")]
    public string LastName
    {
        get { return _lastName; }
        set { _lastName = value; }
    }
}

Step 5: Define the Generic Service Operations

As you may have guessed by now, the service operations of a generic service are also defined in exactly the same way as any other service contract. For the case of this tutorial, we define two operations, GET and REPLACE:

/// <summary>
/// Generic Service Main Operations Port
/// </summary>
[ServicePort]
public class GenericServiceOperations :
    PortSet<DsspDefaultLookup, DsspDefaultDrop, Get, Replace>
{
}

/// <summary>
/// Get Operation
/// </summary>
[Description("Gets the current state.")]
public class Get : Get<GetRequestType, PortSet<GenericState, Fault>>
{
}

/// <summary>
/// Replace Operation
/// </summary>
[Description("Replaces the current state.")]
public class Replace : Replace<GenericState, PortSet<DefaultReplaceResponseType, Fault>>
{
}

Step 6: Compiling the Generic Service

When you compile a generic service implementation you get the same set of DLLs as for any other service (or services if you have multiple services within a single project). However, as the service does not have an actual implementation, it is not possible to run as-is. Service Tutorial 9 (C#) - Implementing and Extending Service Contracts demonstrates various different ways of implementing and extending a generic service declaration.

Summary

In this tutorial, you learned how to:

• Create a Generic Service Project.
• Set the ServiceDeclaration attribute.
• Define the Generic Service Contract.
• Define the Generic Service State.
• Define the Generic Service Operations.
• Compiling the Generic Service.

© 2012 Microsoft Corporation. All Rights Reserved.