• 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

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.

Unfortunately, I don’t believe adding the CompilerGeneratedAttribute (CGA), which was done before RC2′s release, to PostSharp-specific code fixed all of the Code Analysis warnings that our team received. After upgrading to RC2, Code Analysis warned us specifically about initializing our static fields inline in many of our classes and removing the explicit static constructors, as well as the cyclomatic complexity of some of our methods. It was the fact that we did initialize our static fields inline that tipped us off about the same problems that caused me to write my first PostSharp and Code Analysis post. The problem is that adding the CGA is not comprehensive enough to suppress all code analysis violations. For example, PostSharp effectively injects code at certain points in a program execution (join points in a method). You wouldn’t want the CompilerGeneratedAttribute applied to that code, because it could suppress other rule violations that come from your code, not PostSharp’s code. Fortunately PostSharp does not apply the CGA in those circumstances, but there needs to be a middle ground such that PostSharp code is totally ignored by code analysis.

Looking ahead, I’m not sure what the best solution for the PostSharp team is on this. I know it’s low priority compared to other functionality, but as an end user it is frustrating to filter rule violations based on what PostSharp generates. The easiest approach, in my opinion, would be for PostSharp to preserve the assembly the compiler produces. That way, Visual Studio Team Edition for Developers (or Visual Studio Team Suite) can perform static code analysis on those assemblies, and FxCop can have an assembly on disk to analyze.

Since there were some changes in the targets file that PostSharp uses, I had to make a new version of the targets file I showed last time. This time, however, I took the opportunity to fix a bug that the old targets file introduced, which ran code analysis on PostSharp-affected code in certain circumstances.

Last time after using the new targets file, if you ran code analysis (using, for example, the context menu commands “Run Code Analysis” or “Rebuild” if code analysis was enabled) on a project, then everything would run as expected. Code analysis would show only warnings from the assembly before PostSharp “touched” it. The problem was that Code Analysis (CA) would run, and then PostSharp would overwrite the assembly that it analyzed. If the project were built again without any modifications to any file in the assembly, then CA would see that the assembly changed (because PostSharp overwrote it during the last build), and thus would run again.

The new solution takes advantage of the fact that PostSharp also stores the assembly that contains AOP-processed code in the obj$(Configuration)PostSharp directory. This is new process:

1. Compiler runs and places assembly and PDB in obj$(Configuration) folder.
2. Code Analysis runs on obj$(Configuration) DLL.
3. PostSharp disassembles and reassembles DLL in the obj$(Configuration) folder, placing result DLL and PDB in the obj$(Configuration)PostSharp folder. Note that PostSharp does not ovewrite the obj$(Configuration) DLL and PDB.
4. CopyFilesToOutputDirectory copies files from obj$(Configuration) to bin$(Configuration), including the DLL and PDB. Obviously, we want the PostSharp code, not the code created straight from the compiler.
5. CopyPostSharpFilesToOutputDirectory (a new MSBuild target) copies the DLL and PDB from obj$(Configuration)PostSharp to the bin$(Configuration) folder.

This process leaves the obj$(Configuration) DLL and PDB as the one that the compiler created. This gives CA a chance to run on an “untouched” assembly, both inside and outside the build process.

The latest targets file is available here: (Remember to rename the extension to .targets instead of .targets.xml)

PostSharp-1.0 Targets (RC2) – Copy to your %PROGRAMFILES%MSBuildPostSharp directory.

Are you using PostSharp for your .NET development? Do you get frustrated when code analysis within VSTS reports warnings like these:

Now PostSharp is a superb AOP tool for .NET, but it is annoying to see these issues in code analysis again and again; what would be great is if we can edit the build process to make Code Analysis (CA) run before PostSharp processes the assembly. That way, code analysis errors on PostSharp-generated code is ignored, and everyone is happy.

It can take a while to parse through all the targets in Microsoft.Common.targets, Microsoft.CodeAnalysis.targets, and PostSharp-1.0.targets, but here’s the general order of what’s happening with a fresh PostSharp installation.

• …
• Compile
  • …
  • CoreCompile (Delegated to a specific language’s targets file; for example, C# runs csc.exe at this point.)
  • …
  • PostSharpInspectConstants
  • PostSharpInspectReferences
  • PostSharp (Where the actual post-compilation is done)
• …
• PrepareForRun (After build, but before running the application)
  • CopyFilesToOutputDirectory
  • RunCodeAnalysis
• …

So there are obviously a couple of steps between the PostSharp processing and CA. When building the project, the CoreCompile target will place the newly built assembly in the obj$(Configuration) folder. Afterwards, when PostSharp runs, it compiles a new assembly with PDBs in the obj$(Configuration)PostSharp folder. Finally, that is copied to the obj$(Configuration) folder, which overwrites what the CoreCompile task created.

CA waits until the files are copied to the $(OutDir) directory (which is by default bin$(Configuration)) before executing. Thus it would be great if we could now change the order of things to do the following when PostSharp is enabled:

• …
• Compile
  • …
  • CoreCompile (Delegated to a specific language’s targets file; for example, C# runs csc.exe at this point.)
  • …
  • RunCodeAnalysis
  • PostSharpInspectConstants
  • PostSharpInspectReferences
  • PostSharp
• …
• PrepareForRun
  • CopyFilesToOutputDirectory
• …

So the next question is how do we do that?

The first thing is we need to find the targets files for both CA and PostSharp. The former is located at %PROGRAMFILES%MSBuildMicrosoftVisualStudiov9.0CodeAnalysisMicrosoft.CodeAnalysis.targets, and the latter is located at %PROGRAMFILES%MSBuildPostSharpPostSharp-1.0.targets. At the end of the PostSharp targets file, you can see that it inserts itself into the chain of compilation targets I described above.

<PropertyGroup>

    <CompileDependsOn>

        $(CompileDependsOn);

        PostSharpInspectConstants;

        PostSharpInspectReferences;

        PostSharp

    </CompileDependsOn>

    <BuildDependsOn>

        $(BuildDependsOn);

        PostSharpVerify

    </BuildDependsOn>

</PropertyGroup>

Now perhaps we can trick code analysis into running before PostSharp just by re-ordering the dependencies, like this:

<PropertyGroup>

    <CompileDependsOn>

        $(CompileDependsOn);

        RunCodeAnalysis;

        PostSharpInspectConstants;

        PostSharpInspectReferences;

        PostSharp

    </CompileDependsOn>

    <BuildDependsOn>

        $(BuildDependsOn);

        PostSharpVerify

    </BuildDependsOn>

</PropertyGroup>

So we’ve said to run code analysis before the PostSharp processing. Unfortunately, this doesn’t work, as MSBuild reports the following error:

If we navigate to the Microsoft.CodeAnalysis.targets file, we can see that the RunCodeAnalysis target depends on the Compile target. But because we also overrode the CompileDependsOn property to include RunCodeAnalysis, we have two targets that are dependent on each other to run.

The next trick is to change what CodeAnalysis is dependent on. To do this, we need to change its semantics; instead of performing analysis on the $(OutDir)$(TargetName)$(TargetExt)  file (e.g. binDebugTarget.dll), we need to perform analysis on the obj$(Configuration)$(TargetName)$(TargetExt) file (e.g. objDebugTarget.dll). So instead of being dependent on Compile, the target is dependent on the step that generates the objDebugTarget.dll file: CoreCompile.

<Target

    Name=“RunCodeAnalysis“

    Condition=“‘$(RunCodeAnalysis)’==’true’ or ‘$(RunCodeAnalysisOnce)’==’true’“

    Inputs=“$(CodeAnalysisInputAssemblyForTask)“

    Outputs=“$(CodeAnalysisLogFileForTask);$(CodeAnalysisSucceededFile)“

    DependsOnTargets=“CoreCompile;SetCodeAnalysisProperties“

    >

We’re almost done. Unfortunately, now CodeAnalysis runs at the correct point, but it doesn’t run on the correct file. Remember we want it to perform analysis on the obj$(Configuration) assembly before PostSharp has overwritten it.  So how does Code Analysis know where to retrieve the assembly? Well, if we open the Microsoft.CodeAnalysis.targets file again and have a look at the properties, we can see:

<CodeAnalysisInputAssemblyForTask Condition=“‘$(CodeAnalysisInputAssembly)’!=”“>$(CodeAnalysisInputAssembly)</CodeAnalysisInputAssemblyForTask>

<CodeAnalysisInputAssemblyForTask Condition=“‘$(CodeAnalysisInputAssembly)’==”“>$(OutDir)$(TargetName)$(TargetExt)</CodeAnalysisInputAssemblyForTask>

<CodeAnalysisLogFileForTask Condition=“‘$(CodeAnalysisLogFile)’!=”“>$(CodeAnalysisLogFile)</CodeAnalysisLogFileForTask>

<CodeAnalysisLogFileForTask Condition=“‘$(CodeAnalysisLogFile)’==”“>$(CodeAnalysisInputAssemblyForTask).CodeAnalysisLog.xml</CodeAnalysisLogFileForTask>

So what this tells us is that the CodeAnalysisInputAssemblyForTask and CodeAnalysisLogFileForTask files can be overridden by a project file or another targets file by specifying either property in a <PropertyGroup> tag, like this:

<PropertyGroup>

    <CodeAnalysisInputAssemblyForTask>obj$(Configuration)$(TargetName)$(TargetExt)</CodeAnalysisInputAssemblyForTask>

    <CodeAnalysisLogFileForTask>$(CodeAnalysisInputAssemblyForTask).CodeAnalysisLog.xml</CodeAnalysisLogFileForTask>

</PropertyGroup>

When placed in a project file, this will instruct Code Analysis to analyze the assembly that we want and to produce the log file in the correct directory. This is a bit of a hassle when you have to change every single project, and there may be some cases where you want to keep the default behavior of Code Analysis (i.e. point at the binDebug folder when PostSharp is not run). There is one last tweak we can make to automate this change across all projects. Open up the PostSharp targets file and scroll down to the PropertyGroup that defines the CompileDependsOn property. Overwrite that single property group with the following:

<!– Introduces PostSharp in the chain of compilation targets –>

<PropertyGroup Condition=“‘$(RunCodeAnalysis)’==’true’ or ‘$(RunCodeAnalysisOnce)’==’true’“>

    <CompileDependsOn>

        $(CompileDependsOn);

        RunCodeAnalysis;

        PostSharpInspectConstants;

        PostSharpInspectReferences;

        PostSharp

    </CompileDependsOn>

    <CodeAnalysisInputAssemblyForTask>obj$(Configuration)$(TargetName)$(TargetExt)</CodeAnalysisInputAssemblyForTask>

    <CodeAnalysisLogFileForTask>$(CodeAnalysisInputAssemblyForTask).CodeAnalysisLog.xml</CodeAnalysisLogFileForTask>

</PropertyGroup>

<PropertyGroup Condition=“‘$(RunCodeAnalysis)’!=’true’ and ‘$(RunCodeAnalysisOnce)’!=’true’“>

    <CompileDependsOn>

        $(CompileDependsOn);

        PostSharpInspectConstants;

        PostSharpInspectReferences;

        PostSharp

    </CompileDependsOn>

</PropertyGroup>

<PropertyGroup>

    <BuildDependsOn>

        $(BuildDependsOn);

        PostSharpVerify

    </BuildDependsOn>

</PropertyGroup>

This final edit makes the targets a little more robust in that we (1) schedule Code Analysis to run before PostSharp only when CA is enabled and we (2) edit the CA Input Assembly property to target the desired location.

Here are the final targets files (Be sure to rename them to .targets instead of .xml):

PostSharp-1.0 Targets – %PROGRAMFILES%MSBuildPostSharp

Code Analysis VSTS 9.0 Targets – %PROGRAMFILES%MSBuildMicrosoftVisualStudiov9.0CodeAnalysis