Oh my, is it really a new post from little 'ole me? Yes, I have been very busy with various projects, including my Learning WCF book which I'm trying to wrap in the next month here...
I am getting a lot of questions about contracts and versioning, and since I have some sections in my book to address this, I thought I'd post them here. Starting with service contracts.
From the book:
-----
This lab illustrates that the service model is by default version tolerant. Table 2-2 summarizes some possible changes to a service contract and the affect it has on existing clients, if any.
Service Contract Changes
Impact on Existing Clients
Adding new parameters to an operation signature
Client unaffected. New parameters initialized to default values at the service.
Removing parameters from an operation signature
Client unaffected. Superfluous parameters pass by clients are ignored, data lost at the service.
Modifying parameter types
An exception will occur if the incoming type from the client cannot be converted to the parameter data type.
Modifying return value types
An exception will occur if the return value from the service cannot be converted to the expected data type in the client version of the operation signature.
Adding new operations
Client unaffected. Will not invoke operations it knows nothing about.
Removing operations
An exception will occur. Messages sent by the client to the service are considered to be using an unknown action header.
· The bulk of these changes have no direct affect on clients, although the results may be undesirable. The forgiving nature of the service model can be a blessing or a curse depending on how you look at it. Here are some downsides:
You can unwittingly lose information passed by the client
Missing data from the client may not be detected
Type conversions may work, yet the data is semantically invalid
· You can remove the risks of these unexpected results by using data contracts as message parameters and return types. I’ll discuss data contracts in the next section.
· Of course you are entitled to come up with your own strategy for version tolerance, but I recommend that if the implementation semantics of the service contract have changed or if new clients are to be given additional features via extended parameters and/or new operations — you should version the service contract, rather than accepting version tolerance.
To properly version a service contract you should provide a new contract and modify the namespace specified in the ServiceContractAttribute. To version the namespace, you can supply a new value for the year and month, if you follow the naming conventions I’ve recommended. A new contract name should also be specified if the contracts aren’t inherited. In the next two sections I’ll compare two versioning approaches.
· One likely scenario is that you will add new operations without changing the existing service contract. But, you may want to support these new operations at the same endpoint. You can achieve this by creating a new contract that inherits the old contract, adding new operations to the new one. Consider the contract shown in Example 2-8 as the first published version of the service contract.
· Example 2-8. Version 1 of the contract, IServiceA
[ServiceContract(Name="ServiceAContract",
Namespace = "http://www.thatindigogirl.com/samples/2006/06")]
public interface IServiceA
{
[OperationContract]
string Operation1();
string Operation2();
}
· The endpoint configuration for the service implementing the contract might look like this:
<endpoint address="ServiceA" contract="BusinessServiceContracts.IServiceA" binding="basicHttpBinding" />
· When new operations are added to the service to extend its features, you may want to expose the same endpoint to old and new clients while still somehow tracking the contract version related to new features. If you extend the original service contract you can add operations under a new namespace as shown in Example 2-9.
· Example 2-9. Version 2 of the contract, IServiceA2
Namespace = "http://www.thatindigogirl.com/samples/2006/08")]
public interface IServiceA2:IServiceA
string Operation3();
· Note the service contract name is the same, but the namespace has changed. The service type can implement IServiceA2 and it will be able to expose the original operations with their original namespace, while exposing the new operation with the versioned namespace. As such, original clients can hit the same endpoint without impact, while new clients who download the metadata when version 2 is available, can access all operations.
· This scenario does not address the following:
You can’t modify existing operations with contract inheritance
You can’t differentiate old clients from new clients since they hit the same endpoint
· Another approach would be to version the entire contract and create a new endpoint for new clients. In this case, version 2 of the contract might look like that in Example 2-10.
· Example 2-10. Version 2 of the contract, IServiceA2
[ServiceContract(Name="ServiceAContract2",
public interface IServiceA2
· In order to provide a unique WSDL containing only one or the other contract, a unique service type must be created to implement the new contract. Both versions of the service can still share implementation behind the scenes.
· With this implementation the following applies:
You can differentiate old and new clients by service entry point
You can modify existing operations in the new interface (not recommended, you should really provide new operation names)
New clients cannot send messages to the original endpoint
Old clients cannot send messages to the new endpoint
To summarize the discussion of service contract versioning, Figure 2-4 and Figure 2-5 illustrate the decision flow for non-strict and strict-versioning policy, respectively.
Non-strict versioning allows you to add or remove parameters without versioning the service contract. This also means that the implementation code must accommodate how to handle version 1 and version 2 clients. Though possible, the idea of operation signatures changes can be very difficult to track, whereas a data contract as the service operation parameter at least allows for explicitly required and non-required parameters (to be discussed in the "Data Contracts" section of this chapter).
With strict service contract versioning, any change to an operation leads to a new service contract. A new endpoint is always provided to ensure version 2 clients can be differentiated from version 1 clients.
Click the image to see larger view...
Remember Me
Designed by NUKEATION STUDIOS