What is the best way to Version an ASP.NET 2.0 Web Service?

Question

I am maintaining a SOAP web service (ASP.NET version 2.0) and I have to make some changes that will modify the return values of particular methods.

What is the generally accepted method of doing this without breaking existing implementations.

My initial thoughts are that the following would all be possible.

a) Provide new version specific methods within the existing web service e.g. getPerson_v1.4
b) Provide a complete copy of the .asmx file with a new version number e.g. http:/www.example.com/AdminWS_V1_4.asmx. This is not an idea I relish as the service has more than 50 methods and copying that code for changes to 2/3 methods seems like too much duplicated code.
c) Override the web-service constructor to allow passing in a version number. This does not seem to work, and on reflection I'm not sure how that would be represented within a WSDL

Is there a generally accepted way of doing this, or do people have advice based upon their experiences in this area.

Answer 1

We deploy to version directories, for example:

http://www.example.com/soap/v1/ http://www.example.com/soap/v2/ http://www.example.com/soap/v3/

etc.

Answer 2

Unless you change most of the method signatures with each new version, I'd go with (a) - versioned method names. This is how our providers do it and it's working fine for us.

Answer 3

I've just thought of another possible solution which seems quite clean.

I could check for a version number included as a SOAP Header and assume the existing version number if this is not provided.

I can then make the code behave differently for different versions without changing the method signatures. This is possbile as the return values from the Web-Services are XML objects so the method signature remains the same but the content of the XML changes based on version.

Answer 4

In the general case, there's more to versioning a web service than just versioning method names and .asmx file names. Ideally, the interface to a web service (its WSDL) should be a permanent contract, and should never change. One of the implications would be that clients that do not need the changed functionality would never need to change, and therefore would never need to be retested.

Instead of breaking the existing contract, you should create a new contract that contains the changed operations. That contract could "inherit" from the existing contract, i.e., you could "add the methods to the end". Note, however, that you should also put the new contract into a new XML namespace - the namespace basically identifies the WSDL, and keping the namespace but changing the WSDL would be a lie.

You should then implement this new contract at a new endpoint (.asmx file). Whether or not this is in a different directory, or even on a different web site doesn't really matter. What matters is that clients who want the new functionality can refer to the new WSDL at the new URL and call the new service at its new URL, and be happy.

Be aware that one effect of changing an existing contract is that the next time an "Update Web Reference" is performed, you will be changing the code of the client proxy classes. In most shops, changing code requires re-testing, and redeploying. You should therefore think of "just adding methods" as "just adding some client code that has to be tested and deployed", even if the existing client code does not use the new methods.

Answer 5

I have the same versioning issue with webservices that I am developing. We make our users pass a schema version number in the header. They tell us which version of the XML schema they want back. This way, we are always backwards compatible and code is not duplicated.

At my job, we cannot tell the client that they have to switch the URL to the webservice when we version it. In big corporations, changes as small as a URL could take months of testing. It is my feeling that you should not break your clients connection. What we do is, add new features to the latest version. When the client asks for the new features, if they want them, they are forced to upgrade to the newest schema.