David DeWinter

Yes, I am back from the grave. The past two months have been infuriatingly busy for me (and you’ll see why in a later post), but I finally have some time to write again. The topic? Generating serialization classes as part of your build process (Part 1) and in your own way (Part 2).

I might reach only a niche of .NET developers with this post, but it’s something that niche should be aware of. There is a tool in the .NET framework called xsd.exe, and one of its functions is to generate code, specifically .NET classes, from an XML Schema file (XSD). The tool decorates these classes with XML serialization attributes such that when .NET serializes an instance of the generated class that represents the root element, the output conforms to that XML schema. Often, developers using XML schemas will need to change them throughout the course of a project. Leveraging xsd.exe in a project thus requires the generated classes to be updated when an XML schema is updated. This is a bit dangerous in larger projects because not all developers may realize that the tool must be re-run, especially in the case of extremely minor changes to the schema.

Wouldn’t it be better to have a tighter integration among the XML schema, the generated classes, and the build environment? Fortunately, we can achieve this with a few simple steps, thanks to the MSBuild system for projects inside Visual Studio.

We’ll start from scratch here, so first things first: create a new project. Here I’ll just create a class library called "DeWinterXsd". Then add a new XML Schema file to the project. (You can find it under the Data category of items.)

Replace the contents of the schema file with the following snippet. It’s a very simple schema, featuring a root element and two child elements with three attributes among them.

Now that you have the schema, add a new class to your project with the same name as your XML schema file. For example, the name of my schema file is "SampleSchema.xsd", and the name of the class is "SampleSchema.cs". This should nest the .cs file underneath the schema file, akin to how code-behind files are nested under UI files (e.g. Windows Forms, XAML). So how do we generate serialization classes? Right click on your project file and select "Unload Project".

And then right click on the project again and click "Edit xxx.csproj".

Now you’ll see the contents of the .csproj file itself. If you’re not familiar with the MSBuild system, then here’s the gist of it. Building a project in your solution executes a series of tasks, which are logically grouped into targets. Building will actually run only one target, Compile. However, the Compile target can depend on other targets in order to run correctly, so those targets are run before Compile, and so on. Take a look at your output window sometime while building; it will show you the tasks being executed by each target. For more information, read an MSBuild tutorial, like this one.

What we’ll do now is say that before the compilation target occurs, we want to generate serialization classes using xsd.exe. Scroll to the bottom of the file and you should see this:

For now, we’ll uncomment the BeforeBuild target and insert a task to run xsd.exe. But since this is logically better off as its own target (e.g. GenerateSerializationClasses), we’ll specify that the BeforeBuild target depends on another target of our creation.

I’ve placed the above lines right above the comments that discuss the BeforeBuild and AfterBuild targets ("To modify your build process, add your task…"). Now…to actually do something inside GenerateSerializationClasses requires the use of the Exec task, which as its name implies, will execute a task as if running it from the command line. Here we need to run xsd.exe, so we need to find where this tool is located. To do this easily, run "where xsd.exe" from a Visual Studio Command Prompt. My xsd.exe is in one of the Windows SDK directories, so I’ll add it to the Exec task like this:

Straightforward, right? The Exec task tells MSBuild to run xsd.exe using the specified command parameters, which will generate serialization classes based off my XSD file (SampleSchema.xsd). If you reload and rebuild your project, then you’ll see the serialization classes appear in the .cs file you provided. But there’s one more thing we can do here first! It makes sense that we want to generate classes only when the schema file has actually changed, so we’ll need a few more attributes to the GenerateSerializationClasses target. The Inputs attribute specifies the inputs to consider for the target, and the Outputs attribute specifies the outputs to consider for the target. MSBuild will use this data to determine whether to run the target at all. Here, our logic is simple: if the schema file has been modified after the last modified time of the class file, then run the target, and that’s exactly what MSBuild will do. The final XML snippet:

Now, if you reload and rebuild your project, you can see the fruits of your labor:

We’ve generated the code, but it’s not the nicest output. Our classes have camel-cased names to match our element names, and the comments are non-existent for classes and publicly exposed members. Of course, we didn’t add any comments in our XML schema, but even if we used the xs:documentation element to document our elements and attributes, those comments would not be carried across to the generated code.

Next time, I’ll show you how to remedy these and other problems by building your own MSBuild task that can generate the same quality of code as xsd.exe but with a few custom enhancements.

This entry was posted on Tuesday, July 8th, 2008 at 5:58 am and is filed under C# .NET, MSBuild, Visual Studio 2008. 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.