How to mismanage an API

I just read "The world has moved on, have you? Xml APIs you should avoid using".

There are few issues I have with this post and how Microsoft is handling the situation.

How Microsoft handles obsolete APIs in .net

Note that XmlSchemaCollection and XslTransform have been marked as obsolete. Both of these were marked as Obsolete in .net 2. So this means Microsoft publicised the fact that the classes should not be used in in late 2005. So why in .net 4.5 and 2011 do they still exist? The process should have been:

  • Make as obsolete with warning in 2.0 (2005)
  • Mark as obsolete with error in 3.0 (2006)
  • Do not include type in 3.5 (2007)

And on another note why do XmlSchemaCollection and XslTransform exist in the Client Profile? The client profile was introduced in .net 3.5 and removed many APIs to produce a smaller framework. Surely anything marked as obsolete in .net 2 should not have made it to the .net 3.5 Client Profile.

How Microsoft handles "known bugs"

Note that the blog post states XmlTextReader and XmlTextWriter have known bugs.

> We found a number of bugs in these classes

Really? What are these bugs? I see no links in the blog article. There is no obvious information on MSDN about these bugs. Nor is there any obvious documentation on MSDN that these classes should not be used. There is a "Note" saying it is "recommended practice" to use the static "Create" methods. Not exactly as strongly worded at I would hope. I want some big bold text at the top saying "Do not use this class". As it stands it would be very hard for a new comer to .net to know not to use them?

And then this

> Unfortunately these two classes cannot be marked as obsolete because they are part of ECMA-335

Really? I am almost at a loss for words. You have bugs, but won't fix them because people now expect those bugs to happen. To compound the issue this is part of the ECMA standard. How can you tell people not to use classes that are part of the standard? The point of ECMA-335 is that people have common agreed spec to work with no matter who implements the CLI. Mono is looking better and better.

Constructor based API changed to Factory based API

So XmlTextReader/Writer are out and XmlReader/Writer are in. And you should now be using the new Factory approach to creating them.

> This pattern allows for introducing new settings and new implementations of XmlReader/Writer classes in the future without having to change or add new APIs.

Ok so it makes it easier for Microsoft to change or add new APIs but it makes it a pain for anyone else. You see the XmlTextReader/Writer classes were extensible though inheritance. So anyone could add features or fix bugs in an inherited class. So what's wrong with doing the same with XmlReader/Writer classes? Well while they are abstract base classes they contain very little of the true implementation. The real implementation is buried in the internal classes XmlTextReaderImpl and XmlTextWriterImpl. This hidden implementation is constructed through the static Create methods on XmlReader/Writer. So if you want to inherit from XmlReader/Writer you now need to re-implement the entire class.

So my reaction to this

Posted by: Simon Cropp
Last revised: 24 Dec, 2011 05:21 AM History


07 Feb, 2012 03:08 AM


No new comments are allowed on this post.