Tag Archives: Application programming interface

The Open Source vs Commercial Development Myth

The two can Co-Exist

Looking around the internet you could believe that open source software development, and commercial software development, are opposing forces that can never meet or work well together.  All experienced software developers know this is simply untrue, and yet the myth seems to perpetuate anyway.

By being careful, and being keeping with the spirit of the freedoms represented by the open source community.  It is possible for open source developments to benefit commercial software, and commercial developments to benefit open source software.  In the almost two dacades that I’ve now been involved in software development both open source and commercial;  I have never found a conflict between the two ideals that couldn’t be solved in a way that helped everyone.

Understanding the Types of Open Source License

The first thing you need to understand is that not all open source licenses are equal.  There are primarily two kinds of open source: copyleft and permissive.  For commercial software development I find it easy to divide the copyleft licenses into “strong copyleft” and “weak copyleft”.  Let me cover the three categories briefly here:

Strong Copyleft

When a software system or library is placed under a Strong Copyleft licenses the author is indicating two things:

  1. He wants others to be able to use the code he has produced.
  2. He feels the code produced has value enough to ask others to share their own changes to the code and share systems using the code under the same terms.

The most prominent Strong Copyleft licenses are: GPLv2 and GPLv3.

Strong Copyleft licenses are sometimes described as having a “viral” affect.  This is due to the fact that any derived work has to be distributed under the same license terms.  In the spirit of the license a derived work is usually intended to include software that references or links to Strong Copyleft software libraries as well as altered versions of the original.  This means for example you can only use GPL code in your commercial application, if you are happy to now distribute your commercial application under the terms of the GPL.

Personally I would describe Strong Copyleft licenses as the least friendly for commercial software development and many commercial development companies have to avoid it to meet the IP desires of customers and business owners wanting software developed.

Weak Copyleft

When a software system or library is placed under a Weak Copyleft licenses the author is indicating three things:

  1. He wants others to be able to use the code he has produced.
  2. He feels the code produced has value enough to ask others to share their own changes to the code under the same terms.
  3. He is happy for the library to be used in closed-source products.

Weak Copyleft licenses are most often used for libraries.  The author wants bug fixes and enhancements added back to the library so it can continue to improve, but doesn’t care about how you license the software that utilises the library.

The most prominent Weak Copyleft licenses are LGPLv2.1, LGPLv3, MPL, and MS-PL.

Weak Copyleft licenses are mostly about encouraging you to share fixes and enhancements to core functionality and keeping those fixes and enhancements “free”.  It does not generally have the same “viral” affect as strong copyleft licenses because software that references or links to weak copyleft software libraries as not intended to be considered derived works.  This means you can use LGPL code in your commercial application, and distribute your main software under any license you want, however any changes you make to the copyleft library must be distributed under the original copyleft license.

Personally I would describe Weak Copyleft licenses as very friendly to commercial software development.  It encourages you to get benefit from somebody else’s effort, and simply asks for improvements to be shared in return.


When a software system or library is placed under a permissive licenses the author is indicating three things:

  1. He wants others to be able to use the code he has produced.
  2. He’d like some credit for the work he has put in.
  3. He is happy for the code to be used in any future open source or closed source application.

The most prominent permissive licenses are BSD, MIT, and Apache.

Permissive licenses are about preventing wasted effort while people to reinvent the wheel.  The functionality of the code is shared freely for open source or commercial use.  There is no “viral” affect, and you do not need to contribute changes back to the original author or project team, although this doesn’t mean you shouldn’t.

Personally I would describe Permissive licenses as very friendly to commercial software development.  It encourages you to get benefit from somebody else’s existing effort rather than wasting time reproducing the same functionality.  In exchange usually all that is asked for is acknowledgement of the codes origins.

Keeping the Spirit of the Original License Choice

Its important to understand that open source licenses work within the restrictions of the existing copyright framework.  This differs slightly country to country, and generally only forms contracts between people code or software is “distributed” to.  If you are not careful you can get caught up in questions of “can I do this with license X?” or comments “I don’t have to do that because license Y says you are not entitled to it”.  This is not what the open source community is about.  I believe that as well as keeping to the letter of the licenses, you should honour the spirit of the license regardless of the “additional rights” awarded by copyright laws in your country.

If you take a GPL library you want to use, and try and come up with ways to use the software “indirectly” to avoid putting your own code under the GPL, stop and think again.  The code you want to use was shared by the author because he wanted to see enhancements to it shared too.  You may not want to share your innovations., you may not like the GPL.  But that was the intention of the author and you should honour it or choose not to use the GPL code.

Likewise don’t think that because you upload copyleft software you developed to a web server you didn’t “distribute” it so you can keep the source closed.  And don’t create a “wrapper library” around an LGPL library where you add your new functionality so you don’t have to share it.  This isn’t the intention of the author when they let you use their code, and you shouldn’t abuse their intentions for your own gain.

If a product is dual licensed under copyleft and non-copyleft licenses, don’t constantly push the boundaries of what you can do with the copyleft version, contribute to the funding of the library or software by buying a license so it can continue to improve.

Giving Back

There are many ways to give back to the open source community as an commercial software developer.  Some are really simple but under commercial pressures are often ignored.

1. If you fix a bug in a library, no matter what license its under, submit the change back to the author or project team.

2. If you make minor enhancements that are generically useful, submit them back to the author or project team.

3. Don’t contribute incomplete changes or changes specific for your needs only back to the author or project team. These changes usually carry no reusable value and can waste the project’s time tidying them up for inclusion.

4. If you create a library or tool because you couldn’t find the one you needed in the market, and its not something you are wanting to commercialise on its own, make it available under an open source license you are comfortable with so others don’t have to repeat your effort.

5. If you create a useful program, library, or tool; consider duel licensing a “community” edition under a copyleft license.  Yes its true some developers and organisations won’t honour the license, but generally those people would have broken your commercial license terms if they had a chance too.  This dual licensing can be particularly useful for libraries as it can attract the attention students and others keen to learn your libraries or software, and this can in time become a major source of paid license users in the future.

6. Even if you are working on an open source project, don’t change the license of code from permissive to copyleft by adding enhancements and fixes under your project’s copyleft license rather than the original permissive license.  This practice has long been a point of contention between advocates of permissive licenses and those using their code in copyleft projects.  The overall project can still be copyleft, while honouring the spirit of the license for permissive code you use and giving back under the same license.

Commit Pitfalls

Here are a few of the pitfalls that can happen if you’re not careful combining open source software with commercial software products.

1. When you use an open source library don’t assume the author will carry on enhancing it in the future, and don’t assume someone else will fix the bugs.  Many open source projects are maintained in people spare time, and so every day some projects go stale as project teams move away, or change direction.  If you use an open source library in your commercial product, remember that you must plan to be able to maintain it in the future.

2. Always check the license before using an open source library.  Is it compatible with the IP requirements of you and your customers?  Does it have an explicit non-commercial use clause?  Its even worth checking this if you think you “know” the license the project is under.  Its not uncommon for exceptions or additional clauses to be added on top of standard licenses.

3. Don’t expect you can open source a dying product to “hand over” maintenance of it a community.  Be aware that the original author or team of an open source product, always end up the major contributors to that project long term.

4. Don’t assume because you didn’t pay for something, its cost is zero.  You still need to integrate the software or library into your solution, and you still need to train developers on its code base so you can maintain it within your SLAs.

5. Don’t dismiss a GPL library until you’ve checked the license.  Some projects prefer the use of the GPL over the LGPL but add explicit exceptions for the linking of close-source software.


Open source and commercial software can benefit each other, even if their license terms sometimes seem contradictory.  By following the license requirements, and keeping with the spirit that caused the author to open source their software in the first place, the open source projects can benefit from bug fixes and enhancements from commercial users of their software.

Closed source commercial software can benefit by using stable versions of open source libraries reducing development times and potentially delivering a richer experience.

Both open source and commercial users benefit from a dual licensing scheme where it is appropriate, with the larger user base providing a useful support and learning network, as well as a pattern of many active open source users progressing to paid services in the future.

The small print: I’m not a lawyer so please take this article as me sharing my experience as an open source and commercial software developer rather than legal advice about licenses and copyright law.

C# Code Guidelines

Coding Guidelines

Every development team or software development team need guidelines to follow to help them write consistent code that keeps maintenance costs low, and development productivity and code reuse high.

I recently updated the ones I use with my team, and though I’d share them to save others having to create their own.  Feel free to reuse in part or full for yourself or your team, and leave a comment with any general suggestions.  Style can be a very personal thing, so don’t be afraid to adapt them to meet your teams own preferences, the key is that all the team follow the same convention, and wherever possible that convention matches the underlying framework you are using.

Naming Conventions


Use PascalCasing for namespaces, types, and member names.

Use camalCasing for local variables, parameters, and user interface fields.

Use camalCasing with an “m_” prefix for private non-user interface fields.

In 3rd Party Templates or code that uses a “_” prefix within a class rather than a “m_” prefix then be consistant within the class and either rename all to “m_” or continue with the “_” prefix.

Type Notations in Variable Names

Hugarian Notion must not be used – When the type is an important part of the variable’s purpose include it in the name by prefixing or postfixing it to the name without abbreviation.

Do not use abbreviations – If an acronym is widely accepted and used in the framework or toolkit being referenced then it acronym may be used despite the rule to avoid abbreviations.

.NET Word Conventions

Following .NET conventions for the words:

  1. Indexes (not Indices)
  2. UserName (not Username)

Use the following symmetric words when defining pairs of functionality:

  1. Add / Remove
  2. Insert / Delete
  3. Create / Destroy
  4. Initialize / Finalize
  5. Get / Set
  6. LogOn / LogOff
  7. Begin / End
  8. Register / Unregister

Use the following American words rather than the British words for member names:

  1. Color
  2. Initialize

Use of Plural and Singular Words

Name all classes with a singular word or phrase.

Name all collections or with plural words or phrases.

Name all namespaces as plural words or phrases unless the namespace has a special meaning in the MVC framework.

Compatibility with COM and other CLR Languages

Do not name two public or protected members with names that are the same excluding character case.  This would prevent reuse of the classes in languages such as VB.NET.

When an argument for a class is passed in to a method or constructor with the purpose of setting the public member, then use of the same name in camelCase rather than PascalCase is recommend over prefixes or suffixes.


Name all static singletons that initialise themselves “Default” unless there is a specific reason to use another name.

Name all static singletons that do not self-initialise “Current” unless there is a specific reason to use another name.

Simple Names

The following simple names are allowed for the uses specified:

  1. obj – to store a generic object who’s type is unimportant.
  2. i, j, k – for control of loops.
  3. s – to store a string value of a variable already in scope in a different type.
  4. e, ea, ee – for subclasses of EventArgs.
  5. e, ex – for subclasses of Exception.
  6. item, it – for the control variable in LINQ query expressions.

Use of Types in Variable Declarations

Use the most specific type available in a variable declaration that is not initialised in-line.

Use var for types that are initialised in-line.

Do not use var for types that are initialised in-line to values of a standard type (e.g. int, string, decimal etc.).

Use var for variables that are initialised as the result of method calls that return collections.

Use var for variables that are storing anonymous types.

Use var when the exact type of a variables is unimportant to the method as more than a return value from an invocation.

Use object for types that are initialised as the result of method calls where the return type is going to be worked with only via reflection.

Use interfaces for variable types if the work being done is dependent only on the interface.

Use dynamic as a variable type only if the type could not be known at compile time, and the code is not going to reflect on the type.


Constructor Performance

Avoid use of database connections in constructors.

Avoid use of network calls in constructors.

User Interface Design Time Requirements

Constructors for User Interface classes must be design time compatible.

Member Initialisation

Do not add constructor overloads that perform member initialisation as part of its parameters, these should now be handled by the member initialisation syntax.

Factory and Dependency Injection

Provide a zero parameter constructor unless the class is entirely unusable without a parameter.

Ensure the zero parameter constructor is suitable for use in a class factory or service locator.

Ensure the zero parameter constructor is suitable for use in dependency injection.

Ensure constructors do not over initialise to prevent subclasses from changing implementation details.

Virtual Calls

Avoid calling virtual members from constructors as the behaviour is unpredictable.

Static Constructors


Avoid initialising static members within static constructors.

Wherever possible initialise static members on first use.

Asynchronous Code

Use the await and async keywords when creating asynchronous code.

Prefix “Async” onto all methods that need to be awaited.

Do not prefix “Async” onto any method that cannot be awaited, even if the method contains asynchronous code.

When blocking methods are part of a Portable Class Library and cannot use the await and async keywords, use extension methods with the “Async” prefix to provide asynchronous alternatives for platforms that support it.

When to use Properties, Methods, and Extension Methods


Use a property if:

  1. The functionality behaves like a field.
  2. Is a logical attribute of the type.
  3. Is unlikely to throw exceptions.
  4. The contained code has minimum value when debugging.
  5. Does not have a dependency on the order being set.

Never use a property if:

  1. A get implementation is not provided.


Use a method if:

  1. The operation is a conversion.
  2. There is an observable side-effect from the call.
  3. The order of execution is important.
  4. The method may not return.
  5. The method may run code asynchronously.
  6. The result should be cached for reuse within the calling method for performance.

Do not use a method if:

  1. The return value is a collection that remains linked to the instance.

Extension Methods

Use an extension method if:

  1. The operation needs extend a sealed type.
  2. The operation needs to apply to anonymous types.
  3. The operation needs to apply to general IEnumerable types.
  4. Base functionality is provided for an Interface.

Do not use extension methods if:

  1. The behaviour may want to be specialised by a base class.

Place extension methods that form part of a classes or interfaces core API, or platform specific extensions to the core API, in the same namespace as the class, even if it is provided by another assembly.

Always place extension methods that extend core .NET types outside of the System.Collections namespace in a namespace ending in “.Extensions” to avoid littering the namespace of these core objects.

Method Arguments

Name method arguments with names that inform the caller of the intended purpose, not of its internal use.

When a Boolean argument is used as a flag to change fundamental functionality of a method, always call it using the “name: true” style.

Use Boolean arguments called with the “name: true” instead of two member enumerators for all methods, unless the method extends an API where an existing enumerator is better suited.


Catching Exceptions

Only catch exceptions of specific types if the error message being returned will be specialised for the type.

Catch the generic Exception type to isolate calls from the calling code.

A user must be informed of an exception with an error or warning message.

An error or warning message can be omitted if an exception is caught and ignored to avoid a known framework or platform issue and the issue is commented within the catch block.

Do not catch the general Exception type and hide its value from the user.

Throwing Exceptions

Use the existing Exception types to throw your own exceptions.

Only create Exception subclasses when they are to be used multiple times within a library.

LINQ, for, and foreach.

Use LINQ for queries to external data sources.

Use LINQ for queries over in memory data that is designed for use as a dictionary or database.

Use foreach () for iterating over any IEnumerable.

Use var as the item type for the foreach() loop whenever the IEnumerable implements IEnumerable<T>.

Use for() when the iteration is controlled by a numeric block.

Use for() to walk hierarchies.

Use for() or while() when the iteration is controlled by a non-numeric exit condition.

Use do { } while () only where it reduces code compared to a for() or while().


Member Comments

Every public member or class must be commented with an XML comment.

Every protected method and property must be commented.

The comment must be written to explain why somebody would want to invoke the code.

The comment must not be a substitute for a bad member name.

The comment should not attempt to list all exceptions that could be thrown but should exceptions of special Exception subclasses thrown directly by the code.

Do not comment private or internal methods that have obvious use.

Do not comment event handlers unless their implementation is non-obvious.

Ensure member comments are suitable for extraction into API documentation.

Do not repeat the XML comment for overridden methods if the comment has nothing new to add to the base type comment.

Do not repeat the XML comment for the implementation of a member for an interface if the comment has nothing new to add to the interface member comment.

Code Block Comments

Comment code with headers within blocks that perform multiple tasks discrete as part of its implementation.

Comment code blocks that cannot be understood by the code alone.

Comment code wherever a special or magic value is used.

Comment code when a condition in a control block could be misunderstood.

Comment Styles

Use /// Comments when commenting members or classes.

Use // Comments when commenting code blocks or statements

Use /* */ comments only if the comment has to be placed in the middle of a line of code or within a Razor syntax document.

Special Developer Comments

Always mark comments that are reminders of code to fix with “TODO” in upper case followed by a message.  This allows all TODO items to be found and completed or before the release of any solution.

If the last statement of a non-void method is not a return statement, place the lint style comment “/* NOTREACHED */ at the bottom of the method so developers know to maintain this when editing the code.

Braces and Brackets

Brace Positioning

Place opening braces for classes, namespaces, and members on new lines.

Place opening braces for code blocks such as if, for, foreach, while, do, and switch on the same line as the code control statement.

Place all closing braces on new lines.

Place both the opening and closing braces for automatic properties on the same line as the property name e.g. public int MyProperty { get; set; }

Place both the opening and closing braces for anonymous types used as property bags on the same line e.g. Html.Link(“Test”, new { this = “that” })

Place else and else if statements on the same line as the closing brace and keep the next opening brace on the same line too.

Bracket Positioning

Place a space between keywords such as if, for, foreach, and while, and the opening bracket.

Do not place a space between a method name and its opening bracket.

Keep the closing bracket on the same line as the opening bracket in the argument list is small.

If the argument list for a method call is long: keep the opening bracket on the same line as the method name, place each argument on a separate line ending with a comma, and place the closing bracket on a new line.

Flexible API Documentation with ApiDoc (http://apidoc.codeplex.com)

What is ApiDoc

ApiDoc is a tool for creating a set of technical API documents to help developers using your libraries or classes.

As a .NET developer you’ve probably used the MSDN references for various .NET classes on a regular basis.  But how do you make the same style of documentation available to your team or users of your libraries from other companies?

This article shows you how to use ApiDoc to generate MSDN style API documentation for your own classes, in a way that is easy to customise, integrate with existing websites, and can have your own branding applied.

Getting ApiDoc

To get started you need to download ApiDoc.  You can do this from codeplex: apidoc.codeplex.com.

Codeplex Download ApiDoc

The download includes full source code for ApiDoc and a fully functional demo website you can use and customise.  We’ll use this demo website in this article so be sure to download and extract the .zip file to a location you can edit it.

In the future if you want to you could add ApiDoc to your existing ASP.NET site or application via NuGet instead (see ApiDoc and ApiDoc.Mvc4).

NuGet ApiDoc

Getting Started

Once you’ve downloaded and extracted the .zip file open the “ApiDoc.sln” in Visual Studio.

ApiDoc - open solution

To run the demo site make sure the ApiMvcApplication is set as the start-up application and press F5.

Demo Site

By default the site is configured to show the documentation for the ApiDoc library itself.  Have a browse around and you will be able to browse through around the documentation jumping from class to class as easy as you can with the MSDN.

Documenting your own Code

The next step is to get the demo site working with your own code.  Close the web browser and stop debugging the program so you return to Visual Studio.

Under the ApiMvcApplication expand the Content folder and you will find an “AssembliesToDocument” folder:


Using explorer to find the .dll files and associated .xml files for your application and drag and drop them into AssembliesToDocument so they show in the list.

Now open HomeController.cs under Controllers and you’ll see the following:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;

namespace ApiMvcApplication.Controllers
    public class HomeController : Controller
        public ActionResult Index()
            return RedirectToAction("Namespace", "ApiDocumentation", new { id = "ApiDoc" });

The important part here is line 13. You can modify it to match the namespace you want to be your start page by changing id = “ApiDoc” to your own namespace e.g.:

            return RedirectToAction("Namespace", "ApiDocumentation", new { id = "MyApplication" });

You may prefer to open to the index of an assembly:

            return RedirectToAction("Assembly", "ApiDocumentation", new { id = "MyClassLibrary1" });

or directly to your main class:

            return RedirectToAction("Type", "ApiDocumentation", new { id = "MyApplication.MyMainClass" });

Hit F5 again and this time you will see the documentation for your own code rather than for ApiDoc itself.  You can navigate this code exactly as you could before.

Customising the Web Pages

The demo site is a standard ASP.NET MVC 4 site using C# and the razor syntax.  This means if you know how to create standard web applications in this environment customising the site to meet your needs will be very easy.

The views can be found in the default place under Views/ApiDocumentation.  Here you can change the order of documented items, apply custom scripts, or apply your own logic to the API or documentation as you display it.

To customise the style of the site you can edit “Content/Site.css”.  The site uses the standard classes from the MVC project templates, but you can customise specific divs in the views using their member names e.g. “description”, “classes”, or “properties”.

The ApiDocumentation controller can be found under “Controllers/ApiDocumentation.cs” and has a separate action for each member type making it easy to customise or extend.

To make the demo site look nice I’ve used the SyntaxHighlighter scripts to format the code syntax examples in the same way code samples are highlighted on this blog.  If you are customising the demo site for your own purposes you just need to reference the code within a pre block as follows to have the syntax highlighting take place:

    <pre class="brush: csharp">

You should now know everything you need to know to document your own libraries in your own style. If you’d like a link to your library documentation added to the ApiDoc project on Codeplex drop me an email with the link and brief description so I can add it to the site.

Getting Involved

ApiDoc is available under a BSD style license for everyone who needs to generate custom Api Documentation. Its currently Beta software and may contain a few issues which should be pretty easy to sort out and will be fixed as new versions of the library are released. If you want to get involved with the project itself please visit the Codeplex page where all feedback, bug reports, and suggestions are welcome through the discussion pages, and anyone wanting to contribute directly to the project will be invited to do so.

Async extension method wrappers

Asynchronous APIs are becoming more popular thanks in part to the focus on asynchronous user interface design requirements on platforms such as Windows Store Applications for Windows 8 and Windows RT.

This attempt to change the way developers think about long or unpredictable operations is welcome and necessary as databases and files slowly migrate into the cloud.

Unfortunately System.Threading.Tasks and the async and await keywords are not available inside portable class libraries or some of the platforms we target with the Ambidect technology.  We could choose to use an alternative style of asynchronous API, such as call backs, but these are starting to look dated, and require the developer to do a lot more boilerplate work to use.

At this point you may be tempted to give up and provide only an blocking synchronous API and require the developer to manage their own threads on each platform that insists on asynchronous calls; but as I touched on in my previous post about the repository API, we felt it was a much better idea to provide an async API and did so using extension methods.

This technique can be used to wrap almost any synchronous API; but I have to stress at this stage it should only be used if the platform or platforms you are working on do not have a usable native asynchronous API.

For our example we’ll work with the Find method of the IRepository<> interface, but the principles here will work with any synchronous call that needs to be wrapped.

The first thing we need to do is create class to host our extension methods:

using System;
using System.Threading.Tasks;

namespace Mvpc
    public static class IRepositoryExensions_Async
        // TODO this is where to put your extension method code.

If you are not familiar with extension methods, the reason we mark the class as static is because its a requirement of the extension method support of the compiler.  The name of the class can be anything you want, but you can see that I use a simple convention that makes it clear to anybody using the library that the class contains extension methods, so is of no interest to be used directly.

You will note that the class here has been put into the Mvpc namespace to go alongside the class we are wrapping.  When using extension methods that extend the API with asynchronous members this is my recommended approach.  It stops the developer of the class worrying about how the async methods are provided, and intilisense will include them in the list of available class members when working on a platform that supports our asynchronous API.

In cases where the extension methods provide utility functions rather than a core API for a class, it is good practice to keep your extension methods in a separate namespace, e.g. Mvpc.Extensions.  This stops the intilisense list being over-populated with extension methods that are not relevant to the code at hand.  When extending one of the CLRs core types such as object or string I always insist that the extension method goes into a namespace ending in “Extensions” such as Mvpc.Extensions that the developer has to explicitly opt into.  This not only helps keeps the intilisense clean, but also stops accidental dependencies on the specific extension methods creaping into code blocks where they don’t belong.

Now we have a class setup and have decided the right namespace for the class lets add an extension method.  An extension method is exactly the same as a normal static method, except its first parameter is prefixed with the “this” keyword.  This instruction tells the compiler that it can effectively rewrite the extension method call into a static method call, while allowing the developer using the extension method to use a more natural calling convention.  For example instead of having to call:

var repository = ...;
var key = Guid.NewGuid();
IRepositoryBaseExtensions_Async.FindAsync(repository, key);

We can use the much more readable:

var repository = ...;
var key = Guid.NewGuid();

Lets have a look at the code for the FindAsync() extension method itself now:

        public async static Task FindAsync(this IRepository repository, params Guid[] keys)
            var task = System.Threading.Tasks.Task.Factory.StartNew(() =>
                var ret = repository.Find(keys);
                return ret;

            return await task;

The first thing you will note is that we suffix the name of the method with “Async” I find this a very good convention to follow for any method that provides an async API that can have “await” applied to it. It helps the person using the method remember that at some point they will likely want to await on the result.

If you are unfamiliar with the async and await keywords I suggest you have a look at them in the MSDN documentation sufficient to say here that you use async to mark a method as containing asynchronous code, and await to safely wait for the result of an async method before continuing.

As well as the async keyword you will notice the method is also marked as static as it will operate without a class instance and the first parameter is prefixed with “this” keyword to enable the extension method style shorthand call to the method.  We can still call the static method directly if we want, but without the “this” keyword the extension method syntax would not be available when calling the method.

Inside the method we create a new Task with the right return type and use an lambda expression to perform a call to the synchronous API we are wrapping.  This code will be executed in a separate thread before returning its result.  Exactly when the code pauses to wait for the result depends on how we use await when calling the extension method.

More often that not when we will want the code to wait for the value before continuing so we will use await directly on the async call as follows:

var repository = ...;
var key = Guid.NewGuid();
var item = await repository.FindAsync(key);

In this post we’ve wrapped a synchronous call to a repository function with an async extension method, but you can use the technique whenever you find you need to make regular asynchronous calls to a class that couldn’t be built with an asynchronous API, or to which you do not have access to the source to extend with a native asynchronous API yourself.

Mvpc – The Model Layer in more Detail

Overview of the Model Layer

The Mvpc design pattern is based on four layers:

  1. Model
  2. View
  3. Presenter
  4. Command

This article is part of a series covering each layer of the Mvpc design pattern in detail.  This post covers the Model layer.

The model layer itself takes on four core responsibilities that are exclusive to itself:

  1. The representation of data as models.
  2. The storage and retrieval of data into models via repositories.
  3. The conversion of models to and from different shapes.
  4. The mark-up of metadata against models to provide hints to users of a model.

The representation of data as models

When designing Mvpc we took the decision to define a model in as broad terms as possible.  We wanted to make sure anything a programmer would generally call data could be treated as a model.  For this reason we decided that a model would not be based on any existing framework or data modelling tool, and would not require the sub classing of a specific base type or implementation of an specific interface.  Instead we decided that a model for the framework would be a property bag; that is to say a collection of name and value pairs, where the type of the value is usually known.  In practice this means developers are able to see simple code classes as models, as well as more complex data structures.

Using a property bag as a model gives us a lot of flexibility; and means we are compatabile with models generated by almost any existing or future data abstraction or framework such as datasets, the entity framework, POCO, NHibinate,, IDataReader, IDictionary<,>, properties defined as simple code classes and structs, and anything else you can imagine.

Using this technique means that the Mvpc pattern and related libraries do not lock a developer into a particular choice of data abstraction or database engine; but allows developers to continue to use the data abstraction layers they are already used to and familiar with.

The storage and retrieval of data into models via repositories

Once we had decided upon a representation of a model, we needed a way to keep the developers choice of data abstraction separate to the model and the use of a model at point of consumption in a command, view, or code block.  We decided to do that by abstracting the retrieval and storage of data through a simple, well defined repository API (covered in this section), and by allowing a model to change shape to better fit the context of its use (covered in the next section).

The repository is completely responsible for the creation, storage, and retrieval of models.  It is responsible work directly with a data store, and to return data in the shape most applicable for the executing code to use it.

Unlike for the model itself we do insist on a simple base interface for a repository: IReposiitoryBase.

The IRepositoryBase interface exposes type unsafe methods for the four basic data management operations:

  1. Find
  2. Create
  3. Update
  4. Delete

In addition it supports two key query methods for working with ad-hoc queries:

  1. FindAll
  2. FindFirstOrDefault

Then based on over a decades experience of working with data abstraction models and data processing applications we also decided to build into the base two specific “predefined” query methods that would serve a similar purpose to server side views in an SQL database.  These methods are:

  1. GetDisplayList
  2. GetSelectionList

Both of these methods accept an optional query name as a parameter, so the number of queries then can support is unlimited; and importantly the return type is not expected to be the same type returned by the data operations and ad-hoc query methods, and will usually contain data that is not directly stored in the model.  For example a repository for a Sales Order will return or take a SalesOrder model or IEnumerable<SalesOrder> for the data operations but depending on the query name you pass in could return a list of sales order details including a customer names and addresses that do not make up part of the model; or a summed result of total sales broken down by month and year.  For this reason the query methods are both defined as simply returning a System.Collections.IEnumerable to support any collection type at all.

As many of you will know there are pros and cons to making a repository completely type-safe, or independent of type.  We won’t go into them in detail here, but it can generally be summarised that type safe repositories as easy for an end user to work with, and for developers to specialise, but type unsafe repositories can make code more reusable and cope with types that didn’t exist at compile time.

In the end we decided that neither approach alone met our design goals completely so we decided to provide both APIs and let the methods using the repository use the one it found most useful.

Therefore we provide an interface IRepositoryBase that exposes only type unsafe versions of methods.  These are easily recognisable in the Mvpc libraries as their names all end in “Untyped” e.g.:

object CreateUntyped()
bool UpdateUntyped(object)

We then provide an interface IRepository<T> that exposes only type safe versions of the methods type safe to the generic parameter T.  These are generally the more convienent methods to use, so we’ve left these with the simple names with no suffix, e.g.:

T Create()
bool Update(T)

Its worth just pointing out at this point that as the GetDisplayList() and GetSelectionList() methods do not return items match the repositories model type, they are included in IRepositoryBase and do not have explicitly named Untyped() versions.

The final piece in the dual API design was to make it possible for developer consuming a repository to choose either API, but for the developer creating the repository implement only a single API.

To achieve this we introduced an abstract base class RepositoryBase that by default linked the “Untyped” methods to calls to the type safe methods so programmers could write type safe repositories and have the unsafe APIs automatically provided.

While that approach worked well for people writing a specific repository, it explicitly links a repository implementation to a realised class at compile time as not all platforms can support dynamic code execution or the System.Reflection.Emit namespace.

We still didn’t feel this was good enough, and so we provided a set of utility methods that allowed a repository designer to write a repository that only found out its model type at run time, but could still handle the type safe calls by exposing a proxy class to allow those calls to be made.

Because of this we were then able to bundle a number of commonly used options for repositories into the libraries creating a powerful starting point for applications using the libraries.  To avoid bloat and unwanted references to 3rd party libraries, we made each available as a separate package on Nuget so you only need to reference the types you want to use in your application or module.

For each standard repository types we provided two sets of classes:

  1. A type safe generic base class that provides full implementation of the API and allows extension of the API by a developer via subclassing.
  2. A fully dynamic repository that will adapt itself to any model type provided at run time.

The first option is self explanatory and works through normal sub classing and overriding of methods.  The second option however allows us to do particularly interesting things like: rapid prototying repositories for any Entity Framework .edmx file; switching or adding optional support for a new database engine or web service without having to redevelop or even recompile any of the existing code; or providing Json wrappers around any other repository type.

Here is a list of the supported data abstractions that have full support for repositories in the reference Mvpc libraries:

  1. Entity Framwork 5
  2. Entity Framework 4
  3. ADO.NET (System.Data)
  4. POCO
  5. Code Classes via System.Reflection
  6. XML files
  7. JSON Web Services
  8. JSON Database (Mvpc.JsonDatabase – a local database that can work on any device and uses json to store its data)
  9. JsonRepository webservice (a web service that will wrap any other repository and provide secure access to it via a Json based web service).

The JsonRepository webservice is an important option for us to include as not all data abstraction frameworks work on all platforms.  For example ADO.NET or the Microsoft Entity Framework can’t be accessed directly from Windows Store applications or Windows Phones.  Rather than saying “you can’t support these platforms if you use EF5 for data abstraction” we instead provide a built in wrapper that means you can.  And because of the simple design the same wrapper can be used if you build a repository that uses NHibinate or other simpler tool.

The final note to make about the repository API is that when we designed it we always wanted to support both synchronous and asynchronous operation.  Therefore on the platforms that support asynchronous events we have provided an Async version of each of the typed and untyped repository APIs via extension methods. e.g.:

T CreateAsync()
bool UpdateAsync(T)
object CreateUntypedAsync()
bool UpdateUntypedAsync(object)

This means if you are building a custom GUI component to enhance a platform you can use the Async() apis to keep your user interface responsive ,while carrying out repository access that might be accessing remote servers or other potentially slow resources.

As the Async API are provided via extension methods repository designers do not need to implement their own async versions of the repository and can usually ignore the fact their repository will every be accessed asynchronously.  This keeps back with our design principle that a repository should be designed as if there was a single API, but should allow use by the right API for the task at hand.

The Async API is completely compatible with the C# 5 async and await keywords, so they couldn’t be easier to use.  As these keywords are still new to a lot of people we’ll cover them off in a future post.

Repositories are managed via the RepositoryFactory (which implements IRepositoryFactory and is determined via dependency injection) which also manages their connection strings.  This means again that both the user of a repository, and the designer of the repository, do not need to worry about how the connection to a specific database or data store is configured, but can leave that up to the factory to look after this on their behalf.

The conversion of models to and from different shapes

Within a repository it is not unusual to need to take data that’s represented in one class, and convert it into another class.  To give a concrete example, the data may be loaded by the entity framework into a proxy class, but we want to convert that into our more portable model definition which is a plain old code object.

To do this we provide a Model Converter using an IModelConverter interface.  This converter is capable of receiving a model in any format (a Dictionary, a code class, etc) and mapping it across to a new format or type. Later when we need it we can use the same converter to to provide the reverse conversion.

As well as the IModelConverter interface a concrete default implementation is provided called simply ModelConverter.  This default implementation will be used unless an alterative is supplied using dependency injection.

The model converter is most useful within repositories, but is also used elsewhere in the framework, and can be used in your own code.

If you had a method that could operate on any class so long as it had a Boolean “Live” property you can define that “shape” for the model, and use the model converter to convert any compatible model into the shape for you to use, and then back again.

The command layer for example uses the model converter like this when working out how to supply views or models into a command in the compatible type for the command to operate on.  We’ll cover the command layer in detail in the fourth post in this series.

The model converter is also responsible for changing the shape of a model between formats.  For example if we receive a Json representation of a model from a web service the model converter can turn that into a class for us.  When the time comes to pass it back over the web service, we can simply convert it back.  This is actually exactly how the JsonRepository webservice repository works to extend repository support to platforms it wouldn’t otherwise reach.

Because of the shape changing ability of models, and the flexibility of the built in repositories, we are able to use the Rapid Prototyping techniques we’ve pioneered to generate models in a portable shape from Entity Framwork .edmx files or other data sources, to make sure you never have duplicated code that needs to be maintained.  We’ll have a series of articles on using Rapid Prototyping with Mvpc in the future.

The mark-up of metadata against models to provide hints to users of a model

For most purposes a model that simply contains data is all we need.  But there are times when a name, value, and type don’t quite go far enough.  The most obvious example is when showing data on screen.  If a property in a model represents a foreign key linking relational data to another repository, do we really want to force the GUI layer for each platform to have to customise the GUI just to provide this link as a selection list or combobox?  Wouldn’t it be better to mark the property with the repository needed for a selection list, and then let the GUI sort itself out based on this information?

Metadata is used to identify primary keys, display labels, repositories for foreign keys, required fields, special formatting requirements, and a host of other useful things.

In the Mvpc libraries the metadata API consists of an IModelMetadata interface, along with a concrete implementation that has some hard coded defaults based on attributes and recommended Microsoft naming conventions.  This can be overridden using dependency injection for any individual model, or for all models.

A good API shouldn’t require sub classing or overriding too often, so the default implementation also provides the GuiHintAttribute that can be used to mark-up any property of a model to change the metadata for a property without having to create our own IModelMetadata classes.  These are simple to use and would often look like:

            Required = true
        public string Name { get; set; }

            Required = true,
            Repository = typeof(Customers.IRepository),
            UseMultiColumnDropDown = true
        public Guid CustomerFK { get; set; }

These attributes can either be put directly on a model, or in a separate class linked with the MetadataForAttribute.

Personally I have a strong preference for using the MetadataForAttribute as it not only keeps the metadata separate to the model definition, but also allows us to use the same metadata for multiple models if required. For example here is the code for the most common case where the same metadata file is shared between a model, and its repositories, so the metadata applies both when editing the model, and when displaying a the results of GetDisplayList(), which you will recall aren’t actually instances of the model itself:

    public class Metadata
            Required = true
        public object Name { get; set; }

            Required = true,
            Repository = typeof(Customers.IRepository),
            UseMultiColumnDropDown = true
        public object CustomerFK { get; set; }

            ListGroupLevel = 1
        public object Customer { get; set; }

Its worth noting in the above code that the return type of all the properties in the metadata class is “object”.  This is by convention when writing metadata classes for Mvpc because the model class itself already exposes the type so repeating it here would only increase our maintenance costs or at the very least be misleading should we choose to change the type of one of the properties in the future.

We could set the return type of properties in metadata only classes to anything as they are never actually used, and the classes are never instantiated.  Setting them to anything except the real type, or object, could mislead people reading your code however, so its considered best good practice to follow the DRY (don’t repeat yourself) principle here and always use “object”.


When designing the Model layer of the Mvpc design pattern and its commercially available reference library we wanted to make sure we didn’t restrict developers from choosing any of the very good data abstraction platforms already available.  We did this by choosing a very simple definition of a model as a property bag.

To provide maximum flexibility on how the data was then used we allowed the data to change shape and pass between web services, databases, files, and commands in the shape that best suited the code being written in each of those areas, and in a way seamless to the developer consuming the model.

A flexible repository API with a lot of standard implementations and full rapid prototyping support allows us to expose a small and standard API for data operations ensuing the code we write never becomes dependent on a particular database or data storage engine or style.

Finally by allow metadata to be attached to models we are able to give hints to the GUI and other code on how to make the most of the model; allowing us to minimise the platform specific code needed for a model to be as small as possible.  When we need to make changes to model metadata in the future we can carry out the change in a single place and have that change reflected across all platforms.

Hope this detailed overview has given you a good understanding of the model layer in the Mvpc design pattern and libraries.  The next post in the series should be out next week and will look at the view layer in similar detail.