The world has moved on, have you? Xml APIs you should avoid using.

There is a few Xml APIs you should not be using. In some cases the complier makes this obvious – the API is marked as obsolete and you will get a warning when compiling an application that uses any of these APIs. All the obsolete APIs have their replacements. The replacement for the obsolete XmlSchemaCollection class is the XmlSchemaSet class. The replacement for the obsolete XslTransform class is the XslCompiledTransform class (btw. I recommend reading Effective Xml Part 3: Didn’t you say XslCompiledTransform was fast? before moving from XslTransform to XslCompiledTransform. While it is pretty easy (too easy?) to move by just changing class name and fixing up parameters in method calls such a move will most likely make you transformations slow) . The reason why you should not be using deprecated APIs is that there is no active work going on in these areas – non security-critical bugs are not being fixed, new features are not being added, performance improvements are not being coded and finally the API may be removed in a future version of the .NET Framework (meaning the user of your application will update his/her machine and out of sudden the application may stop working).

Obsolete APIs are easy since the compiler helps identifying them but there are two more APIs you should avoid using – namely XmlTextReader and XmlTextWriter. We found a number of bugs in these classes which we could not fix without breaking existing applications. The easy route would be to deprecate these classes and ask people to use replacement APIs instead. Unfortunately these two classes cannot be marked as obsolete because they are part of ECMA-335 (Common Language Infrastructure) standard (https://www.ecma-international.org/publications/standards/Ecma-335.htm) – the companion CLILibrary.xml file which is a part of Partition IV).

The good news is that even though these classes are not deprecated there are replacement APIs for these in .NET Framework already and moving to them is relatively easy. First it is necessary to find the places where XmlTextReader or XmlTextWriter is being used (unfortunately it is a manual step). Now all the occurrences of XmlTextReader should be replaced with XmlReader and all the occurrences of XmlTextWriter should be replaced with XmlWriter (note that XmlTextReader derives from XmlReader and XmlTextWriter derives from XmlWriter so the app can already be using these e.g. as formal parameters). The last step is to change the way the XmlReader/XmlWriter objects are instantiated – instead of creating the reader/writer directly it is necessary to the static factory method .Create() present on both XmlReader and XmlWriter APIs. The factory method will create and return an implementation of XmlReader/XmlWriter depending on the settings (XmlWriterSettings/XmlReaderSettings) passed to the .Create() method (or default settings if no settings were passed). This pattern allows for introducing new settings and new implementations of XmlReader/XmlWriter classes in the future without having to change or add new APIs.

Pawel Kadluczka

Comments

• Anonymous
  October 09, 2011
  "the world has moved on" from XML to Json :-)

• Anonymous
  October 09, 2011
  Thanks

• Anonymous
  October 12, 2011
  In response simoncropp.com/how-to-mismanage-an-api

• Anonymous
  October 14, 2011
  Decent explanation, why few of the API's were made obsolete. Of course we need to change the code accordingly to ensure better support. Keep posting.

• Anonymous
  October 19, 2011
  The world has moved on... to XSLT 2... when can we expect MS to catch up?

• Anonymous
  October 30, 2011
  The comment has been removed