Chapter 9: Contracts

Microsoft Windows Communication Foundation (WCF) contracts map Microsoft .NET Framework types to messaging constructs. To illustrate, consider a service that requests, confirms, and cancels restaurant reservations. This service consists of one endpoint located at http://contoso.com/reservations. The endpoint exposes three operations: RequestReservation, ChangeReservation, and CancelReservation. The RequestReservation and ChangeReservation operations use the request/reply Message Exchange Pattern (MEP), and the CancelReservation operation uses the datagram MEP. Some message structures are shared between these operations, and others are not. Using only the types shown in the preceding four chapters, it is possible to build this kind of messaging application. If we choose this path, however, we have to interact with raw messages, channels, and channel listeners. While this might be a good academic exercise, it is by no means a chore that we can accomplish quickly, and it is likely to be fraught with errors. By using contracts (and the techniques covered in Chapter 10, “Dispatchers and Clients”), we can place the burden of the work on the WCF infrastructure and greatly reduce the amount of code that we must write. As a result of the boost in productivity, virtually all WCF applications will use contracts and the WCF serialization infrastructure. This chapter describes the different kinds of contracts and how they impact the shape of a messaging application.

Contracts Defined

A contract is an agreement between messaging participants. An agreement of this sort names, defines, and provides addresses for the operations that a Web service exposes. In doing so, it describes each operation in a service, the MEP of each operation, and the message structures supported by an operation. Over time, the industry has developed and refined vendoragnostic grammars like Web Services Description Language (WSDL) and Extensible Schema Definition (XSD) to provide common ground for these agreements, and most modern Web service platforms are able to produce as well as understand WSDL and XSD documents. As a result, a contract in a messaging application is often assumed to be a set of WSDL and XSD documents. In WCF applications, a contract is not necessarily a set of WSDL and XSD documents, but rather a set of .NET type definitions. Once in place, these type definitions can then be turned into a set of WSDL and XSD documents as needed.

If one embraces the tenets of service orientation in the purest sense, a contract is the logical place to start designing a service. In the real world, businesses operate in much the same fashion. Trading partnerships between large organizations take their true shape in the legal contract between organizations. No two large companies would ever start trading goods without first having a legal framework in place that governs that trade. In this setting, a legal contract defines liability, terms of payment, jurisdictions, ownership, and so on. The legal contract must be understood by both parties. If one organization uses terms that are not known to the other organization, the contract must spell out those terms explicitly before the other organization signs the contract. In essence, a legal contract becomes a clearly defined playing field that removes assumptions about the responsibilities and behaviors of parties entering into the contract. Similarly, a Web service contract defines the responsibilities and behaviors of messaging participants, and it should be in place before message exchange begins. Because of the contract’s critical role, it is often a good idea to start design and development efforts by working on the contract.

WCF contracts are .NET type definitions annotated with special attributes, and these annotated type definitions can be used to generate industry-standard WSDL and XSD documents. WCF contracts map types and members of those types to services, operations, messages, and message parts. There are three types of contracts in WCF: service contracts, data contracts, and message contracts. Service contracts map types to service definitions and type members to service operations. Data contracts and message contracts map types to service operation message definitions. A message contract offers more control over a message definition than a data contract does. A data contract maps the body of a message to type members, while a message contract maps the headers and the body of a message to type members.