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/.

Why do I like it? Or should the question be why do you not? It can be an extremely efficient way of obtaining large amounts of information about a project in very little time. A visual representation of a system gives a better understanding of a project overall, than a long-winded contract or several hours of perusing code can ever do.

Well written, considered and thought out project documentation can be a huge time and money saver. Sounds good doesn’t it. So why do developers hate documentation? Why don’t we ever find the time to keep it up to date?

Well, from what I have seen project documentation doesn’t get updated because there is generally no one in the team who actually owns it. It is seen as a pain and a chore; because lets face it, most people like to jump in and hack the code and why would we want to sit and write about what we have just done; we have done it already! You should be able to read the code, blah, blah, blah. Excuses. Unfortunately, our colleagues don’t fully understand that their rushed implementations or their bag of buzz words, latest technologies, multiple levels of indirection, inversion and misunderstood pattern implementations, are not easy to understand. And frankly, in three months time they won’t understand it either. Rant over.

And just having documentation isn’t enough. I have seen documentation associated with development projects which is out of date, poorly written and of very little value to anyone. Occasionally, developers are required to update documentation that is actually intended as contractual business documentation; again unhelpful.

What Constitues Good Documentation?

OK. So what constitutes a good set of documentation in a project. One acronym – UML. A picture paints a thousand words and all that. Now don’t get me wrong, I don’t think you should document every inch of code in a project. But even a document giving a generalised overview of the project, its architecture, architectural intent and diagrams which show visually this information; is priceless.

Observer Pattern

Time to put my money where my mouth is. This is what I think you should seriously consider having as a basic documentation set.

• Architecture. A UML diagram showing the constituent parts of the architecture, a description of the system and its intended purpose.
• System. You should document and diagram, with class diagrams, the major sections of the system. Again with a description of intent and purpose.
• Document complex interactions. In larger systems there are at least one portion of the system that requires a little more thought because of that clever implementation. Make sure it is again documented. A sequence diagram showing the interaction between classes and again, description of intent and purpose.

With this all developers will know how the system is architected, what it was supposed to be doing and how it is achieving it. This means that when they come to fix a bug or modify the system because of change requests that they understand what needs to be changed and how that effects the rest of the system. And of course they would update the documentation so that everyone else knows as well.

I use Evernote to make that information available. I have been using it for work and play for about a year, and it is has become a tool I just can’t live without. Evernote is available on the Web, Desktop, iPhone and other mobile devices and systems. This is how I have been using Evernote.

Project Information

First of all, to get information about the project I am working on. Where I work at the moment, there are many projects, which I may not be continually assigned to. This makes it difficult to keep in mind all of the things you need to know. Server address, UAT connection details, information about the project, recent work carried out. In essence anything that I deem interesting or important about a project gets thrown in to Evernote.

Evernote makes it easier to get back up to speed on projects rather than having to review the somewhat dry read which is the technical documentation.

Bug Fixes

If I have found a fix to an error I get on a project it is good to record this in Evernote, as it makes the fix available to other projects. Granted this is not as useful for very specific bugs but when you have issues with the Microsoft Enterprise Library, that information is going to be useful again.

To Do Lists

If I am working on a large job. I record all of the elements of that task as a Note. I can then check of each item as I get it done and as new things crop up and I can extend the to do list. So now I don’t forget where I am up to or what I have left to do.

Have a look at Evernote and let me know how you end up using it.

So aside from making corporate sites, business web applications, sticking within UX guidelines and the basic principle of CRAP (Contrast, Repetition, Alignment and Proximity). My design skills have not really had much of run out. Until now.

My first real design for my first real client, and a very picky and strong willed one at that: the other half.

Amy has been writing songs and playing live for a couple of years now, recently she decided to get a band together and rock out like she has always wanted. So with that, a new website, a new look, a new start.

So today, it is unveiled; the many months of  “discussions” has resulted in this very grungy looking website.

Here are a couple of screen shots to give you an a look.

Amy Wyke's Website

Amy Wyke Gallery Page

Amy is performing a number of gigs across England at the moment, go take a look.

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!