Contracts

A contract defines what functionality a service offers and what functionality can be used by the client. The contract can be completely independent of the implementation of the service.

The contracts defined by WCF can be grouped into three different contract types: data contracts, service contracts, and message contracts. The contracts can be specified by using .NET attributes.

• Data contract - The data contract defines the data received and returned from the service. The classes used for sending and receiving messages have data contract attributes associated.

• Service contract - The service contract is used to define the WSDL that describes the service. This contract is defined with interfaces or classes.

• Message contract - If complete control over the SOAP message is needed, a message contract can specify what data should go into the SOAP header, and what belongs to the SOAP body.

Let’s get into contracts in more detail.

Service Contract

The service contract defines the operations the service can perform. The attribute [ServiceContract] is used with interfaces or classes to define a service contract. The methods that are offered by the service have the attribute [OperationContract] applied as you can see with the interface IRoomService.

  [ServiceContract] public interface IRoomService {    [OperationContract]    bool ReserveRoom(RoomReservation roomReservation); } 

The possible properties that you can set with the [ServiceContract] attribute are described in the following table.

Open table as spreadsheet

ServiceContract Property	Description
ConfigurationName	This property defines the name of the name of the service configuration in a configuration file.
CallbackContract	When the service is used for duplex messaging, the property CallbackContract defines the contract that is implemented in the client.
Name	The Name property defines the name for the <portType> element in the WSDL.
Namespace	The Namespace property defines the XML namespace for the <portType> element in the WSDL.
SessionMode	With the SessionMode property, you can define is sessions are required calling operations of this contract. The possible values Allowed, NotAllowed, and Required are defined with the SessionMode enumation.
ProtectionLevel	The ProtectionLevel property defines if the binding must support protecting the communication. Possible values are defined by the ProtectionLevel enumeration: None, Sign, EncryptAndSign.

With the [OperationContract], you can specify properties as shown in the following table.

Open table as spreadsheet

OperationContract Property	Description
Action	WCF uses the Action of the SOAP request to map it to the appropriate method. The default value for the Action is a combination of the contract XML namespace, the name of the contract and the name of the operation. If the message is a response message, Response is added to the Action string. You can override the Action value by specifying the Action property. If you assign the value “*“, the service operation handles all messages.
ReplyAction	While Action sets the Action name of the incoming SOAP request, ReplyAction sets the Action name of the reply message.
AsyncPattern	If the operation is implemented by using an asynchronous pattern, set the AsyncPattern property to true. The async pattern is discussed in Chapter 18.
IsInitiating IsTerminating	If the contract consists of a sequence of operations, with the initiating operation assign the IsInitiating property, the last operation of the sequence needs the IsTerminating property. The initiating operation starts a new session; the server closes the session with the terminating operation.
IsOneWay	With the IsOneWay property set, the client does not wait for a reply message. Callers of a one-way operation have no direct way to detect a failure after sending the request message.
Name	The default name of the operation is the name of the method the operation contract is assigned to. You can change the name of the operation by applying the Name property.
ProtectionLevel	With the ProtectionLevel property, you define if the message should be signed or encrypted and signed.

With the service contract, you can also define the requirements that the service has from the transport with the attribute [DeliveryRequirements]. The property RequireOrderedDelivery defines that the messages sent must arrive in the same order. With the property QueuedDeliveryRequirements, you can define that the message is sent in a disconnected mode, for example, by using Message Queuing.

Tip 

Message Queuing is discussed in Chapter 39.

Data Contract

With the data contract, CLR types are mapped to XML schemas. The data contract is different from other .NET serialization mechanisms; with runtime serialization, all fields are serialized (including private fields), with XML serialization only the public fields and properties are serialized. The data contract requires explicit marking of the fields that should be serialized with the [DataMember] attribute. This attribute can be used regardless of whether the field is private or public, or if it is applied to a property.

  [DataContract(Namespace="http://www.thinktecture.com"] public class RoomReservation {    [DataMember] public string Room;    [DataMember] public DateTime StartDate;    [DataMember] public DateTime EndDate;    [DataMember] public string ContactName;    [DataMember] public string EventName; } 

For being platform- and version-independent, using data contracts is the best way to define what data should be sent. However, you can also make use of XML serialization and runtime serialization. XML serialization is the mechanism used by ASP.NET Web services, .NET Remoting uses of runtime serialization.

With the attribute [DataMember], you can specify the properties described in the following table.

Open table as spreadsheet

DataMember Property	Description
Name	By default the serialized element has the same name as the field or property where the [DataMember] attribute is applied. You can change the name with the Name property.
Order	The Order property defines the order of serialization the data members.
IsRequired	With the IsRequired property, you can specify that the element must be received with serialization. This property can be used for versioning. If you add members to an existing contract, the contact is not broken as by default the fields are optional (IsRequired=false). You can break an existing contract by setting IsRequired to true.
EmitDefaultValue	The property EmitDefaultValue defines whether the member should be serialized if it has the default value. If EmitDefaultValue is set to true, the member is not serialized if it has the default value for the type.

Message Contract

A message contract is used if complete control over the SOAP message is needed. With the message contract, you can specify what part of the message should go into the SOAP header and what belongs to the SOAP body. The following example shows a message contract for the class ProcessPersonRequestMessage. The message contract is specified with the attribute [MessageContract]. The header and body of the SOAP message are specified with the attributes [MessageHeader] and [MessageBodyMember]. By specifying the Position property, you can define the element order within the body. You can also specify the protection level for header and body fields.

  [MessageContract] public class ProcessPersonRequestMessage {    [MessageHeader]    public int employeeId;    [MessageBodyMember(Position=0)]    public Person person; } 

The class ProcessPersonRequestMessage is used with the service contract that is defined with the interface IProcessPerson:

  [ServiceContract] public interface IProcessPerson {    [OperationContract]    public PersonResponseMessage ProcessPerson(          ProcessPersonRequestMessage message); }