Simon Ince's Blog : ASP.NET

Loading Scripts Late

simonince — Tue, 20 Oct 2009 19:52:00 GMT

On the ASP.NET ScriptManager control there is a useful little property that very few people have heard of called “LoadScriptsBeforeUI”. What does it do?

Well, simply put...

· When “true” (the default) it will render <script> tags for each script you reference using the ScriptManager at the top of your HTML.

· When “false” it will render these <script> tags at the bottom of your HTML.

Oh right. Why would I bother?

Well to put it simply it is because all browsers stop parsing and rendering HTML while they are downloading and executing scripts... which means if you put your <script> tags at the top of a web page none of your page will start to render until all scripts are downloaded and dealt with. The bottom line is that while your page is downloading scripts, the page is usually blank, and your user is wondering why the page is taking so long to load.

In a development environment this may not seem particularly important – but deploy your application to somewhere bandwidth and network speed are unknown, and it can often become an issue. Users don’t like sitting waiting for your site to respond, so you could be losing users!

Let’s see it

Let’s see what this looks like in action – download the attached sample solution and view the two pages. One downloads my scripts first; and I’ve made sure one of the scripts takes 5 seconds to load, so it is obvious how slow the page is. The other page loads the script last... and you’ll notice the page renders immediately, without waiting for the script.

Have a look at the HTML source and see where the references to TestScript.js and GetScript.ashx are.

The Gotcha

I’ve just showed you how to improve the perceived performance of your web site by changing one setting from “true” to “false”! Right?

But I’m afraid there is a catch. You’ll also notice there is a button on my test web pages. This is to demonstrate something important; you need to be very aware of when the scripts are being downloaded. This leads to two opposing issues;

1. If you have scripts that execute as soon as they’re downloaded, they probably assume that the DOM has been built. In this case, they usually must be rendered last. I’d recommend using page load events instead, so that you don’t have this requirement.

My sample demonstrates this; only when TestScript.js is loaded after the UI has been rendered does the button work, because TestScript.js assumes the button exists and attaches an event handler. If I put this in pageLoad instead it wouldn’t be an issue.

2. If you have event handlers embedded in your HTML that depend upon some framework scripts you’re downloading later, the user could click the button before your scripts have downloaded and the handler would error! This approach to wiring up event handlers looks something like this;

<button onclick="callMethod()">Click Me</button>

The solution here is to attach event handlers programmatically, as I have done in TestScript, but in the pageLoad event instead. You could even consider defaulting your buttons/controls to a "disabled" state, enabling them once you've attached the event handlers. This can sit well with the principles of Unobtrusive JavaScript and progressive enhancement if your controls have default non-script behaviours, so is a good practice anyway.

The End...

I think this shows a useful technique that can really improve users’ perception of your web site... as long as you design your use of script to work correctly. Enjoy!

Executing JavaScript after a Partial Render

simonince — Thu, 30 Jul 2009 00:01:00 GMT

I had a fun day debugging some ASP.NET plus jQuery this week, and came across something I’ve known is possible for some time, but that I’ve never actually needed to do... and that was to ensure a bit of JavaScript ran once an UpdatePanel had refreshed as part of a partial render.

It turns out that this is easy; all you need to do is register your JavaScript code block with some methods on ScriptManager, rather than using the standard ClientScript methods.

For example, consider the HTML below (I’ve omitted the rest of the page including the script manager, but it is in the download);

<asp:Button

ID="ClickMeButton"

runat="server"

Text="Click Me to Refresh Below"

onclick="ClickMeButton_Click" />

<asp:UpdatePanel

ID="MyUpdatePanel"

runat="server"

UpdateMode="Conditional">

<asp:AsyncPostBackTrigger

ControlID="ClickMeButton"

EventName="Click" />

</Triggers>

Last Updated:

<asp:Label

ID="UpdateTimeLabel"

runat="server" />

</ContentTemplate>

</asp:UpdatePanel>

</div>

</div>

Here we have a simple UpdatePanel, with a button that triggers the async postback. There is also an empty DIV with ID “log”.

In the server-side code of the button click event I have some code that looks a bit like this;

string time = DateTime.Now.ToLongTimeString();

ScriptManager.RegisterStartupScript(

UpdateTimeLabel,

typeof(Label),

"UpdateTimeLabelStartupScript",

CreateScript(time),

true);

The CreateScript function simply returns some JavaScript in a string that reads as follows (the {0} is replace with a time);

$('#log').append('Last Server Run: {0}<br />');

This uses jQuery to append a message to our “log” DIV.

There is also an alternative though; using the Sys.Application.add_load method to attach a page load script function, or creating a pageLoad JavaScript function that is a synonym for the same thing. I’ve done the latter;

function pageLoad() {

$('#log').append('pageLoad executed<br />');

}

This function is executed when the page initially renders and when every partial render completes. This means the content of my “log” DIV rapidly starts to look like this;

pageLoad executed

Last Run: 21:56:12

pageLoad executed

Last Run: 21:56:14

pageLoad executed

Last Run: 21:56:19

pageLoad executed

Easy huh?

I hope that adds some clarity to your options for executing script as the result of a partial postback. Check out the attached if you want to try it yourself.

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?

Monitor your ASP.NET Cache API Behaviour

simonince — Mon, 20 Jul 2009 14:36:00 GMT

Recently I was working on diagnosing a performance issue with a customer’s web site with a colleague (this is one of our favourite engagement types so if you need some help let me know J), and we found that items were being trimmed very regularly from the ASP.NET Cache, causing excessive back-end work, and in turn reduced scalability.

* a “cache trim” is when ASP.NET looks for unused (based on a LRU algorithm) cache entries and deletes them.

So if you’re using the ASP.NET Cache API (or indeed any cache provider) to store custom application data, the moral of the story is to make sure you size your cache appropriately, and monitor it during test and live to see how it behaves.

It is worth knowing that an un-configured ASP.NET Cache takes a memory limit of the minimum of either 60% of physical RAM, or a fixed size RAM. This fixed size is different depending upon your processor architecture - see Thomas Marquardt's post here for some more detail. The idea is that when the limits imposed by configuration are approached, the cache will start trimming.

I’ve attached a very simple ASP.NET application that you can play with to study the cache behaviour while you’re reading the next section. Host it in IIS for the best results.

Setting Cache Limits

It is possible to set limits on how much memory an ASP.NET Application Pool can consume in IIS (see here), and you can also configure behaviour using settings on the cache web.config element. It is important to understand exactly what these mean;

· privateBytesLimit (in web.config, on the cache element): This is the maximum number of bytes that the host process is permitted to consume before the cache is trimmed. In other words, it is not the memory to dedicate to the cache, nor a limit to the memory that the worker process can use... but rather the total memory usage by the w3wp process (in IIS7) at which cache trimming will occur.

· percentagePhysicalMemoryUsedLimit (in web.config, on the cache element): This is the maximum percentage of RAM that the machine can use before the cache is trimmed. So on a 4gb machine with this set to 80%, the cache would be trimmed if Task Manager reported over 3.2gb (i.e. 80% of 4gb) was in use. Note that this is not the percentage memory used by ASP.NET or caching – it is the memory used machine-wide.

· Private Memory Limit (in IIS7 manager, as an advanced property of the App Pool): This is the maximum number of private bytes a worker process can consume before it is recycled (which will of course also empty the cache). If you set this limit lower than privateBytesLimit in web.config, you’ll always get a recycle before a cache trim... which sounds unlikely to be what you would want.

Things to Watch

The remaining content of this post itemises things you should consider monitoring to assess your cache’s performance. Some of it is obvious – but it is surprising how easy it is to overlook the obvious when your boss is breathing down your neck about your slow application J

Overall Application Performance

The best indicator that something might be going wrong is if your application is performing badly. Or maybe it was performing fine, but you’ve changed something or gotten more users, and suddenly it’s not so fast. Make sure you collect timing data in your IIS logs, and use LogParser to parse and analyse them. Also use standard performance counters from ASP.NET, WCF, and whatever other technologies you’re using. Get a feel for where and when things are slow or failing. This isn’t specific to caching, but it is an essential first step!

Hits on the resource you’re caching data from

Do some simple maths on the number of hits your back-end resource is getting. For example, if you have a “GetCities” web service, the results of which are cached for 2 hours, and you have 4 front-end load balanced web servers each with their own cache, you should expect a maximum of 4 hits to that web service every 2 hours. If you’re seeing more than that, alarm bells should be ringing.

Cache Entries

There are some great performance counters for the ASP.NET Cache API, so use those to monitor the state of the cache. Specifically the “ASP.NET Apps\Cache API Entries” counter is the number of items that are in the ASP.NET Cache right now. It should be broadly stable over longer periods with approximately the same load. If you cache an item per user, per region, or anything similar, be aware that this can dramatically affect your cache behaviour and memory consumption... in which case Cache Entries can be quite revealing.

Cache Trims

The “ASP.NET Apps\Cache API Trims” counter is the number of cache items that have been removed due to a memory limit being hit (i.e. they were trimmed). Obviously this should ideally be very low or zero under normal operation. Too many trims could indicate you need to revisit your caching strategy, or manually configure cache memory limits.

Cache Turnover Rate

The “ASP.NET Apps\Cache API Turnover Rate” counter shows the number of newly added and removed/expired/trimmed cache items per second. A target for this number depends on the behaviour of your application, but generally it should be fairly low – ideally items should be cached for quite some time before they expire or are removed. A high turnover rate could imply frequent trims, frequent explicit removals in application code, dependencies firing frequently (e.g. a SqlCacheDependency), or a sudden increase in user load (if, for example, you’re caching something per user).

Private Bytes

Monitoring the “Process\Private Bytes” counter for the w3wp process (assuming you’re using IIS7) tells you how much memory IIS is using for your ASP.NET application. A cache trim is likely to show up as a sudden drop in consumed bytes, and equally you should be able to see how close it is to memory limits for your configuration.

Worker Process Restarts

It is initially a little easy to confuse the cause of a drop in consumed Private Bytes between heavy cache trimming and an Application Pool recycle, so you should also watch the “ASP.NET\Worker Process Restarts” performance counter to ensure you know which happened.

Cache Removed Reasons

When you add items to the ASP.NET cache you can optionally specify a CacheItemRemovedCallback. This means that when the item is removed from the cache the call-back you’ve specified is called, passing in a CacheItemRemovedReason. This is great for adding some debugging instrumentation – if your item was trimmed due to memory pressure then the reason will be “underused”. Other reasons are Expired (you specified a time limit), Removed (you called Cache.Remove) and DependencyChanged (a file, SQL table, or other dependency setup with a CacheDependency was fired).

If you decide to add some logging using this approach I’d recommend adding a switch that enables or disables setting a call-back, as there is a small overhead in dealing with it.

Cache Memory Percentages

There are two slightly mysterious sounding cache counters too. I must admit, at first it took me a few minutes to get my head around exactly what these counters meant.

The first is “ASP.NET Apps\Cache % Machine Memory Limit Used”. This is literally the current physical memory usage by the whole machine as a percentage of the configured (or default) maximum physical memory usage. What?! Well, if you have edited the “percentagePhysicalMemoryUsedLimit” setting to 60%, this means your machine can use up to 60% of its physical memory before cache trimming occurs (not a very realistic example I know!). This counter reports the current usage as a percentage of the maximum... so if your machine is using 40% of available physical RAM, and the limit is 60%, this counter would report 66% (40 divided by 60, multiplied by 100 to get a percentage). It is important to note that this is memory consumed across the whole machine – not just by ASP.NET.

The second is “ASP.NET Apps\Cache % Process Memory Limit Used”. This is the total Private Bytes in use by the current ASP.NET process as a percentage of the limit specified in “privateBytesLimit”. So if you set the limit at 400mb, and your process is currently using 350mb, that would be reported as 87.5% (350 divided by 400, multiplied by 100 to get a percentage).

If either of these counters hits 100% ASP.NET will almost immediately trim 50% of your cache by picking the least recently used items... so obviously you don’t want to be hitting these limits often.

Conclusion

Phew. Well I hope that’s useful stuff. The best advice I can give is to do some real sums. Many customers cache data items per user, plus huge lists of reference data that can grow over time. The end result can be caches that are crippled over a fixed concurrent user level, or take a long time to reload large reference data sets when they have been trimmed. It is more than possible to do some rough maths to work out how much memory your application is using for the cache, and how this changes according to user numbers, regions, languages, locations, roles, user types, base offices, or other parameters – and the results can be very illuminating.

Finally, remember that you should always test using hardware, configuration, and simulated user loads that are as close to live as you can possibly afford, as this gives you the best possible chance of catching problems early.

Detecting Server.Transfer

simonince — Mon, 13 Jul 2009 19:47:00 GMT

How do you know when a page is being rendered as the result of a Server.Transfer, rather than a Response.Redirect or the user browsing directly to a page?

Actually it’s quite easy, assuming you’re using the default ASP.NET pipeline. In reality the “thing” that is responsible for handling an HTTP request is aptly called an HttpHandler – that is, they implement the IHttpHandler interface. Of course, you can create your own handlers if you just want to return a document, or your own manually rendered content, or similar.

But... the Page class also implements IHttpHandler, and ASP.NET therefore uses some cleverness to work out which page should be rendered, and then uses an instance of that Page-derived class as the HttpHandler.

So the bottom line is that if you do a Server.Transfer, the HttpHandler for the request will be the page that was originally being rendered... Therefore, the following code when executed from within a page will display “true” if a Server.Transfer has occurred;

TransferredLabel.Text = (Context.Handler != this).ToString();

Easy huh? Try the attached if you want to see this in action.

Enforcing Unobtrusive JavaScript

simonince — Fri, 10 Jul 2009 21:07:00 GMT

Unobtrusive JavaScript is a concept that’s been around for quite a while, but it’s now finally starting to make its way into the mainstream. The basic idea is that you should separate your JavaScript from your HTML – so instead of;

<a href="Default.aspx" onclick="alert('Sorry, that is unavailable'); return false;" >Click Here</a>

You should have something like this;

<a id="ClickHereLink" href="Default.aspx">Click Here</a>

... with some matching JavaScript in another file somewhere;

function pageLoad() {

var link = $get('ClickHereLink');

$addHandler(link, 'click', preventClick);

}

function preventClick() {

alert('Sorry, that is unavailable');

return false;

}

I’m not here to tell you why this is so great, but the best discussion and walkthrough of issues I’ve found is this article on onlinetools.org, so check it out if you’re interested.

How do I enforce it?

Recently I found myself cursing some code I’d written a long time ago, when I found it littered with onclick and onload handlers. It was frankly a pain to work out how it works. It was at this point that I thought “I should write something to shout at me when I write don’t write unobtrusive JavaScript”.

Coincidentally I have also been doing some work on HTML parsing, and I have to say I’ve found the XPath-like features in the HTML Agility Pack to be incredibly useful. If you’ve never used it I’d recommend taking a look.

It occurred to me that this was the perfect tool to do what I wanted – so I set about creating a simple MSBuild task that uses the HTML Agility Pack to scan ASPX and ASCX files for Obtrusive JavaScript – basically a form of static code analysis. If you’re interested in customising MSBuild, check this out.

The implementation is very simple;

· It is derived from Microsoft.Build.Utilities.Task.

· There is a property that is an array of ITaskItems, flagged with a [Required] attribute, as a way to pass in a list of files to check.

· There’s a hard-coded (for now) list of validation XPath expressions, with matching explanations.

· In the Execute method override, it loops through all the files.

· For each file, it opens the HTML and applies every XPath to it.

· If there are any matches for the XPath, it creates a build failure.

The key to success here is the simplicity with which the HTML Agility Pack lets me use XPath to find elements. The following is the basics of my code;

HtmlDocument doc = new HtmlDocument();

doc.Load(path);

HtmlNodeCollection results =

doc.DocumentNode.SelectNodes(

validator.SearchXPath);

Easy huh? The XPath expressions themselves mostly look like this;

//*[@onkeypress]

This will match any HTML element that has an onkeypress attribute... which of course means that the developer has specified a JavaScript event handler in the HTML, and broken the rules of unobtrusivitiy (hey, if that’s not a word I’m having first dibs on inventing it J).

Remembering that we’re actually scanning ASP.NET mark-up, not pure HTML, we can also check for ASP.NET attributes that actually create JavaScript event handlers in HTML too;

//*[@onclientclick]

Again, this is not difficult. The tricky one appears when you realise that it is valid to have OnClick in ASP.NET code! Of course, an <asp:button> can have an OnClick attribute referring to the server-side event handler. I wondered about saying “match any with an onclick that don’t have a runat attribute”, but this isn’t quite accurate (HtmlControls can have runat=”server” too remember).

In the end I went for explicitly excluding the ASP.NET controls that I knew were OK to use OnClick;

//*[@onclick and not(

name()='asp:button' or name()='asp:bulletedlist' or

name()='asp:imagebutton' or name()='asp:imagemap' or

name()='asp:linkbutton')]

Finally, I wanted to check that there was no JavaScript inside the page HTML itself... even between <script> tags. In other words, the only valid <script> tags should reference an external file, as follows;

[Of course, you could also use the <asp:ScriptManager> control if you wanted to; in fact I’d prefer it]

To achieve this I check that there is nothing other than whitespace between the start and end script tags;

//script[string-length(normalize-space(text()))>1]

... and that’s it! As usual, the source code for this MSBuild Task is attached to this post, along with a demonstration Web App.

Wiring up the Task

Now we have a simple MSBuild task, all that is left to do is add it to a build. I created a new ASP.NET Web Application, right clicked the project file and chose “unload”, and then edited the XML manually.

The only bit I needed to add was as follows;

<UsingTask

AssemblyFile="..\JsBuildTasks.dll"

TaskName="ValidateUnobtrusive" />

<ValidateUnobtrusive

SourceFiles="@(Content)" />

</Target>

First I import my task (I’ve copied a Release build of the assembly to the parent directory above my Web App project). Next, I override the BeforeBuild target, and add an instance of my ValidateUnobtrusive task. I’ve passed in an expansion of all the Content files in the project. The task filters for *.aspx and *.ascx at the moment – if you wanted to add *.html that would be trivial.

Save the file, and right click it to choose Reload Project. At this point Visual Studio 2008 warns you about a customised MSBuild project file – just choose “Load Project Normally” and you’re away.

From this point on, whenever you build a project containing Obtrusive JavaScript you’ll see errors like these;

Error Use of the 'onclick' JavaScript event on 'a' tag in markup causes Obtrusive Javascript. You should attach this handler in script instead.

Error Failed on 'script' tag . A JavaScript region containing something other than white space was found. You should link to related JavaScript resources files rather than embed script in a page.

Conclusion

I think this works really well so far (although I’m at the early stages of trialling it); if you try it do let me know how you get on. One of the particularly cool things (that I haven’t tried yet as I’m working isolated on my laptop most of the time right now, and I’m short of time) is that this could be wired up into a Continuous Integration build, under Team Build – I guess that would be a good plan if you didn’t like running the validation as part of your local build, or if it starts to perform badly due to the complexity or size of your pages.

I also think it raises other questions and possibilities. For example; how about some static analysis of “.js” files themselves? Could this help check for Directly Accessible Scripts, for example?

Using Anchor Links with AJAX History

simonince — Wed, 24 Jun 2009 20:49:00 GMT

A customer asked me about doing this the other day, and I’d never come across it, although it seems obvious now! If I have a page that makes use of ASP.NET’s server-side ScriptManager AJAX history features but also want to link to an anchor on that page, I get problems.

For example, if I have a page like this;

... imagine (or try the download!) that I can click the “here” link to jump to an anchor defined further down the page as follows;

<h1><a id="bottom">Bottom</a></h1>

<p>

This is at the bottom.

Click <a href="#">here</a> to jump to the top.

</p>

Nothing complex... until I point out that the drop-down list and Person details are in an UpdatePanel, and that when the user selects a different user, server-side code such as the following is run (note that Person.All is a very basic repository of test data);

var selectedId =

Int32.Parse(PeopleList.SelectedItem.Value);

var selected =

Person.All.Where(p => p.Id == selectedId).Single();

if (PageScriptManager.IsInAsyncPostBack)

PageScriptManager.AddHistoryPoint(

PersonIdHistoryKey,

selectedId.ToString(),

String.Format("Viewing {0}", selected.Name));

This adds a “history point” to the URL that I can use to reload the correct Person should the user bookmark the page and revisit another time. The key here is how it encodes it – the fragment of the URL after the hash is used (note I’ve disabled the encryption for this post);

http://myserver/Default.aspx#&&PersonIdHistoryKey=3

Of course, if I now click on my “click here” link shown above, the target anchor (“#bottom”) will replace the AJAX history state data. If you want to see what I mean, download my demo solution and delete the component we’re about to write from the page.

A Solution

I thought about this for a while, and came up with an interesting and reusable solution. I created an ASP.NET Extender component that is used to “extend” the ScriptManager control. This extender emits an ASP.NET AJAX JavaScript behaviour that supplies some additional client-side functionality.

Specifically, when the behaviour is initialised, it performs the following actions;

// add a handler for the navigate event

var navigateDelegate =

Function.createDelegate(this, this.handleNavigate);

Sys.Application.add_navigate(navigateDelegate);

// when the page is loaded, scan for every link that

// targets a "#something" anchor and add a "click"

// javascript handler to it

var clickDelegate =

Function.createDelegate(this, this.handleClick);

Sys.Application.add_load(function() {

$('a[href^=#]').click(clickDelegate);

});

Basically we’re doing two things here – firstly, hooking up to the client-side “navigate” event that is fired when a page loads that has client-side History information embedded in the URL... this is done in the same way as for the server-side history portion we saw above, but after the # and before the && symbols. Have a read of this walkthrough for a bit more info on the client-side aspect to AJAX history.

Secondly we’re adding some code to run once the page has finished loading. This code uses a jQuery selector to find all “a” (anchor) tags for which the HREF begins with a # symbol. Once these have been identified, a click event handler is assigned to them all. This means we’re applying functionality to every link on the page that targets a local anchor mark with a single statement – nice!

There are then two more elements to the solution; handleClick (fired when the user clicks on one of these “a” tags), and handleNavigate (fired when a page loads that contains client-side history markers).

handleClick

When a user clicks on link to a local anchor (i.e. of the form “#something”) we run the following script;

var eventSource = args.target;

var parts = eventSource.href.split('#');

if (parts && parts.length > 1) {

var target = parts[1];

Sys.Application.addHistoryPoint({ jumpTo: target }, document.title);

if (target) {

var targetElement = $get(target)

if (targetElement)

this._scrollToElement(targetElement);

}

else

window.scrollTo(0, 0);

return false;

}

What this does is three things;

1. It finds the link that caused the event, and splits out the portion of the URL after the “#” – which of course is the ID of the anchor we want to navigate to.

2. It adds a client-side history point, including the name of the target anchor we want to display as an expando property called “jumpTo” on an anonymous object. This means we can recreate the behaviour if the user bookmarks the page.

3. It finds the target element and scrolls it into view. If the target is blank, it assumes we’re aiming for the top of the page.

Easy huh?!

handleNavigate

This function is fired when a page loads, if it contains client-side history information.

var target = args.get_state().jumpTo;

if (target) {

var targetElement = $get(target);

if (targetElement)

this._scrollToElement(targetElement);

}

All this does is to extract the data from the history state that we encoded in the handleClick function – we’re after the value of the “jumpTo” expando property. Once it has that, it tries to find the element on the page, and if it is found, scrolls it into view.

Summary

The end result is a URL that can look something like this;

http://myserver/Default.aspx#jumpTo=bottom&&PersonIdHistoryKey=1

... it should be obvious that we have both a client-side (in red) and server-side (in green) portion encoded here.

This component is so easy to use – we can just drop it onto a page, extending the ScriptManager control, and immediately enabling the handling of local anchor references without customising the HTML. Of course, if JavaScript is disabled, it will still work fine.

Let me know what you think – there are plenty of ways to enhance or alter this behaviour if it doesn’t work quite how you want it to (for example, you might not like it returning to the same place after every postback, or you might need to use client-side history for both this and something else at the same time). I’d also love to hear if you use it and have some feedback.

I’ve attached the source (usual disclaimers apply – this is not production strength code) so download it and have play.

Using ASP.NET Dynamic Data in an existing Web Site

simonince — Fri, 01 May 2009 15:39:00 GMT

One of the tasks I used to hate when building a new system was adding admin pages to allow simple create/update functionality for lookup data. For example, maintaining a simple list of Products. It takes ages to write, and is very boring – even if you write templates to generate code it consumes a lot of time for such a commonly repeated and simple task.

ASP.NET Dynamic Data has now arrived, which gives a great way to “scaffold” CRUD pages over an Entity Framework Object Context (or other sources). But what if I have a web site that is mostly a line-of-business system, with complex business logic and custom UI, and I need to administer a small set of tables too?

Well, you can add Dynamic Data to a portion of your existing web site! This means you no longer need to write your own administration pages.

* Before you start off on this merry path, read this to make sure the relevant sections of your Entity Framework model are supported by Dynamic Data... for example, Complex Types are not.

How?

There’s a walkthrough that covers adding Dynamic Data to an existing web site here, so give that a read and you’ll be 80% of the way there. [Note: I also had to add a reference to System.Web.Entity at the end of the walkthrough to get it all working]

Next, make sure you have set ScaffoldAllTables to false – the last thing you want to do is expose your non-lookup data for direct editing by admin staff. All that should be exposed is a few key tables of static data. So, in Global.asax, make sure your data model registration looks like this;

model.RegisterContext(

typeof(OrderDbEntities),

new ContextConfiguration()

{ ScaffoldAllTables = false });

But how does the user get to this administration functionality? I’d recommend putting it under a virtual subfolder in your web site – perhaps named “Admin”. This is really just a route (read up on the new ASP.NET Routing features if this is unfamiliar) and needn’t really exist as a physical folder. So in Global.asax, we set it up as follows;

routes.Add(new DynamicDataRoute("Admin/{table}/{action}.aspx")

{

Constraints = new RouteValueDictionary(

new { action = "List|Details|Edit|Insert" }),

Model = model

});

Note that my route begins with “Admin/...”, which means the user will browse to URLs as follows to get to the admin pages;

http://{add address here}/myfakewebsite/Admin/Product/List.aspx

You can of course link to these pages from elsewhere within your site to save the user typing them in.

At the moment, we’re not scaffolding any of our tables, so none of these URLs will work yet. The next step, then, is to pick a table to expose for administration. I’m going to use a Product table that has ID, Description, Price and CreatedBy/CreatedDate fields. In my EF model the entity also has an OrderItems navigation property which allows me to get all Order Item records that are an instance of an order for the current product...

Due to the way EF supports partial classes, I can tell the Dynamic Data runtime to scaffold the Product table using an attribute (from the System.ComponentModel.DataAnnotations namespace & assembly) on a partial class. I added a C# class to the Web Site with the same namespace as the Entity Framework model, and pasted in the following code;

[ScaffoldTable(true)]

public partial class Product

{

}

Immediately this attribute is added the Product table is available for editing. There are a few problems when I browse to the new page though;

1. It is displaying the link to Order Items even though it isn’t editable (because Order Item isn’t scaffolded).

2. I can edit the columns I’m using for Audit – CreatedBy and CreatedDate. Not good.

It turns out changing this is quite easy. Using some additional attributes and a metadata class as follows customises the model sufficiently (see here for more info on this metadata class approach);

[MetadataType(typeof(ProductMetadata))]

[DisplayColumn("Description")]

[ScaffoldTable(true)]

public partial class Product

{

}

public class ProductMetadata

{

[UIHint("TextReadOnly")]

public string CreatedBy;

[UIHint("TextReadOnly")]

public string CreatedDate;

[ScaffoldColumn(false)]

public EntityCollection<OrderItem> OrderItem;

}

I’ve now instructed the runtime not to display the Order Item navigation property, and to use the Description field should I display Products in a list somewhere (as part of a foreign key drop-down, for example).

I’ve also asked it to use the “TextReadOnly” user control to render my CreatedDate and CreatedBy fields instead of the standard Text control, by placing a [UIHint] attribute on two metadata properties. To create the TextReadOnly control I copied-and-pasted the “Text.ascx” control twice, and renamed the copies to “TextReadOnly.ascx” and “TextReadOnly_Edit.ascx”. This control will now be used whenever the CreatedDate and CreatedBy fields are displayed (note I’ve cheated here – CreatedDate is really a date but as I’m happy with the default ToString display mechanism for it I didn’t bother creating a DateTime ReadOnly control).

As you can see, these user controls are available for you to edit under the DynamicData/FieldTemplates folder that was copied in as part of the original walkthrough. If you want to change this folder to be somewhere else, check out this article.

Finally, we probably want to limit access to the admin pages to a limited set of privileged users. The easiest way to do this is using standard ASP.NET authorisation, by adding a location and authorisation element to web.config;

<system.web>

</authorization>

</system.web>

</location>

Next steps...

There’s plenty more you might like to do, so I would recommend looking further into the features that Dynamic Data provides.

One that is particularly likely to be of interest is customising validation of data that is maintained... a good starting point is the ValidationAttribute.

You probably also want to change Site.master to better reflect your site (or move it, rename it, and update the templates under DynamicData/PageTemplates to use the new one). As long as you have a ScriptManager and the required Content Placeholder on there, it should work great. You can obviously make use of your own CSS too, or even go as far as changing all the field templates.

If you’d like a general overview of how Dynamic Data fits together, have a read of the Infrastructure Overview.

Finally, remember that I’m basing mine on an Entity Framework model, so I could customise the model too – for example, hooking up to the SavingChanges event to perform processing and/or validation on the Product table before it is saved to the database.

I hope all that is useful, and saves you time and boredom for your next system... enjoy!

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.

AJAX Script Patterns: Service Agent

simonince — Fri, 05 Dec 2008 00:45:00 GMT

I’ve been thinking for a while about how people tend to build AJAX applications, as there seems to be something a lot of people have forgotten. This post examines how applying a pattern you probably know very well to AJAX could help – and leaves it to you to decide whether this is useful. Let me know what you think.

Setting the Scene

In your average application architecture, you’ll generally find a “Resource Access” layer that contains Service Agents (also known as Service Gateways) for accessing remote web services. What are these for? Well, I think the MSDN documentation on the pattern sums it up nicely in the Problem statement;

“How do you decouple the details of fulfilling the contract responsibilities defined by the [remote web] service from the rest of your application?”

The answer is of course that you create a class to manage the interaction with your service and hide the inner workings and contract implementations from the rest of your code. This class and any supporting entities make up your Service Agent.

AJAX: Why so Different?

With the growing popularity of AJAX, and the great features available in Microsoft AJAX, more and more web sites use script to call services hosted back on the ASP.NET server to load data, and dynamically update the page with DOM operations.

So how come so many sites have forgotten what we learnt years ago? This script calls a web service – and this web service forms a part of a larger system. It may change – the contracts, the implementation, the name, the location... Consider that these web services may also be shared between AJAX, Silverlight, ASP.NET, WPF, and/or other technologies as clients. So each of these could require tweaks to your shared web service (even if they’re using a different endpoint that uses a different binding, chances are the contracts and implementation are shared).

Microsoft AJAX helps us by auto-generating the web service proxy and related entities for calling a script-enabled web service. But if you change the web service, this changes the generated proxy, and you could find many pages in your web site suddenly need JavaScript changes to work correctly again. We don’t get the rich compile-time support in JavaScript that we get with .NET languages, so you might not find these problems until testing, or worse, live.

Therefore I see two options for handling this;

1. You could create a reusable ASP.NET AJAX server control that wraps up the web service calls and UI manipulation. This means you’ve just got one place to make changes, so is a great solution.

2. If the service is used differently in each place, perhaps it just doesn’t suit being a control. In which case, I propose creating a script-based Service Agent.

A Simple Example

To demonstrate this, I’ve created the bare minimum of a simple WCF service to be called from AJAX;

[ServiceContract(

Namespace =

"http://samples.microsoft.com/jslayering")]

[AspNetCompatibilityRequirements(

RequirementsMode =

AspNetCompatibilityRequirementsMode.Allowed)]

public class PersonService

{

[OperationContract]

public GetPersonResponse GetPerson(

GetPersonRequest request)

{

Implementation

}

[MessageContract]

public class GetPersonRequest

{

[MessageBodyMember]

public int Identifier { get; set; }

}

[MessageContract]

public class GetPersonResponse

{

[MessageBodyMember]

public bool Found { get; set; }

[MessageBodyMember]

public Person Person { get; set; }

}

[DataContract]

public class Person

{

[DataMember]

public int Identifier { get; set; }

[DataMember]

public string Name { get; set; }

[DataMember]

public int Age { get; set; }

}

You can see I’ve also chosen to use Message Contracts... we’ll see why in a moment J

All that happens in this service is the client requests a Person’s details, and they either get Found=true and a Person entity back, or Found=false. In my implementation this is hard-coded and randomised, so excuse the grim code.

Creating a Service Agent

The first thing we need is a JavaScript entity to hold person details in. This is because the Person class above is part of the contract of the web service – so if we change it, the JavaScript entity generated by Microsoft AJAX will change too... so we need to protect the rest of our JavaScript code from this. Let’s see my simple entity;

/// <reference name="MicrosoftAjax.js"/>

/// <reference path="~/PersonService.svc" />

Type.registerNamespace("ServiceAgents");

ServiceAgents.Person = function(id, name, age) {

this._id = id;

this._name = name;

this._age = age;

}

ServiceAgents.Person.prototype = {

get_id: function() {

return this._id;

get_name: function() {

return this._name;

get_age: function() {

return this._age;

}

ServiceAgents.Person.registerClass(

'ServiceAgents.Person');

if (typeof (Sys) !== 'undefined')

Sys.Application.notifyScriptLoaded();

* Note the use of the <reference> tag so I get intellisense in Visual Studio 2008!

This is the simplest of objects, and just stored the three fields found on a Person entity. Next, we need a Service Agent. I’ve chosen to create this as a component (inherited from Sys.Component) mainly because I might want to add event handlers and more to it another time, so having it as a managed disposable object is potentially useful.

/// <reference name="MicrosoftAjax.js"/>

/// <reference path="~/PersonService.svc" />

/// <reference path="Person.js" />

Type.registerNamespace("ServiceAgents");

ServiceAgents.PersonServiceAgent = function() {

ServiceAgents.PersonServiceAgent.

initializeBase(this);

}

ServiceAgents.PersonServiceAgent.prototype = {

initialize: function() {

ServiceAgents.PersonServiceAgent.

callBaseMethod(this, 'initialize');

dispose: function() {

ServiceAgents.PersonServiceAgent.

callBaseMethod(this, 'dispose');

GetPerson: function(identifier, callback) {

var success = Function.createDelegate(

this, this._onSuccess);

var failure = Function.createDelegate(

this, this._onFailure);

// call the web service

samples.microsoft.com.jslayering.PersonService.

GetPerson(identifier, success, failure, callback);

_onSuccess: function(result, context) {

// check we got a result back

if (!result.Found)

this._onFailure({ get_message: function()

{ return 'Person not found'; } },

context);

else {

// translate to our Person entity

var returnentity = new ServiceAgents.Person(

result.Person.Identifier,

result.Person.Name,

result.Person.Age);

// call the callback that was passed in

context(returnentity);

}

_onFailure: function(result, context) {

alert('A call to the Person Service failed: '

+ result.get_message());

}

ServiceAgents.PersonServiceAgent.registerClass(

'ServiceAgents.PersonServiceAgent', Sys.Component);

// ensure an instance of this component is created

// when the page is initialising

if (typeof (Sys) !== 'undefined') {

Sys.Application.add_init(

function() {

$create(

ServiceAgents.PersonServiceAgent,

{ id: 'PersonSA' },

null, null, null);

});

Sys.Application.notifyScriptLoaded();

}

There are four things to note in this component;

1. The only public method we’ve added is GetPerson. This literally sets up some call-backs and passes the call on to the auto-generated script proxy.

2. When the call succeeds, we check a result was found (using the Found property on the Message Contract) and if it was, we create a new instance of our own Person entity to pass back, by calling the supplied call-back method.

3. If there’s a failure we handle it; I could have let the caller do this, but this component is for illustrative purposes only... it is by no means perfect and I wanted to keep it quite brief!

4. We ensure an instance of our component is created when the page initialises, so that page script can easily consume it.

Using the Service Agent

Making use of this component is easy – we need to import the relevant services and scripts, and then get a reference to it using the $find method, and call it! First I register the scripts with a ScriptManager. We still need to point out on every page that we want to import the service, and now have to specify our Service Agent scripts too;

<asp:ScriptManager

ID="PageScriptManager"

runat="server">

<asp:ServiceReference

Path="~/PersonService.svc" />

</Services>

<asp:ScriptReference

Path="~/Scripts/Person.js" />

<asp:ScriptReference

Path="~/Scripts/PersonServiceAgent.js" />

</Scripts>

</asp:ScriptManager>

Then I’ve got the following script on my page;

function getPerson() {

var id = $get('RequestIdentifierTextBox').value;

var serviceAgent = $find('PersonSA');

serviceAgent.GetPerson(id, displayPerson);

// prevent post-back as we've handled it client side

return false;

}

function displayPerson(result) {

$get('IdentifierLabel').innerHTML = result.get_id();

$get('NameTextBox').value = result.get_name();

$get('AgeTextBox').value = result.get_age();

}

... which drives a page that looks like this;

Breaking the Application

Well this is not worthwhile unless we can demonstrate a tangible benefit. Imagine that code similar to that above is scattered throughout our web site, and we have many pages to maintain. Now imagine that our web service needs to change. Maybe the XML namespace is updated... or maybe we decide to rip out all of our Message Contracts (a bit contrived, but it demonstrates what we’re talking about!). My service becomes;

[ServiceContract(

Namespace =

"http://samples.microsoft.com/jslayering")]

[AspNetCompatibilityRequirements(

RequirementsMode =

AspNetCompatibilityRequirementsMode.Allowed)]

public class PersonService

{

[OperationContract]

public Person GetPerson(int identifier)

{

Implementation

}

Immediately our auto-generated proxy changes and the JavaScript code breaks. There’s no Found property anymore, we just get a null Person back if there is no match. And we can’t access a Person property on the Message Contract because it isn’t there... we’ve got a Person instead.

Obviously applying these changes site-wide would be a real headache. But for us, it’s easy. We just change a few lines! We’ll just tweak our _onSuccess call-back in the Service Agent;

_onSuccess: function(result, context) {

// note we only check for a result, not result.Found

if (!result)

this._onFailure({ get_message: function()

{ return 'Person not found'; } },

context);

else {

// note the changes when building our return entity –

// no ".Person." message contract syntax

var returnentity =

new ServiceAgents.Person(

result.Identifier,

result.Name,

result.Age);

context(returnentity);

}

Hey presto! Our site works again, and you can leave the office at a sensible time!

Conclusion

Obviously this is extra coding effort to put together a Service Agent, but do you see the benefits? Is it worthwhile? What about other patterns? How about View-Presenter, for example? Do they apply to JavaScript? Do you use this kind of approach already?

I’d love to know what you think, and what you do right now... feel free to comment or blog back at me.

The attached code should demonstrate all this – there are “-before” and “-after” web sites, both containing implementations of this page with a Service Agent and using direct calls against the auto-generated proxy.

In the “after” site I’ve removed the Message Contracts and tweaked the Service Agent... but I haven’t fixed the direct proxy calls so you can see how it breaks.

Enjoy...

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