Simon Ince's Blog : WCSF

Do you need web client development help?

simonince — Tue, 21 Jul 2009 15:01:00 GMT

Then tell us what you need! Blaine has blogged a link to a survey that patterns & practices will use to help them understand what challenges that are affecting you the most... so that they can choose the right areas to focus effort in providing guidance.

If you’ve got a couple of minutes spare head over to the survey...

What tasks or areas are difficult? What consumes the most time? What is it that causes you post-deployment headaches? What parts of the process are tricky? What don't you do because it is hard?

Are you using the WCSF?

simonince — Fri, 05 Dec 2008 17:10:00 GMT

Have you been using the Web Client Software Factory? Or have you tried it and not adopted it? Or have you used some of the bundle content but not the whole factory?

Michael Puleio has just started a thread on codeplex requesting feedback on who is using the factory, and talks about it briefly in this post.

Combine that with Blaine’s WCSF Roadmap post and you can see p&p are already thinking about the next version of guidance for ASP.NET applications. Now is the chance to comment on what really matters to you, and what would help you in your day-to-day job.

WCSF Application Architecture 7: Remote Logic with WCF Services

simonince — Fri, 18 Jul 2008 18:55:00 GMT

This article is part of a series;

· WCSF Application Architecture 1: Introduction

· WCSF Application Architecture 2: Application Controller

· WCSF Application Architecture 3: Model View Presenter

· WCSF Application Architecture 4: Environment Abstraction

· WCSF Application Architecture 5: Defining Modules

· WCSF Application Architecture 6: Structuring Modules

Unfortunately it is also the worst named post in the series J

Introduction

It is a common requirement for customers to want to split web applications across physically separate tiers, usually using some kind of services technology. This post discusses some approaches to this using the Web Client Software Factory.

Although I focus on using WCF services, many of the concepts apply to ASMX and other technologies too – I have just chosen WCF as I believe it to be the best way to write services in the current .NET Framework environment.

* Note: Chances are I’m going to use the term Web Services a lot in this post. What I really mean when I say that is any kind of remote service – pretty much anything that can be written with WCF, for example.

Food for Thought

So first things first – let’s clear up some common myths.

1: SOA != Services

Just because your application uses Web Services (or any other kind of remote service), that doesn’t make it Service Oriented. It could still be just an app that uses Web Services. The current Wikipedia definition of SOA starts with a nice succinct statement about this;

“(SOA) is ... where functionality is grouped around business processes and packaged as interoperable services ... SOA separates functions into ... services ... which are made accessible over a network in order that they can be combined and reused in the production of business applications”.

In other words, if you’re writing a Web Service and Web Application as an inextricably linked pair that make up a single system, chances are you’re not doing SOA. SOA is an Enterprise Architecture, not an Application Architecture (although some applications will be built on the Enterprise Architecture by aggregating and reusing business services, and hence some apps are validly referred to as Service Oriented).

What this means to me is two things

1. Be pragmatic about what rules you follow when you are writing a completely isolated internal application.

2. Ask yourself this: “Why are we using a Web Service?” If your answer is “Because our company policy is that all new apps must be Service Oriented” (or something similar) I would recommend stepping back, and thinking deeply for a short while. How is adding a Web Service making your application Service Oriented? Is it really adding any value? If so, great – there are many valid reasons... but make sure you know what they are!

2: Services cost performance

Using a remote service is expensive (in terms of processing time, for example). If you previously had a method call that looked like this;

View.Orders = myBusinessLogic.GetOrders(user, startDate, endDate);

... and you move the implementation of GetOrders to be a remote Web Service, you will notice a significant performance degradation. Raw performance and scalability are often at odds like this! Suddenly we must serialize user information and dates, locate the remote service and open a channel, pass the data across a potentially unreliable network, spin up a service instance, deserialize the information, perform the business logic call that used to exist on the client, serialize the results, pass them back across the network, deserialize the results and turn them into a .NET list, and finally close the channel to the remote service. Phew. Now all that might be pretty fast in .NET, but it will be slower than an in-process method call.

Having said that, if the logic you must execute is expensive itself, you may find that removing load from the client Web Server and scaling it out to another physical tier improves the scalability of your system. I’m not saying don’t use services here – I just want you to be realistic about it!

3: RPC != Messaging

Because services add overheads, it is important to adopt a message exchange approach rather than a remote procedure call approach. What does this mean? Basically it comes down to two things;

1. Granularity. RPC consists of chatty, frequent calls between client and service, very quickly making it difficult to scale your system. When you think RPC, think of many systems written with Remoting or Java’s RMI. Message exchanges are courser grained and minimise the amount of calls and proportion of overheads involved.

2. Programming Model. I tend to find that RPC encourages the sharing of concepts internal to a service with the outside world. Use a message oriented approach makes you think about defining the contracts, abstracting where necessary, and encapsulating behaviour appropriately. Watch for a future post on the Service Interface pattern when I get a chance!

Candidate Architectures

So now that we’ve thought a little about what we want to avoid, let’s see a couple of approaches and discuss their characteristics.

1: Baseline

First up is our baseline architecture; this is what future examples will evolve from, and represents a basic WCSF application (ignoring splits across modules) without any kind of service layer.

Note that I’ve decided to expose my business logic here using a WCSF application service (not a web service). This communicates with my “model” (basically the business logic), which in turns talks to various data access classes (e.g. DbAccess). I hope that’s pretty straightforward.

2: Split Tiers

I nearly named this “RPC approach” because I feel that it encourages an RPC style of programming. Components above the dotted line are in my WCSF Web Application, and those below it are in the WCF Web Service.

What we have done here is just move the logic into a Web Service, and then change the WCSF application service that previously exposed business logic to purely act as a facade to the remote Web Service – in other words, it is a Service Agent or Service Proxy. This is a key concept – a Web Service is a resource, so if you are communicating with a Web Service directly in a class, you’re writing a resource (or data) access component.

The problem with this approach, in my opinion, is that this encourages developers to just call methods as though they were local to the web application, potentially leading to an RPC style system with very chatty communications and a serious scalability problem. Often people don’t realise that they are effectively writing an application that has no business logic layer (the Web Application)!! This is obviously contrary to well understood wisdom nowadays, and looking at the diagram above, I hope you see how unnatural it looks.

This lack of separation can also lead to changes in the service contracts affecting the UI. This is by no means ideal.

3: Remote Services

My preferred approach is shown below;

Here you can see that our missing logic layer has made a triumphant return! This might seem subtle but I think it completely changes class responsibilities and how your developers perceive the system. The logic in the Web Application is responsible for deciding when to go to a web service, or when to use a local cache, how to co-ordinate calls between different resources (you might have multiple web services!), when to enforce security or other policy, and so on. This then leaves your Resource Access layer able to dedicate itself to providing a real shield from the inner workings of the service calls.

As I’m sure regular readers have noticed, I’m a big fan of talking in concrete examples, so let’s see some (simplified) code that demonstrates this approach. Firstly, the Presenter and implied View;

public class MyPresenter<IMyView>

{

private ILogicService _logicService;

public MyPresenter([ServiceDependency] ILogicService logicService)

{

_logicService = logicService;

}

public void OnRetrieveOrders()

{

List<OrderEntity> results =

_logicService.FetchOpenOrdersForCurrentUser(

View.StartDate, View.EndDate);

View.Orders = results;

}

The key here is that the presenter is using a WCSF service (badly named as ILogicService) to fetch orders for display to the user. These orders are represented by an “OrderEntity” entity. Next, let’s see an example of an ILogicService implementation;

public class LogicService : ILogicService

{

private IAuthenticationService _authenticationService;

private IEntityTranslatorService _entityTranslatorService;

public LogicService(

[ServiceDependency] IAuthenticationService

authenticationService,

[ServiceDependency] IEntityTranslatorService

entityTranslatorService)

{

_authenticationService = authenticationService;

_entityTranslatorService = entityTranslatorService;

}

public List<OrderEntity> FetchOpenOrdersForCurrentUser(

DateTime startDate,

DateTime endDate)

{

OrderServiceProxy proxy = null;

try

{

proxy = new OrderServiceProxy();

proxy.Open();

proxy.LogOnService(CERTIFICATE_DETAILS);

string orderStatusCode =

proxy.GetOrderStatusCode(OrderStatus.Open);

List<Order> orders = proxy.GetOrders(

_authenticationService.CurrentUserName,

orderStatusCode,

startDate,

endDate);

List<OrderEntity> results =

_entityTranslatorService.Translate<Order, OrderEntity>(orders);

proxy.Close();

return results;

}

catch (Exception)

{

if (proxy != null)

proxy.Abort();

throw;

}

There are a few really important points to make here;

1. I have chosen to abstract environmental issues, such as authentication, away into a framework service. See my previous post on Environment Abstraction for more information on this.

2. All the management of the interaction with the service proxy is kept out of the Presenter, and instead is handled by our WCSF application service.

3. I am performing Entity Translation between the “Order” and “OrderEntity” objects. The former is actually part of the definition of the Order Service’s Service Contract, in that it defines how the remote service is communicated with. The latter is a Business Entity defined by my WCSF module. Therefore it is important that I expose the Business Entity not the proxy communication entity further up my architecture.

4. The service performs some limited Orchestration – it calls a number of methods on the service to achieve what is seen by the Presenter as a single business operation. Obviously I would prefer a very course grained service design, but I’ve done this to illustrate that this is the right place to perform any required orchestration (potentially across multiple services) and workflow.

5. The disposal of the proxy is done correctly. A “using” block is not the best way to deal with WCF proxies – see Avoiding Problems with the Using Statement.

6. This is also the right place for rich error handling, publishing, and compensation – please don’t follow my poor example in this respect J

7. I haven’t used the rich implementation of the Service Interface pattern I would usually, because constructing the messages would increase the volume of sample code and detract from the point. I’ll probably post about Service Interfaces soon, so watch this space!

The final important point is that this separation of business logic, resource access, entity translation, etc is likely to be repeated by the Order Service.

Potential Gotchas

When using WCF proxies there are a number of things worth knowing about. The first is the best way to use a “using” block, mentioned above.

Secondly, remember that a WCSF service is a singleton – so if you cache the WCF proxy you will be using the same one for every call, no matter which end user is browsing your site. No probs... oh, hang on! But what if you’re using a session-full binding? That would mean all your WCF calls would be using the same session, no matter which end user the call was for! This could certainly be a problem – so be very careful about this.

Thirdly, if you are caching your WCF proxy remember that a faulted proxy cannot be used again. So if your backend service fails and then comes back up, and you’re caching the proxy forever and for every user, your web application will be unusable until you cause it to flush the cache (e.g. by restarting the App Pool). The correct way to handle a faulted proxy is by adding the following code when creating it;

proxy = new OrderServiceProxy();

((IOrderServiceChannel)proxy).Faulted +=

new EventHandler(OrderService_Faulted);

In the event handler you can then react in some way – perhaps by Aborting the proxy and replacing it with a fresh one. This is obviously pretty academic for my example code above, but if you are caching proxies, consider this carefully. Also, if you don’t have a business logic layer, you might find it more difficult to deal with this kind of situation!

Finally, I’ve used the class generated by “Add Service Reference” in Visual Studio. It is actually pretty slow to new up one of these for every business operation when compared to using a cached ChannelFactory. In .NET 3.5 this is less true, but I’d recommend this post comparing the two approaches.

Summary

There are many issues I’ve not covered here – security architecture, for example (Trusted Subsystem versus Delegation), and many, many, many, more. But I hope this has gotten you started on how to structure your code, freeing you up to investigate some of the more subtle complexities. Good luck!

And finally... a Summary of Summaries

This is the last post in my series on Web Client Software Factory Application Architecture. That doesn’t mean I’ll not post about WCSF again of course, just that we have now covered plenty, from the basic patterns involved to some more “fluffy” concepts of designing modules or service layers. I hate television series that have no end (wow, it is seriously difficult not to name and shame here, that’s how much I hate it!), so I’ll take my own advice and finish on a high J

Remember how much I haven’t covered – there is plenty of information out there, from the WCSF community site, landing page, other bloggers, obviously in the factory documentation, and so on. And if you’re blogging about it, do let me know!

WCSF Application Architecture 6: Structuring Modules

simonince — Fri, 04 Jul 2008 13:13:00 GMT

This article is part of a series;

· WCSF Application Architecture 1: Introduction

· WCSF Application Architecture 2: Application Controller

· WCSF Application Architecture 3: Model View Presenter

· WCSF Application Architecture 4: Environment Abstraction

· WCSF Application Architecture 5: Defining Modules

Introduction

This post is intended to address some common scenarios when using the Web Client Software Factory, in particular relating to how modules should be structured internally, and how they should relate to each other... as with all my other posts, this is based on what I’ve done and what I’ve seen others do – I’m sure there are other ways out there, so please feel free to chip in if you have something to say, suggest, or disagree with.

I’m going to present architectural candidates for you to consider, and discuss why you might choose to use them, which I hope should give you ideas about how they might apply to your situation.

So, get comfortable, and read on!

For consistency with my previous post in this series, I will assume that initially we have some business modules (Customers, Accounts, and Orders) and a foundation module (Infrastructure). I’ll pick and choose from these to illustrate my points as we go.

Model 1: Classic

I’ve named this model “Classic” as it is pretty much the basic use of the WCSF as it was intended;

Note: An arrow indicates a reference – so Customers has a project reference to Customers.Interfaces. The coloured bars indicate responsibilities for each project.

This diagram shows us a number of things;

1. The WCSF provides an out-of-the-box option to define an “interfaces” project for each module, in which the public “contract” of the module is defined. An “Interfaces” project contains contracts (i.e. for services a module exposes) and entities.

2. The Web Site contains the Web Pages and User Controls for a module.

3. The implementation projects (what I call the module projects that are not suffixed with “.interfaces”) contain the full remaining layers of the architectural stack, from UI (presenters etc) through business logic, to resource access.

4. The Web Site may reference both interface and implementation projects.

5. The implementation projects may reference their own or other modules’ “interfaces” projects. This allows modules to take dependencies on services exposed by other modules in a loosely coupled way.

6. As shown by the X marks, modules should not reference each other in any other way. Doing so would cause their implementations to be tightly coupled, and can cause circular references – which would be really bad news.

I’m a big believer in showing some code to demonstrate how this works, so let’s take a simple example and consider the following;

namespace Customers.Interfaces

{

public class Customer

{

public int Id { get; set; }

public string Name { get; set; }

}

public interface ICustomerService

{

List<Customer> GetCustomers();

}

namespace Customers

{

public class CustomerService : ICustomerService

{

public List<Customer> GetCustomers()

{

// implementation

}

Here we see the Customer entity and the ICustomerService contract are defined in the Customers.Interfaces project, and a real implementation of CustomerService in the implementation project. Obviously there would be IView definitions and Presenters in the implementation module too, and ASPX pages etc in the web site, but these are not relevant to this example.

Model 2: Shared Entities

Model 1 is in many ways the ideal – but the problem is life is often more complicated than this! The first thing you’re likely to encounter is when two modules need to share the same entity. So consider what happens if I define the following (slightly contrived) contract in my Orders.Interfaces project;

namespace Orders.Interfaces

{

public class OrderDetails

{

public string OrderReference { get; set; }

}

public interface IOrderService

{

void PlaceOrder(Customer customer, OrderDetails order);

}

Looks great huh? Ah, but Customer is defined in Customers.Interfaces... I could add a reference from Orders.Interfaces to Customers.Interfaces, but how long would it be before I needed to do the same in reverse and had a circular reference?

This leads me to a piece of advice;

Avoid having references between “.interfaces” projects

Also, remember that in my previous article we discovered that it is good practice to ensure that one and only one module owns access to any particular data source. So we shouldn’t create two different customers entities. So what do we do?

This diagram has way too many arrows on it to indicate acceptable references, but I wanted to provide a complete view, so I apologise! Basically, then, this boils down to creating a separate shared project in which you put common entities and contracts. Entities that only relate to a single module can stay in that module’s interfaces project.

So in our example, this becomes as follows;

namespace Shared

{

public class Customer

{

public int Id { get; set; }

public string Name { get; set; }

}

namespace Customers.Interfaces

{

public interface ICustomerService

{

List<Customer> GetCustomers();

}

namespace Customers

{

public class CustomerService : ICustomerService

{

public List<Customer> GetCustomers()

{

// implementation

}

namespace Orders.Interfaces

{

public class OrderDetails

{

public string OrderReference { get; set; }

}

public interface IOrderService

{

void PlaceOrder(Customer customer, OrderDetails order);

}

You see that the Customer entity has moved out, and now we have no circular reference concerns.

Model 3: Layered Modules

I have historically always separated my application layers by project – I find this helps keep the layering clear, and keeps the volume of code in any one project to a manageable level. The WCSF does not do this by default – but it doesn’t prevent you from doing it! In fact, some of the reference implementations split modules in a similar way;

This diagram shows that I have added two new standard C# projects to the solution, and named them Customers.Data and Customers.Logic (note I have omitted the Orders functionality here just to keep the diagram simple). My layers are now kept nice and separate. Each layer may reference the layer below, but not vice-versa.

Now there is an interesting point to make from this diagram – my Logic and Data projects have no reference to the Customers.Interfaces project. This means they cannot deal with the “Customer” entity!

I actually think this is a matter of choice – it depends on how much you wish to ensure your layers are loosely coupled. Using the approach I have taken, you would need to use an adapter or entity translation pattern in the Customers implementation project. Here, the UI facing classes (such as presenters or services) would translate between the outward facing entities defined in Customers.Interfaces, and those used internally by the module (perhaps database-focused entities). The services in the Customers module would simply act as a facade to real logic, contained in the Logic project.

The truth is, it can be a bit of a pain taking this approach, so you may wish to compromise – but the point is, it needs a few moments of thought. Choose an approach that you feel comfortable with and stick to it throughout your solution.

Model 4: Split Modules

An alternative approach to bringing extra clarity to your layering is to physically split up your modules;

Note: I have excluded the Web Site from this diagram, as I’m sure you’re getting the point!

Here you can see that we have Customers and Orders business modules, without matching interfaces projects. These only contain UI code, allowing you to keep the projects really focused. We then have two foundation modules – CustomersLogic and OrdersLogic (not very well named, I admit!). These modules expose services to the UI modules to allow them to access the “model” (as Model-View-Presenter) that is our business logic. The reference between the UI code and the business logic is loosely coupled as it goes via the foundation modules’ interfaces projects. If you really wanted, you could take this one step further and split the foundation modules into more projects as we discussed in the Layered Modules approach.

This is indeed very similar to the Layered Modules approach, except that it gives you an opportunity to deploy business logic separately to your user interface. This can have big benefits for team working (e.g. different teams working on the UI and business logic), or for deployment – perhaps your UI works for a number of systems, with different business logic plugged in behind?

Model 5: Split Master Logic Module

All of these approaches so far have one thing in common; they expect you to be able to vertically partition your code to some greater or lesser extent. In reality, this is the hardest bit of getting your WCSF implementation right – what parts of the system are really independent from each-other?

In particular, if you are migrating an existing system you may well find all of your business logic and data access is so tightly related, interlinked, and interdependent, that you cannot split it into modules without all sorts of circular references, shared entities, and so on. You could try, and end up with spaghetti dependencies between modules – even if it is loosely coupled, too many dependencies on each-other’s services is not a good sign. Or maybe you just happen to be building a small system that only really has one single area of functionality?

So all this means you could well end up with one single module, immediately losing some of the benefits to team working, componentisation, etc, that come with modularisation. Right?

Well, this is where the Split Master Logic Module approach comes in. Split your UI into modules – because that is often pretty easy - and then keep all your back end logic in a single foundation module that exposes services to the rest of your application;

I must make it clear that with this model you are missing out on the benefits of the complete vertical slice through your architecture you would get with a purist approach, but it does still have a place I believe.

This allows you to work in a loosely coupled way, modularising your UI (including independent deployment of modules if you wish), yet maximising the reuse of any existing business logic you have – it could be as simple as surfacing existing code as WCSF application services. You of course still have all the flexibility of a loosely coupled architecture too, so should you wish to migrate your existing code to a new, more modular architecture, just plug-and-play different service implementations as time goes by.

Conclusion

Well, that’s it – a lightning fast tour of some approaches to splitting your modules up. Have I missed an approach? Have you come up with something better? Do you hate one of the approaches above? As always, shout up and let me know.

The one approach I haven’t discussed is using a Service Layer to physically split the UI from a logic tier. Watch this space and I’ll try to post some thoughts on this soon.

Finally, I threw a few comments into the text above that might have got you thinking... if so, check out;

· The Adapter pattern

· Entity Translation – best explained by Don Smith, in context of the Web Service Software Factory but relevant to us too!

· My thoughts on LINQ solution structures (aimed at a WPF app, but some relevance to the web)

Enjoy!

WCSF Application Architecture 5: Defining Modules

simonince — Thu, 19 Jun 2008 13:44:00 GMT

This article is part of a series;

· WCSF Application Architecture 1: Introduction

· WCSF Application Architecture 2: Application Controller

· WCSF Application Architecture 3: Model View Presenter

· WCSF Application Architecture 4: Environment Abstraction

Modularity Primer

One of the big pushes from the Web Client Software Factory was for Modularity – see the documentation online here for more information. This was for a number of reasons – supporting different teams working on the same web site but in different functional areas, clear separation of functionality, independent deployment, and more.

It is very common for systems to be considered “modular” in a horizontal fashion (e.g. logging frameworks, data access frameworks, or an application with both WebForm and WinForm UIs), but not so common for them to be split vertically. So what is a vertically modular application? Simply put, it is dividing an application into slices of functionality that span the architectural stack – from UI to Database.

In the previous posts in this series we have discussed a few concepts well worth knowing about in order to fully understand how we position the content of each module. I’d recommend checking back if you are not sure you know these concepts. You also need to know about the fundamental module types: Foundation Modules contain no UI elements, and Business Modules contain both UI and logic.

This post focuses on how the WCSF was designed to be used from the beginning – future posts will present ways to supplement, build on, or alter this basic approach.

A simple sample

To frame our discussions in this post lets magic up a simple module structure for a fictional web client application;

Here we can see 3 Business Modules (Customers, Accounts, and Orders) and a Foundation Module (Infrastructure) containing primarily Environment Abstractions. The Business Modules make use of a set of remote services and/or databases.

What makes a good Module?

So how did I decide to split this application into these modules? At the time of writing, this was the Wikipedia definition of “modular programming”;

“Modular programming is a software design technique that increases the extent to which software is composed from separate parts, called modules. Conceptually, modules represent a separation of concerns, and improve maintainability by enforcing logical boundaries between components. Modules are typically incorporated into the program through interfaces.”

The emphasis is mine, and is there to highlight what I think are some really key concepts of modularity. Namely they should be separate, there should be quantifiable boundaries between different modules, and communication across modules should be enforced using interfaces (or contracts).

Based on this knowledge, and experience of using the WCSF, let’s try and come up with some more concrete “rules of thumb” then;

1. Abstract application services into one or more shared “runtime” or “infrastructure” foundation modules.

2. Each business module should be separate: aim to minimise the communications between business modules if you want to avoid the spaghetti effect.

3. Align business modules with logical functional areas, which have meaning in your business domain.

4. Ensure that each sequence of pages (i.e. a Page Flow, or Wizard) is contained within a single module.

5. Allow multiple sequences of pages per module.

6. Partition according to the business services your modules consume; for example consider having a CRM module, and a Finance module, if these are two services managed elsewhere in your business.

7. Define business entities in a single module; if you need to refer to the private Invoice entity defined in the Finance module from your CRM module, have you perhaps got the boundaries wrong?

8. Consider the development process; if you have teams working concurrently on a system, are the modules you’ve chosen a logical split of work?

Do you have any more from your own personal experience? Shout up if so.

Finally, bear in mind that in spite of all this separation, modules must be related in some way – if they are really totally separate, why aren’t they just two different systems?!

10 Points of Pain

Great, modules are easy then? Well, almost! I’ll try and elaborate on some of the issues that can arise;

1. I don’t know where to put my User Controls and Custom Controls!

2. I’ve got spaghetti intercommunication between my modules using services!

3. I’ve so many modules I can’t find my code!

4. Where do I define my entities?

5. How do I reuse my company’s existing internal libraries?

6. I’ve too much code to organise in a single module!

7. My Application Controllers are too complex!

8. Which module should “own” communicating with my Web Service / database / flat file / mother-in-law?

9. I’m used to having separate projects for UI process, Business Logic, and so on – my developers are confused by having both in the same project, and we’re finding our layers are getting blurred!

10. My Architects are not happy bunnies; we like to be able to host our UI and business tiers separately!

In tried and tested fashion, let us address each of these in turn...

10 Instant Cures

1: I don’t know where to put my User Controls and Custom Controls!

This is really two questions: User Controls and Custom Controls tend to be handled differently.

For User Controls I would recommend putting them in the Shell module, perhaps in a sub-folder of the main web application named “Controls”. This ensures they are easily accessible to other modules. One really key point to consider here, though, is whether they should contain calls to business logic in their Presenters. I would encourage you to avoid this – Shell is not the place for this kind of thing. Instead, I would define properties and events on my control to allow it to be reused across my solution. Bear in mind this also introduces an additional dependency between modules and the Shell, which needs to be considered for deployment, versioning, etc. This is fine – the Themes, Skins, CSS and master page already dictate this, but do remember you must pay attention to it.

For Custom Controls I am assuming you would like to write (or already have) a control library to store them in. A really common mistake people make when first using the WCSF is to worry about putting everything in a module – this is by no means a dictation of the solution structure, and I would encourage you to avoid modules when they are not appropriate. In the case of a reusable control library I would use a standard C# project (or a compiled assembly), referenced from the Web project as usual. Just remember not to couple your controls to your business logic.

2: I’ve got spaghetti intercommunication between my modules using services!

Yikes. This is generally a sign that your module boundaries are not right, or that you’ve simply got too many modules. Watch this space for a post related to this shortly (sorry, but I’ll be saying that a lot in the coming paragraphs, I just don’t have the space!), but basically it boils down to you having two options;

1. Merge your modules into one. If it is really bad, and now you see that actually the two (or more) areas are not as separate as you first thought, this could be a good move.

2. Create a new “in between” foundation module in which to host the specific pieces of business logic that should be shared, moving it out of two business modules. Caution is advised; if the logic is completely core to the modules this could get misleading (e.g. moving LookupCustomer functionality out of the Customers module might be counter-intuitive).

I have to say, more often than not I’ve seen architecture diagrams start with many modules and end up with fewer. The fact of the matter is that factoring an application into modules is difficult.

3: I’ve so many modules I can’t find my code!

You’ve probably got too many modules. You shouldn’t create one module per page-flow, or one module per folder in a web site, or one module screen, etc. Modules should have substance to them, in much the same way that a class should. They should do everything required in a particular business area. Think about the comments under point (2).

4: Where do I define my entities?

This is a potentially tricky subject, as it depends on quite a number of variables. You basically have two choices; a) Define them with the “owning” module, or b) Define them in a shared C# project (e.g. named “Microsoft.Samples.Entities”), and reference this throughout your solution. Of course, this means your modules become tightly coupled to this entity definition project....... watch this space for a post on this.

5: How do I reuse my company’s existing internal libraries?

This is closely related to Custom Controls covered in point (1). Remember that not everything must be a module – in fact, the WCSF uses the Enterprise Library, and these are standard .NET assemblies (but could easily just be the source tree as C# projects included in the solution). So, when appropriate, import your company’s existing assets using a standard project or assembly reference. As I mentioned earlier, though, do make sure you don’t tightly couple your frameworks to your application logic.

6: I’ve too much code to organise in a single module!

There are two possibilities here. Firstly, you could consider splitting your module into smaller modules, if that really makes sense according to the guidelines in this post.

Secondly, this could be very closely related to issues #5 (“how do I reuse my company’s existing internal libraries?”) and #9 (“I’m used to having separate projects”). If it is framework code that you’re talking about, go ahead and pull it out into a separate project. If it is the business logic, data access, and so on, and you’re finding the volume of code and complexity seems unnatural to fit into a single project... I agree. Watch this space for a discussion on scaling the factory (from a volume of code point of view, not performance and scalability).

7: My Application Controllers are too complex!

So add more Application Controllers!! The WCSF creates a single controller per module by default, but there is no reason why you cannot create more if it becomes useful. For example, if you have a complex controller named “RegisterNewCustomerController” that handles flow for the registration process, you might also want to create a “RegisterNewPartnerController” that handles registering a partner organisation.

To do this, simply add a new C# class and interface to store your controller implementation and definition, and add a line to the module’s ModuleInitializer.Load method, just below that generated by the factory by default;

container.RegisterTypeMapping<ICustomersController, CustomersController>();

container.RegisterTypeMapping<IMyNewController, MyNewController>();

This allows you to use the [CreateNew] attribute as usual on your Presenters to get a reference to your new controller.

If you use this approach, do carefully consider how to factor your controllers. Remember that you might find it useful to use the controller as a facade to state as well, and therefore you must choose what to do if multiple controllers need the same piece of state. This is as much a convention decision as technical, but it is a decision that needs consideration.

8: Which module should “own” communicating with...

You may well find that your modules align neatly with your organisation’s approach to SOA, mapping a module to a Service with ease. But you might not!

Consider my sample module definition, and imagine that somewhere I store Customers’ addresses. Immediately you might assume this is something the Customers module needs. But what about our Orders module? It needs to know where to dispatch goods to!

So as a solution, I’ll let my Orders module call into this Address store too. Instantly my architecture starts looking a mess, as Orders and Customers read and write my “Customer Database”;

This breaks SOA principles (I’m thinking autonomous services mainly) which, although not strictly applicable to our modules, do provide some wisdom to this kind of situation. Now I can’t change my Customer Database implementation without reworking every module!

An alternative solution could be for the Customers module to expose an “Address” application service, meaning that Customers still owns the Address entity and service, yet other modules can access the data. If my database changes, only the implementation of the service (and hopefully not the interface defining its contract) in the Customers module needs to change.

Therefore, the recommendation here is;

Make sure a single module owns access to any given resource.

Of course, extrapolate this out too far and you could end up in Problem #2’s space (“I’ve got spaghetti intercommunication between my modules using services”). Alternatively, you might find that all your modules need almost all of your data... in which case watch this space for a related post.

9: I’m used to having separate projects

A lot of organisations are used to using projects to split layers, and in fact I think this is a really good way of working. Using a default out-of-the-box Business Module means that your business logic, entities, resource access, frameworks, and service definitions are all lumped in together in a single C# project, and this could lead to the boundaries between layers getting blurred. We want to separate concerns at the module boundaries (vertically) but not at the cost of layer boundaries (horizontal).

Watch this space for a post related to this...

10: My Architects are not happy bunnies

So what if you want to run your UI tier on physically separate hardware from your business logic tier? Or you already have a service layer containing all the application’s business logic that is used by an existing Windows implementation (no doubt you used the SCSF or Prism to build it J), and you just want to tack an extra web-enabled User Interface onto it?

Well this is a completely valid approach, and in fact the Global Bank Reference Implementation does exactly this, so be sure to check it out. I’ll also be posting more information on this architectural model soon.

Wrap-up

I hope that’s been useful to help you think about shaping modules in your application. As usual, do shout up if you have something to say, and stay tuned for the remainder of the series...

More MVC vs MVP

simonince — Tue, 17 Jun 2008 12:23:00 GMT

Phil Haack, currently famous for working on the ASP.NET MVC Framework, has just blogged a great article comparing Model View Controller and Model View Presenter. I’d highly recommend giving it a read. There is also an old post of mine here comparing MVC and MVP within the context of the Web Client Software Factory and the (as it was then) recently announced ASP.NET MVC Framework.

This seems to be a hot topic at the moment, as people are trying to understand which pattern suits them best.

I would strongly recommend giving this some thought, but remember that patterns are not everything – what also counts is the wider framework that you select. Whether that is classic “vanilla” WebForms, the ASP.NET MVC Framework, the WCSF, any number of open source frameworks, or your own in-house framework; each of these when combined with the patterns they implement bring different levels of accelerated development, testability of UI classes, dictated solution structure, or assistance beyond the UI patterns.

What is important is to pick an approach and build on it... but then you’ll be bored of me saying that by now if you read this blog regularly!

WCSF Application Architecture 4: Environment Abstraction

simonince — Mon, 16 Jun 2008 20:31:00 GMT

This article is part of a series;

· WCSF Application Architecture 1: Introduction

· WCSF Application Architecture 2: Application Controller

· WCSF Application Architecture 3: Model View Presenter

Abstraction Contraption

My previous (and future!) posts have focused on some specific sections of the Web Client Software Factory (WCSF), but this one is a little less focused. The point of this post is to encourage you to consider when you should be abstracting away from ASP.NET concepts, and to see how you can achieve this relatively easily.

Why?

As usual, then, the first question is “Why?” There’s no point in doing something if we don’t have a reason. I think there are two very good reasons to abstract away from ASP.NET concepts, and one less good but still valid reason.

1. Testability

2. Good Design

3. Portability

I’m sure you’ve noticed I like presenting lists, and then working through them, so let’s stick to my standard approach!

Testability

Many people adopt patterns such as MVP and Application Controller to help enable them to use automated tests to exercise their code. However, imagine your Application Controller is handling page flow, and needs to redirect the user to the home page. Consider the following code;

void CompleteWizard()

{

HttpContext.Current.Response.Redirect("Home.aspx");

}

This looks like a perfectly reasonable way to achieve the desired effect... until you come to write a unit test. Most testing frameworks will give you a NullReferenceException when running this code, because there is no “Current” HttpContext. Even if this was not a problem, we might want to test that the correct page has been navigated to – and this is very difficult in the above example.

Good Design

Object Oriented Design is hard, there’s no two ways about it. If you think it’s easy, I’d encourage you to take a step back and think about alternative approaches to the code you wrote yesterday, and you might be surprised! I don’t mean your code is wrong – I mean there are many different ways to design, many different patterns, and many shades of gray. There are almost certainly other ways of writing that code. What should I abstract? What is an acceptable trade-off between pure OO design and pragmatic deadline-focused delivery? No answers here I’m afraid – experience helps, but it will always be a tricky subject.

However, there are two questions I like to ask myself when considering a class design;

1. Does this code do everything that it needs to in order to meet the objective?

2. Does this code have knowledge of anything or perform any tasks that are not core to its primary objective?

This is basically my simplified (and no doubt watered down) interpretation of the Principle of Least Knowledge / Law of Demeter. See an interesting discussion about this on Derek’s Blog.

So if we consider my Application Controller example above, the answer to the second question might be “yes – it has knowledge of the ASP.NET infrastructure”. It is now your call as to whether this is a problem. Sometimes pragmatism must win over, and we’ll ignore the issue – other times, we should take steps to clarify our class responsibilities a little.

Portability

Portability is actually very closely related to testability, so although I’ve flagged this as my “less good” reason it is still completely valid. Basically the question to ask yourself is;

“If I change this application to be a WinForms/WPF/Silverlight/Mobile/WCF/etc (*) app, what will fail due to the lack of an ASP.NET environment?” (* delete as appropriate)

Using my example above, I would have to answer that the Application Controller would fail. This is related to testability as obviously a unit test host is another environment in the same way that a WinForms host is – so I’m sure you see the parallel.

Now this might be very important to some people, and I would encourage you to consider it. However, I would also strongly advise that you exercise caution. Converting an ASP.NET application to run in WinForms may sound great, but in reality it is not straightforward. You need to consider the different way in which users interact with a system (post-backs versus in memory applications), how things are rendered (different data-binding, mark-up, styling, etc), and more. Supporting both WinForms and WebForms with the same code base at the same time is also more difficult than you might imagine – it can be done, but requires careful thought and skilled development.

How? A Simple Example

The ideal way to handle environment abstraction in the WCSF is to have one or more “Infrastructure” Foundation Module(s) that publish global services. We’ll discuss modules more later, so I won’t go into the details of this decision, but just take away that we’re making global abstraction services available to my application.

To get the most from this series of posts you need to know a little about the WCSF, but in case you’re not too familiar with it one word of warning! Don’t confuse Services in the WCSF with Web Services, Service Agents, a Service Interface, customer service representatives, or any other kind of service!! Services simply provide a way to expose common functionality across a whole application (including across modules) in a loosely-coupled manner. A service is defined by an interface, and implemented in a C# class – then it is registered by a module for consumption by any other component that needs it.

So looking at the code, an example navigation service might have an interface like this;

interface INavigationService

{

void Navigate(Screen screen);

}

You could easily just take a string argument to this method that specifies the name of the destination page, but I think this leads to a tendency to include the path and location of each page in the Application Controller. Therefore I create a class named Screen that looks like this;

class Screen

{

private Screen(string location)

{

_location = location;

}

private string _location;

public string Location

{

get

{

return _location;

}

public static readonly Screen Home = new Screen("~/Home.aspx");

public static readonly Screen Bookings = new Screen("~/Bookings.aspx");

public static readonly Screen EditProfile = new Screen("~/Edit/MyProfile.aspx");

}

Note that the constructor is private, so only Screen can create instances of itself. I then create a set of static instances that point to specific screen locations. This means the Screen class appears like an enum to the casual observer, yet I have encoded behaviour information into each instance that consumers can use. If I wanted to, I could mark the Location property “internal”, so that only the assembly it is contained in can use it, thus hiding even more implementation.

One important point to note here is that I should really take this a step further and abstract Screen into an IScreen interface and web specific implementation. This is because my implementation above does include information on the web pages locations. I deliberately haven’t done this though to keep this example simple, and to demonstrate one key subject at a time. If this doesn’t seem clear shout up and I’ll elaborate in another blog post.

Anyway, next we need an INavigationService implementation that works in the Web world.

class WebNavigationService : INavigationService

{

public void Navigate(Screen screen)

{

HttpContext.Current.Response.Redirect(screen.Location);

}

This should be pretty self explanatory, and of course we must register this implementation in our module initialising class;

class MyModuleInitializer : ModuleInitializer

{

protected virtual void AddGlobalServices(

IServiceCollection globalServices)

{

globalServices.AddNew<WebNavigationService, INavigationService>();

}

This creates a new instance of a WebNavigationService, and registers it as an INavigationService for consumption by any WCSF module in the current solution. We’ll talk about structuring modules in another post, remember.

The final important step is to consume our new service. Consider the following Application Controller class;

class ApplicationController

{

private INavigationService _navigationService;

[ServiceDependency]

public INavigationService NavigationService

{

set

{

_navigationService = value;

}

public void CompleteWizard()

{

_navigationService.Navigate(Screen.Home);

}

This CompleteWizard method is the very same method we saw earlier, but now we have no direct dependency on an HttpContext. Instead we simply call into an INavigationService implementation, a reference to which is kindly provided to us by the WCSF when the controller is created using Property Injection (note the ServiceDependency attribute).

Prove it!

So what’s the difference now? I can now unit test my Application Controller independently. Of course, there is nothing wrong with testing a number of different classes at once – just remember that if you do this chances are it isn’t a unit test any more, but instead is an integration test. Both of these types of test are invaluable, but I always like to start with a unit test.

A really simple example unit test for our CompleteWizard method might look as follows;

class ApplicationControllerTest

{

void TestCompleteWizardGoesHome()

{

// setup for test

MockNavigationService navService = new MockNavigationService();

ApplicationController controller = new ApplicationController();

controller.NavigationService = navService;

// attempt navigate

controller.CompleteWizard();

// check results

Assert.AreEqual(navService.LastDestination, Screen.Home.Location);

}

class MockNavigationService : INavigationService

{

public string LastDestination { get; set; }

public void Navigate(Screen screen)

{

LastDestination = screen.Location;

}

Summary

I hope this has helped you see when it is really useful to abstract away from the environment using Services in the Web Client Software Factory. It is also really nice to apply to things like Logging, Tracing, Authorisation, and so on – application infrastructure if you like.

Getting the balance right between when to abstract and when not to is difficult – but do remember that a) once you have chosen not to it is harder to back track than you think, and b) once you’ve chosen to abstract you’ll add to your workload!

I still have nightmares about a fictional scenario with all those HttpContext.Current calls scattered through a whole solution, and trying to rationalise them 1 week before code complete is due...

WCSF Application Architecture 3: Model View Presenter

simonince — Wed, 11 Jun 2008 11:58:00 GMT

This article is part of a series;

· WCSF Application Architecture 1: Introduction

· WCSF Application Architecture 2: Application Controller

Model View Presenter

The MVP pattern is effectively an evolution of Model View Controller, and is mainly geared at improving the structure and testability of User Interface code. There is a good article here that discusses UI patterns, and a previous post of mine that contrasts the MVP pattern with a pre-release version of the ASP.NET MVC Framework. The Web Client Software Factory (WCSF) uses the MVP pattern, and relies on Dependency Injection to wire up the class dependencies.

The following diagram should help you visualise how MVP is put together;

Note that each Presenter has exactly one View, and each View has exactly one Presenter. There is one Model for the whole application (ahem, see later posts on modularity J).

Let’s consider each item in turn.

Model

The model is often misunderstood. It sounds like it should just be data, but then where does my business logic sit? Well, I see the model as representing the whole of my business logic – entities, workflows, and components. It is the window into the real non-UI part of my application. Sticking to our standard architecture defined in the introduction post, the model should only expose business logic components. It should not surface data access components, web service proxies, or other private classes that are further down the architecture stack.

Note that in much of the WCSF documentation the “Model” in MVP is silent – mainly because you could argue it isn’t really a key part to the structure of the UI code, as it is business logic. Hence you might see MVP referred to as “the View-Presenter pattern”. It’s the same thing...

We will discuss the model, how to structure it, and how to implement it in later posts, but for now just think of it as a bunch of plain old .NET objects that “do business logic”.

View

A view is used to display data to the user, and therefore in the WCSF is an ASP.NET “aspx” page and its code behind. In the WCSF, this aspx page must implement an interface (e.g. “IHomePage” would define the Home Page view, “HomePage.aspx” would implement it, and it would have a matching presenter named “HomePagePresenter”). The code that exists in this class should be very simple – and should be focussed on two simple tasks;

1. Taking instructions from the Presenter and converting them into ASP.NET calls.

2. Taking events from the user (such as button clicks) and passing them on to the Presenter to field.

Effectively, the view is responsible for translating between the Presenter and ASP.NET concepts.

Note that on the pattern diagram above I really wish I could remove the arrow from the view to the model. This is because when I use MVP I enforce a rule that the View should under no circumstances call directly to the business logic. The only reason the arrow is there is because the view may have read-only access to some business entities for rendering purposes only. This is heading towards the “supervising controller” variant of the pattern described in the WCSF documentation here, which I find to be the only practical way to implement data-binding.

Presenter

A presenter instructs a view what should be displayed and when, and responds to events raised by the view. It should be unaware of ASP.NET concepts. It should also be the class that interacts with the business logic, potentially passing on single or multiple business entities to the view for rendering. In other words, it is the go-between for business logic and rendered UI.

In the WCSF the presenter has a reference to the view as defined by an interface, hence the two-stage and dotted link in the diagram above.

An example

So after all this theoretical talk, let’s see a really simple example of a Model-View-Presenter trio and how they work. Have a look at the following (simplified for clarity) code.

interface IMyView

{

void DisplayText(string name);

}

class MyView : IMyView

{

public MyViewPresenter Presenter { get; set };

public void DisplayText(string name)

{

TextBox1.Text = name;

}

public void ExitButton_Clicked(object sender, EventArgs e)

{

Presenter.OnExit(Page.User.Identity.Name);

}

class MyViewPresenter : Presenter<IMyView>

{

void ViewLoaded()

{

View.DisplayText("Welcome");

}

void OnExit(string username)

{

BusinessLogic.ExitUser(username);

View.DisplayText("You clicked Exit!");

}

What we have here is the following;

1. An interface that defines the operations that our View exposes (just “DisplayText” in this case).

2. An implementation of the view (aspx mark-up omitted in this example). This receives instructions such as “DisplayText” and translates them into ASP.NET concepts – such as setting the Text property on a TextBox.

3. A presenter, which instructs the View what to do during initialisation, and responds to View events (such as Exit). Note that the Exit method calls into business logic and then updates the view.

I hope that is a nice clear simple example of the interaction between the classes.

How do I get my data?

This example contains a really interesting yet subtle point, and that is how to pass data from a view “up” to the presenter. In my code, I make the following call;

Presenter.OnExit(Page.User.Identity.Name);

What this means is that my view is responsible for collecting the relevant data and passing it on to the presenter at the appropriate time. Now this isn’t necessarily wrong, and in many cases is the easiest way to write code – but actually I think it is sub-optimal.

The issue is that we already have an interface defining what our view provides, and I feel that this should really be the contract between presenter and view for as much information as possible. Therefore, I would prefer the following implementation;

interface IMyView

{

void DisplayText(string name);

string CurrentUsername { get; }

}

class MyView : IMyView

{

public MyViewPresenter Presenter { get; set };

public void DisplayText(string name)

{

TextBox1.Text = name;

}

public void ExitButton_Clicked(object sender, EventArgs e)

{

Presenter.OnExit();

}

public string CurrentUsername

{

get

{

return Page.User.Identity.Name;

}

class MyViewPresenter : Presenter<IMyView>

{

void ViewLoaded()

{

View.DisplayText("Welcome");

}

void OnExit()

{

BusinessLogic.ExitUser(View.CurrentUsername);

View.DisplayText("You clicked Exit!");

}

(note: changes are in italic)

What I’ve done here instead is expose the user’s login name as a property on the view, which is defined in the interface that serves as the “contract” between the presenter and the view. I then just raise the “OnExit” event from the view to the presenter, and it is the presenter’s responsibility to extract the information it needs from the view.

This example uses the username, but I would also use it for passing the contents of a textbox edited by the user through to the presenter – expose a property on the view that the presenter extracts the required text from when needed.

I personally think this is more elegant, plus I find it actually helps when writing unit tests. What do you think?

MVP + Application Controller

The final point to make is where the interaction with an Application Controller fits in. Hopefully the diagram below helps;

I believe that, if you go with my preferred approach to the pattern described in a previous post, the presenter should be the only point of interaction with the Application Controller. So in my simple example above, you might have code that looks like this;

class MyViewPresenter : Presenter<IMyView>

{

void ViewLoaded()

{

View.DisplayText("Welcome");

}

void OnExit()

{

BusinessLogic.ExitUser(View.CurrentUsername);

ApplicationController.CompleteExit();

}

The CompleteExit method would more than likely redirect the user to the home page.

Summary

MVP is subject to less confusion once you have ironed out what an Application Controller does, but there are some key points to remember;

1. There should be no logic other than simple data binding or property access in a View.

2. There should be no ASP.NET concepts in a Presenter or the Model.

3. The View must not directly call Model (business logic) methods, but may have a reference to business entities to simplify rendering and data binding.

4. The Presenter should orchestrate the relationship between the View and the Model (business logic).

Following these guidelines should help enable you to unit test your presenters effectively, and should make you smile when you have to make a change to the code... meaning you know exactly where and how to make that change.

Keep listening to hear about modularity in the WCSF, and as always – chip in if you agree, disagree, or don’t think I’ve explained something sufficiently...

WCSF Application Architecture 2: Application Controller

simonince — Fri, 06 Jun 2008 11:59:00 GMT

This article is part of a series;

· WCSF Application Architecture 1: Introduction

So why do we have patterns? I think it is basically to reuse good designs, and to adopt a common terminology when discussing software. But so often the subtleties of patterns are difficult to get right, and this causes confusion when people say “my presenters do X, what do your presenters do?”

I am a little concerned that I’m just going to add to this confusion with these articles. If that’s the case, I never wrote it OK? You didn’t hear it here. It was some other Simon...... J. Joking aside, I think having an open and interactive debate about the different approaches can only help – so please do feel free to comment or blog right back at me!

Anyway, there are two key patterns used in the Web Client Software Factory (WCSF). Application Controller and Model View Presenter. This post examines Application Controller, watch this space for one on Model View Presenter.

Application Controller

To quote Fowler, an Application Controller is used as “a centralized point for handling screen navigation and the flow of an application”. The intention is to abstract the complexity of flow through a set of screens into a discrete controller. Fowler does also suggest that “input controllers then ask the Application Controller for the appropriate commands for execution against a model”. This is where I think the variation arises in the implementation of this pattern.

In most systems today “business logic” is a really fancy word for a bunch of .NET classes that take input from the User Interface, validate it, apply some rules (“business rules”), and bung it in a database, or perhaps chuck it over a service boundary ^*. Occasionally there is a full domain model, but in most cases this logic is pretty straightforward (perhaps a Transaction Script). Therefore I might make a call like this;

MyLogic.SubmitLoanRequest(“Simon Ince”, loanID, loanAmount);

Now this isn’t exactly the Command pattern that Fowler refers to, and although I know some teams use the Command pattern heavily, it is not usually used in .NET land as the primary interface to the business logic.

So if we’re not able (or don’t want) to return the “... appropriate commands for execution...” from the Application Controller, what should we do? Well, I’ve seen three approaches;

1. Use the Application Controller for both Page Flow and as a facade to the Business Logic

2. Use the Application Controller for Page Flow and to supervise Business Logic interaction when required

3. Use the Application Controller purely for Page Flow, effectively as a “slave” class

Option 1: Page Flow plus Facade

Consider the implementation below;

class UserInterface

{

void Page_Load(object sender, EventArgs e)

{

List<string> loanTypes = ApplicationController.GetLoanTypes();

LoanList.DataSource = loanTypes;

LoanList.DataBind();

}

void SubmitButton_Click(object sender, EventArgs e)

{

ApplicationController.SubmitLoanRequest("Simon", 1, 2);

}

class ApplicationController

{

static List<string> GetLoanTypes() {

return BusinessLogic.GetLoanTypes();

}

static void SubmitLoanRequest(string name, int loanid, int value) {

BusinessLogic.SubmitLoanRequest(name, loanid, value);

Navigate("HomePage");

}

Clearly what I have here is as follows;

a) A business logic class that does the work (implied, not typed out for brevity)

b) An application controller that conforms to “Option 1” above

c) A User Interface that uses the Application Controller

Because I am using “Option 1”, my call to get a list of Loan Types from the User Interface must go through the Application Controller to remain consistent with the approach. The submission of the loan request also goes through the controller, which calls the business logic and then makes a decision about page flow.

Let’s try to consider some of the advantages and disadvantages to this approach;

Advantages	Disadvantages
The Application Controller always gets to decide what should happen next. If, for example, a requirements change means a call to GetLoanTypes should redirect the user to a login page, it can do that with ease, and without any other classes changing.	Every business logic method that must be called from the User Interface must have a matching facade method in the Application Controller, even if it doesn’t add any behaviour, and literally just passes on the call (and I’ve seen this a lot). For a large system, this becomes a pain very quickly, from the point of coding effort, lines of code, maintenance effort, unit testing and so on.
There is a very clear pattern of execution – the UI can never short-circuit the approach to call directly into the business logic.	Is it really harder to add a call to the Application Controller if a navigation requirement changes than it is to add a line of code into the controller? I don’t think so, which I personally believe makes this approach overkill.

Option 2: Page Flow plus Occasional Logic Supervisor

Consider the implementation below;

class UserInterface

{

void Page_Load(object sender, EventArgs e)

{

List<string> loanTypes = BusinessLogic.GetLoanTypes();

LoanList.DataSource = loanTypes;

LoanList.DataBind();

}

void SubmitButton_Click(object sender, EventArgs e)

{

ApplicationController.SubmitLoanRequest("Simon", 1, 2);

}

class ApplicationController

{

static void SubmitLoanRequest(string name, int loanid, int value) {

BusinessLogic.SubmitLoanRequest(name, loanid, value);

Navigate("HomePage");

}

What has changed? I’ve removed the requirement for business logic methods that do not have a navigation component to go through the Application Controller. Therefore, my User Interface calls directly to the business logic’s GetLoanTypes method. However, because I know SubmitLoanRequest will require a navigation event, I do call through the Application Controller, which in turns “supervises” calling the business logic and then performs the navigation as before.

Let’s try to consider some of the advantages and disadvantages to this approach;

Advantages	Disadvantages
There is no need for every business logic call to have a facade method in the Application Controller – only those that have a navigation component are needed.	You must decide up front which operations have a possible navigation away from the current page involved.
Flow through the code is simplified – it is more obvious which logic components are used by each UI component.	If you want to change an operation so that it involves a navigation event, you must add code to the Application Controller and tweak your UI code.
	There are now two ways to call business logic – through the Application Controller and from the UI. I think this lacks clarity.

Option 3: Page Flow Slave

Consider the implementation below;

class UserInterface

{

void Page_Load(object sender, EventArgs e)

{

List<string> loanTypes = BusinessLogic.GetLoanTypes();

LoanList.DataSource = loanTypes;

LoanList.DataBind();

}

void SubmitButton_Click(object sender, EventArgs e)

{

BusinessLogic.SubmitLoanRequest("Simon", 1, 2);

ApplicationController.CompleteSubmitLoanRequest(true);

}

class ApplicationController

{

static void CompleteSubmitLoanRequest(bool success) {

if (success)

Navigate("HomePage");

else

Navigate("ErrorPage");

}

What has changed this time?

We’ve now completely removed any interaction between the Application Controller and the business logic, instead letting the UI handle all of this. The controller is purely responsible for deciding what to do next, or “controlling the flow”. Note that I have also added a Boolean parameter purely to illustrate that the controller may need additional state – which we will discuss further shortly.

Let’s try to consider some of the advantages and disadvantages to this approach;

Advantages	Disadvantages
The controller’s responsibilities become very clearly defined and encapsulated.	The Application Controller might need some information from the business logic to make a decision. This could complicate the UI code as it may need to fetch extra data to pass into the controller, or might corrupt our approach by having the controller call into the business logic again!
It is easy to change the way page flow works, perhaps by introducing Page Flow components (e.g. Windows Workflow) because the controller is kept simple and free from other responsibilities.	If you want to change an operation so that it involves a navigation event, you must add code to the Application Controller and tweak your UI code.
There is no need for facade methods to any business logic methods.

So which is best?

This is where I dodge the question. The point is – which do you prefer? I personally prefer Option 3 – I find it keeps the controller’s responsibilities very clearly defined, and when combined with other UI patterns (e.g. MVP) keeps a good balance of code in the right places. I think it also makes testing easier – as you are only testing a controller for flow, not business logic. But I wouldn’t claim this to be the only way.

State

It is worth making a point about state too. An Application Controller needs to make decisions – and these need to be based on what the user did, what they previously did (e.g. if they’ve not logged in, they will be treated differently to a user that has logged in), and what their state means (e.g. if they are under 17, the “CanApplyForUKDrivingLicense” setting would be false). This means the controller needs some awareness of state.

There are three ways to deal with this (you’ll be sick of option lists by the end of this series I’m sure!);

1. Store state in the Application Controller. Expose properties to the UI to get/set state for the current user. This works well, I think, as it centralises your state management. Check out the StateValue<T> and StateDependency features of the WCSF for this.

2. Pass all required state into your Application Controller when you call a method on it. This can also work, as long as you don’t have too much state to be passing around.

3. Have your Application Controller call out into your business logic to get the results of rules based on some state. This is only half a solution, as you will need to know some of the “who” and “what” first anyway. I also think it corrupts the model a little, and so I prefer to avoid this where possible.

In reality, I usually use a combination of (1) and (2) – (1) for real user state, and (2) for the results of business rules.

What is Page Flow?

The final topic to cover is the definition of Page Flow. This is absolutely not the same as “site navigation”. If you try to model the whole of your web site using some kind of Page Flow mechanism, whether that is an Application Controller or otherwise, you will (in my opinion) be creating a tonne of work for yourself. Instead, use the standard ASP.NET navigation controls, hyperlinks, buttons, menus, etc to navigate around your site. This is what they’re there for – and making use of them should keep your pain levels low!

Page Flow is when you have a process in your site that should be completed from end to end – for example, a hotel booking wizard, or a mortgage application. This process might be reached and initiated by a hyperlink from your home page, but once within the process the “back” and “next” buttons would use an Application Controller to determine the steps through the wizard.

If you now take a step back and consider the options presented above, I find that this understanding of page flow is a natural fit with my preferred option 3. Not all pages will be part of a “flow”, so what do you do with the business logic calls then? Should they go through a controller when there is no need for one to assist with page flow? I don’t think so.

Summary

I hope this has helped you think about the Application Controller pattern. Chances are you’ll recognise many of these different approaches, but if you think I’ve missed any shout up – I’m always keen to hear what others are doing, and how successful each approach has been. Stay tuned for a look at MVP!

* over simplification intended!

WCSF Application Architecture 1: Introduction

simonince — Thu, 05 Jun 2008 19:27:00 GMT

[Edit] By popular demand (well, one request!) I've added links to all the articles in this series here;

WCSF Application Architecture 1: Introduction (this post)
WCSF Application Architecture 2: Application Controller
WCSF Application Architecture 3: Model View Presenter
WCSF Application Architecture 4: Environment Abstraction
WCSF Application Architecture 5: Defining Modules
WCSF Application Architecture 6: Structuring Modules
WCSF Application Architecture 7: Remote Logic with WCF Services

[/Edit]

One of the questions I get a lot from customers is “how do I write a real world application using the Web Client Software Factory (WCSF)?” The problem is that I think everyone writes applications slightly differently, but also significantly there is no single correct way. What is important is to get two things right;

Select an approach

I honestly believe that one of the best ways to improve the quality, maintainability, and document-ability (no really, I’m sure that’s a word!!) of your system is to pick a single approach and stick to it throughout the application. What is even better is to consistently use the same (or a gradually evolving and improving) approach throughout all your applications.

The developer learning curve is massively flattened if you do this – everyone knows how to add operation X to page Y, because they all follow pattern Z. With this consistency in place you should find your team feels really comfortable, reassured, and secure in what they’re doing. I think this is really important. It then gives people the confidence to innovate in the important areas (that small percentage of an application that needs to be “special” in some way) and to understand how they might evolve the approach for next time, into something even better.

Of course, documenting your software is made much easier by having a consistent approach too – it tends to lead to the evolution of natural terminology (often driven from or derived from patterns you’re using) that the team use when communicating, whether that be on paper or verbally. I can’t count the number of times I’ve been in team meetings when someone has said something like “have you re-gened the DTO and DTM, because my Presenter needs updating to reflect the changes to the user Catalogue”. Everyone knows which project and folder the DTO, DTM, Presenter, and Catalogue classes live, and everyone knows what they do. Therefore;

stress -= 10;

communication ++;

Select an appropriate approach

OK, so I admit that this is cheating. It’s like saying “to have a happier life, do everything right”. Don’t you hate it when you get to the end of a “how to do X” article and it basically tells you to go and work it out yourself?

Well I won’t be quite such a pain – I can help with this. I think there are a standard set of variances that I have seen in how people use the Web Client Software Factory in particular, and therefore my intention is to describe how these variances might help or hinder you, and which I tend to favour in different situations.

The two main drivers behind variances in implementation in my mind are the different interpretations and uses of Modularity and Patterns.

The WCSF brings a strong modular approach to solutions, encouraging you to split your application into Business Modules and Foundation Modules. You can find more information on these concepts here. I will explain some differences in how you might choose to implement these modules, and how you might split your application up.

The Model-View-Presenter and Application Controller patterns are also used extensively in the WCSF. Some useful information on this can be found here, here, and in this great article on UI patterns in general. However, the way that people use these two patterns in the real world actually differs in quite subtle ways, which can have an impact on how much effort is required to write and maintain your application, and I find personally on my perception of how worthwhile using the patterns is. For example, having to write an extra 6 classes and 12 methods to format a string is bad in my mind, but separating the logic to format the string from that to display it is good. There is always a balance there somewhere!

Assumed Application Structure

Throughout all my posts I am going to assume that the most common case of application architecture is known to you – and that this is our starting point. The architecture I am referring to is the common interpretation of that described in Application Architecture for .NET. That is, it looks something like this;

Not rocket science, but a common starting point for us all.

Watch this space

So, stay tuned. I’ll post some follow-up articles to this that hopefully will shed some light on what the differences are. Feel free to chip in – if you love or hate one of my suggestions, or think I’ve floated a good or bad idea, shout up in the comments section and help me get a real feel for how people are doing this around the world.

Web Client Software Factory February 2008 Ships!

simonince — Fri, 29 Feb 2008 12:47:00 GMT

Great news from Glenn... The WCSF February 2008 release (i.e. 2.0) has just shipped. Check out the landing page and the community site.

This release has addressed many of the top feature requests, supports Visual Studio 2008 and .NET 3.5, includes more guidance, quickstarts and how-to walkthroughs... what’s more, they’ve improved the Composite Web Application Block both by extending it and improving performance, and something I’d not noticed - added support for dependency injection on ASMX Web services.

Great news – and congratulations to the team. Hopefully they’ll have a few moments to relax before the next project J

February 2008 GAX and GAT

simonince — Mon, 18 Feb 2008 11:05:00 GMT

Just a quick note as I’ve had my body pretty much surgically attached to my laptop and various (geeky) books recently... normal service will be resumed soon hopefully J

Anyway, some great news for Software Factories; the Guidance Automation Extensions (GAX) and Guidance Automation Toolkit (GAT) [VS2005, VS2008] February 2008 Release is upon us – see more information on Grigori’s blog.

This includes some bug fixes, improved installation/un-installation support, and of course that all-important support for Visual Studio 2008.

This support of course enables up and coming releases such as the Web Client Software Factory 2.0, as per these comments from Glenn. I’m really looking forward to seeing what the team’s hard work has produced.

WCSF 2.0 Around the Corner

simonince — Mon, 04 Feb 2008 20:48:00 GMT

If you haven’t found it already, Glenn Block has posted a great summary of what is included in the Web Client Software Factory 2.0... which is apparently just around the corner.

And Paulo Morgado has been posting all sorts of demo code relating to using the WCSF bundles.

Sit down and get comfortable for a serious dose of WCSF blog posts from the p&p guys over the coming weeks, no doubt!

The ASP.NET MVC framework, using the WCSF as a yardstick!

simonince — Thu, 22 Nov 2007 18:37:00 GMT

Well, right up until this morning I was planning on blogging about the similarities and differences between the patterns used by the Web Client Software Factory (WCSF) and the up and coming ASP.NET MVC Framework... and then I saw Glenn’s post linking to this great article on patterns used to structure User Interface code. Gutted. Someone has already done it, and what’s worse, they’ve done it much better and more thoroughly than what I had in mind!

Still, I think I can squeeze some mileage out of my thoughts over the past few days... J

Much of this post is my current evolving thinking on the two frameworks, and therefore if you disagree do feel free to chip in and air your views. I’m only specifically comparing against the WCSF because I feel they share many characteristics and address similar problem spaces, and so I think it leads to a good illustration of what the MVC framework might give us, and what you need to be aware of.

My thoughts are also based entirely on what information is in the public domain – I have not had any internal conversations about this, so not only does it “not necessarily represent the views of my employer”, but chances are it will be just plain wrong as CTPs start to appear... so join the debate!

In case you are not sure which patterns I’m referring to, have a quick read of the links under patterns used in the Web Client Software Factory. Specifically we’re interested in View-Presenter and Application Controller. For the MVC framework, there is an hour long video of Scott doing a demo, two posts by Scott here and here, and a good set of notes here.

So how do these WCSF patterns directly compare to those proposed in the ASP.NET Model-View-Controller framework? In the Web Client factory we have a Model (implied, although not named in View-Presenter), a View, a Presenter, and a Controller, and in the MVC framework we have a Model, View, and Controller. So surely the mapping is pretty obvious? Well, it isn’t the simple one-to-one you might think. Here’s what I’ve come up with so far;

Responsibility	WCSF MVP	ASP.NET MVC
Page flow	Controller (single)	Controller (many)
Business logic	Model	Model
Interaction with Business logic	Presenter*	Controller (many)
Presentation logic	Presenter	View (code behind)*
Presentation UI	View	View (mark-up)*

* Two points to note; a) you don’t necessarily have to split a View by code behind & mark-up in the MVC framework, but it seems a logical way to indicate the two roles a page can fulfil; b) many people use the Controller as a facade to the business logic in the WCSF, but the key above is that the instruction to interact with the logic is generally initiated by the Presenter calling a method on the Controller.

So what are these key differences? I’ll try to boil it down to some concrete points.

Controllers

The WCSF tends to have an Application Controller per module, but the MVC framework has many (likely to be one per group of views). So in the WCSF we might have a SalesController that handles all page flow (and potentially business logic interaction) for the Sales module. However, in the MVC framework we might have a PricingController, an InvoiceController, and a CustomerController. Page flow is not necessarily owned by any single Controller.

There may therefore be an opportunity in MVC framework applications to use something similar to an Application Controller to centralise some of the page flow; perhaps by directing all relevant requests to a single Controller Action on an Application Controller to route appropriately. More thought required I reckon!

Entry Points

The primary entry point to the WCSF framework is the View followed by the Presenter. So when the user browses to “~/DisplayProducts.aspx”, the DisplayProducts page is constructed, and the DisplayProductsPresenter is attached to it. This Presenter then drives interaction with the Controller as required to fetch Model data, decide on Page Flow, and so on.

In the MVC framework, the primary entry point is a Controller, as Controllers are URL addressable. So when the user browses to “~/Products/Display”, the ProductsController would be created, and it’s “Display” action would be invoked. This then interacts with the Model and decides which View to use to render the output.

This also drives the relationship between Views and Controllers; rather than there being one Controller for a set of Views (as I approximated above) it is really that an area of functionality has a single Controller – and that Controller may have a set of supporting Views. Therefore the Controller becomes the primary unit driving application functionality, contrary to the WCSF, in which Views are the primary unit that drives functionality.

Of course, the more obvious point to note on Entry Points is the REST-friendly URLs that the MVC framework uses by default. I don’t personally think this adds any significant benefits, but it certainly looks clean and sits with the framework well.

Views

The MVC framework has no separation of View and Presenter. The WCSF splits presentation logic into a Presenter class, and the technology-specific implementation of this into an ASPX page that implements the View definition. Conversely, in the MVC framework all logic to co-ordinate the physical rendering of a result set is contained in an ASPX page.

Perhaps an interesting point here is that the MVC framework’s Controller actually does much of the work that the WCSF’s Presenter does (in initiating interaction with the Model), and therefore MVC framework Views are expected to be significantly simpler than the View-Presenter pairing in the WCSF – pretty much just rendering mark-up and data binding expressions. This simple presentation code is roughly equivalent to what is contained in the WCSF’s View implementation (without the Presenter). So is there any point in separating further “presentation logic” in the MVC framework?

There are two reasons why a Presenter is useful in my opinion;

a) When there is real logic required to decide how to render a View.

b) When this real logic would benefit from Unit Testing.

But the approach encouraged by the MVC framework is to avoid logic in a view, and to stick to pretty straightforward data-binding etc. Instead of one complex View, you may choose to have many simpler Views. For example, if you have a list of products that can be clicked to display details of each, in the WCSF you may implement this as a single View with collapsible sections... hence there is logic to handle clicks, showing and hiding sections, retrieving data, and so on. However, in the MVC framework this would possibly be better implemented as two Views – a list View, and a details View. When the list is clicked, the request goes through to the Controller which renders the result using the details View. This is in fact likely to be necessary to avoid the View from interacting with the Model. (How does it get the individual product’s details if a View can’t interact directly with the Model? It can’t! It needs the Controller to do that first.)

ASP.NET

Something not so obvious is the way in which each framework sits in the ASP.NET runtime. Scott points out the following in this post about the MVC framework;

The MVC framework supports using the existing ASP.NET .ASPX, .ASCX, and .Master markup files as "view templates" (meaning you can easily use existing ASP.NET features like nested master pages, <%= %> snippets, declarative server controls, templates, data-binding, localization, etc). It does not, however, use the existing post-back model for interactions back to the server. Instead, you'll route all end-user interactions to a Controller class instead - which helps ensure clean separation of concerns and testability (it also means no viewstate or page lifecycle with MVC based views).

In other words, the choice to force all requests through the Controller outlaws the post-back model. In contrast, one of the goals of the WCSF was to support standard ASP.NET functionality wherever possible, to maximise the speed at which developers could get going with it, and allow it to sit well with existing frameworks. This is of course because the WCSF is an accelerator built on the framework, and the MVC framework is just that... an underlying framework.

The choice not to support post-backs in the MVC framework makes absolute sense to produce a more purist application architecture, but it does mean that developers must shift how they think about writing aspx pages.

I’ve mentioned this in a discussion about the patterns because I think it helps define component responsibilities – i.e. a View is much more lightweight in the MVC framework than a classic ASPX page might be. It moves the focus away from building WinForms-like pages to building simple rendering-only templates. I personally believe that if you make this leap, you’re more likely to avoid building monstrous pages that rely heavily on View State, and are difficult to test and maintain...

I also wonder what kind of benefits we may see by not using View State, not going through a page initialisation and load for every post-back button click...

The End... or rather, The Beginning

To conclude, then, my view is that these two frameworks share some common objectives and techniques, and therefore that each can potentially contribute significantly to the other. In the comments on his posts Scott implies a CTP is just around the corner, so let’s look forward to playing with it for real.