WCF 4 Step By Step Chapter 6 Note (Maintaining Service Contracts and Data Contracts)

In Chapter 1, “Introducing Windows CommunicationFoundation,” you learned that one of the fundamental tenets of Service Oriented Architectures(SOA) is that services share schemas and contracts, not classes or types.

The service contract does not depend on the communication mechanism that the service uses to send and receive messages.The communicationsmechanism is governed by the channel stack constructed from the binding information specified in the service configuration file. You can change the network protocol or address of a service without modifying the code in the service or in any client applications that access the service.

Client applications wishing to communicate with the servicemust be able to construct the appropriate SOAP messages.

Selectively Protecting Operations

Tips:In the Message Logging pane, set LogMessagesAtServiceLevelto False and verify that LogMessagesAtTransportLevel is set to True. To minimize the logging overhead, you will trace messages only as they flow in and out of the transport level.At this level, you will be able to see the effects of the message level security applied by the binding and the service contract—logging at the service (message) level will only show unencrypted messages as theyare received and sent by the service.

The ProtectionLevel property of the OperationContract attribute specifies how messages invoking this operation—and output by this operation—are protected. In this case,
EncryptAndSign specifies that calls to the ListProducts and GetProduct operations must be signed by the client and encrypted by using a key negotiated with the service. This requires that the security mode of the binding used by the client and service implements message-level authentication.

 [ServiceContract]
    public interfaceIProductsService
    {
        // Get theproduct number of every product
       [FaultContract(typeof(SystemFault))]
       [FaultContract(typeof(DatabaseFault))]
       [OperationContract(ProtectionLevel = ProtectionLevel.EncryptAndSign)]
       List<string> ListProducts();
 
        // Get thedetails of a single product
       [OperationContract(ProtectionLevel = ProtectionLevel.EncryptAndSign)]
        ProductDataGetProduct(string productNumber);
 
        // Get thecurrent stock level for a product
      [OperationContract(ProtectionLevel = ProtectionLevel.Sign)]
        int CurrentStockLevel(stringproductNumber);
 
        // Change thestock level for a product
       [OperationContract(ProtectionLevel = ProtectionLevel.Sign)]
        boolChangeStockLevel(string productNumber, short newStockLevel, string shelf, intbin);
    }           

Versioning a Service

 

// Service contract describing the operations provided bythe WCF service
[ServiceContract(Namespace="http://adventure-works.com/2010/02/28",Name="IProductsService")]
public interface IProductsService
{
// Get the product number of every product
[FaultContract(typeof(SystemFault))]
[FaultContract(typeof(DatabaseFault))]
[OperationContract(ProtectionLevel =ProtectionLevel.EncryptAndSign)]
List<string> ListProducts();
// Get the details of a single product
...
}
// Version 2 of the service contract
[ServiceContract(Namespace="http://adventure-works.com/2010/05/31",Name="IProductsService")]
public interface IProductsServiceV2
{
// Get the product number of matching products
[FaultContract(typeof(SystemFault))]
[FaultContract(typeof(DatabaseFault))]
[OperationContract(ProtectionLevel =ProtectionLevel.EncryptAndSign)]
List<string> ListMatchingProducts(string match);
// Get the details of a single product
...
}

Generally you will find that you can add parameters to an operation (and even remove parametersfrom an operation), and existing client applications will still be able to call them. If youadd a parameter to an operation, and the client application fails to provide a value for this parameter, it will be assigned a default value that depends on its type; null for a referencetype, 0 for a numeric or character type, and false for a Boolean type. Note that these defaultvalues (null, 0 or false) apply even if you attempt to make the parameter optional and assign ita different default value when you declare the method that implements the operation. Forexample, if you defined the ListProducts method as shown in the code fragment thatfollows, the default value specified for the match parameter (“W”) will be ignored if the clientapplication omits this parameter and a null string will be used instead.

 

[PrincipalPermission(SecurityAction.Demand,Role="WarehouseStaff")]
public List<string> ListProducts(string match ="W")
{
...
}
 

Note: the SOAP standard does not allow a service to expose multiple operations that share the same name in the same service, Apart from giving the operations different names in the C#interface, an alternative approach is to use the Name property of the OperationContract attribute in the service contract, like this:

[OperationContract(Name="ListMatchingProducts",...]
List<string> ListProducts(string match);
 
[OperationContract(...]
List<string> ListProducts();
 

Making Breaking and Nonbreaking Changes to a ServiceContract 

Strictly speaking, you should consider a service contract tobe immutable; any changes that you make to the contract are likely to affect clientapplications, which might no longer be able to communicate with the service correctly.In practice, youhave seen that you can make some changes to a service contract without breaking the terms ofthis contract, as far as a WCF client application is concerned. Table 6-1 summarizes somecommon changes that developers frequently make to service contracts and the effects thatthese changes can have on existing client applications.

 Table 6-1 (Change:Effect)

Adding a new operation:This is a nonbreaking change.

Removing an operation:This is a breaking change.

Changing the name of an operation:This is a breaking change.

Changing the protection level of an operation:This is abreaking change

Adding a parameter to an operation:This is a nonbreakingchange. Existing client applications will be  ableto invoke the operation, but the formatter used by the WCF     runtimewill initialize missing parameter values to default values.

Reordering parameters in an operation:This is a breakingchange

Removing a parameter from an operation:This may be anonbreaking change as long as the parameter is removedfrom the end of the parameter list, in which case any

 datapassed by the client application for this parameter will be ignored

Changing the types of parameters or the return type of anoperation:This may be breaking change if the formatter used by the WCF runtimecannot convert data from the original types to the new types

Adding a FaultContract to an operation:This is a breakingchange.Existing client applications can be sent fault messages that they willnot be able to interpret correctly.

Removing a FaultContract from an operation:This is anonbreaking change.

Changing the Name or Namespace property of theServiceContract attribute for a service contract:This is a breaking change. 

Modifying a Data Contract 

The WCF runtime uses the built-in XML serialization features of the.NET Framework to serialize and deserialize primitive .NET Framework data types, such asintegers, real numbers, or even strings. For more complex structured types, the service mustspecify the exact format for the serialized representation;The WCF runtime can then use a data contract serializer (an instance of theDataContractSerializer class) to serialize and deserialize these types.

The data contract serializer serializes the membersof a data contract in alphabetic order.

Changing the order of members in a data contract is a breaking change, and the formatter used by the client application has not deserializedthe data correctly Changing the namespace for a data contract is another example of a breaking change. The DataContract attribute provides a Namespace property. Bydefault, WCF uses the namespace “http://schemas.datacontract.org/2004/07” with the.NET Framework namespace containing the data contract appended to the end. 

You can also add new members to a data contract. Under some circumstances, you can perform this task without breaking existing client applications. You should notice that adding a member to a data contract changes the schema exported byWCF. Client applications use this schema to determine the format of the data they sendand receive in SOAP messages. Many client applications that use SOAP (including thosebuilt by using WCF and ASP.NET Web services) will happily ignore additional fields in SOAPmessages.However, a small number of client applications created by using other technologies canenable strict schema validation.

As when changing the order of data members, you should bevery mindful of existing client applications when adding a new member to a data contract. If the client application does not populate every field in a serialized object, WCF will usedefault values—False for Booleans, 0 for numerics, and null for objects. If these default valuesare unacceptable, you can customize the serialization and deserialization process byimplementing serialization callback methods in the WCF service.

Data Contract Compatibility

If you need to version a data contract, you should do so ina manner that maintains compatibility with existing client applications. The DataMember attributeprovides two properties that can assist you:

IsRequired:If you set this property to true, then the SOAPmessage that the service receives must include a value in this data member. Bydefault, the value of this property

is false, and the WCF runtime will generate default valuesfor any missing fields.

EmitDefaultValue:If you set this property to true, the WCFruntime on the client will generate a default value for a data member if it is notincluded in the SOAP message

sent by the client application. This property is true bydefault.

 

If you need to maintain strict conformance to a datacontract in future versions of the service, you should set the IsRequired property of each data memberin the data contract to true and set the EmitDefaultValue property to false when building thefirst version of a service. You should never make a data member mandatory (IsRequired set totrue) in a new version of a data contract if it was previously optional (IsRequired setto false). This helps to maintain backward compatibility with older clients.