David DeWinter

A while ago, I posted about integrating the xsd.exe tool into the build process within Visual Studio or MSBuild. This time around, we’ll look at generating the code for the XML Serialization object model and making a few tweaks as part of the process. Here I will specifically look at retrieving the comments in the xsd:documentation elements and applying them to code elements as XML comments. We’ll break this down into four key steps along with some closing comments and source code.

• Creating the Schema
• Generating the Code
• Making Your Modifications (xs:documentation comments to XML comments)
• Integrating with MSBuild
• Let the Buyer Beware
• Reference Source Code

Creating the Schema

Before we start, we’ll need a schema to work with. For simplicity, we’ll use the same schema as last time with the addition of xsd:documentation elements to provide descriptions for some elements and attributes. The complex types are also no longer anonymous.

The descriptions here are nonsensical, but this example is small enough to demonstrate the power of what we can do with custom code generation. We still aim to generate classes at build time, but first we have to implement the logic that the build step will use. The next sections describe what we need to do.

Generating the Code

The first step is to import the schema into the code.

using (XmlReader reader = XmlReader.Create(mySourceXsdFile))

{

    xsd = XmlSchema.Read(reader, null);

    schemaSet.Add(xsd);

}

We instantiate a new instance of the System.Xml.Serialization.XmlSchemas (in System.Xml.dll) class and add the schema file to that schema set. In the code above, mySourceXsdFile is a field which is set during the construction of the object which contains this code. The next step is to translate the schema definition into a CodeDom CodeNamespace and then export that CodeNamespace instance to code. Simple, right?

Fortunately for us, there are classes built into the framework to handle this. First we set up a schema importer and a code exporter:

The argument for the CodeNamespace constructor takes a string representing the desired namespace name for the generated code. The translation between these objects occurs using an System.Xml.Serialization.XmlTypeMapping instance to connect the two. To create the type mapping, we’ll need an System.Xml.XmlQualifiedName representing the root element of the schema. The exporter can then export that type mapping to a CodeDom representation, which we can utilize to write the code output to a file. The result looks something like this:

The code above iterates over items in the schema until the root element (XmlSchemaElement) is found, at which the importer will import the type mapping, and the exporter will export it to the CodeNamespace defined earlier. At the end of the for loop, the CodeNamespace object contains all of the types representing the XML schema. At the end, we tell a CSharpCodeProvider to generate code from the types in the namespace to an output file, ready for consumption. The code is very simple; however, we are not utilizing the CodeDom APIs to their full potential. Because the types are accessible before generating the code, we can make any changes we desire before writing the code. This is the crux of this post—being able to customize the generated code.

Making Your Modifications

If you are familiar with the CodeDom APIs, then at this point you can probably start making your own modifications. But, just in case you aren’t, I will quickly walk through how to generate XML documentation comments on the generated code members. Re-examining the loop over the objects in the XML schema, we can reasonably infer based on our specific schema that there is more than one object in the collection. In this case, the other named complex types are part of this collection; consequently, we can modify the code in the loop to consider elements and attributes:

There are a few significant changes here. First, immediately after the type mapping is exported, we cast all of the CodeNamespace’s types to CodeTypeDeclarations for use later in the loop. On subsequent iterations of the loop, we anticipate running into XmlSchemaComplexType objects. The code then retrieves the appropriate CodeTypeDeclaration which matches that complex type, retrieves the documentation for that type, and sets the summary comment. The pattern is repeated for the attributes in each complex type.

The GetDocumentation and SetSummaryComment methods are fairly simple and involve manipulating the object models of XML Schema and CodeDom, respectively, to achieve their goals. Fortunately for the GetDocumentation method, there is a base class in the object model which encapsulates all elements which can be annotated.

Above we assume that the xsd:documentation element will be the first one within the xsd:annotation element. This is not a safe assumption for all schemas.

Integrating with MSBuild

The final step is to integrate this code generator with MSBuild. If you are familiar with creating custom tasks in MSBuild, then this will be review for you. However, the steps are as follows:

1. (Optional) Encapsulate the business logic laid out above into a separate, re-usable class.
2. Create a class inheriting from Microsoft.Build.Utilities.Task (in Microsoft.Build.Utilities.dll or Microsoft.Build.Utilities.v3.5.dll).
3. Create properties for each parameter that the task uses to accomplish its goal. (You may consider items like XsdFileLocation or DestinationFile.)
4. Override the Execute method to carry out your custom logic, utilizing the properties as necessary.

A sample implementation could look like this:

Once the task is created, we can go back to editing the project file as we did in the first post in the series. As a reminder, here is what we had before:

And here is what we have now:

  <XsdGen DestinationFile="SampleSchema.g.cs" Namespace="DeWinter.Samples.Serialization" XsdLocation="SampleSchema.xsd" />

</Target>

<Target Name="BeforeBuild" DependsOnTargets="GenerateSerializationClasses">

</Target>

Before the actual compilation step, MSBuild will execute the GenerateSerializationClasses target, locate the XsdGen task in DeWinter.XsdGen.dll, and then call the Execute method on that task. This will generate the XML Schema object model as desired (notice the XML comments below):

Let the Buyer Beware

The ironic part about writing this post is that the more I wrote, the less appealing this method was. Think about it; you are essentially writing a replacement for xsd.exe. The more generalized you want to make it the more difficult it becomes. In this post I accounted for named complex types only. What about anonymous complex types? Complex types that are extensions or restrictions of other complex types? Other facets like enumerations? XML Schema has a multitude of different elements, and building a suitable replacement for xsd.exe that suits your needs just isn’t worth it most of the time.

The other problem I have with it is just that there is so little gain to justify the amount of work you would put into it. My original justification for investigating this method was that it made the object model much nicer to work with, because it was well-commented and not as awkward to use as the normally generated OM (object model). But that’s really subjective!

My personal opinion, though, is that the object model generated by xsd.exe is fine. If you really want an object model that is "better" to work with (whatever "better" means to you), then build an abstraction layer on top of the generated OM and have a service class translate between the two. In my next post on serialization I’ll cover this.

Reference Source Code

This was my reference for this post, and there quite a few more features included, like stripping suffixes from type names and "correcting" the casing of the generated classes. (Hmm, that is becoming a theme among my work now, isn’t it…?). But it is not complete and probably works only against very limited situations. I would advise you to use this for reference only. And of course, the disclaimer…

Disclaimer: This software is provided as is, and I am not responsible or liable for any damages arising in any way out of the use of this software, even if advised of the possibility of such damage.

Download

This entry was posted on Sunday, September 28th, 2008 at 12:12 pm and is filed under C# .NET, MSBuild. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.