• 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

Here are some previous posts which (briefly) describe the domain:

http://blogs.rev-net.com/ddewinter/2008/02/16/the-linq-to-sql-model/

http://blogs.rev-net.com/ddewinter/2008/02/16/linq-to-sql-and-database-schema-sync/

Any ideas about directions for the tool? Or maybe something that wasn’t covered in the screencast? I’d love to hear your ideas.

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.

Yes? Then this article is for you. If not, you might know what this entry’s going to cover, but perhaps you’ll learn something new.

In tools I’ve been building, I’ve always been dissatisfied with this sort of "error reporting" (outside of logging, of course), but none of us have had the time to build something really spectacular to handle exceptions. And I have to say–thank goodness we didn’t! Yesterday I read about the ExceptionMessageBox class, and this is the sort of thing I’ve been waiting for! (Except it’s been out for well over a year…but that’s another story).

Since pictures speak better than words, the same exception from the first image is thrown again and is handled with the ExceptionMessageBox under default settings:

New and Improved

Much cleaner, huh? Not only does it give you the original exception, but it gives you all of the inner exception detail as well. When you click on the "Show Technical Details" icon in the toolbar (the button on the right) you’ll see a much appreciated stack trace for each of the exceptions in your chain.

Details

All of this is accomplished with two lines of code:

Very simple, indeed. The ExceptionMessageBox class is in the Microsoft.SqlServer.MessageBox namespace in the Microsoft.ExceptionMessageBox assembly. That assembly is available for download on this page. (Search for "Exception Message Box.")

In addition, the ExceptionMessageBox supports a fair number of properties that should be touched on. We’ll cover the highlights here:

Properties

• Beep (Boolean) – Specifies whether the ExceptionMessageBox beeps when it is launched (similar to a normal MessageBox).
• Buttons (ExceptionMessageBoxButtons) – Specifies the type of buttons used by the ExceptionMessageBox. You can also use Custom buttons, a nice touch on top of the original MessageBoxButtons enumeration.
• Caption (String) – The caption/title of the ExceptionMessageBox form.
• CustomDialogResult (ExceptionMessageBoxDialogResult) – Specifies the button that was clicked when using custom buttons.
• CustomSymbol (Bitmap) – Specifies a custom image to display instead of the normal Asterisk, Error, Warning, Information, etc.
• DefaultDialogResult (DialogResult) – Specifies the result of user action on the dialog when not using custom buttons.
• IsCheckBoxChecked (Boolean) – Specifies whether a check box for "Do not show this dialog again" was checked.
• Message (Exception) – The original exception passed into the ExceptionMessageBox constructor.
• MessageLevelDefault (Int32) – Specifies the maximum number of exceptions shown in the dialog. For example, if an exception is thrown that has two inner exceptions, and the MessageLevelDefault property is set to 2, then only the top-level exception and the first inner exception will be shown in the dialog.
• Options (ExceptionMessageBoxOptions) – Enables various options like right-to-left reading or right alignment.
• ShowCheckBox (Boolean) – Specifies whether to show the checkbox which enables developers to hook into users’ preferences on whether they want to show the dialog again.
• ShowToolBar (Boolean) – Specifies whether to show the toolbar (which allows copying text from the message and showing technical details).
• Symbol (ExceptionMessageBoxSymbol) – The symbol to show in the message box, like Asterisk, Error, Warning, and so on.
• Text (String) – If the message box is being used for custom text instead of an exception, then this property will be populated with that text.
• UseOwnerFont (String) – If you want to keep a consistent look across your application, you can tell the ExceptionMessageBox to use its owner window’s font instead of the default.

Methods

• SetButtonText – There are a couple of overloads for this method. It’s used to set the text of one to five buttons on the dialog. This only applies if the Buttons property is ExceptionMessageBoxButtons.Custom.
• Show – Where the magic happens. The basic version of this method requires an IWin32Window as an owner window. The nice thing is that you can pass in null. This would be appropriate if the executing code is inside of an event handler for AppDomain.UnhandledException, for example.

Event

• OnCopyToClipboard -This is a pretty interesting event. It’s raised when the user clicks on the copy to clipboard button in the toolbar or presses Ctrl+C. The event supplies a CopyToClipboardEventArgs instance that has two properties: ClipboardText and EventHandled. When the event is raised, the text hasn’t been copied to the clipboard yet. Instead, you get the chance to handle the event separately. If you want to do your own custom processing and not copy the text to the clipboard, then set the EventHandled property to true on the event arguments and the clipboard data will not be changed. I thought this would be useful for doing something extra, like emailing developers with exception information. However, there’s no easy way to change the text on the toolbar button…

So that’s a brief look at the ExceptionMessageBox. One thing I didn’t cover was how to use the multifarious CheckBox-related properties to stop showing the message box to end users. Here are some links that can help you further:

How To: Program The ExceptionMessageBox

The ExceptionMessageBox Class

Download Page For ExceptionMessageBox (Search for "Exception Message Box")

The approach a co-worker and I had taken to serialize the data was to write controls and control-specific data in XML and to write serializable objects (business objects that the controls had references to) as binary data. During this process, I had a very painful debugging experience trying to figure out why the BinaryFormatter was trying to serialize a ListBox when I had told it to serialize one of our business objects. The only thing we had done differently before saving was that we had edited a property which showed a dialog which contained a few ListBox objects.

That action was most definitely related to the issue, but we still couldn’t think of why it was trying to serialize the ListBox, especially after the dialog was closed.

After a couple of hours, I was a little astounded at the cause. It turns out that when we set the DataSource property on the ListBoxes in the dialog I mentioned earlier, the WireDataSource() method in the ListControl was called. Since our business entities also implement IComponent (courtesy of .netTiers), the method attaches its DataSourceDisposed method to the Disposed event of the bound object. Thus, when we tried to serialize the object, the link between its Disposed event and the DataSourceDisposed event handler had not been broken, and it had tried to save the containing type of DataSourceDisposed.

The simple fix was to set the DataSource properties on the ListBox to null when the Form closed. Almost a kick in the face after all that.

I’ve recently been working with the rules engine and PolicyActivity in WF. I’ve found that you can log what’s going on with the rules engine with the following configuration in the configuration file:

<configuration>

    <system.diagnostics>

        <switches>

            <add name=“System.Workflow.Activities.Rules“ value=“All“/>

            <add name=“System.Workflow.LogToFile“ value=“1“/>

        </switches>

    </system.diagnostics>

</configuration>

However, it’s also possible to trace using any trace listeners registered with the Trace.Listeners collection using the following:

<configuration>

    <system.diagnostics>

        <switches>

            <add name=“System.Workflow.Activities.Rules“ value=“All“/>

            <add name=“System.Workflow.LogToTraceListeners“ value=“1“/>

        </switches>

    </system.diagnostics>

</configuration>

I mention this because in the context that I found it, I found almost no documentation on this. It’s probably more easily accessible than I think, but it’s here just in case. =)

This entry is also a response to Ben’s blog entry, located here, which you should read first because it explains the difference between the two approaches.

Now…a little about why I disagree that EIMI should be used as often as possible.

1. Having to cast an object to the interface just to call the interface method can get a little annoying in code. When you’re working on a team that might not be so familiar with this pattern then it takes extra time for them to get acquainted with it, because it’s a little awkward. However, this may be a superficial reason to some, so let’s continue…
2. Regarding that cast, think about a case where you have a value type that has used EIMI to implement an interface. When you cast to the interface you burden your application by forcing a box operation on the value type so it can actually be treated as that interface type.
3. Furthermore, with EIMI, if you derive from a class that implements an interface in this manner, you can’t call your base class’s implementation of that interface.

Now, I’m not saying that EIMI is useless. There are some specific cases when it is necessary. Take for instance the following example:

[code lang="csharp"] public interface IWindow
{
object GetMenu();
}
public interface IRestaurant
{
object GetMenu();
}
public class Pizzeria : IWindow, IRestaurant
{
object IWindow.GetMenu() { ... }

object IRestaurant.GetMenu() { ... }
}
[/code]

Here you have to use EIMI because you have two interfaces with the same method names. It doesn’t make sense to call GetMenu() and expect the CLR to infer which interface you’re binding to.

Another case where EIMI can come in handy is to improve compile-time safety. Let’s say you have a struct that implements a non-generic interface, like IComparable:

[code lang="csharp"] public interface IComparable
{
Int32 CompareTo(Object other);
}

public struct SomeValueType : IComparable
{
private int x;

public SomeValueType(Int32 x) { this.x = x; }

public Int32 CompareTo(Object other)
{
return x - ((SomeValueType)other).x;
}
}

// Now in some other method I can call CompareTo like this
public static void Main()
{
SomeValueType v = new SomeValueType(0);
Object o = new Object();
Int32 n = v.CompareTo(v); // Undesired Boxing
n = v.CompareTo(o); // InvalidCastException
}[/code]

So now instead of what’s listed above, you want to enforce some semblance of compile-time safety with your interface method. Here’s something you can do with EIMI:
[code lang="csharp"] public struct SomeValueType : IComparable
{
private int x;

public SomeValueType(Int32 x) { this.x = x; }

Int32 IComparable.CompareTo(Object other)
{
return CompareTo((SomeValueType)other);
}
public Int32 CompareTo(SomeValueType other)
{
return x - other.x;
}
}

// Now in some other method I can call CompareTo like this
public static void Main()
{
SomeValueType v = new SomeValueType(0);
Object o = new Object();
Int32 n = v.CompareTo(v); // No Boxing
n = v.CompareTo(o); // Compile-time Error
}[/code]

Of course, if we box SomeValueType into an IComparable instance then it would throw as above, so this s”olution” only alleviates the problem; in most cases your best bet would be to use a generic interface to enforce type-safety and remove boxing/unboxing operations.

Because of this, I have concluded that I will not use EIMI every chance I get, but instead will focus on using IIMI unless I really need to use EIMI as outlined by cases above.

The first way to determine the type of an object instance is to use reflection. You may have heard that reflection causes significant overhead. This is no exception. Here’s an example.

public void Display(IList displayer)
{
if (displayer.GetType() == Type.GetType("System.Collections.ArrayList"))
{
return;
}
// Other processing...
}

It’s bad enough that we’re using reflection for this information (via the GetType() method of displayer), but also that we’re hardcoding the type of the class we’re interested in with “System.Collections.ArrayList.” This can be cleaned up to the following:

public void Display(IList displayer)
{
if (displayer.GetType() == typeof(System.Collections.ArrayList))
{
return;
}
// Other processing...
}

However, it’s still reflection. Instead of using this, consider using the is keyword, which in fact does not use reflection at all but a special MSIL statement which is pretty quick, as far as what I’ve heard.

public void Display(IList displayer)
{
if (displayer is System.Collections.ArrayList)
{
return;
}
// Other processing...
}

Another keyword that is often overlooked is the as keyword. This handles casting on reference types. Although I hope you haven’t, maybe you’ve seen something like this before:

DataSet ds;
try
{
ds = (DataSet)Request.Cache["ds"];
}
catch { }

You don’t even need a try/catch statement here; just use the as keyword! Not only will it handle times when it is impossible to cast to the requested type by setting the value to null, but it also uses the same MSIL instruction as is, so it’s pretty efficient. You can’t use these two keywords with value types because value types and reference types are handled differently in memory.

Here’s one last example:

public void Display(IList«IDisposable» list)
{
int count = list.Count;
for (int i = 0; i < count; ++i)
{
IDisposable item = list[i];
if (item is SqlConnection)
{
(item as SqlConnection).Open();
}
// Other processing...
}
}

Say you wanted to check if a particular item is a SqlConnection object, and if it is, open it. Remember how is and as do basically the exact same thing though? So in this previous block of code you have a double cast. Consider doing something like the following:

public void Display(IList«IDisposable» list)
{
int count = list.Count;
for (int i = 0; i < count; ++i)
{
IDisposable item = list[i];
SqlConnection cnn = item as SqlConnection;
if (cnn != null)
{
cnn.Open();
}
// Other processing...
}
}

// Matt’s first rule of performance:
// 0 > 1 > 2

So what does that mean? The gist is that if you need to get a result from a property or method, and you need to manipulate that value in more than one place, it’s better to call it once than call it twice. But even so, it’s better not to call anything at all if you can help it.

An example of this in practice was what he was referring to at the time: (beware, ORM jargon approaching!) the Multiplicity property of a Role object. This RoleMultiplicity is a measure of how many times a unique value could go into a fact table representing the role’s opposite role on a binary fact type i.e. if I had the fact type “Person(ID) has PersonName()” with a uniqueness and mandatory role constraint on the side of the Person object, calling the Multiplicity property of the PersonName’s role would give me RoleMultiplicity.ExactlyOne (opposite role’s constraints signify this).

Little did I know that calling this property was an immensely expensive procedure. It has to get the fact type from the model by using VS2005’s “Store” (as its name implies, stores everything that would be on the diagram, and we have know idea how that’s done; could be something of O(n²) complexity; see how Algorithms comes into play?!), and then create a new collection based on the roles from the model. It thens checks the count of the collection which does a lot of other checks (F11 makes you sick), and then does another loop to check for what multiplicity that role actually has. Before investigating all of that for ourselves, this is what our code looked like:

Before the Rule – Notice the properties referenced multiple times.

After the Rule – Notice how things are pulled out.

So remember:
When in doubt, pull it out.