But first the pattern: Martin Fowlers Discussion of the MVC Pattern.

General MVC Resources

These links are websites with lots of various information about MVC, with no specific focus.

• Microsoft’s MVC Framework Website
• All of Scott Hanselman’s MVC Posts
• Scott Guthrie for eveything .NET
• An introduction to MVC
• A list of MSDN resources for learning the details of the MVC Framework

Architecture and Pipeline

A very good description of the full request response pipeline in MVC.NET, this is for version 1.0 but the information is still useful.

• Architectural Overview of MVC Framework
• V1.0 Request/Response Pipeline Overview

Model Binding Information

• Creating a Model Binder
• IModelBinder Autobinding

Routing

• MSDN Review of the MVC Routing Process

After we have painstakingly entered all of that XML code comments in our source code. We need a nice way to see the fruits of our labours. NDoc emerged years ago and provided a way to get your documentation in to a compiled CHM file, but crashed and burned when generics was released in .NET 2. Documentation tools/generators whatever have never kind of cut the mustard since then.

Lets have a look at the Live Documenter.

.NET documentation has never looked so good

The Live Documenter supports all currently available versions of the .NET framework, project and solution files. So when you want to view your documentation you can just simply point it at your current solution file. You will be greeted by the library view.

Assemblies in Live Documenter

You are presented with a list of all of the libraries in the solution. The black ones have XML comments the grey ones have not. When you select one of the libraries the list of namespaces is displayed in the reading panel on the right. Nice and simple.

Lets just jump in and see what a documented class looks like.

Classes in Live Documenter

The class is displayed as you expect. The remarks you entered are displayed, the see links you created are displayed AND they link through to the associated class, method, property. The inheritance tree is displayed and the see also links from the documentation. The tree view shows all the other classes, enumeration, interfaces in the same namespace.

/// <summary>
/// The AssemblyDef provides the top level information and entry point to
/// all types, methods etc reflected from a .NET executable.
/// </summary>
/// <remarks>
/// <para>The AssemblyDef is the starting point for obtaining reflected information
/// about a .NET assembly. This information is obtained by parsing and discerning
/// information about <see cref="TypeDef"/>s, <see cref="MethodDef"/>s etc from
/// the .NET metadata stored in the <see cref="PeCoffFile"/>.</para>
/// <para>The assembly implements a mechanism for generating unique identifiers
/// that can be assigned to each of the elements reflected in this assembly. The
/// unique identifier is not really required but can help other applications to
/// store keys and find reflected elements more quickly and uses less memory than
/// string based unique identifiers.</para>
/// <example>
/// <code>
/// // Instantiate from a full file path and name
/// AssemblyDef assembly = AssemblyDef.Create(myAssemblyPath);
///
/// // Instantiate from an already existing loaded metadata file
/// PeCoffFile peCoffFile = new PeCoffFile(myAssemblyPath);
/// AssemblyDef assembly = AssemblyDef.Create(peCoffFile);
/// </code>
/// </example>
/// </remarks>
/// <seealso cref="PeCoffFile"/>

There is a full list of supported XML tags on the MSDN website.

The method view is just as good. It displays the exceptions, type parameters, parameters, summaries and remarks as expected.

Methods in the Live Documenter

You can also search the whole solution for methods, classes etc. The Live Documenter will show you an auto-complete search box with the results for you query.

Searching in the Live Documenter

It handily displays the summary text with each result to help you figure out which result you was actually looking for.

There is plenty more to get excited about with the Live Documenter, it’s super fast, really good looking and I suggest you download your FREE copy from http://theboxsoftware.com/products/live-documenter/.

The code below should be placed in your Application_EndRequest event handler in global.asax. By placing a break point in the code directly after evaluation you can see a collection of all the routes, if it matched the request and a reference to the RouteData to see more detailed information.

This code works by re-evaluating each of the Routes defined in your application against the current request. The first match in the collection is the match that MVC will have used to handle your request.

List<object> routes = new List<object>();
foreach (System.Web.Routing.Route current in System.Web.Routing.RouteTable.Routes) {
	System.Web.Routing.RouteData data = current.GetRouteData(
		new HttpContextWrapper(HttpContext.Current)
		);
	bool matches = data != null;
	routes.Add(new { Match=matches, Url=current.Url.ToString(), Data=data});
}

For a better long term implementation try using Phil Haack’s debugging implementation or get the route debugging code from the ASP.NET MVC Unleashed book.

Basically since NDoc curled up and died a long time ago I have really wanted a nice xml comment documenter to read all those lovely comments I have been painstakingly hand crafting since , well, as long as I can remember. This has been curled up at the back of mind for ages. And a little while ago I decided I would start faffing around with the .NET meta-data and just try to learn a little more about how the CLR holds it’s data in PE files, what kind of data and well.. OK I can’t justify it really. Anyway; two thoughts collided and the rest is unwritten history.

What it Does

This documentor takes a solution, project or library and churns through all the internal gubbins of the built libraries for the VS files or itself for the DLL. It then locates the lovely XML comment files, mingles them together and spits out some nice legible information. I haven’t painted that in the most beautiful light but I am British so it remains understated.

• Reads VS Solution, Project and Library files
• Parses XML comments (supports the basic Microsoft set) to produce documentation
• Updates live the changes you make to the your source code
• Allows searching of types, properties and methods
• Supports code comments for generic types and methods
• Provides syntax in C# or Visual Basic

It was a real struggle getting information about the internal workings of PE files, the Internet is a little sparse in this regard, so I had to get the aid of two books .NET IL Assembler and Reversing to help me on the way. Whilst I was reinventing the wheel Microsoft released an open source reflection library (which I can no longer find a link to) which seems to do everything, ah well. However, I think I will in future posts, describe in a little more detail what I did and learnt while making this app.

Appearances can be Deceiving

This doesn’t look the best at the moment, but it’s still in development so bear with me! I really need to polish the front end up and apply some UX magic; so with that in mind lets have a look at some screenies.

View of a Class

View of a Namespace

The class view has all of the information you would expect. Full namespace declaration, deceleration syntax, all your lovely comments, inheritance tree and by the powers of WPF lots of control over how you view the page. All of the param references, type references, exception information (for methods) is linked up from the comments. The UI currently allows you to view easily which libraries have comments and which don’t.

As you can see by the method view below, it supports generic types and methods. Type, method, property etc signatures are generated and can be changed to multiple languages; although I have only written code to support VB and C# at the moment.

View of a Method

I all in all am pretty excited about where this is going at the moment and for the ideas I have about where it will be going on a more long term basis. One little thing I – in the long term – am hoping to get in there is dynamically creating UML diagrams. The idea of being able to see a methods full sequence diagram, cant be anything but a help for people working on new projects or revisiting old ones!

Finally, the main idea behind this application is that it is used more like a live reference, an open book; which you would have open at the same time as a project. Because of this the application will continually update itself based on changes you make to your solutions, projects, code and comments. I thought that was a little different from your normal wait for application to generate static pages, currently event with a large 20 project solution this still opens quickly and is extremely usable. I hope that has made you interested and I will speak up again when I have something that I can throw out there.

This application will be made available from my company, The Box Software.

Automating DTO Population

First of all grab yourself a copy of the source code. A general overview of the process is; you specify — using attributes — the mappings between your business objects and your data transfer objects. These attributes can describe simple properties, complex properties and collections. After that is done, throw the object at the converter and Bob’s your uncle!

Mapping DTO Properties with Attributes

There are two attributes DTOSimpleMapper and DTOCollectionMapper; the basic signature of the attributes is shown below.

[DTOSimpleMapper(params string[] fields)]
[DTOCollectionMapper(Type ofType, string fromField)]

[DTOSimpleMapper("FromProperty.Child.Identifier")]
public int ConvertedProperty;

The ‘fields’ and ‘fromField’ parameters describe the property on the origin object that is to be converted. The destination for the conversion is always the property the attribute is decorating. The fields are represented as a string where the field is a child property the ‘.’ notation can be used to indicate this. I.e. “Parent.Child.Child”.
The params string[] parameters on both attributes can be used to describe more complex conversions, when the converting types have multiple properties the conversion can be described by passing in an array of strings which define the from and to properties. I.e:

[DTOSimpleMapper("Prop1.Prop2=Identifier", "Prop2.Prop1=Name")]

The first parameter on the DTOCollectionMapper tells the converter what the destination array elements are:

[DTOCollectionMapper(typeof(string), "FromProperty"]
public string[] ConvertedCollection;

The converter will work with any collection that implements IEnumerable. As with the simple mapper, the property name can describe more complex conversions. This is useful where you have a generic DTO that is used to describe many elements:

[DTOCollectionMapper(typeof(IdentifiedElement), "FromPoperty", "Identifier=Identifier",
"Child.Name=Name")]
public List Children;

Finally where the conversions are more complex the type for the property can describe its own conversion:

Public class RelatedChildDTO {
     [DTOSimpleMapper("Identifier")] public int Identifier;
     [DTOSimpleMapper("Name")] public string Name;
}
Public class ParentDTO {
     [DTOSimpleMapper("Child")]
     public RelatedChildDTO Child;
}

With the above example the converter will check the type of instance it is creating and use the attributes described on that type to perform the conversion.

Conditional Population

Both of the attributes allow for Type conditional conversions as well, both are overloaded with a type property that is checked in the conversion process and only performed when the origin type is the same:

[DTOSimpleMapper(typeof(ConditionalBusinessObject), "FromProperty")]
public string ConvertedProperty;

Automatic Conversion

Now you have described the way objects are converted we are left with actual conversion, the library has a Converter class with a simple static method called Convert. This method takes an instance of an origin object and a type for the destination object.

BusinessObject bus = new BusinessObject();
// set business properties
DTO dto = (DTO)Convertor.Convert(bus, typeof(DTO));

The result of this method call is that the DTO is created and populated using the attributes, the conversion is done!
Here is the source code, it contains test classes which should give you a better idea of how it all works, enjoy!