July 2009
Silverlight: Composite Web Apps With Prism
This article reviews the Prism project developed by the Microsoft patterns & practices group and demonstrates how to apply it to composite Web applications using Silverlight. Shawn Wildermuth
RESTful XHTML: RESTful Services With ASP.NET MVC
This article describes how to use XHTML and ASP.NET MVC to implement REST services. Aaron Skonnard
Scale Out: Distributed Caching On The Path To Scalability
Developers frequently face issues related to scalability bottlenecks when they have applications that need to handle a lot of load. This article describes the role of a distributed cache in building scalable applications. Iqbal Khan
Inside Windows 7: Introducing The Taskbar APIs
This is Part 2 of a multipart article series on Windows 7. The focus of Part 2 is the Windows 7 taskbar. Yochay Kiriaty & Sasha Goldshtein
Testable MVC: Building Testable ASP.NET MVC Applications
Justin Etheredge
Columns
Editor's Note: Viva la Evolution!: | Toolbox: Static Analysis Database Tools, Managing Remote Computers, And More: If you want to apply static analysis to your databases, connect to remote computers, find out more about the Entity Framework, or just check into some cool podcasts for your daily commute, then you'll want to read more about these latest tools and resources.Scott Mitchell | CLR Inside Out: Building Tuple: In this column, the author lays out some guiding principles that you should follow when working with the ASP.NET MVC framework.Matt Ellis
Basic Instincts: Stay Error Free With Error Corrections: Error corrections are an essential part of the Visual Basic coding experience. This article explores the many error correction features offered by Visual Basic and provides a glimpse at the future release of Visual Studio 2010.Dustin Campbell | Cutting Edge: Comparing Web Forms And ASP.NET MVC: In this month's column, we’ll explore the pros and cons of both ASP.NET Web Forms and ASP.NET MVC.Dino Esposito | Test Run: Request-Response Testing With F#: This month we show you how to use F# to perform HTTP request-response testing for ASP.NET Web applications.James McCaffrey
Service Station: More On REST: This month's column answers frequently asked questions about implementing REST.Jon Flanders | Extreme ASP.NET: Guiding Principles For Your ASP.NET MVC Applications: In this column, the author lays out some guiding principles that you should follow when working with the ASP.NET MVC framework.Scott Allen | Wicked Code: Taking Silverlight Deep Zoom To The Next Level: With the help of Silverlight Deep Zoom and a remarkable control named MultiScaleImage, you can create scenes with many levels of zoom. Jeff Prosise illustrates with what else but the Mandlebrot set.Jeff Prosise
Foundations: Securing The .NET Service Bus: This column shows you how to secure the .NET Services Bus and also provides some helper classes and utilities to automate many of the details.Juval Lowy


Silverlight
Composite Web Apps With Prism
Shawn Wildermuth
Code download available from the MSDN Code Gallery
Browse the Code Online

This article discusses:
  • Silverlight 2
  • Application composition
  • Dependency injection
This article uses the following technologies:
Silverlight 2, Prism
Contents
Why Prism?
Introducing Dependency Injection
Startup Behavior
Modularity
UI Composition
Event Aggregation
Delegate Commands
Wrapping Up
Your first experience with Silverlight was probably something small: a video player, a simple charting application, or even a menu. These types of applications are simple and straightforward to design, and segmenting them into rigorous layers with separate responsibilities is overkill.
Problems surface, however, when you try to apply a tightly coupled style to large applications. As the number of moving parts grows, the simple style of application development falls apart. Part of the remedy is layering (see my article "Model-View-ViewModel In Silverlight 2 Apps"), but a tightly coupled architecture is just one of a number of problems that need to be solved in large Silverlight projects.
In this article, I show you how to build an application using the composition techniques of the Composite Application Library from the Prism project. The example I develop is a simple editor of database data.

As requirements change and a project matures, it is helpful if you can change parts of the application without having these changes cascade throughout the system. Modularizing an application allows you to build application components separately (and loosely coupled) and to change whole parts of your application without affecting the rest of the code.
Also, you might not want to load all the pieces of your application at once. Imagine a customer management application in which users log on and can then manage their prospect pipeline as well as check e-mail from any of their prospects. If a user checks e-mail several times a day but manages the pipeline only every day or two, why load the code to manage the pipeline until it is needed? It would be great if an application supported on-demand loading of parts of the application, a situation that can be addressed by modularizing the application.
The patterns & practices team at Microsoft created a project called Prism (or CompositeWPF) that is meant to address problems like these for Windows Presentation Foundation (WPF) applications, and Prism has been updated to support Silverlight as well. The Prism package is a mix of framework and guidance for building applications. The framework, called the Component Application Library (CAL), enables the following:
  • Application modularity: Build applications from partitioned components.
  • UI composition: Allows loosely coupled components to form user interfaces without discrete knowledge of the rest of the application.
  • Service location: Separate horizontal services (for example, logging and authentication) from vertical services (business logic) to promote clean layering of an application.
The CAL is written with these same design principles in mind, and for application developers it is a buffet-style framework—take what you need and leave the rest. Figure 1 shows the basic layout of the CAL in relation to your own application.
Figure 1 Composite Application Library
The CAL supports these services to aid you in composing your application from smaller parts. This means the CAL handles which pieces are loaded (and when) as well as providing base functionality. You can decide which of these capabilities help you do your job and which might get in the way.
My example in this article uses as much of the CAL as possible. It is a shell application that uses the CAL to load several modules at run time, place views in regions (as shown in Figure 2), and support services. But before we get to that code, you need to understand some basic concepts about dependency injection (also called Inversion of Control, or IoC). Many of the CAL's features rely on dependency injection, so understanding the basics will help you develop the architecture of your Silverlight project with Prism.
Figure 2 Composite Application Architecture

Introducing Dependency Injection
In typical development, a project starts with an entry point (an executable, a default.aspx page, and so on). You might develop your application as one giant project, but in most cases some level of modularity exists in that your application loads a number of assemblies that are part of the project. The main assembly knows what assemblies it needs and creates hard references to those pieces. At compile time, the main project knows about all the referenced assemblies, and the user interface consists of static controls. The application is in control of what code it needs and usually knows all the code it might use. This becomes a problem, however, because development takes place inside the main application project. As a monolithic application grows, build time and conflicting changes can slow down development.
Dependency injection aims to reverse this situation by providing instructions that set up dependencies at run time. Instead of the project controlling these dependencies, a piece of code called a container is responsible for injecting them.
But why is this important? For one thing, modularizing your code should make it easier to test. Being able to swap out a project's dependencies enables cleaner testing so that only the code to be tested can be the source of a test failing, instead of code somewhere in the nested chain of dependencies. Here's a concrete example. Imagine you have a component that other developers use to look up addresses for particular companies. Your component depends on a data access component that retrieves the data for you. When you test your component, you start by testing it against the database, and some of the tests fail. But because the schema and builds of the database are constantly changing, you don't know whether your tests are failing because of your own code or the data access code. With your component's hard dependency on the data access component, testing the application becomes unreliable and causes churn while you track down failures in your code or in other's code.
Your component might look something like this:
public class AddressComponent
{
  DataAccessComponent data = new DataAccessComponent();

  public AddressComponent()
  {
  }

  ...
}
Instead of a hard-wired component, you could accept an interface that represents your data access, as shown here:
public interface IDataAccess
{
  ...
}

public class AddressComponent
{
  IDataAccess data;

  public AddressComponent(IDataAccess da)
  {
    data = da;
  }

  ...
}
Ordinarily, an interface is used so you can create a version that allows you to adjust your code. This approach is often called "mocking." Mocking means creating an implementation of the dependency that does not actually represent the real version. Literally, you're creating a mock implementation.
This approach is better because the dependency (IDataAccess) can be injected into the project during construction of the object. The implementation of the IDataAccess component will depend on the requirements (testing or real).
That's essentially how dependency injection works, but how is the injection handled? The job of the container is to handle creation of the types, which it does by allowing you to register types and then resolving them. For example, assume you have a concrete class that implements the IDataAccess interface. During start up of the application, you can tell the container to register the type. Anywhere else in your application where you need the type, you can ask the container to resolve the type, as shown here:
public void App_Startup()
{
  container.RegisterType<IDataAccess, DbDataAccess>();
}

...

public void GetData()
{
  IDataAccess acc = container.Resolve<IDataAccess>();
}
Depending on the situation (testing or production), you can swap out the implementation of IDataAccess simply by changing the registration. Additionally, the container can handle construction injection of dependencies. If an object that needs to be created by the container's constructor takes an interface that the container can resolve, it resolves the type and passes it to the constructor, as shown in Figure 3.
Figure 3 Type Resolution by the Container
public class AddressComponent : IAddressComponent
{
  IDataAccess data;

  public AddressComponent(IDataAccess da)
  {
    data = da;
  }
}

...

public void App_Startup()
{
  container.RegisterType<IAddressComponent, AddressComponent>();
  container.RegisterType<IDataAccess, DbDataAccess>();
}

public void GetAddresses()
{
  // When we ask the container to create the AddressComponent,
  // it sees that a constructor takes a IDataAccess object
  // so it automatically resolves that dependency
  IAddressComponent addr = container.Resolve<IAddressComponent>();
}
Notice that the AddressComponent's constructor takes an implementation of IDataAccess. When the constructor creates the AddressComponent class during resolution, it automatically creates the instance of IDataAccess and passes it to the AddressComponent.
When you register types with the container, you also tell the container to deal with the lifetime of the type in special ways. For example, if you are working with a logging component, you might want to treat it as a singleton so that every part of the application that needs logging does not get its own copy (which is the default behavior). To do this, you can supply an implementation of the abstract LifetimeManager class. Several lifetime managers are supported. ContainerControlledLifetimeManager is a singleton per process and PerThreadLifetimeManager is a singleton per thread. For ExternallyControlledLifetimeManager, the container holds a weak reference to the singleton. If the object is released externally, the container creates a new instance, otherwise it returns the live object contained in the weak reference.
You use the LifetimeManager class by specifying it when registering a type. Here's an example:
container.RegisterType<IAddressComponent, AddressComponent>(  new ContainerControlledLifetimeManager());
In the CAL, the IoC container is based on the Unity framework from the patterns & practices group. I'll use the Unity container in the following examples, but there are also a number of open source alternatives to the Unity IoC container, such as Ninject, Spring.NET, Castle, and StructureMap. If you are familiar with and already using an IoC container other than Unity, you can supply your own container (although it takes a little more effort).

Startup Behavior
Ordinarily in a Silverlight application, the startup behavior is simply to create the main XAML page's class and assign it to the application's RootVisual property. In a composite application, this work is still required, but instead of creating the XAML page class, a composite application typically uses a bootstrapping class to handle startup behavior.
To start, you need a new class that derives from the UnityBootstrapper class. This class is in the Microsoft.Practices.Composite.UnityExtensions assembly. The bootstrapper contains overridable methods that handle different parts of startup behavior. Often, you will not override every startup method, only the ones necessary. The two methods you must override are CreateShell and GetModuleCatalog.
The CreateShell method is where the main XAML class is created. This is typically called the shell because it is the visual container for the application's components. My example includes a bootstrapper that creates a new instance of the Shell class and assigns it to RootVisual before returning this new Shell class, as shown here:
public class Bootstrapper : UnityBootstrapper
{
  protected override DependencyObject CreateShell()
  {
    Shell theShell = new Shell();
    App.Current.RootVisual = theShell;
    return theShell;
  }

  protected override IModuleCatalog GetModuleCatalog()
  {
    ...
  }
}
The GetModuleCatalog method, which I'll explain in the next section, returns the list of modules to load.
Now that you have a bootstrapper class, you can use it in your Silverlight application's startup method. Usually, you create a new instance of the bootstrapper class and call its Run method, as shown in Figure 4.
Figure 4 Creating an Instance of the Bootstrapper
public partial class App : Application
{

  public App()
  {
    this.Startup += this.Application_Startup;
    this.Exit += this.Application_Exit;
    this.UnhandledException += this.Application_UnhandledException;

    InitializeComponent();
  }

  private void Application_Startup(object sender, StartupEventArgs e)
  {
    Bootstrapper boot = new Bootstrapper();
    boot.Run();
  }

  ...
}
The bootstrapper is also involved in registering types with the container that different parts of the application require. To accomplish this, you override the ConfigureContainer method of the bootstrapper. This gives you a chance to register any types that are going to be used by the rest of the application. Figure 5 shows the code.
Figure 5 Registering Types
public class Bootstrapper : UnityBootstrapper
{
  protected override void ConfigureContainer()
  {
    Container.RegisterType<IShellProvider, Shell>();
    base.ConfigureContainer();
  }

  protected override DependencyObject CreateShell()
  {
    // Get the provider for the shell
    IShellProvider shellProvider = Container.Resolve<IShellProvider>();

    // Tell the provider to create the shell
    UIElement theShell = shellProvider.CreateShell();

    // Assign the shell to the root visual of our App
    App.Current.RootVisual = theShell;

    // Return the Shell
    return theShell;
  }

  protected override IModuleCatalog GetModuleCatalog()
  {
    ...
  }
}
Here, the code registers an interface for a class that implements the IShellProvider interface, which is created in our example and is not part of the CAL framework. That way we can use it in our implementation of the CreateShell method. We can resolve the interface and then use it to create an instance of the shell so we can assign it to RootVisual and return it. This methodology may seem like extra work, but as you delve into how the CAL helps you build your application, it becomes clear how this bootstrapper is helping you.

Modularity
In a typical .NET environment, the assembly is the main unit of work. This designation allows developers to work on their code separately from each other. In the CAL, each of these units of work is a module, and for the CAL to use a module, it needs a class that can communicate the module's startup behavior. This class also needs to supports the IModule interface. The IModule interface requires a single method called Initialize that allows the module to set itself up to be used in the rest of the application. The example includes a ServerLogger module that contains the logging capabilities for our application. The ServerLoggingModule class supports the IModule interface as shown here:
public class ServerLoggerModule : IModule
{
  public void Initialize()
  {
    ...
  }
}
The problem is that we don't know what we want to initialize in our module. Since it's a ServerLogging module, it seems logical that we want to register a type that does logging for us. We want to use the container to register the type so that whoever needs the logging facility can simply use our implementation without knowing the exact type of logging it performs.
We get the container by creating a constructor that takes the IUnityContainer interface. If you remember the discussion of dependency injection, the container uses constructor injection to add types that it knows about. IUnityContainer represents the container in our application, so if we add that constructor, we can then save it and use it in our initialization like so:
public class ServerLoggerModule : IModule
{
  IUnityContainer theContainer;

  public ServerLoggerModule(IUnityContainer container)
  {
    theContainer = container;
  }

  public void Initialize()
  {
    theContainer.RegisterType<ILoggerFacade, ServerBasedLogger>(
      new ContainerControlledLifetimeManager());
  }
}
Once initialized, this module is responsible for the logging implementation for the application. But how does this module get loaded?
When using the CAL to compose an application, you need to create a ModuleCatalog that contains all the modules for the application. You create this catalog by overriding the bootstrapper's GetModuleCatalog call. In Silverlight, you can populate this catalog with code or with XAML.
With code, you create a new instance of the ModuleCatalog class and populate it with the modules. For example, look at this:
protected override IModuleCatalog GetModuleCatalog()
{
  var logModule = new ModuleInfo()
  {
    ModuleName = "ServerLogger",
    ModuleType =       "ServerLogger.ServerLoggerModule, ServerLogger, Version = 1.0.0.0"
  };

  var catalog = new ModuleCatalog();
  catalog.AddModule(logModule);

  return catalog;
}
Here, I simply add a single module called ServerLogger, the type defined in the ModuleInfo's ModuleType property. In addition, you can specify dependencies between modules. Because some modules might depend on others, using dependencies helps the catalog know the order in which to bring in the dependencies. Using the ModuleInfo.DependsOn property, you can specify which named modules are required to load another module.
You can load the catalog directly from a XAML file, as shown here:
protected override IModuleCatalog GetModuleCatalog()
{
  var catalog = ModuleCatalog.CreateFromXaml(new Uri("catalog.xaml",
                                                     UriKind.Relative));
  return catalog;
}
The XAML file contains the same type information you can create with code. The benefit of using XAML is that you can change it on the fly. (Imagine retrieving the XAML file from a server or from another location based on which user logged on.) An example of a catalog.xaml file is shown in Figure 6.
Figure 6 A Sample Catalog.xaml File
<m:ModuleCatalog
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:sys="clr-namespace:System;assembly=mscorlib"
  xmlns:m="clr-namespace:Microsoft.Practices.Composite.Modularity;
    assembly=Microsoft.Practices.Composite">
  <m:ModuleInfoGroup InitializationMode="WhenAvailable">
    <m:ModuleInfo ModuleName="GameEditor.Client.Data"
        ModuleType="GameEditor.Client.Data.GameEditorDataModule,
          GameEditor.Client.Data, Version=1.0.0.0"/>
    <m:ModuleInfo ModuleName="GameEditor.GameList"
      ModuleType="GameEditor.GameList.GameListModule,
      GameEditor.GameList, Version=1.0.0.0"
      InitializationMode="WhenAvailable">
      <m:ModuleInfo.DependsOn>
        <sys:String>GameEditor.Client.Data</sys:String>
      </m:ModuleInfo.DependsOn>
    </m:ModuleInfo>
  </m:ModuleInfoGroup>
</m:ModuleCatalog>
In this XAML catalog, the group includes two modules and the second module depends on the first. You could use a specific XAML catalog based on roles or permissions, as you could with code.
Once the catalog is loaded by the bootstrapper, it attempts to create instances of the module classes and allow them to initialize themselves. In the code examples here, the types have to be referenced by the application (therefore, already loaded into memory) for this catalog to work.
This is where this facility becomes indispensible to Silverlight. Although the unit of work is the assembly, you can specify a .xap file that contains the module or modules. To do this, you specify a Ref value in ModuleInfo. The Ref value is a path to the .xap file that contains the module:
protected override IModuleCatalog GetModuleCatalog()
{
  var logModule = new ModuleInfo()
  {
    ModuleName = "ServerLogger",
    ModuleType =
      "ServerLogger.ServerLoggerModule, ServerLogger, Version= 1.0.0.0",
    Ref = "ServerLogger.xap"
  };

  var catalog = new ModuleCatalog();
  catalog.AddModule(logModule);

  return catalog;
}
When you specify a .xap file, the bootstrapper knows that the assembly is not available and goes out to the server and retrieves the .xap file asynchronously. Once the .xap file is loaded, Prism loads the assembly and creates the module type and initializes the module.
For .xap files that contain multiple modules, you can create a ModuleGroup that contains a set of ModuleInfo objects and set the Ref of the ModuleGroup to load all those modules from a single .xap file:
var modGroup = new ModuleInfoGroup();
modGroup.Ref = "MyMods.xap";
modGroup.Add(logModule);
modGroup.Add(dataModule);
modGroup.Add(viewModule);

var catalog = new ModuleCatalog();
catalog.AddGroup(modGroup);
For Silverlight applications, this is a way to compose your applications from multiple .xap files, which allows you to version different sections of your composed application separately.
When creating Silverlight modules to be housed in a .xap file, you create a Silverlight Application (not a Silverlight Library). Then you reference all the module projects you want to put in the .xap file. You need to remove the app.xaml and page.xaml files because this .xap file will not be loaded and run like a typical .xap file. The .xap file is just a container (could be a .zip file, it doesn't matter). Also, if you are referencing projects that are already referenced in the main project, you can change those references to Copy Local=false in the properties because you don't need the assemblies in the .xap file (the main application has already loaded them, so the catalog will not try to load them a second time.)
But loading a huge application with multiple calls across the wire does not seem like it would help performance. That is where the ModuleInfo's InitializationMode property comes into play. InitializationMode supports two modes: WhenAvailable, in which the .xap file is loaded asynchronously and then initialized (this is the default behavior), and OnDemand, in which the .xap is loaded when explicitly requested. Since the module catalog does not know the types in the modules until initialization, resolving types that are initialized with OnDemand will fail.
On-demand support for modules and groups allows you to load certain functionality in a large application as needed. Startup time is accelerated, and other required code can be loaded as users interact with an application. This is a great feature to use when you have authorization to separate parts of an application. Users who need only a few parts of the application do not have to download code they'll never use.
To load a module on demand, you need access to an IModuleManager interface. Most often, you request this in the constructor of the class that needs to load a module on demand. Then you use IModuleManager to load the module by calling LoadModule, as shown in Figure 7.
Figure 7 Calling LoadModule
public class GameListViewModel : IGameListViewModel
{
  IModuleManager theModuleManager = null;

  public GameListViewModel(IModuleManager modMgr)
  {
    theModuleManager = modMgr;
  }

  void theModel_LoadGamesComplete(object sender,
                                  LoadEntityCompleteEventArgs<Game> e)
  {
    ...

    // Since we now have games, let's load the detail pane
    theModuleManager.LoadModule("GameEditor.GameDetails");
  }
}
Modules are simply the unit of modularization in your applications. In Silverlight, treat a module much like you would a library project, but with the extra work of module initialization, you can decouple your modules from the main project.

UI Composition
In a typical Explorer application, the left pane displays a list or tree of information and the right side contains details about the item selected in the left pane. In the CAL, these areas are called regions.
The CAL supports defining regions directly in XAML by using an attached property on the RegionManager class. This property allows you to specify regions in your shell and then indicate what views should be hosted in the region. For example, our shell has two regions, LookupRegion and DetailRegion, as shown here:
<UserControl
  ...
  xmlns:rg=
    "clr-namespace:Microsoft.Practices.Composite.Presentation.Regions;
    assembly=Microsoft.Practices.Composite.Presentation">
  ...
  <ScrollViewer rg:RegionManager.RegionName="LookupRegion" />
  <ScrollViewer rg:RegionManager.RegionName="DetailRegion" />
</UserControl>
A RegionName can be applied to the an ItemsControl and its derived controls (for example, ListBox); Selector and its derived controls (for example, TabControl); and ContentControl and its derived controls (for example, ScrollViewer).
Once you define regions, you can direct modules to load their views into the regions by using the IRegionManager interface, as shown here:
public class GameListModule : IModule
{
  IRegionManager regionManager = null;

  public GameListModule(IRegionManager mgr)
  {
    regionManager = mgr;
  }

  public void Initialize()
  {
    // Build the View
    var view = new GameListView();

    // Show it in the region
    regionManager.AddToRegion("LookupRegion", view);
  }
}
This facility allows you to define regions in your application where views can appear and then have the modules define how to place views into the region, allowing the shell to be completely ignorant of the views.
The behavior of the regions might be different depending on the control type being hosted. The example uses a ScrollViewer so that one and only one view can be added to the region. In contrast, ItemControl regions allow for multiple views. As each view is added, it shows up as a new item in the ItemsControl. That facility makes it easier to build functionality like a dashboard.
If you are using an MVVM pattern to define your views, you can mix the regions and the service location aspects of the container to make your views and view models ignorant of each other and then let the module join them at run time. For example, if I change the GameListModule, I can register views and views models with the container and then join them before applying the view to the region, as shown in Figure 8.
Figure 8 Joining Views in a Region
public class GameListModule : IModule
{
  IRegionManager regionManager = null;
  IUnityContainer container = null;

  public GameListModule(IUnityContainer con, IRegionManager mgr)
  {
    regionManager = mgr;
    container = con;
  }

  public void Initialize()
  {
    RegisterServices();

    // Build the View
    var view = container.Resolve<IGameListView>();

    // Get an Implemenation of IViewModel
    var viewModel = container.Resolve<IGameListViewModel>();

    // Marry Them
    view.ApplyModel(viewModel);

    // Show it in the region
    regionManager.AddToRegion("LookupRegion", view);
  }

  void RegisterServices()
  {
    container.RegisterType<IGameListView, GameListView>();
    container.RegisterType<IGameListViewModel, GameListViewModel>();
  }
}
This approach allows you to use UI composition while maintaining the strict separation of MVVM.

Event Aggregation
After you have multiple views in your applications through UI composition, you face a common problem. Even though you have built independent views to support better testing and development, there are often touch points where the views cannot be completely isolated. They are logically coupled because they need to communicate, but you want to keep them as loosely coupled as possible regardless of the logical coupling.
To enable loose coupling and cross-view communication, the CAL supports a service called event aggregation. Event aggregation allows access to different parts of the code to publishers and consumers of global events. Such access provides a straightforward way of communicating without being tightly coupled and is accomplished using the CAL's IEventAggregator interface. IEventAggregator allows you to publish and subscribe to events across the different modules of your application.
Before you can communicate, you need a class that derives from EventBase. Typically, you create a simple event that derives from the CompositePresentationEvent<T> class. This generic class allows you to specify the payload of the event you are going to publish. In this case, the GameListViewModel is going to publish an event after a game is selected so that other controls that want to change their context as the user selects a game can subscribe to that event. Our event class looks like the following:
public class GameSelectedEvent : CompositePresentationEvent<Game>
{
}
Once the event is defined, the event aggregator can publish the event by calling its GetEvent method. This retrieves the singleton event that is going to be aggregated. The first one who calls this method creates the singleton. From the event, you can call the Publish method to create the event. Publishing the event is like firing an event. You do not need to publish the event until it needs to send information. For example, when a game is selected in the GameList, our example publishes the selected game using the new event:
// Fire Selection Changed with Global Event
theEventAggregator.GetEvent<GameSelectedEvent>().Publish(o as Game);
In other parts of your composed application, you can subscribe to the event to be called after the event is published. The Subscribe method of the event allows you to specify the method to be called when the event is published, an option that allows you to request threading semantics for calling the event (for example, the UI thread is commonly used), and whether to have the aggregator hold a reference to the passed in information so that it is not subject to garbage collection:
// Register for the aggregated event
aggregator.GetEvent<GameSelectedEvent>().Subscribe(SetGame,
                                                  ThreadOption.UIThread,
                                                  false);
As a subscriber, you can also specify filters that are called only in specific situations. Imagine an event that returns the state of an application and a filter that is called only during certain data states.
The event aggregator allows you to have communication between your modules without causing tight coupling. If you subscribe to an event that is never published or publish an event that is never subscribed, your code will never fail.

Delegate Commands
In Silverlight (unlike WPF), a true commanding infrastructure does not exist. This forces the use of code-behind in views to accomplish tasks that would be accomplished more readily directly in XAML using the commanding infrastructure. Until Silverlight supports this facility, the CAL supports a class that helps solve this problem: the DelegateCommand.
To get started with DelegateCommand, you need to define the DelegateCommand in your ViewModel so you can data-bind to it. In the ViewModel, you would create a new DelegateCommand. The DelegateCommand expects the type of data to be sent to it (often Object if no data is used) and one or two callback methods (or lambda functions). The first of these methods is the action to execute when the command is fired. Optionally, you can specify a second callback to be called to test whether the command can be fired. The idea is to enable the disabling of objects in the UI (buttons, for example) when it is not valid to fire the command. For example, our GameDetailsViewModel contains a command to support saving data:
// Create the DelegateCommand
SaveCommand = new DelegateCommand<object>(c => Save(), c => CanSave());
When SaveCommand is executed, it calls the Save method on our ViewModel. The CanSave method is then called to make sure the command is valid. This allows the DelegateCommand to disable the UI if necessary. As the state of the view changes, you can call the DelegateCommand.RaiseCanExecuteChanged method to force a new inspection of the CanSave method to enable or disable the UI as necessary.
To bind this to XAML, use the Click.Command attached property that is in the Microsoft.Practices.Composite.Presentation.Commands namespace. Then bind the value of the command to be the command you have in your ViewModel, like so:
<Button Content="Save"
        cmd:Click.Command="{Binding SaveCommand}"
        Style="{StaticResource ourButton}"
        Grid.Column="1" />
Now when the Click event is fired, our command is executed. If you want, you can specify a command parameter to be sent to the command so you can reuse it.
As you might be wondering, the only command that exists in the CAL is the Click event for a button (or any other selector). But the classes you can use to write your own commands are fairly straightforward. The sample code includes a command for SelectionChanged on a ListBox/ComboBox. This command is called the SelectorCommandBehavior and derives from the CommandBehaviorBase<T> class. Looking at the custom command behavior implementation will provide you with a starting place to write your own command behaviors.

Wrapping Up
There are definite pain points when developing large Silverlight applications. By building your applications with loose coupling and modularity, you gain benefits and can be agile in responding to change. The Prism project from Microsoft provides the tools and guidance to allow that agility to come to the surface of your project. While Prism is not a one-size-fits-all approach, the modularity of the CAL means you can use what fits in your specific scenarios and leave the rest.

Shawn Wildemuth is a Microsoft MVP (C#) and the founder of Wildermuth Consulting Services. He is the author of several books and numerous articles. In addition, Shawn currently runs the Silverlight Tour, teaching Silverlight 2 around the country. He can be contacted at shawn@wildermuthconsulting.com.


RESTful XHTML
RESTful Services With ASP.NET MVC
Aaron Skonnard
Code download available from the MSDN Code Gallery
Browse the Code Online

This article discusses:
  • REST
  • XHTML
  • ASP.NET MVC
This article uses the following technologies:
REST, XHTML, ASP.NET
Contents
XHTML: Representing Data and Links
XHTML: Representing Input with Forms
Understanding the ASP.NET MVC Architecture
Implementing the Model
Implementing the Controller
Designing URIs with Routes
Implementing the Views
Consuming the Bookmark Service
Acknowledgments
A RESTful service is a web of resources that programs can navigate. When designing a RESTful service, you have to think carefully about how your web will work. This means designing resource representations with links that facilitate navigation, describing service input somehow, and considering how consumers will navigate around your service at run time. Getting these things right is often overlooked, but they're central to realizing the full potential REST has to offer.
Today, humans navigate sites using Web browsers that know how to render HTML and other popular content types. HTML provides the syntax and semantics for establishing links between resources (<a> element) and for describing and submitting application input (<form> and <input> elements).
When a user clicks on an <a> element in the rendered page, the browser knows to issue an HTTP GET request for the target resource and render the response. When a browser encounters a <form> element, it knows how to render the form description into a user interface that the user can fill out and submit using either a GET or POST request. When the user presses a submit button, the browser encodes the data and sends it using the specified request. These two features are largely responsible for the success of the Web.
Using links in conjunction with the universal HTTP interface makes it possible to redirect requests to new locations over time and change certain aspects of security on the fly without changing the client code. A standard approach for forms means that you can add or remove input properties and change default values, again without changing the client code. Both features are very useful for building applications that evolve over time.
Your RESTful services should also somehow provide these two features through whatever resource representation you decide to use. For example, if you're designing a custom XML dialect for your service, you should probably come up with your own elements for establishing links and describing service input that will guide consumers through your web. Or you can simply use XHTML.
Most developers don't immediately consider XHTML as an option for "services," but that's actually one of the ways it was intended to be used. XHTML documents are by definition well-formed XML, which allows for automated processing using standard XML APIs. And since XHTML is also HTML, it comes with <a>, <form>, and <input> elements for modeling link navigation and service input as I described earlier. The only thing that's a little strange at first is how you model user-defined data structures—however, you can model classes and fields with <div> and <span> elements and collections of entities with <ol> and <li> elements. I'll walk through how to do this in more detail later in the article.
To summarize, there are several reasons to consider XHTML as the default representation for your RESTful services. First, you can leverage the syntax and semantics for important elements like <a>, <form>, and <input> instead of inventing your own. Second, you'll end up with services that feel a lot like sites because they'll be browsable by both users and applications. The XHTML is still interpreted by a human—it's just a programmer during development instead of a user at runtime. This simplifies things throughout the development process and makes it easier for consumers to learn how your service works. And finally, you can leverage standard Web development frameworks to build your RESTful services.
ASP.NET MVC is one such framework that provides an inherently RESTful model for building XHTML-based services. This article walks through some XHTML design concepts and then shows you how to build a complete XHTML-based RESTful service that you can download from the MSDN Magazine site.

XHTML: Representing Data and Links
Before I dive into the details of ASP.NET MVC, let's first look at how you can represent common data structures and collections in XHTML. This approach isn't the only way to accomplish this, but it's a fairly common practice in XHTML-based services today.
Throughout this article, I'll describe how to implement a simple bookmark service. The service allows users to create, retrieve, update, and delete bookmarks and navigate a web of bookmarks in a variety of ways. Suppose you have a C# class representing a bookmark that looks like this:
public class Bookmark
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Url { get; set; }
    public string User { get; set; }
}
The first question is how can you represent a Bookmark instance in XHTML? One approach is to combine <div>, <span>, and <a> elements, where <div> elements represent structures, <span> elements represent fields, and <a> elements represent identity and links to other resources. In addition, you can annotate these elements with the XHTML "class" attribute to provide additional type metadata. Here's a complete example:
<div class="bookmark">
  <span class="bookmark-id">25</span>
  <span class="bookmark-title">Aaron's Blog</span>
  <a class="bookmark-url-link" href="http://pluralsight.com/aaron"
  >http://pluralsight.com/aaron</a>
  <span class="bookmark-username">skonnard</span>
</div>
The next question is how will consumers process this information? Since it's well-formed XML, consumers can use any XML API to extract the bookmark information. Most .NET programmers will probably find that XLinq provides the most natural programming model for consuming XHTML programmatically. In addition, you can go one step further by enhancing XLinq with some helpful XHTML-focused extension methods that make the programming model even easier.
Throughout this article, I'll use a set of XLinq extension methods that I've included in the downloadable sample code. These extensions give you a good idea of what's possible. The following code shows how to consume the bookmark XHTML shown previously using XLinq and some of these extensions:
var bookmarkDetails = bookmarkDoc.Body().Struct("bookmark");
Console.WriteLine(bookmarkDetails["bookmark-id"].Value);
Console.WriteLine(bookmarkDetails["bookmark-url"].Value);
Console.WriteLine(bookmarkDetails["bookmark-title"].Value);
Now, if you want to improve how this bookmark renders in a browser, you can add a Cascading Stylesheet (CSS) to control browser-specific rendering details or add some additional UI elements and text that don't compromise the consumer's ability to extract the data of interest. For example, the following XHTML will be easier for humans to process, but you can still use the previous .NET code sample to process the information without any modification:
<h1>Bookmark Details: 3</h1>
<div class="bookmark">
  BookmarkID: <span class="bookmark-id">25</span><br />
  Title: <span class="bookmark-title">Aaron's Blog</span><br />
  Url: <a class="bookmark-url-link" href="http://pluralsight.com/aaron"
  >http://pluralsight.com/aaron</a><br />
  Username: <span class="bookmark-username">skonnard</span></a><br />
</div>
Collections of resources aren't hard to model either. You can represent a list of bookmarks with a combination of <ol>, <li>, and <a> elements as shown here:
<ol class="bookmark-list">
  <li><a class="bookmark-link" href="/bookmarks/1">Pluralsight Home</    a></li>
  <li><a class="bookmark-link" href="/bookmarks/2">Pluralsight On-    Demand!</a></li>
  <li><a class="bookmark-link" href="/bookmarks/3">Aaron's Blog</a></li>
  <li><a class="bookmark-link" href="/bookmarks/4">Fritz's Blog</a></li>
  <li><a class="bookmark-link" href="/bookmarks/5">Keith's Blog</a></li>
</ol>
The following code shows how to print this list of bookmarks to the console:
var bookmarks = bookmarksDoc.Body().Ol("bookmark-list").Lis();
bookmarks.Each(bm => Console.WriteLine("{0}: {1}",
    bm.Anchor().AnchorText, bm.Anchor().AnchorLink));
Notice how each <li> contains an <a> element that links to a specific bookmark. If you were to navigate one of the anchor elements, you would retrieve the bookmark details representation shown earlier. As you begin to define links between resources like this, your service starts becoming a web of linked resources.
It's pretty obvious how humans can navigate between resources using a Web browser, but how about consuming applications? A consuming application just needs to programmatically locate the anchor element of interest and then issue a GET request targeting the URI specified in the "href" attribute. These details can also be hidden behind an XLinq extension method that encapsulates anchor navigation.
The following code shows how to navigate to the first bookmark in the bookmark list and then to the target bookmark URL. The resulting XHTML is printed to the console:
var bookmarkDoc = bookmarks.First().Anchor().Navigate();
var bookmarkDetails = bookmarkDoc.Body().Struct("bookmark");
var targetDoc = bookmarkDetails.Anchor("bookmark-url-link").Navigate();
Console.WriteLine(targetDoc);
Once you start thinking about building consumers that navigate your service as a web of resources, you're officially starting to think in a more RESTful way.

XHTML: Representing Input with Forms
Now let's say a consumer wants to create a new bookmark in the system. How does the consumer figure out what data to send and how to send it without WSDL? The answer is easy: XHTML forms.
The consumer first issues a GET request to the URI for retrieving the create bookmark form. The service returns a form that looks something like this:
<h1>Create Bookmark</h1>
<form action="/bookmark/create" class="create-bookmark-form" method="post">
  <p>
    <label for="bookmark-title">Title:</label><br />
    <input id="bookmark-title" name="bookmark-title" type="text" value="" />
  </p>
  <p>
    <label for="bookmark-url">Url:</label><br />
    <input id="bookmark-url" name="bookmark-url" type="text" value="" />
  </p>
  <p><input type="submit" value="Create" name="submit" /></p>
</form>
The form describes how to build an HTTP POST request for creating a new bookmark. The form indicates that you need to provide the bookmark-title and bookmark-url fields. In this example, bookmark-id will be autogenerated during creation, and bookmark-username will be derived from the logged-in user identity. The form also tells you what you need to send and how to send it.
When this form is rendered in a browser, a human can simply fill out the form and click Submit to create a new bookmark. A consuming application basically does the same thing by submitting the form programmatically. Again, this process can be made easier by using some form-based extension methods, shown here:
var createBookmarkForm = createBookmarkDoc.Body().Form("create-bookmark-  form");
createBookmarkForm["bookmark-title"] = "Windows Live";
createBookmarkForm["bookmark-url"] = "http://live.com/";
createBookmarkForm.Submit();
When this code runs, the Submit method generates an HTTP POST request targeting the "action" URL, and the input fields are formatted together as a URL-encoded string (application/x-www-form-urlencoded). In the end, it's no different from using the browser—the result is a new bookmark.
Although today's browsers support GET and POST only for the form method, nothing is stopping you from also specifying PUT or DELETE as the form "method" when targeting nonbrowser consumers. The Submit extension method performs equally well for any HTTP method you specify.

Understanding the ASP.NET MVC Architecture
The ASP.NET MVC architecture is based on the popular model-view-controller design pattern that has been around for decades. Figure 1 illustrates the various ASP.NET MVC components and how they relate to one another. ASP.NET MVC comes with a routing engine that sits in front of the other MVC components. The routing engine receives incoming HTTP requests and routes them to a controller method. The routing engine relies on a centralized set of routes that you define in Global.asax.
Figure 1 ASP.NET MVC Architecture
The centralized routes define mappings between URL patterns and specific controller methods and arguments. When you generate links, you use these routes to generate the links appropriately. This makes it easy to modify your URL design throughout the development process in one central location.
It's the job of the controller to extract information from the incoming request and to interact with the user-defined model layer. The model layer can be anything ( Linq to SQL, ADO.NET Entity Framework, NHibernate, and so on)—it's the layer that performs business logic and talks to the underlying database. Notice how the model is not within the System.Web.Mvc namespace. Once the controller has finished using the model, it creates a view, supplying the view with model data for the view to use while rendering the output.
In the following sections, I'll walk through the process of implementing a complete bookmark service using the ASP.NET MVC architecture. The service supports multiple users and both public and private bookmarks. Users can browse all public bookmarks and filter them based on username or tags, and they can fully manage (CRUD) their own collection of private bookmarks.
To get started, you need to create an ASP.NET MVC project. You'll find the ASP.NET MVC Web Application project template in the list of Web project types. The default project template gives you a sample MVC starter application that you can actually run by pressing F5.
Notice how the solution structure provides directories for Models, Views, and Controllers—this is where you place the code for these different components. The default template comes with two controllers: one for managing user accounts (AccountController), and another for supporting requests to the home directory (HomeController). Both of these are used in the bookmark service.

Implementing the Model
The first thing you should focus on is the model for the bookmark service. I've built a simple SQL Server database that contains three tables for managing bookmark information—Bookmark, Tag, and BookmarkTag (see Figure 2)—and they're pretty self-explanatory.
Figure 2 Bookmark Service Linq to SQL Model
The only caveat is that the example relies on the built-in ASP.NET forms authentication and membership service, which is provided by the default AccountController that comes with the project, to manage the service user accounts, Hence, user account information will be stored in a different database (aspnetdb.mdf), separate from the bookmark information. The username is simply stored in the Bookmark table.
It's the job of the model to provide business objects and logic on top of the database. For this example, I've defined the Linq to SQL model shown in Figure 2. This model, defined in BookmarksModel.dbml, generates the C# code found in BookmarksModel.designer.cs. You'll find classes named Bookmark, Tag, and BookmarkTag. You'll also find a BookmarksModelDataContext class, which bootstraps the entities.
At this point, you can decide to work directly with the Linq to SQL classes as your MVC model layer, or you can go a step further by defining a higher-level repository class that defines the logical business operations and shields the controller/view from even more of the underlying data manipulation details. Figure 3 shows the definition for the BookmarksRepository class used in the bookmark service.
Figure 3 BookmarksRepository Class
public class BookmarksRepository
{
    // generated Linq to SQL DataContext class
    BookmarksModelDataContext db = new BookmarksModelDataContext();

    // query methods
    public IQueryable<Bookmark> FindAllBookmarks() { ... }
    public IQueryable<Bookmark> FindAllPublicBookmarks() { ... }
    public IQueryable<Bookmark> FindBookmarksByUser(string username)  { ... }
    public IQueryable<Bookmark> FindPublicBookmarksByUser(string username) { ... }
    public IQueryable<Bookmark> FindBookmarksByTag(string tag) { ... }
    public Bookmark FindBookmarkById(int id) { ... }
    public IQueryable<string> FindUsers(){ ... }
    public IQueryable<Tag> FindTags() { ... }
    public Tag FindTag(string tag) { ... }

    // insert/delete methods
    public void AddBookmark(Bookmark bm) { ... }
    public void AddTag(Tag t) { ... }
    public void AddTagForBookmark(string tagText, Bookmark bm) { ... }
    public void DeleteBookmark(Bookmark bm) { ... }

    // persistence
    public void Save() { ... }
}

Implementing the Controller
The controller is the piece of code responsible for managing the HTTP request life cycle. When a request arrives, the ASP.NET MVC routing engine determines which controller to use (based on the URL) and then routes the request to the controller by calling a specific method on it. Hence, when you write a controller, you're writing the entry points that will be called by the routing engine.
For the bookmark service, we want to allow authenticated users to create, edit, and delete bookmarks. When creating bookmarks, users should be able to mark them as public (shared) or private. All users should be able to browse public bookmarks and filter them by username or tags. Private bookmarks, however, should be visible only to the owner. Consumers should also be able to retrieve the details for a particular bookmark, assuming they are authorized to do so. We should also make it possible to browse all users and tags in the system as a way to navigate the public bookmarks associated with them.
Figure 4 shows the methods the BookmarkController class needs to support the service requirements I just described. The first three query methods make it possible to retrieve all public bookmarks, bookmarks by user, or bookmarks by tag. The class also includes methods for retrieving users and tags and for retrieving the details of a specific bookmark instance. All these methods respond to HTTP GET requests, but each one will be bound to a different URI template when the routes are defined.
Figure 4 BookmarkController Class
[HandleError]
public class BookmarkController : Controller
{
    // underlying model
    BookmarksRepository bmRepository = new BookmarksRepository();

    // query methods
    public ActionResult BookmarkIndex() { ... }
    public ActionResult BookmarksByUserIndex(string username) { ... }
    public ActionResult BookmarksByTagIndex(string tag) { ... }
    public ActionResult UserIndex() { ... }
    public ActionResult TagIndex() { ... }
    public ActionResult Details(int id) { ... }

    // create boomark
    [Authorize]
    public ActionResult Create() { ... }
    [Authorize]
    [AcceptVerbs(HttpVerbs.Post)]
    public ActionResult Create(FormCollection collection) { ... }

    // update bookmark
    [Authorize]
    public ActionResult Edit(int id) { ... }
    [Authorize]
    [AcceptVerbs(HttpVerbs.Put | HttpVerbs.Post)]
    public ActionResult Edit(int id, FormCollection collection)

    // delete bookmark
    [Authorize]
    public ActionResult Delete(int id) { ... }
    [Authorize]
    [AcceptVerbs(HttpVerbs.Delete | HttpVerbs.Post)]
    public ActionResult Delete(int id, FormCollection collection) { ... }
}
The rest of the methods are for creating, editing, and deleting bookmark instances. Notice that there are two methods for each logical operation—one for retrieving the input form, and another for responding to the form submission—and each one of these methods requires authorization. The Authorize attribute ensures that the caller is authenticated and authorized to access the controller method. (The attribute also allows you to specify users and roles.) If an unauthenticated or unauthorized user attempts to access a controller method annotated with [Authorize], the authorization filter automatically redirects the user to the AccountController's Logon method, which presents the "Logon" view to the consumer.
You use the AcceptVerbs attribute to specify which HTTP verbs a particular controller method will handle (the default is GET). A single method can handle multiple verbs by ORing the HttpVerb values together. The reason I've bound the second Edit method to both PUT and POST is to accommodate browsers. This configuration allows browsers to invoke the operation using POST, while nonbrowser consumers can use PUT (which is more correct). I've done something similar on the second Delete method, binding it to both DELETE and POST. I still have to be careful that my method implementations ensure idempotency, which is a requirement for both PUT and DELETE.
Let's look at how a few of these methods have been implemented. First is BookmarkIndex:
public ActionResult BookmarkIndex()
{
    var bms = bmRepository.FindAllPublicBookmarks().ToList();
    return View("BookmarkIndex", bms);
}
This implementation simply retrieves the list of public Bookmark entities from the repository and then returns a view called BookmarkIndex (passing in the list of Bookmark entities). The view is responsible for displaying the list of Bookmark entities supplied to it by the controller.
The Details method looks up the target bookmark and returns a 404 Not Found error if it doesn't exist. Then it ensures that the user is authorized to view the bookmark. If so, it returns the Details view, supplying the identified Bookmark entity. Otherwise it returns an Unauthorized response to the consumer.
public ActionResult Details(int id)
{
    var bm = bmRepository.FindBookmarkById(id);
    if (bm == null)
        throw new HttpException(404, "Not Found");
    if (!bm.Shared)
    {
        if (!bm.Username.Equals(HttpContext.User.Identity.Name))
            return new HttpUnauthorizedResult();
    }
    return View("Details", bm);
}
As a final example, let's look at the two Create methods. The first is actually quite simple—it returns the Create view to present the form description for creating a new bookmark:
[Authorize]
public ActionResult Create()
{
    return View("Create");
}
Figure 5 shows the second Create method, which responds to the form submission request. It creates a new Bookmark entity from the bookmark information found in the incoming FormCollection object and then saves it to the database. It also updates the database with any new tags that were associated with the bookmark and then redirects users to their lists of personal bookmarks to indicate success.
Figure 5 The Create Method That Responds to a Form Submission Request
[Authorize]
[AcceptVerbs(HttpVerbs.Post)]
public ActionResult Create(FormCollection collection)
{
    try
    {
        Bookmark bm = new Bookmark();
        bm.Title = collection["bookmark-title"];
        bm.Url = collection["bookmark-url"];
        bm.Shared = collection["bookmark-shared"].Contains("true");
        bm.LastModified = DateTime.Now;
        bm.Username = HttpContext.User.Identity.Name;
        bm.Tags = collection["bookmark-tags"];

        bmRepository.AddBookmark(bm);
        bmRepository.Save();

        ... // create any new tags that are necessary

        return RedirectToAction("BookmaryByUserIndex",
            new { username = HttpContext.User.Identity.Name });
    }
    catch
    {
        return View("Error");
    }
}
I don't have space to cover the entire controller implementation, but these code samples should give you a taste for the kind of code you write in the controller.

Designing URIs with Routes
The next thing you need to do is define URL routes that map to the various BookmarkController methods. You define your application routes in Global.asax within the RegisterRoutes method. When you first create an MVC project, your Global.asax will contain the default routing code shown in Figure 6.
Figure 6 Default Routing Code
public class MvcApplication : System.Web.HttpApplication
{
    public static void RegisterRoutes(RouteCollection routes)
    {
        routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

        routes.MapRoute(
            "Default",                             // Route name
            "{controller}/{action}/{id}",          // URL with parameters
            new { controller="Home",               // Parameter defaults
                   action="Index", id="" }
        );

    }

    protected void Application_Start()
    {
        RegisterRoutes(RouteTable.Routes);
    }
}
The single call to MapRoute creates a default routing rule that acts like a catchall for all URIs. This route outlines that the first path segment represents the controller name, the second path segment represents the action name (controller method), and the third path segment represents an ID value. This single rule can handle the following URIs and route them to the appropriate controller method:
/Account/Logon
/Bookmark/Create
/Bookmark/Details/25
/Bookmark/Edit/25
Figure 7 shows the routes I'm using for this bookmark service example. With these additional routes in place, consumers can browse to "/users" to retrieve the list of users, "/tags" to retrieve the list of tags, or "/bookmarks" to retrieve the list of public bookmarks. Consumers can also browse to "/tags/{tagname}" or "/users/{username}" to filter bookmarks by tag or username, respectively. All other URIs are handled by the default route shown in Figure 6.
Figure 7 Bookmark Service Routes
public static void RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    // customer routes
    routes.MapRoute("Users", "users",
        new { controller = "Bookmark", action = "UserIndex" });
    routes.MapRoute("Tags", "tags",
        new { controller = "Bookmark", action = "TagIndex" });
    routes.MapRoute("Bookmarks", "bookmarks",
        new { controller = "Bookmark", action = "BookmarkIndex" });
    routes.MapRoute("BookmarksByTag", "tags/{tag}",
        new { controller = "Bookmark", action = "BookmarksByTagIndex", tag = "" });
    routes.MapRoute("BookmarksByUser", "users/{username}",
        new { controller="Bookmark", action="BookmarksByUserIndex", username="" });
    // default route
    routes.MapRoute("Default", "{controller}/{action}/{id}",
        new { controller = "Home", action = "Index", id = ""});
}

Implementing the Views
Up to this point, most of what we've done applies to both MVC "sites" and "services." All MVC applications need models, controllers, and routes. Most of what's different about building MVC "services" is found in the view. Instead of producing a traditional HTML view for human consumption, a service must produce a view that's appropriate for both human and programmatic consumption.
We're going to use XHTML for our default service representation and apply the techniques described earlier for mapping bookmark data to XHTML. We'll map data entities to <div> and <span> elements, and we'll represent collections using a combination of <ol> and <li>. We'll also annotate these elements with the "class" attribute to provide consumers with additional type metadata.
ASP.NET MVC "views" are just .aspx pages that define a view template. The .aspx pages are organized by controller name within the Views directory. Each view can be associated with an ASP.NET master page to maintain a consistent template. Figure 8 shows the master page for the bookmark service.
Figure 8 Bookmark Service Master Page
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title><asp:ContentPlaceHolder ID="Title" runat="server" /></title>
</head>
<body>
    <div style="text-align:right">
        <% Html.RenderPartial("LogOnUserControl"); %>
    </div>
    <h1><asp:ContentPlaceHolder ID="Heading" runat="server" /></h1>
    <hr />
    <asp:ContentPlaceHolder ID="MainContent" runat="server" />
    <hr />
    <div class="nav-links-footer">
        <%=Html.ActionLink("Home", "Index", "Home", null,
           new { @class = "root-link" } )%> |
        <%=Html.ActionLink("Public Bookmarks", "BookmarkIndex", "Bookmark", null,
           new { @class = "public-bookmarks-link" } )%> |
        <%=Html.ActionLink("User Bookmarks", "BookmarksByUserIndex", "Bookmark",
           new { username = HttpContext.Current.User.Identity.Name },
           new { @class = "my-bookmarks-link" })%> |
        <%=Html.ActionLink("Users", "UserIndex", "Bookmark", null,
           new { @class = "users-link" } )%> |
        <%=Html.ActionLink("Tags", "TagIndex", "Bookmark", null,
           new { @class = "tags-link" } )%>
    </div>
</body>
</html>
The master page defines three placeholders: one for the page title, another for the <h1> heading, and another for the main content area. These placeholders will be filled in by each individual view. In addition, the master page displays a login control at the top of the page, and it provides a footer containing the root service links to simplify navigation. Notice how I'm using the Html.ActionLink method to generate these links based on the predefined routes and controller actions.
Figure 9 shows the main Bookmark Index view you get back when you browse to "/bookmarks". It displays the list of bookmarks using a combination of <ol>, <li>, and <a> elements. The <ol> elements are annotated with class="bookmark-list", and each <a> element is annotated with class="bookmark-link". This view also provides a link to retrieve the Create bookmark form description (right above the list). If you navigate to the link, the Create view shown in Figure 10 comes into action.
Figure 9 Bookmark Index View
<%@ Page Title="" Language="C#" MasterPageFile="~/Views/Shared/Site.
Master" Inherits="System.Web.Mvc.ViewPage
<IEnumerable<MvcBookmarkService.Models.Bookmark>>" %>

<asp:Content ID="Content1" ContentPlaceHolderID="Title" runat="server">
Public Bookmarks</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderID="Heading" runat="server">
Public Bookmarks</asp:Content>
<asp:Content ID="Content3" ContentPlaceHolderID="MainContent" runat="server">
    <%= Html.ActionLink("Create bookmark", "Create", "Bookmark", new { id = "" },
           new { @class = "create-bookmark-form-link" } )%>
    <ol class="bookmark-list">
        <% foreach (var item in Model) { %>
            <li><%= Html.ActionLink(Html.Encode(item.Title), "Details", "Bookmark",
                    new { id = item.BookmarkID }, new { @class = "bookmark-link" })%></li>
        <% } %>
    </ol>
</asp:Content>
Figure 10 Bookmark Create View
<%@ Page Title="" Language="C#" MasterPageFile="~/Views/Shared/Site.Master"
    Inherits="System.Web.Mvc.ViewPage<MvcBookmarkService.Models.Bookmark>" %>

<asp:Content ID="Content1" ContentPlaceHolderID="Title" runat="server">
Create Bookmark</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderID="Heading" runat="server">
Create Bookmark</asp:Content>
<asp:Content ID="Content3" ContentPlaceHolderID="MainContent" runat="server">
    <% using (Html.BeginForm("Create", "Bookmark", FormMethod.Post,
       new { @class = "create-bookmark-form" } ))
       {%>
        <p>
            <label for="Title">Title:</label><br />
            <%= Html.TextBox("bookmark-title")%>
        </p>
        <p>
            <label for="Url">Url:</label><br />
            <%= Html.TextBox("bookmark-url")%>
        </p>
        <p>
            <label for="Tags">Tags:</label><br />
            <%= Html.TextBox("bookmark-tags")%>
        </p>
        <p>
            <label for="Shared">Share with public: </label>
            <%= Html.CheckBox("bookmark-shared")%>
        </p>
        <p>
            <input type="submit" value="Create" name="submit" />
        </p>
    <% } %>
</asp:Content>
The Create view produces a simple XHTML form, but the <form> element is annotated with class="create-bookmark-form", and each <input> element has been given a contextual name/ID value that identifies each bookmark field. This form gives consumers a complete XHTML description of how to programmatically create a new bookmark using our service (by simply submitting the form).
As a final example, Figure 11 shows the beginning of the Bookmark Details view. Here I'm using a <div> element to represent the bookmark structure (class="bookmark") along with <span> and <a> elements to represent the bookmark fields. Each carries a "class" attribute to specify the field name.
Figure 11 Bookmark Details View
<%@ Page Title="" Language="C#" MasterPageFile="~/Views/Shared/Site.Master"
   Inherits="System.Web.Mvc.ViewPage<MvcBookmarkService.Models.Bookmark>" %>

<asp:Content ID="Content1" ContentPlaceHolderID="Title" runat="server">
Bookmark Details: <%= Model.BookmarkID %></asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderID="Heading" runat="server">
Bookmark Details: <%= Model.BookmarkID %></asp:Content>
<asp:Content ID="Content3" ContentPlaceHolderID="MainContent" runat="server">
    <br />
    <div class="bookmark">
     BookmarkID: <span class="bookmark-id"><%= Html.Encode(Model.BookmarkID) %></span><br />
     Title: <span class="bookmark-title"><%= Html.Encode(Model.Title)    %></span><br />
     Url: <a class="bookmark-url-link" href="<%= Html.Encode(Model.Url) %>">
     <%= Html.Encode(Model.Url) %></a><br />
     Username: <%=Html.ActionLink(Model.Username, "BookmarksByUserIndex", "Bookmark",
     new { username=Model.Username }, new { @class="bookmark-username-link" }) %><br />
...
Again, I don't have space to look at all the view examples in detail, but I hope this illustrates how you can produce clean XHTML result sets that are easy for both applications and humans to consume.

Consuming the Bookmark Service
The easiest way to consume the bookmark service is through a Web browser. Thanks to the XHTML design, you should be able to browse to the service's root URL and begin navigation from there. Figure 12 shows what the browser looks like when you browse to the root of the bookmark service and log in. You can click Public Bookmarks to navigate to the list of all public bookmarks, and then navigate to a specific bookmark in the list. If you click Edit, you can actually edit the bookmark details (see Figure 13). The service is fully usable from any Web browser.
Figure 12 Browsing to the MVC Bookmark Service
Figure 13 Editing a Specific Bookmark
While you're browsing around the service, select View Source occasionally in your browser, and you'll notice how simple the resulting XHTML looks, which again makes it easy to program against.
Figure 14 shows the code for a complete .NET client application that consumes the bookmark service. It uses the set of XLinq extension methods I described earlier to simplify the XHTML and HTTP processing details. What's interesting about this sample is that it acts more like a human—it needs only the root URI to navigate to everything else of interest exposed by the bookmark service.
Figure 14 Writing a .NET Client to Consume the Bookmark Service using XLinq
class Program
{
    static void Main(string[] args)
    {
        // navigate to the root of the service
        Console.WriteLine("Navigating to the root of the service...");
        Uri uri = new Uri("http://localhost:63965/");
        CookieContainer cookies = new CookieContainer();
        var doc = XDocument.Load(uri.ToString());
        doc.AddAnnotation(uri);

        // navigate to public bookmarks
        Console.WriteLine("Navigating to public bookmarks...");
        var links = doc.Body().Ul("nav-links").Lis();
        var bookmarksLink = links.Where(l => l.HasAnchor("public-bookmarks-link")).First();
        var bookmarksDoc = bookmarksLink.Anchor().Navigate();
        bookmarksDoc.AddAnnotation(cookies);

        // display list of bookmarks
        Console.WriteLine("\nPublic bookmarks found in the system:");
        var bookmarks = bookmarksDoc.Body().Ol("bookmark-list").Lis();
        bookmarks.Each(bm => Console.WriteLine("{0}: {1}",
            bm.Anchor().AnchorText, bm.Anchor().AnchorLink));

        // navigate to the first bookmark in the list
        Console.WriteLine("\nNavigating to the first bookmark in the list...");
        var bookmarkDoc = bookmarks.First().Anchor().Navigate();
        var bookmarkDetails = bookmarkDoc.Body().Struct("bookmark");

        // print the bookmark details out to the console window
        Console.WriteLine("Bookmark details:");
        Console.WriteLine("bookmark-id: {0}", bookmarkDetails["bookmark-id"].Value);
        Console.WriteLine("bookmark-url-link: {0}",
            bookmarkDetails["bookmark-url-link"].Value);
        Console.WriteLine("bookmark-title: {0}", bookmarkDetails["bookmark-title"].Value);
        Console.WriteLine("bookmark-shared: {0}", bookmarkDetails["bookmark-shared"].Value);
        Console.WriteLine("bookmark-last-modified: {0}",
            bookmarkDetails["bookmark-last-modified"].Value);

        // retrieving login form
        Console.WriteLine("\nRetrieving login form...");
        Uri logonUri = new Uri("http://localhost:63965/Account/Logon");
        var logonDoc = XDocument.Load(logonUri.ToString());
        logonDoc.AddAnnotation(logonUri);
        logonDoc.AddAnnotation(cookies);

        // logging on as skonnard
        Console.WriteLine("Logging in as 'skonnard'");
        var logonForm = logonDoc.Body().Form("account-logon-form");
        logonForm["username"] = "skonnard";
        logonForm["password"] = "password";
        logonForm.Submit();
        Console.WriteLine("Login successful!");

        // create a new bookmark as 'skonnard'
        var createBookmarkDoc = bookmarksDoc.Body().Anchor(
            "create-bookmark-form-link").Navigate();
        createBookmarkDoc.AddAnnotation(cookies);
        var createBookmarkForm = createBookmarkDoc.Body().Form("create-bookmark-form");
        createBookmarkForm["bookmark-title"] = "Test from console!";
        createBookmarkForm["bookmark-url"] = "http://live.com/";
        createBookmarkForm["bookmark-tags"] = "Microsoft, Search";
        createBookmarkForm.Submit();
        Console.WriteLine("\nBookmark created!");
    }
}
The client starts by navigating to the root address, and then it looks for the link to the public bookmarks. Next it navigates to the public bookmark list and identifies a specific bookmark of interest (in this case, the first one). Next it navigates to the bookmark details and displays them to the console window. Then it retrieves the login form and performs a login using a set of credentials. Once logged in, the application retrieves the create bookmark form, fills it out, and submits a new bookmark to the system.
There are a few key observations to make at this point. First, the console application is capable of doing everything a human can do through the Web browser. That's the killer feature of this XHTML design style. Second, consumers need only to be hard-coded against the root URIs exposed by the service. All other URIs are discoverable at run time by navigating links found within the XHTML. And finally, processing XHTML structures isn't that much different from anything else—it's just data. Plus, this type of code only gets easier as you move toward dynamic languages in future versions of .NET.
Ultimately, ASP.NET MVC provides an inherently RESTful framework for implementing a web of XHTML-based resources that can be consumed by both humans and applications simultaneously. You can download the entire sample application shown in this article from the MSDN Magazine Web site.
For another complete example of an XHTML-based RESTful service found in the real world, browse to the Microsoft/TechNet Publishing System (MTPS) Content Services. This service uses many of the practices I've outlined in this article.

Acknowledgments
Thanks to both Tim Ewald and Craig Andera, whose creative thinking in this area provided fuel for my article. Tim also provided the XLinq extension methods found in the accompanying sample application.

Aaron Skonnard is a cofounder of Pluralsight, a Microsoft training provider offering both instructor-led and on-demand developer courses. These days Aaron spends most of his time recording Pluralsight On-Demand! courses focused on Cloud Computing, Windows Azure, WCF and REST. You can reach him at http://pluralsight.com/aaron and http://twitter.com/skonnard.


Scale Out
Distributed Caching On The Path To Scalability
Iqbal Khan

This article discusses:
  • Distributed caching
  • Scalability
  • Database synchronization
This article uses the following technologies:
ASP.NET, Web services, HPC applications
Contents
Distributed Caching
Must-Have Features in Distributed Cache
Expirations
Evictions
Caching Relational Data
Synchronizing a Cache with Other Environments
Database Synchronization
Read-Through
Write Through, Write Behind
Cache Query
Event Propagation
Cache Performance and Scalability
High Availability
Performance
Gaining Popularity
If you're developing an ASP.NET application, Web services or a high-performance computing (HPC) application, you're likely to encounter major scalability issues as you try to scale and put more load on your application. With an ASP.NET application, bottlenecks occur in two data stores. The first is the application data that resides in the database, and the other is ASP.NET session state data that is typically stored in one of three modes (InProc, StateServer, or SqlServer) provided by Microsoft. All three have major scalability issues.
Web services typically do not use session state, but they do have scalability bottlenecks when it comes to application data. Just like ASP.NET applications, Web services can be hosted in IIS and deployed in a Web farm for scalability.
HPC applications that are designed to perform massive parallel processing also have scalability problems because the data store does not scale in the same manner. HPC (also called grid computing) has traditionally used Java, but as .NET gains market share, it is becoming more popular for HPC applications as well. HPC applications are deployed to hundreds and sometimes thousands of computers for parallel processing, and they often need to operate on large amounts of data and share intermediate results with other computers. HPC applications use a database or a shared file system as a data store, and both of these do not scale very well.

Distributed Caching
Caching is a well-known concept in both the hardware and software worlds. Traditionally, caching has been a stand-alone mechanism, but that is not workable anymore in most environments because applications now run on multiple servers and in multiple processes within each server.
In-memory distributed caching is a form of caching that allows the cache to span multiple servers so that it can grow in size and in transactional capacity. Distributed caching has become feasible now for a number of reasons. First, memory has become very cheap, and you can stuff computers with many gigabytes at throwaway prices. Second, network cards have become very fast, with 1Gbit now standard everywhere and 10Gbit gaining traction. Finally, unlike a database server, which usually requires a high-end machine, distributed caching works well on lower cost machines (like those used for Web servers), which allows you to add more machines easily.
Distributed caching is scalable because of the architecture it employs. It distributes its work across multiple servers but still gives you a logical view of a single cache. For application data, a distributed cache keeps a copy of a subset of the data in the database. This is meant to be a temporary store, which might mean hours, days or weeks. In a lot of situations, the data being used in an application does not need to be stored permanently. In ASP.NET, for example, session data is temporary and needed for maybe a few minutes to a few hours at most.
Similarly, in HPC, large portions of the processing requires storing intermediate data in a data store, and this is also temporary in nature. The final outcome of HPC might be stored in a database, however. Figure 1 shows a typical configuration of a distributed cache in an enterprise.
Figure 1 Distributed Cache Shared by Various Apps in an Enterprise

Must-Have Features in Distributed Cache
Traditionally, developers have considered caching only static data, meaning data that never changes throughout the life of the application. But that data is usually a very small subset—maybe 10%—of the data that an application processes. Although you can keep static data in the cache, the real value comes if you can cache dynamic or transactional data—data that keeps changing every few minutes. You still cache it because within that time span, you might fetch it tens of times and save that many trips to the database. If you multiply that by thousands of users who are trying to perform operations simultaneously, you can imagine how many fewer reads you have on the database.
But if you cache dynamic data, the cache has to have certain features designed to avoid data integrity problems. A typical cache should have features for expiring and evicting items, as well as other capabilities. I'll explore these features in the following sections.

Expirations
Expirations are at the top of the list. They let you specify how long data should stay in the cache before the cache automatically removes it. You can specify two types of expirations: absolute-time expiration and sliding-time (or idle-time) expiration.
If the data in your cache also exists in a master data source, you know that this data can be changed in the database by users or applications that might not have access to the cache. When that happens, the data in the cache becomes stale. If you're able to estimate how long this data can be safely kept in the cache, you can specify absolute-time expiration—something like, "Expire this item 10 minutes from now" or "Expire this item at midnight tonight."
One interesting variation to absolute expiration is whether your cache can reload an updated copy of the cached item directly from your data source. This is possible only if your cache provides a read-through feature (see later sections) and allows you to register a read-through handler that reloads cached items when absolute expiration occurs. Except for a few commercial caches, most caches do not support this feature.
You can use idle-time (sliding-time) expiration to expire an item if it is not used for a given period of time. You can specify something like, "Expire this item if nobody reads or updates it for 10 minutes." This approach is useful when your application needs the data temporarily, but once the application is finished using it, you want the cache to automatically expire it. ASP.NET session state is a good candidate for idle-time expiration.
Absolute-time expiration helps you avoid situations in which the cache has a stale copy of the data or a copy that is older than the master copy in the database. Idle-time expiration is meant to clean up the cache after your application no longer needs certain data. Instead of having your application keep track of necessary cleanup, you let the cache take care of it.

Evictions
Most distributed caches are in-memory and do not persist the cache to disk. This means that in most situations, memory is limited and the cache size cannot grow beyond a certain limit, which could be the total memory available or much less than that if you have other applications running on the same machine.
Either way, a distributed cache should allow you to specify a maximum cache size (ideally, in terms of memory size). When the cache reaches this size, it should start removing cached items to make room for new ones, a process usually referred to as evictions.
Evictions are made based on various algorithms. The most popular is least recently used (LRU), where those cached items that have not been touched for the longest time are removed. Another algorithm is least frequently used (LFU). Here, those items that have been touched the least number of times are removed. There are a few other variations, but these two are the most popular.

Caching Relational Data
Most data comes from a relational database, but even if it does not, it is relational in nature, meaning that different pieces of data are related to one another—for example, a customer object and an order object.
When you have these relationships, you need to handle them in a cache. That means the cache should know about the relationship between a customer and an order. If you update or remove a customer from the cache, you might want the cache to also automatically update or remove related order objects from the cache. This helps maintain data integrity in many situations.
But again, if a cache cannot keep track of these relationships, you have to do it, and that makes your application much more cumbersome and complex. It's a lot easier if you just tell the cache at the time data is added that an order is associated with a customer, and the cache then knows that if that customer is updated or removed, related orders also have to be updated or removed from the cache.
ASP.NET Cache has a really cool feature called CacheDependency, which allows you to keep track of relationships between different cached items. Some commercial caches also have this feature. Figure 2 shows an example of how ASP.NET Cache works.
Figure 2 Keeping Track of Relationships Among Cached Items
using System.Web.Caching;

...

public void CreateKeyDependency()
{
   Cache["key1"] = "Value 1";
   // Make key2 dependent on key1.
   String[] dependencyKey = new String[1];
   dependencyKey[0] = "key1";
   CacheDependency dep1 = new CacheDependency(null, dependencyKey);

   Cache.Insert("key2", "Value 2", dep2);
}
This is a multilayer dependency, meaning that A can depend on B and B can depend on C. So, if your application removes C, A and B have to be removed from the cache as well.

Synchronizing a Cache with Other Environments
Expirations and cache dependency features are intended to help you keep the cache fresh and correct. You also need to synchronize your cache with data sources that you and your cache don't have access to so that changes in those data sources are reflected in your cache to keep it fresh.
For example, let's say your cache is written using the Microsoft .NET Framework, but you have Java or C++ applications modifying data in your master data source. You want these applications to notify your cache when certain data changes in the master data sources so that your cache can invalidate a corresponding cached item.
Ideally, your cache should support this capability. If it doesn't, this burden falls on your application. ASP.NET Cache provides this feature through CacheDependency, as do some commercial caching solutions. It allows you to specify that a certain cached item depends on a file and that whenever this file is updated or removed, the cache discovers this and invalidates the cached item. Invalidating the item forces your application to fetch the latest copy of this object the next time your application needs it and does not find it in the cache.
If you had 100,000 items in the cache, 10,000 of them might have file dependencies, and for that you might have 10,000 files in a special folder. Each file has a special name associated with that cached item. When some other application—whether written in .NET or not—changes the data in the master data source, that application can communicate to the cache through an update of the file time stamp.

Database Synchronization
The need for database synchronization arises because the database is being shared across multiple applications, and not all those applications have access to your cache. If your application is the only application updating the database and it can also easily update the cache, you probably don't need the database synchronization capability. But in a real-life environment, that's not always the case. Whenever a third party or any other application changes the database data, you want the cache to reflect that change. The cache reflects changes by reloading the data, or at least by not having the older data in the cache.
If the cache has an old copy and the database a new copy, you now have a data integrity problem because you don't know which copy is right. Of course, the database is always right, but you don't always go to the database. You get data from the cache because your application trusts that the cache will always be correct or that the cache will be correct enough for its needs.
Synchronizing with the database can mean invalidating the related item in the cache so that the next time your application needs it, it will fetch it from the database. One interesting variant to this process is when the cache automatically reloads an updated copy of the object when the data changes in the database. However, this is possible only if your cache allows you to provide a read-through handler (see the next section) and then uses it to reload the cached item from the database. However, only some of the commercial caches support this feature, and none of the free ones do.
ASP.NET Cache has a SqlCacheDependency feature (see Figure 3) that allows you to synchronize the cache with a SQL Server 2005/2008 or Oracle 10g R2 or later version database—basically any database that has the .NET CLR built into it. Some of the commercial caches also provide this capability.
Figure 3 Using SqlDependency to Synchronize with a Relational Database
using System.Web.Caching;
using System.Data.SqlClient;

...

public void CreateSqlDependency(Customers cust, SqlConnection conn)
{
  // Make cust dependent on a corresponding row in the
  // Customers table in Northwind database
  string sql = "SELECT CustomerID FROM Customers WHERE ";
  sql += "CustomerID = @ID";
  SqlCommand cmd = new SqlCommand(sql, conn);
  cmd.Parameters.Add("@ID", System.Data.SqlDbType.VarChar);
  cmd.Parameters["@ID"].Value = cust.CustomerID;

  SqlCacheDependency dep = new SqlCacheDependency(cmd);
  string key = "Customers:CustomerID:" + cust.CustomerID;

  Cache.Insert(key, cust, dep);
}
ASP.NET Cache SqlCacheDependency allows you to specify a SQL string to match one or more rows in a table in the database. If this row is ever updated, the DBMS fires a .NET event that your cache catches. It then knows which cached item is related to this row in the database and invalidates that cached item.
One capability that ASP.NET Cache does not provide but that some commercial solutions do is polling-based database synchronization. This capability is helpful in two situations. First, if your DBMS does not have the .NET CLR built into it, you cannot benefit from SqlCacheDependency. In that case, it would be nice if your cache could poll your database on configurable intervals and detect changes in certain rows in a table. If those rows have changed, your cache invalidates their corresponding cached items.
The second situation is when data in your database is frequently changing and .NET events are becoming too chatty. This occurs because a separate .NET event is fired for each SqlCacheDependency change, and if you have thousands of rows that are updated frequently, this could easily crowd your cache. In such cases, it is much more efficient to rely on polling, where with one database query you can fetch hundreds or thousands of rows that have changed and then invalidate corresponding cached items. Of course, polling creates a slight delay in synchronization (maybe 15–30 seconds), but this is acceptable in many cases.

Read-Through
In a nutshell, read-through is a feature that allows your cache to directly read data from your data source, whatever that may be. You write a read-through handler and register it with your cache, and then your cache calls this handler at appropriate times. Figure 4 shows an example.
Figure 4 Example of a Read-Through Handler for SQL Server
using System.Web.Caching;
using System.Data.SqlClient;
using Company.MyDistributedCache;

...

public class SqlReadThruProvider : IReadhThruProvider
{
  private SqlConnection _connection;

  // Called upon startup to initialize connection
  public void Start(IDictionary parameters)
  {
    _connection = new SqlConnection(parameters["connstring"]);
    _connection.Open();
  }

  // Called at the end to close connection
  public void Stop() { _connection.Close(); }

  // Responsible for loading object from external data source
  public object Load(string key, ref CacheDependency dep)
  {
    string sql = "SELECT * FROM Customers WHERE ";
    sql += "CustomerID = @ID";
    SqlCommand cmd = new SqlCommand(sql, _connection);
    cmd.Parameters.Add("@ID", System.Data.SqlDbType.VarChar);

    // Let's extract actual customerID from "key"
    int keyFormatLen = "Customers:CustomerID:".Length;
    string custId = key.Substring(keyFormatLen,
    key.Length - keyFormatLen);
    cmd.Parameters["@ID"].Value = custId;

    // fetch the row in the table
    SqlDataReader reader = cmd.ExecuteReader();

    // copy data from "reader" to "cust" object
    Customers cust = new Customers();
    FillCustomers(reader, cust);

    // specify a SqlCacheDependency for this object
    dep = new SqlCacheDependency(cmd);
    return cust;
  }
}
Because a distributed cache usually lives outside your application, it is shared across multiple instances of your application or even multiple applications. One important capability of a read-through handler is that the data you cache is fetched by the cache directly from the database. Hence, your applications don't have to have database code. They can just fetch data from the cache, and if the cache doesn't have it, the cache goes and takes it from the database.
You gain even more important benefits if you combine read-through capabilities with expirations. Whenever an item in the cache expires, the cache automatically reloads it by calling your read-through handler. You save a lot of traffic to the database with this mechanism. The cache uses only one thread, one database trip, to reload that data from the database, whereas you might have thousands of users trying to access that same data. If you did not have read-through capability, all those users would be going directly to the database, inundating the database with thousands of parallel requests.
Read-through allows you to establish an enterprise-level data grid, meaning a data store that not only is highly scalable, but can also refresh itself from master data sources. This provides your applications with an alternate data source from which to read data and relieves a lot of pressure on your databases.
As mentioned earlier, databases are always the bottleneck in high-transaction environments, and they become bottlenecks due mostly to excessive read operations, which also slow down write operations. Having a cache that serves as an enterprise-level data grid above your database gives your applications a major performance and scalability boost.
However, keep in mind that read-through is not a substitute for performing some complex joined queries in the database. A typical cache does not let you do these types of queries. A read-through capability works well for individual object read operations but not in operations involving complex joined queries, which you always need to perform on the database.

Write Through, Write Behind
Write-through is just like read-through: you provide a handler, and the cache calls the handler, which writes the data to the database whenever you update the cache. One major benefit is that your application doesn't have to write directly to the database because the cache does it for you. This simplifies your application code because the cache, rather than your application, has the data access code.
Normally, your application issues an update to the cache (for example, Add, Insert, or Remove). The cache updates itself first and then issues an update call to the database through your write-through handler. Your application waits until both the cache and the database are updated.
What if you want to wait for the cache to be updated, but you don't want to wait for the database to be updated because that slows down your application's performance? That's where write-behind comes in, which uses the same write-through handler but updates the cache synchronously and the database asynchronously. This means that your application waits for the cache to be updated, but you don't wait for the database to be updated.
You know that the database update is queued up and that the database is updated fairly quickly by the cache. This is another way to improve your application performance. You have to write to the database anyway, but why wait? If the cache has the data, you don't even suffer the consequences of other instances of your application not finding the data in the database because you just updated the cache, and the other instances of your application will find the data in the cache and won't need to go to the database.

Cache Query
Normally, your application finds objects in the cache based on a key, just like a hash table, as you've seen in the source code examples above. You have the key, and the value is your object. But sometimes you need to search for objects based on attributes other than the key. Therefore, your cache needs to provide the capability for you to search or query the cache.
There are a couple of ways you can do this. One is to search on the attributes of the object. The other involves situations in which you've assigned arbitrary tags to cached objects and want to search based on the tags. Attribute-based searching is currently available only in some commercial solutions through object query languages, but tag-based searching is available in commercial caches and in Microsoft Velocity.
Let's say you've saved a customer object. You could say, "Give me all the customers where the city is San Francisco," when you want only customer objects, even though your cache has employees, customers, orders, order items, and more. When you issue a SQL-like query such as the one shown in Figure 5, it finds the objects that match your criteria.
Figure 5 Using a LINQ Query to Search Items in the Cache
using Company.MyDistributedCache;

...

public List<Customers> FindCustomersByCity(Cache cache, string city)
{
  // Search cache with a LINQ query
  List<Customers> custs = from cust in cache.Customers
                          where cust.City == city
                          select cust;
  return custs;
}
Tagging lets you attach multiple arbitrary tags to a specific object, and the same tag can be associated with multiple objects. Tags are usually string-based, and tagging also allows you to categorize objects into groups and then find the objects later through these tags or groups.

Event Propagation
You might not always need event propagation in your cache, but it is an important feature that you should know about. It's a good feature to have if you have distributed applications, HPC applications, or multiple applications sharing data through a cache. What event propagation does is ask the cache to fire events when certain things happen in the cache. Your applications can capture these events and take appropriate actions in response.
Say your application has fetched some object from the cache and is displaying it to the user. You might be interested to know if anybody updates or removes this object from the cache while it is displayed. In this case, your application will be notified, and you can update the user interface.
This is, of course, is a very simple example. In other cases, you might have a distributed application where some instances of your application are producing data and other instances need to consume it. The producers can inform the consumers when data is ready by firing an event through the cache that the consumers receive. There are many examples of this type, where collaboration or data sharing through the cache can be achieved through event propagation.

Cache Performance and Scalability
When considering the caching features discussed in the previous sections, you must not forget that the main reasons you're thinking of using a distributed cache, which are to improve performance and, more important, to improve the scalability of your application. Also, because your cache runs in a production environment as a server, it must also provide high availability.
Scalability is the fundamental problem a distributed cache addresses. A scalable cache is one that can maintain performance even when you increase the transaction load on it. So, if you have an ASP.NET application in a Web farm and you grow your Web farm from five Web servers to 15 or even 50 Web servers, you should be able to grow the number of cache servers proportionately and keep the same response time. This is something you cannot do with a database.
A distributed cache avoids the scalability problems that a database usually faces because it is much simpler in nature than a DBMS and also because it uses different storage mechanisms (also known as caching topologies) than a DBMS. These include replicated, partitioned, and client cache topologies.
In most distributed cache situations, you have two or more cache servers hosting the cache. I'll use the term "cache cluster" to indicate two or more cache servers joined together to form one logical cache. A replicated cache copies the entire cache on each cache server in the cache cluster. This means that a replicated cache provides high availability. If any one cache server goes down, you don't lose any data in the cache because another copy is immediately available to the application. It's also an extremely efficient topology and provides great scalability if your application needs to do a lot of read-intensive operations. As you add more cache servers, you add that much more read-transaction capacity to your cache cluster. But a replicated cache is not the ideal topology for write-intensive operations. If you are updating the cache as frequently as you are reading it, don't use the replicated topology.
A partitioned cache breaks up the cache into partitions and then stores one partition on each cache server in the cluster. This topology is the most scalable for transactional data caching (when writes to the cache are as frequent as reads). As you add more cache servers to the cluster, you increase not only the transaction capacity but also the storage capacity of the cache, since all those partitions together form the entire cache.
Many distributed caches provide a variant of a partitioned cache for high availability, where each partition is also replicated so that one cache server contains a partition and a copy or a backup of another server's partition. This way, you don't lose any data if any one server goes down. Some caching solutions allow you to create more than one copy of each partition for added reliability.
Another very powerful caching topology is client cache (also called near cache), which is very useful if your cache resides in a remote dedicated caching tier. The idea behind a client cache is that each client keeps a working set of the cache close by (even within the application's process) on the client machine. However, just as a distributed cache has to be synchronized with the database through different means (as discussed earlier), a client cache needs to be synchronized with the distributed cache. Some commercial caching solutions provide this synchronization mechanism, but most provide only a stand-alone client cache without any synchronization.
In the same way that a distributed cache reduces traffic to the database, a client cache reduces traffic to the distributed cache. It is not only faster than the distributed cache because it is closer to the application (and can also be InProc), it also improves the scalability of the distributed cache by reducing trips to the distributed cache. Of course, a client cache is a good approach only when you are performing many more reads than writes. If the number of reads and writes are equal, don't use a client cache. Writes will become slower because you now have to update both the client cache and the distributed cache.

High Availability
Because a distributed cache runs as a server in your production environment, and in many cases serves as the only data store for your application (for example, ASP.NET session state), the cache must provide high availability. This means that your cache must be very stable so that it never crashes and provides the ability to make configuration changes without stopping the cache.
Most users of a distributed cache require the cache to run without any interruptions for months at a time. Whenever they have to stop the cache, it is usually during a scheduled down time. That is why high availability is so critical for a distributed cache. Here are a few questions to keep in mind when evaluating whether a caching solution provides high availability.
  • Can you bring one of the cache servers down without stopping the entire cache?
  • Can you add a new cache server without stopping the cache?
  • Can you add new clients without stopping the cache?
In most caches, you use a specified maximum cache size so that the cache doesn't exceed the amount of data. The cache size is based on how much memory you have available on that system. Can you change that capacity? Let's say you initially set the cache size to be 1GB but now want to make it 2GB. Can you do that without stopping the cache?
Those are the types of questions you want to consider. How many of these configuration changes really require the cache to be restarted? The fewer, the better. Other than the caching features, the first criteria for having a cache that can run in a production environment is how much uptime the cache is going to give you.

Performance
Simply put, if accessing the cache is not faster than accessing your database, there is no need to have it. Having said that, what should you expect in terms of performance from a good distributed cache?
The first thing to remember is that a distributed cache is usually OutProc or remote, so access time will never be as fast as that of a stand-alone InProc cache (for example, ASP.NET Cache). In an InProc stand-alone cache, you can probably read 150,000 to 200,000 items per second (1KB object size). With an OutProc or a remote cache, this number drops significantly. In terms of performance, you should expect about 20,000 to 30,000 reads per second (1KB object size) as the throughput of an individual cache server (from all clients hitting on it). You can achieve some of this InProc performance by using a client cache (in InProc mode), but that is only for read operations and not for write operations. You sacrifice some performance in order to gain scalability, but the slower performance is still much faster than database access.

Gaining Popularity
A distributed cache as a concept and as a best practice is gaining more popularity. Only a few years ago, very few people in the .NET space knew about it, although the Java community has been ahead of .NET in this area. With the explosive growth in application transactions, databases are stressed beyond their limits, and distributed caching is now accepted as a vital part of any scalable application architecture.

Iqbal Khan is president and technology evangelist at Alachisoft. Alachisoft provides NCache, an industry-leading .NET distributed cache for boosting performance and scalability in enterprise applications. Iqbal has an MS in computer science from Indiana University, Bloomington. You can reach him at iqbal@alachisoft.com.


Inside Windows 7
Introducing The Taskbar APIs
Yochay Kiriaty & Sasha Goldshtein

This article discusses:
  • Taskbar Buttons
  • Overlay Icons
  • Progress Bars
  • Thumbnail Toolbars
This article uses the following technologies:
Windows 7

This article is based on a prerelease version of Windows 7. Details are subject to change.
Contents
Taskbar Buttons
Overlay Icons and Progress Bars
Thumbnail Toolbars
Jump Lists
Miscellaneous Features
Summary
The Windows 7 taskbar is the latest in a series of evolutionary taskbar designs that started with Windows 1.0. It represents a design and architectural change with regard to user experience, and offers significant improvements in user productivity. Figure 1 shows the Windows 1.0 taskbar. (Note that the 1.0 taskbar bears more resemblance to the Windows 7 taskbar than to the Windows Vista taskbar.)
Figure 1 Windows 1.0 taskbar
Analysis from a number of user sessions during recent years has shown that having an abundance of launch surfaces (those areas dedicated to launch programs) does not necessarily make the user's work any easier. As far as user interface design is concerned, to prevent user confusion it's often better to have only one way to accomplish a task.
The design goals of the Windows 7 taskbar are to bring control back to the user and to minimize confusion, by supporting the following principles:
  • Single launch surface for frequent programs and destinations. This helps keep those applications and data that you use all the time right at your fingertips.
  • Easy to control, where switching between applications and windows and arranging windows are made easy and manageable.
  • Clean, noise-free, simple.
Large taskbar buttons, visual clarity, and sleekness of design dominate users experience once they are logged on to Windows 7. But how can developers leverage the new functionality that the Windows 7 taskbar has to offer? How do the underlying mechanisms work together to enable the best user experience? In this article, we will explore the new features and underlying functionality of the Windows 7 taskbar, supported with examples in native and managed code.

Taskbar Buttons
Taskbar buttons provide the gateway to access the functionality of the new Windows 7 taskbar. The biggest thing to notice is that the taskbar also contains icons for applications that are not currently running. For example, the user may pin applications to the taskbar, which results in a pinned icon on the taskbar but the application is not running. Clicking the icon causes the app to launch. This is a unification of the Quick Launch concept and the standard Windows taskbar. In fact, there is no need for the Quick Launch area on Windows 7 any longer; the only reason the Quick Launch folder is still in Windows 7 is for backwards compatibility.
You may have already heard about jump lists, thumbnail toolbars, taskbar progress bars, and other features. They are all connected with the large, redesigned taskbar buttons that occupy the new taskbar. The Windows 7 taskbar buttons, shown in Figure 2, are identified with multiple visual effects. They make it possible to immediately identify which applications are running, whether there are multiple windows in the same application, which application is currently active, and which taskbar button currently has the mouse hovering over it.
Figure 2 Various Windows 7 Taskbar Button States
All the Windows 7 taskbar features are unlocked only after you have created the taskbar button for your application. This makes sense, since you can't change the taskbar overlay icon, for example, if there is no taskbar button yet! In practice, this means that managed and native applications using the new Windows 7 taskbar APIs will have to wait for a new window message, identifiable by the TaskbarButtonCreated string. To obtain the identifier of this message, you must call the RegisterWindowMessage Win32 API and pass the TaskbarButtonCreated string as a parameter.
The following code shows how a Win32 application receives the window message indicating that the taskbar button is created:
DWORD g_wmTBC = (DWORD)-1;

//In the window procedure:
switch (msg) {
case WM_CREATE:
    g_wmTBC = RegisterWindowMessage(L"TaskbarButtonCreated");
    //Proceed to create the window
case g_wmTBC:
    //The taskbar button has been created
}
A managed application, for example an application using Windows Forms, would have to override the window procedure (the WndProc method) of the form to process window messages. The following code shows this:
uint wmTBC = (uint)-1;

[DllImport("user32.dll")]
static extern uint RegisterWindowMessage(string message);

void Form_Load() {
    wmTBC = RegisterWindowMessage(L"TaskbarButtonCreated");
}
protected override void WndProc(...) {
    if (msg == wmTBC) {
        //The taskbar button has been created
    }
}
Now you know how to make sure that your application does not use the Windows 7 taskbar before there is a taskbar button in place. Before we jump to more interesting features, there's just one additional piece of information that you need to complete the puzzle. How are taskbar buttons associated with windows and applications? How does the system decide whether an application needs two taskbar buttons for its different windows or whether multiple applications need to share a single taskbar button?
The answer is application ID. This is a new property of the Windows Shell and is an attribute of windows, processes and shell links (also known as shortcuts). By controlling the application ID of individual windows and processes, application developers can ensure that the taskbar buttons are associated to their windows exactly as they deem fit. The application ID is a string—not a GUID—that can take a free format of up to 128 characters. To make sure application IDs do not accidentally collide, the recommendation is to include in the application ID the company name, product name, and application name. The default application ID for a window is determined by the default application ID for the process to which the window belongs. This is, in turn, a default application ID generated for the executable file that the process runs. Try launching an application like Notepad several times to see this in action. There is only one taskbar button created even if you run multiple instances of Notepad at the same time.
Customizing these default IDs involves explicitly setting an application ID for the process or for an individual window, producing interesting scenarios. For example, if you set the application ID of two different processes to the same value, windows created by both of these processes will be grouped to the same taskbar button. Alternatively, if you set the application ID of two individual windows (within the same process) to different values, two taskbar buttons will be created, one for each window. The combination of process application ID and window-specific application ID provides for maximum flexibility. In Figure 3, the left pane shows that the windows from different processes are all grouped under one taskbar button. The right pane shows that multiple windows from the same process have multiple taskbar buttons.
Figure 3 Windows, Processes, and Taskbar Buttons
Setting the application ID for a process involves a call to the SetCurrentProcessExplicitAppUserModelID Win32 function from shell32.dll. Setting the application ID for a window requires calling the SHGetPropertyStoreForWindow function and then manipulating the returned IPropertyStore object. The following example shows you how to do this:
PROPVARIANT pv;
InitPropVariantFromString(L"MyAppID", &pv);

IPropertyStore* pps;
VERIFY(SHGetPropertyStoreForWindow(hwnd, IID_PPV_ARGS(&pps)));
VERIFY(pps->SetValue(PKEY_AppUserModel_ID, pv));
VERIFY(pps->Commit());
So far we've escaped the necessity of calling complicated APIs from managed code, but now we have no choice. Fortunately, the Windows API Code Pack comes to the rescue.
The Windows API Code Pack for the Microsoft .NET Framework provides a library that can be used to access new Windows 7 and Windows Vista features from managed code. . At the time of this writing, the code pack includes support for Windows 7 shell libraries, known folders, Windows Vista task dialogs, Windows 7 jump lists, icon overlays, progress bars, and other features. While this is not an officially supported Microsoft product, the code pack provides a very good jump-start for managed application developers targeting Windows 7. It alleviates the necessity to implement managed wrappers for complicated Windows features.
The Windows API Code Pack provides the static Taskbar.AppId property for manipulating the application ID of a given process. Unfortunately, there is no equivalent for setting the application ID of a specific window. Instead, this can be accomplished by either writing the required wrapper manually or using the predecessor of the Windows API Code Pack. (A sample interoperability library for the Windows 7 taskbar can be downloaded from Windows 7 taskbar: Developer Resources. Using the library provides you with the Windows7Taskbar.SetWindowAppId static method which does the ugly interoperability work.)

Overlay Icons and Progress Bars
The route to most Windows 7 taskbar features is via the ITaskbarList3 interface. If you're using managed code and managed wrappers, you might never have to come across this interface. However, if you're using native code, it's important that you know how to get your hands on one. That's easy if you just make sure that you do so after you received the message indicating that the taskbar button was created. In other words, you must wait for the taskbar button to become initialized, and then obtain a pointer to the ITaskbarList3 interface, like so:
ITaskbarList3* ptl;
VERIFY(CoCreateInstance(
    CLSID_TaskbarList, NULL, CLSCTX_ALL,
    IID_ITaskbarList3, (void**)&ptl));
Setting an overlay icon or providing a progress bar in the Windows 7 taskbar is a fairly easy task. Fortunately, for managed developers, there is a managed equivalent in the Windows API Code Pack. To set an overlay icon, you use the ITaskbarList3::SetOverlayIcon method, which takes an icon handle (HICON) and a string serving as an accessible description. The managed equivalent is the Taskbar.OverlayImage property, which is equally easy to use.
The following code controls an application's overlay icon based on a selection made in a combo box (also shown in Figure 4):
void comboBox1_ValueChanged(...) {
    if (comboBox1.SelectedItem == ...) {
        Taskbar.OverlayImage = new OverlayImage(icon1, "Icon 1");
    } else {
        Taskbar.OverlayImage = new OverlayImage(icon2, "Icon 2");
    }
}
Figure 4 Windows Live Messenger and its Overlay Icon
Similarly, the ITaskbarList3::SetProgressState and ITaskbarList3::SetProgressValue methods modify the state of the taskbar progress bar. There are several states available for applications to use: indeterminate, paused, error and normal. The appearances of the various states are summarized in Figure 5. The managed equivalent is the Taskbar.ProgressBar.State and Taskbar.ProgressBar.CurrentValue static properties, as well as the Taskbar.ProgressBar.MaxValue property.
Figure 5 Various States of the Taskbar Progress Bar
The following code and Figure 6 demonstrate how a background operation can affect the state of the taskbar progress control (assume that the DoWork function runs in a separate, background thread):
HWND hmainwnd;//Application main window
ITaskbarList3* ptl;//Created earlier

DWORD WINAPI DoWork(LPVOID) {
    ptl->SetProgressState(hmainwnd, TBPF_NORMAL);
    for (int i = 0; i < WorkToDo; ++i) {
        DoSomePartOfTheWork(i);
        ptl->SetProgressValue(hmainwnd, i, WorkToDo);
    }
    ptl->SetProgressState(hmainwnd, TBPF_PAUSED);
    return 0;
}
Figure 6 Internet Explorer Reports Download Progress.
Applications that take advantage of the built-in file operation functionality, added to the Windows Shell in Windows Vista, automatically get taskbar progress support for free. If you use the Win32 SHFileOperation function or IFileOperation interface, your taskbar button will automatically light up with progress information, even if you're invoking the APIs from a console application. In managed code, you can read Stephen Toub's MSDN Magazine article from December 2007, titled ".NET Matters: IFileOperation in Windows Vista." His FileOperation class provides an excellent wrapper of the underlying native API and makes it equally easy to use from managed code. Try his samples on Windows 7, and you will immediately see a demonstration of the taskbar progress bar.

Thumbnail Toolbars
Thumbnail toolbars are a great addition to the Windows 7 taskbar landscape. Thumbnail and live preview functionality have been greatly enriched in Windows 7 (unfortunately, it is not within the scope of this article to discuss them in any detail). Thumbnail toolbars provide a mini "remote-control" opportunity for a window from its thumbnail. For example, to switch to the next song in Windows Media Player you don't need to use the clumsy Media Player desk band or to switch to the Media Player application. Instead, you can use the thumbnail toolbar directly to perform this task, without interrupting your work flow by jumping to another application, as shown in Figure 7.
Figure 7 Windows Media Player Provides a Thumbnail Toolbar for Convenient Navigation.
To use a thumbnail toolbar, you must wait for the taskbar button to become initialized, and then obtain a pointer to the ITaskbarList3 interface, as described earlier. Next, you initialize a set of THUMBBUTTON structures that describe the individual buttons that appear in the toolbar (note that you are limited to seven buttons at most, and that there is no way to add or remove buttons after you initialize the toolbar, only to disable or hide them.) Finally, you call the ITaskbarList3::ThumbBarAddButtons and ITaskbarList3::ThumbBarUpdateButtons methods to control the thumbnail toolbar.
When a thumbnail button is clicked, the application receives a WM_COMMAND message with the high word of the wParam set to THBN_CLICKED and the low word set to the button ID. This message is dispatched to the window to which the thumbnail belongs. Figure 8 demonstrates the creation and message handling that are required.
Figure 8 Creation and Message Handling
ITaskbarList3* ptl;//Created earlier

//In your window procedure:
switch (msg) {
case g_wmTBC://TaskbarButtonCreated
    THUMBBUTTON buttons[2];
    buttons[0].dwMask = THB_ICON|THB_TOOLTIP|THB_FLAGS;
    buttons[0].iId = 0;
    buttons[0].hIcon = GetIconForButton(0);
    wcscpy(buttons[0].szTip, L"Tooltip 1");
    buttons[0].dwFlags = THBF_ENABLED;
    buttons[1].dwMask = THB_ICON|THB_TOOLTIP|THB_FLAGS;
    buttons[1].iId = 1;
    buttons[1].hIcon = GetIconForButton(1);
    wcscpy(buttons[0].szTip, L"Tooltip 2");
    buttons[1].dwFlags = THBF_ENABLED;
    VERIFY(ptl->ThumbBarAddButtons(hWnd, 2, buttons));
    break;

case WM_COMMAND:
    if (HIWORD(wParam) == THBN_CLICKED) {
        if (LOWORD(wParam) == 0)
            MessageBox(L"Button 0 clicked", ...);
        if (LOWORD(wParam) == 1)
            MessageBox(L"Button 1 clicked", ...);
    }
    break;
The managed equivalent does not currently appear in the Windows API Code Pack, but it is planned to appear in a future release. In the meantime, you can use the Windows 7 taskbar Interop Sample Library. It contains the ThumbButtonManager class with the corresponding CreateThumbButton and AddThumbButtons methods for controlling the thumbnail toolbar, and also the ThumbButton class for modifying the thumbnail button state at runtime. To receive notifications, you register for the ThumbButton.Clicked event and override your window procedure to dispatch the messages to the ThumbButtonManager class, which does the dispatching magic for you. (For more details, see the blog article "Windows 7 Taskbar: Thumbnail Toolbars.")

Jump Lists
The final feature of the Windows 7 taskbar that we discuss in detail here is the jump list, arguably the most important feature that applications need to take advantage of in order to truly shine on Windows 7. In the Windows 7 taskbar, each taskbar button is associated with a jump list. This is a retractable menu that shows a collection of items (also called destinations) and tasks that are relevant to the given application. Destinations are typically represented by shell items (through the IShellItem interface), and are files/documents that your application works with. Tasks are typically represented by shell links (also known as shortcuts, through the IShellLink interface), and can be used to launch other associated applications or even your own application with a different set of command line arguments.
Some applications may choose to customize the tasks area of a jump list. For example, Windows Live Messenger uses a variety of tasks and separators to make it easier to use the application from the jump list, as shown in Figure 9.
Figure 9 Windows Live Messenger
Some other applications might choose to customize the items (or destinations) area of the jump list, and even categorize the items to make the user's work more convenient. At the very least, applications should provide a collection of recent or frequent items pertinent to the application, because users will grow to expect this functionality from every Windows 7 application. As an example, consider the Microsoft Office Word jump list, as shown in Figure 10. Even though Word was not designed for Windows 7, it uses the recent items infrastructure built into Windows and the jump list works by default.
Figure 10 Jump List of Recent Documents
It should be pretty clear that it's possible to get the jump list to work for you without a significant effort. For recent items to appear in your application's jump list, follow these steps:
  1. Make sure that your application's file type is associated with your application in the Windows registry (as a registered handler). Note that your application does not have to be the primary or default handler for the file type. (See msdn.microsoft.com/en-us/library/dd378402(VS.85).aspx for more information.)
  2. Make sure that you use the common file dialogs for loading and saving files. If you aren't using the common file dialogs, let the Windows Shell know when you're using a file as a result of a user's request by calling the SHAddToRecentDocs Win32 function. (See the "Common Dialog Box Library" article on MSDN for more information on common dialogs.)
If your jump list requires further customization, you can add custom categories of destinations or custom tasks to enrich its functionality. The ICustomDestinationList is the source of jump list functionality, along with the following useful methods: AddUserTasks, AppendCategory, and AppendKnownCategory. To begin a list-building transaction, you call BeginList, and then you can choose between AbortList and CommitList, which are self-explanatory. You can also delete all items from the list by calling DeleteList. An example of a list-building transaction is available in the Windows 7 SDK.
The managed equivalent is significantly easier to use. It all begins with the Taskbar.JumpList property, which unlocks a handful of methods for manipulating the jump list's destinations and tasks: the AddToRecent method is the equivalent of SHAddToRecentDocs, the KnownCategoryToDisplay property determines whether to show recent or frequent items by default, the UserTasks property returns a modifiable collection of user tasks, and the CustomCategories property returns a collection of custom categories (each custom category has a name and a collection of jump list items). The following example demonstrates a list-building transaction for adding items and tasks to the application's jump list:
JumpListLink notepad = new JumpListLink {
    Title = "Launch Notepad", Path = @"C:\Windows\notepad.exe" };

JumpListItem doc1 = new JumpListItem(@"doc1.txt");
JumpListItem doc2 = new JumpListItem(@"doc2.txt");
CustomCategory category = new CustomCategory("Special Items");
category.JumpListItems.Add(doc1);
category.JumpListItems.Add(doc2);

Taskbar.JumpList.UserTasks.Add(notepad);
Taskbar.JumpList.CustomCategories.Add(category);
An important thing to note is that the user may choose to remove items from the taskbar by right-clicking them and selecting "Remove from this list." Applications must be aware of this functionality. If they attempt to add an item that a user has removed, it will cause the entire list-building transaction to fail. In Win32 code, when calling the ICustomDestinationList::BeginList method, you receive a collection of removed items that should require extra care so you don't add these items again:
ICustomDestinationList* cdl;
VERIFY(CoCreateInstance(CLSID_DestinationList, ..., IID_ICustomDestinationList, (void**)cdl));

IObjectArray* removedItems;
cdl->BeginList(&maxSlots, IID_IObjectArray, (void**)removedItems);
//…Iterate removedItems and make decisions
removedItems->Release();
Alternatively, you can proactively call the ICustomDestinationList::GetRemovedDestinations method to retrieve the removed items before initiating the list-building transaction. Managed applications can leverage the functionality built into the Windows API Code Pack and rely on the JumpList class that automatically does not add items that were previously removed by the user. Alternatively, managed applications can register to the Taskbar.JumpList.JumpListItemsRemoved event that occurs when the infrastructure detects (within a list-building transaction) that items were removed from the jump list.
While the variety of alternatives in the jump list might appear overwhelming, bear in mind that most users will expect your application to provide at least the simplest interface—such as the list of recent or frequent items that have been used throughout your application. If you adhere to this fundamental requirement, you are almost guaranteed to satisfy your users; if you add custom functionality to your jump list through custom tasks and destinations, you've got your differentiation opportunity on Windows 7.

Miscellaneous Features
The Windows 7 taskbar contains a variety of other features that we did not cover in this article. Among them are: Live Preview (also known as Aero Peek), thumbnail customization (can enhance users productivity when previewing applications,) thumbnail support for Tabbed Document Interface (TDI) and Multiple Document Interface (MDI) applications, and several others.
For an overview of these features, as well as a discussion of the related native APIs and their managed equivalents, see the following resources:
  • Engineering Windows 7: The Windows 7 Taskbar
  • Windows 7 Taskbar Sample Library: An Overview
  • Windows 7 Taskbar: APIs
  • Windows 7 Taskbar: Thumbnail Clip and Custom Previews
  • Windows 7 Taskbar: Window Switchers and Previews In Depth
  • MSDN Channel 9 Taskbar Videos

Summary
In this article, we have explored some features of the Windows 7 taskbar, such as application IDs, thumbnail toolbars, overlay icons, progress bars and jump lists. The Windows 7 taskbar provides a clean, sleek launch surface that strongly benefits users. Integrating into this surface will be a primary goal for any application developer for Windows 7.
Using the native Win32 APIs or the managed Windows API Code Pack provides you with a differentiating opportunity to light up your applications on Windows 7. Bear in mind that the taskbar is the first thing users see after logging on to Windows, and you'll want your application to be pinned to their taskbar.

Yochay Kiriaty is a Technical Evangelist at Microsoft , focusing on Windows 7. He has more than a decade of experience in software development. He has written and taught academic computer science courses and is an active contributor to The Windows Blog.

Sasha Goldshtein is a Senior Consultant at Sela Group, an international training, consulting and development company. Sasha leads the Performance and Debugging team at Sela and specializes in managed and native solutions on Windows, including high-performance applications, interoperability scenarios and high-availability server applications. He is the author of Windows Internals and Windows Vista courses that have been delivered worldwide and submitted to the Microsoft Courseware Library. Sasha is a speaker at various Microsoft conferences.


Testable MVC
Building Testable ASP.NET MVC Applications
Justin Etheredge

This article discusses:
  • ASP.NET MVC
  • Building testable solutions
  • Dependency injection
This article uses the following technologies:
ASP.NET
Contents
Testing Support in ASP.NET MVC
Tooling
Application Scenario
High-Level Application Design
Abstracting the Model
The Repository Pattern
Injecting the Repository
Implementing the Service Layer
Isolating View Logic
Testing Routes
Passing Dependencies of Actions as Parameters
Testing with Action Results
Wrapping Up
You've probably heard the old adage, "Better, faster, cheaper, pick any two." If you want something good and fast, it isn't going to be cheap, and if you want something fast and cheap, it isn't going to be very good. Cheaper, faster, and better means that we need to write more code more quickly, right? If only it were that simple. Learning to type faster might satisfy two of the requirements, but it isn't going to make the software you develop any better. So how do we make software better? What does "better" mean?
"Better" means producing flexible, maintainable software with a low number of defects; better software is all about long-term maintainability. To achieve this, a key design decision is to ensure that components are loosely coupled. Loosely coupled software has many benefits. One that stands out is that it improves our ability to test solutions. If we write software that can be broken down easily into small parts, it becomes easier to test. It sounds simple when you word it that way, but the amount of software in use today that is difficult to test or maintain shows that it is not as straightforward as we might like to think. Software needs to be coupled to do anything useful, but developers need tools and techniques to decrease coupling so that solutions are easier to test.

Testing Support in ASP.NET MVC
We are seeing something of a renaissance in testing tools and techniques. Everywhere you look you find test frameworks and tools such as mocking containers and dependency injection frameworks. Not all these tools' purpose is for testing, but in the end they allow us to build applications that are much more testable.
From a general perspective, a testable application is an application that is loosely coupled enough to allow its independent parts to be tested in isolation. Writing an application that is testable requires a lot of design work from the start, but to build testable applications, developers must also use tools and frameworks that are designed around paradigms that are easily testable. If you are not working with tools that allow you to build testable applications, no amount of good design will help. Thankfully, ASP.NET MVC was designed from the ground up to be testable, and several key design choices were made to allow developers to create testable applications.
Some would say that the Model View Controller (MVC) pattern is inherently more testable than the Page Controller pattern (the pattern employed by ASP.NET Web Forms) because it encourages separation of the application flow logic and the display logic. In the MVC pattern, the logic that controls the flow of the application resides inside the controller classes, so a developer can easily instantiate and execute this logic as though it were any other .NET class. This allows developers to easily execute the business logic using a simple unit test in much the same way they would test any other POCO (Plain Old CLR Object) class.
Another choice the development team at Microsoft made was to allow many pieces of the framework to be pluggable. Among the more important pieces are the controller factories, which control the instantiation of controller classes. Allowing developers to replace or extend controller factories makes it possible to execute logic that can resolve and inject the dependencies of the controllers. Allowing for the dependencies of a controller to be injected at run time is key to creating more loosely coupled and testable applications.
In traditional ASP.NET, one of the obstacles that developers come across during testing is the plethora of static classes used during each request. The ASP.NET MVC team made the decision to wrap many of the .NET static helper classes (such as HttpContext and HttpRequest) so that they can be replaced during testing with a stub. ASP.NET MVC provides many abstractions to help developers avoid using these classes, but in places where you are required to use them, the wrappers make this code easier to test.

Tooling
Even though ASP.NET MVC provides many of the tools developers need to create testable applications, you cannot rely on it to guide you in the right direction. Instead, you must design your applications deliberately to support testing, and a few additional tools help with this:
  • Unit Testing Framework. xUnit.NET by Brad Wilson and Jim Newkirk. xUnit provides a way to run automated unit tests. Many people use MSTest, but many other unit testing frameworks are out there, and I encourage you to take a look at some of them. I chose xUnit.NET because it is simple, easily extended, and has a very clean syntax. I'm using the xUnit test runner for Resharper, but the xUnit GUI test runner is in the Tools folder of the sample application.
  • Dependency Injection Framework. Ninject 2 by Nate Kohari. Ninject provides a way to wire up classes in your application. I'll describe this approach in more depth later in the article.
  • Mocking Framework. Moq by Clarius Consulting. Moq provides a framework for mocking interfaces and classes during testing.

Application Scenario
To show how to design a testable application, I'll use a simple application scenario in which lists of categories and products are displayed on a Web page. The application also includes simple screens to view, edit, and create categories and products. The simple schema, shown in Figure 1, consists of a one-to-many mapping between categories and products.
Figure 1 Schema for the Sample Application

High-Level Application Design
When you create an application, the initial design can go a long way toward helping or hindering the application's long-term health—its maintainability and testability. The approach taken in many architectures is to find the optimal amount of abstraction without creating too much overhead. The MVC pattern already provides some architectural guidance by defining three layers for an application. Some developers might think that these three levels provide enough abstraction to produce large applications. Unfortunately, that often isn't the case, and as you will see, the model can easily be more than a single layer.
You must remember that in many small applications, including the sample for this article, three levels of abstraction is probably sufficient. In these instances, having some views, controllers, and a set of classes to interact with is likely enough. However, several additional layers of abstraction are needed to create a highly testable application. Many architectural patterns at our disposal can help in forming the overall design, including the MVC pattern.
ASP.NET MVC Code-Behind Pages
If you were following ASP.NET MVC before the final release, you may have noticed that the code-behind pages have been removed from the framework. These pages served no functionality in the ASP.NET MVC framework and promoted putting logic into views, where it does not belong. Any logic contained in views is difficult to test in much the same way that code-behind files in ASP.NET Web Forms are difficult to test.
Most of you reading this article are probably familiar with the pattern, but you might not have thought about its implications for application testability. The first part of the MVC pattern is the view, which contains logic for rendering data to a client. Originally, this was a user interface, but a client can be a Web browser, a Web service, client-side JavaScript, and so on. The view should be used only to render data for a consumer, and the amount of logic needed should be abstracted into helper classes as much as possible.
The model represents the back end of an application. This part of the application, which is very loosely defined in the ASP.NET MVC implementation of the pattern, can take on many different forms, and it will very likely depend on the scope of your application. In a small application with little complex business logic, for example, this layer might simply be a set of business objects using the Active Record pattern that you interact with directly in the controller layer.
The controller orchestrates the flow of the application by taking data from the model and passing it to the appropriate view. Since this class is separate from the display logic, by employing a few techniques you should be able to instantiate this class in a unit test and have no dependencies on the ASP.NET runtime. This enables complete testing of the controller without having to run inside a Web server.

Abstracting the Model
When looking at these layers, you might see a few places where additional abstraction would make it easier to test an application. This is common with more complex applications, one area being between the controller and the model. If you have the layering I described earlier, your controller actions might look something like the following:
[AcceptVerbs(HttpVerbs.Post)]
public ActionResult Edit(int id, FormCollection formCollection)
{
    Category category = Category.FindById(id);
    category.Name = formCollection["name"];
    category.Save();
    return RedirectToAction("List");
}
The challenges here are at least twofold. First, you cannot easily test this code without having a database connection. Because we are using the Active Record pattern, our data access code is coupled to the domain entity, so we cannot easily swap it out. Also, if you have business logic that is not entirely contained in the domain entity, you could start leaking business or application logic into the controller class. This might lead to duplication of code or even worse—bugs stemming from inconsistencies in implementation. This can hinder testability because you now need to make sure you are testing the same behavior in multiple places within the application.

The Repository Pattern
The next step in improving the testability of this design is to leverage the Repository pattern, which is detailed by Martin Fowler in his book Patterns of Enterprise Application Architecture. The Repository pattern is often misinterpreted as a layer that sits between the application and a database, but in fact it is a layer that sits between your application and any sort of persistent storage. This pattern confines all your data access to a few key places, allowing you to remove it to facilitate testing application logic in isolation.
Implementations of the Repository pattern provide a view of your persistent storage that appears to be an in-memory repository. The interface to such a repository could be similar to this:
public interface ICategoryRepository
{
    IEnumerable<Category> FindAll();
    void Insert(Category category);
    Category FindById(int id);
    void Update(Category category);
}
Testing in Isolation
Some people might think that testing in isolation is not important and choose to only write integration tests. A testing framework such as MSTest or NUnit can still execute integration tests, but they test multiple layers of the application, including making calls across the network, accessing the disk, persisting data to a database, and so on. These sorts of tests are very important and should be present in all applications, but as an application grows, these tests become very slow and can be brittle on different developer machines. Separating unit tests and integration tests allows you to run the unit tests quickly and reliably on developer machines while running your integration tests regularly on your build server.
When you begin to separate classes from one another and test in isolation, you'll find that testing becomes much less brittle and much easier. When you mock a dependency, you control exactly what it returns, and you can more easily test the edge cases of the calling class. Also, because you aren't relying on multiple levels of dependencies, you don't need to account for as much when you are preparing for your test scenarios. Just keep in mind that testing classes in isolation is not a replacement for writing integration tests to make sure that all components work well together.
The important thing to note here is that you are moving the data persistence out of the domain entity and into a separate class, which you can replace more easily during testing. Applying the pattern to the Edit Action shown earlier would look like Figure 2.

Injecting the Repository
The code in Figure 2 looks clean, but how would you replace the repository class during testing? That's easy. Instead of instantiating the class inside the method, you pass it in the class. In this case, you can pass it in as a constructor parameter. The problem, however, is that you don't control the instantiation of the controller classes. To solve this problem, you can use the dependency injection framework that I referenced earlier. Numerous frameworks are available on the market. I chose to use Ninject 2. (If you aren't familiar with dependency injection, see the article in the September 2005 issue of MSDN Magazine by Griffin Caprio, "Dependency Injection." As I said, the first step in using dependency injection is to pass the CategoryRepository into the controller via the controller's constructor:
public CategoryController(ICategoryRepository categoryRepository)
{
    this.categoryRespository = categoryRepository;
}
Figure 2 Leveraging the Repository
[AcceptVerbs(HttpVerbs.Post)]
public ActionResult Edit(int id, FormCollection formCollection)
{
    var categoryRepository = new CategoryRepository();
    Category category = categoryRepository.FindById(id);
    category.Name = formCollection["name"];
    categoryRepository.Update(category);

    return RedirectToAction("List");
}
Next, you need to tell Ninject that whenever it sees an ICategoryService interface, it needs to inject an instance of the CategoryService. Every dependency injection framework has a different method of configuration, and Ninject uses a code-based configuration instead of the more usual XML. Because this binding is very straightforward, the code to implement it is just one line:
Bind<ICategoryRepository>().To<CategoryRepository>().InTransientScope();
This statement tells the dependency injection framework to bind ICategoryRepository to CategoryRepository in a transient scope, which means that each time an ICategoryRepository is requested, you get a new instance of CategoryRepository. This is in contrast to something like a singleton scope, where you continue to get back the same instance of the repository.
With the controller refactored so that the repository is passed in through the constructor, you can now test the behavior of the controller independently of the database. One way to accomplish this is by writing a dummy class (commonly referred to as a stub), which implements the ICategoryRepository interface. You can then implement the methods you need to return dummy data and perform dummy operations, although this seems like a lot of work. In addition, what happens when you need to return more than one set of dummy data for a single method in different tests? You would end up with multiple implementations of the stub, or flags in the stub, and that might be a significant amount of extra effort.
Here is where a good mocking framework can come in. A mocking framework allows you to create mock objects. Mock objects allow developers to emulate, through interfaces or virtual methods, the behavior of another class during testing and then verify that expected events occurred. The behavior of mock objects (also simply called mocks) is what allows you to replace dependencies in your classes and then test those classes without having the real dependencies in place.
This might be a bit confusing, but you need the mocking framework to let you do some stubbing. Yes, that's right. Because a mock is an object that allows you to assert that a certain action has been performed on it, and a stub provides dummy data or actions, it should be clear that in most real-world scenarios you want a mixture of the two. Given this fact, most mocking frameworks have functionality that allows you to stub out methods or properties without asserting any behavior. (If you are still a bit confused about mocks versus stubs, Martin Fowler has a good article on the topic, "Mocks Aren't Stubs."
The code in Figure 3 shows a test that mocks the ICategoryRepository interface, stubs out the FindAll method so that it returns a dummy list of categories, and then passes the mocked instance to the controller class. Then the List method on the controller class is called, and the result can be asserted. In this case, the test is asserting that the model is an IEnumerable of Category and that there is one category in the list.
Figure 3 List Action Test with Mocks
[Fact]
public void ListActionReturnsListOfCategories()
{
    // Arrange

    // create the mock
    var mockRepository = new Mock<ICategoryRepository>();

    // create a list of categories to return
    var categories = new[] { new Category {Id = 1, Name = "test"} };

    // tell the mock that when FindAll is called,
    // return the list of categories
    mockRepository.Setup(cr => cr.FindAll()).Returns(categories);

    // pass the mocked instance, not the mock itself, to the category
    // controller using the Object property
    var controller = new CategoryController(mockRepository.Object);

    // Act
    var result = (ViewResult) controller.List();

    // Assert
    var listCategories = Assert.IsAssignableFrom<IEnumerable<Category>>(result.ViewData.Model);
    Assert.Equal(1, listCategories.Count());
}
At this point, the application is looking good. We have a repository that can be replaced during testing and a method for mocking this repository so that we can test the controller behavior in isolation. For some applications, this might be all that's required with respect to the controllers, but many medium to large applications still have another layer of abstraction in place.

Fine-Grained Services
In a more complex application, you might take a more fine-grained service approach and have a set of task or event classes that represent the actions that can be performed in the system. This can have a twofold effect. First, it can reduce the size and complexity of your service classes. These classes can grow quite large if they are not contained. Second, it gives you more control over dependencies because now you only need to worry about the dependencies of individual actions rather than the dependencies of your entire service.
Implementing the Service Layer
A service layer sits on top of an application's domain model and provides a set of operations that can be performed against it. This gives you a place to centralize logic that belongs in your application but might not necessarily belong inside the domain model—logic that would have otherwise likely leaked into the controller's methods. For example, what if you needed to do a security check around the code in Figure 2? You don't want to perform the operation in the action method (although you might under certain circumstances) because reusing this action in another place would require you to bring the security along with it. Or, what if you wanted to put a transaction around an operation? You certainly don't want this logic inside the controller class.
Instead, you can provide a layer of classes that define an application's services and use those classes to perform different actions. In a simple application, such as the sample in this article, the service layer might very closely mimic the methods on the repository, as you can see in the following code, but if the application had more business logic, these methods would likely represent business actions rather than basic CRUD methods:
public interface ICategoryService
{
    IEnumerable<Category> FindAll();
    Category FindById(int id);
    void Save(Category category);
}
For the first two methods in the service, calls are delegated to the repository, and then the results are returned, but you might notice that the services have a Save method instead the Update and Delete methods on the repository. Since the application is able to determine whether an object has been saved, the decision to call Update or Insert on the repository can be left up to the service.
Inserting the service layer into the mix greatly reduces the coupling between the controller classes and the repository classes while keeping your controllers lighter because you can push a lot of logic into the services. The design of the controller classes must be changed to reflect the use of services instead of repositories, so instead of injecting repositories into these classes, you inject the services. In turn, you inject the repositories into the services. This might sound complicated, but with dependency injection, you won't even notice—it all gets wired up for you.
The entire dependency injection configuration (including the Product repository and service) looks like Figure 4.
Figure 4 Dependency Injection Configuration
public class DefaultModule: NinjectModule
{
    public override void Load()
    {
        Bind<ICategoryService>().To<CategoryService>().InTransientScope();
        Bind<ICategoryRepository>().To<CategoryRepository>().InTransientScope();

        Bind<IProductService>().To<ProductService>().InTransientScope();
        Bind<IProductRepository>().To<ProductRepository>().InTransientScope();
    }
}
Now that we are passing repositories and services through constructors, you need to construct the controllers using the dependency injection framework. The dependency injection framework handles the construction and injection of the dependencies, but you need to ask for the controller class from the framework. This is much easier than you might anticipate because the ASP.NET MVC team made the controller factories pluggable. You simply need to implement a controller factory as in Figure 5, and you can then easily replace the default instantiation of the controller classes.
Figure 5 Ninject Controller Factory
public class NinjectControllerFactory : DefaultControllerFactory
{
    private readonly IKernel kernel;

    public NinjectControllerFactory(IKernel kernel)
    {
        this.kernel = kernel;
    }

    protected override IController GetControllerInstance(Type controllerType)
    {
        return (IController)kernel.Get(controllerType);
    }
}
Since the controller factory inherits from the default implementation, you just need to override the GetControllerInstance method and then request the type from the Ninject kernel, which is the class that controls object instantiation in Ninject. When the kernel receives a controller type, Ninject self-binds (tries to construct) the type because it is a concrete type. If the kernel receives a CategoryController type, the constructor will have a parameter of type ICategoryService. Ninject looks to see if it has a binding for this type, and when it finds the type, it performs the same action, looking for a constructor. The Ninject kernel instantiates a CategoryRepository and passes it to the constructor for ControllerService. Then it passes the ControllerService object to the constructor for the CategoryController. All this happens inside the dependency injection container simply by asking for the type.
The controller factory must be registered for it to work. Registration requires the addition of only a single line to the global.asax file:
public void Application_Start()
{
    // get the Ninject kernel for resolving dependencies
    kernel = CreateKernel();

    // set controller factory for instantiating controller and injecting dependencies
    ControllerBuilder.Current.SetControllerFactory(new NinjectController Factory(kernel));
}
Now, when the user requests a URL and ASP.NET MVC tries to create a controller, it actually ends up being constructed by the dependency injection container. When the controller is tested, you can mock the service to test the controller in isolation, as shown in Figure 6.
Figure 6 Testing List Action with Mocked Service
[Fact]
public void ListActionReturnsListOfCategories()
{
    // Arrange
    var mockService = new Mock<ICategoryService>();
    var categories = new[] { new Category { Id = 1, Name = "test" } };
    mockService.Setup(cr => cr.FindAll()).Returns(categories);
    var controller = new CategoryController(mockService.Object);

    // Act
    var result = (ViewResult) controller.List();

    // Assert
    var listCategories = Assert.IsAssignableFrom<IEnumerable<Category>>(result.ViewData.Model);
    Assert.Equal(1, listCategories.Count());
}

Isolating View Logic
You might think at this point that you have enough layers to allow for complete testability. However, we have not yet explored the complexity of views. Imagine a scenario in which you have a product class with a price attribute. (The sample application shows this.) Now let's say that you want to display this price to the user formatted as currency. Some developers might say you should put this requirement in your view, as shown here:
<%= Html.Encode(String.Format("{0:c}", this.Model.Price)) %>
I personally don't like this approach because I can't easily conduct unit tests on this logic when the field is being formatted in the view. (I don't mind using a UI testing framework, but I want to get as much of my testing as possible done in my unit tests.) One solution is to add a property on the product class to format the price for display, but I don't like doing that because it means that the concerns of my view are starting to leak into the domain layer. Something as simple as a price format might not seem like a big deal, but problems always seem to increase as your application grows in size, and small items start to cause issues. For example, what happens if you need to display a price differently on two pages? Will you start adding overloads for each different version to your domain object?
One good approach is to use the presentation model pattern. Presentation models can be mapped to and from domain objects and can hold view-specific logic and values that can easily be tested. In the sample application, a presentation model has been created for each form. Since most of the forms are quite similar, they inherit from shared base classes. In a more complex application, however, they would likely contain very different code and logic depending on the form.
If a presentation model were employed, the previous statement would instead look like this:
<%= Html.Encode(this.Model.DisplayPrice) %>
You could easily test this property in a unit test like that shown in Figure 7. Note that the DisplayPrice was placed on the abstract base class, so a stub was created that inherits from this base class to facilitate testing. Remember, a stub is just an object that returns fake data used for testing. Since you cannot instantiate an abstract class, you use the stub to test the base functionality.
Figure 7 Unit Test for a Method
[Fact]
public void PriceIsFormattedAsCurrency()
{
    // Arrange
    var product = new Product {Price = 9.22m};
    var presentationProduct = new
        PresentationProductStub(product);

    // Act
    string cost = presentationProduct.DisplayPrice;

    // Assert
    Assert.Equal("$9.22", cost);
}
The PresentationProductStub class descends from the PresentationProductBase class, which maps to and from the Product class. This causes the List action for the ProductController class to look like the following:
public ActionResult List()
{
    var products = productService.FindAll();
    return View(new ProductList().MapList(products));
}
The products are being pulled normally from the service, but before they are sent to the view, they are passed to a method on the ProductList class that converts the list of Product classes into a list of ProductList classes. Using a model for your views has several distinct advantages. First, as you already saw, you can add view-specific behavior to your class that can easily be unit tested. This is useful for formatting or transforming data for display. Second, you can use the default model binders built into ASP.NET MVC and place your presentation model on the parameter list of a POST method, as shown here:
[AcceptVerbs(HttpVerbs.Post)]
public ActionResult Create(ProductCreate productCreate)
{
    productService.Save(productCreate.GetProduct());
    return RedirectToAction("List");
}
If you are not aware of how the ASP.NET MVC default model binder works, it simply maps fields in the HTML by name onto properties of the class that are in the parameter list. If I put the Product class in the parameter list in the preceding code, a user could maliciously POST a piece of data named "Id" and overwrite the key on the model. This is obviously not a good thing. A user could similarly match up the names of any field on my class and overwrite the values. Using models on the views allows you to use the default model binders (if you choose) while still being able to control which properties are mapped to your domain object.
The alternative is to define mapping classes that you can use to map entities coming in through action method parameters to entities that you want to save to the database. This allows you to control which properties to copy before saving to the database. Another option is to create a reflection-based mapping tool that you could use to map the fields that you want, similar to the AutoMapper tool created by Jimmy Bogard.

Testing Routes
Now, with many of the high-level architectural tips for testing out of the way, let's focus on more fine-grained testing approaches. The first step in implementing an ASP.NET MVC application is to write tests to verify the behavior of the routes within the application. It is important to ensure that the base route "~/" will forward to the appropriate controller and action, and that other controllers and actions forward correctly as well. It is extremely important to have these tests in place from the beginning so that later, as more routes are added to your application, you are guaranteed that routes that were already defined are not broken.
Start by defining the test for the default route (see Figure 8). In this application, the default controller is defined to be the "category" controller, and the default action in this controller is set to "list". Our test should check the base route and assert that the correct values are contained in the route data.
Figure 8 Testing Route Data
[Fact]
public void DefaultUrlRoutesToCategoryControllerAndListAction()
{
    // Arrange
    var context = ContextHelper.GetMockHttpContext("~/");
    var routes = new RouteCollection();
    MvcApplication.RegisterRoutes(routes);

    // Act
    RouteData routeData = routes.GetRouteData(context.Object);

    // Assert
    RouteTestingHelper.AssertRouteData(routeData, "Category", "List", "");
}
This test is using a helper function to assert the values of the default route, shown here:
public static void AssertRouteData(RouteData routeData,
    string controller, string action, string id)
{
    Assert.NotNull(routeData);
    Assert.Equal(controller, routeData.Values["controller"]);
    Assert.Equal(action, routeData.Values["action"]);
    Assert.Equal(id, routeData.Values["id"]);
}
Using this same general test pattern, you can pass any route that follows the Controller/Action/Id pattern (such as "~/Product/Edit/12") to the HttpContext and assert the values (see Figure 9).
Figure 9 Testing Route Data with Helper
[Fact]
public void ProductEditUrlRoutesToProductControllerAndListAction()
{
    // Arrange
    var context = ContextHelper.GetMockHttpContext("~/Product/Edit/12");
    var routes = new RouteCollection();
    MvcApplication.RegisterRoutes(routes);

    // Act
    RouteData routeData = routes.GetRouteData(context.Object);

    // Assert
    RouteTestingHelper.AssertRouteData(routeData, "Product", "Edit", "12");
}
With this method, the tests for routes are a little verbose (for clarity of learning), and they could certainly be shortened. Ben Scheirman has done some interesting work in this area, and he has a good post on his blog about making very terse route assertions ("Fluent Route Testing in ASP.NET MVC").

Passing Dependencies of Actions as Parameters
The second tip is to pass all dependencies to controller actions as parameters to the action method. I illustrate this with the file download example in the sample application. As I mentioned earlier, an HttpRequest in the ASP.NET runtime is a static class that is incredibly hard to replace or mock during unit testing. In ASP.NET MVC, wrapper classes are provided to allow these classes to be mocked, but the process of mocking them or stubbing them out can still be complex.
To mock an HttpRequestBase object, you need to mock the HttpContextBase object that it sits on and then fill in several properties for each. For the file-saving problem, you need to mock the HttpServerUtilityBase that sits on HttpContextBase. Instead of trying to create multiple mock objects to mimic all the different pieces of the HttpContextBase, it would be nice to just make the HttpServerUtilityBase a parameter of the action method and then pass in that single mocked class during testing:
[AcceptVerbs(HttpVerbs.Post)]
public ActionResult Edit(int id, ViewProduct viewProduct,
    HttpServerUtilityBase server, HttpPostedFileBase imageFile)
{
Notice that the third parameter in the preceding code is the type that we need to use, and the type that we need to mock. With the method signature like this, we only need to mock the HttpServerUtilityBase class. If we had accessed this class through this.HttpContext.Server, it would have been necessary to mock the HttpContextBase class as well. The problem is that just adding the HttpServerUtilityBase class to the method parameters won't make it work; you have to provide a way to tell ASP.NET MVC how to instantiate this class. This is where the framework's model binders come in. Note that HttpPostedFileBase already has a custom model binder assigned to it by default.
Model binders are classes that implement the IModelBinder interface and provide a way for ASP.NET MVC to instantiate types on action methods. In this case, we need a model binder for the HttpServerUtilityBase. We can create a class that looks like the following:
public class HttpServerModelBinder: IModelBinder
{
    public object BindModel(ControllerContext controllerContext,
        ModelBindingContext bindingContext)
    {
        return controllerContext.HttpContext.Server;
    }
}
The model binder has access to both the controller's context and a binding context. This model binder simply accesses the controller's context and returns the HttpServerUtilityBase class on the HttpContext class. All that is left is to tell the ASP.NET MVC runtime to use this model binder when it finds a parameter of type HttpServerUtilityBase. Note that this code is placed in the Global.asax file as so:
public void Application_Start()
{
    // assign model binder for passing in the
    // HttpServerUtilityBase to controller actions
    ModelBinders.Binders.Add(typeof(HttpServerUtilityBase), new HttpServerModelBinder());
}
Now, when an HttpServerUtilityBase is passed as a parameter to an action method, the ASP.NET MVC runtime invokes the BindModel method on the HttpServerModelBinder to get an instance of that class. It is very simple to create model binders, and they make testing controller actions much easier.

Testing with Action Results
One of the early complaints about ASP.NET MVC concerned the difficulty of testing operations such as which view was being rendered from an action method. You had to mock the controller context, a view engine, and so on. It was really painful. In preview 3, the ASP.NET MVC team added the concept of action results, which are classes that descend from the ActionResult class and represent a task that the action is going to perform. Now, in ASP.NET MVC, every action method returns the type ActionResult, and a developer can choose from a number of built-in action-result types or create his or her own. This helps with testing because you can invoke an action method and inspect the result to see what occurred. Let's take the example of a ViewResult that we can create by invoking the View method on the base Controller class, as shown here:
public ActionResult List()
{
    IEnumerable<Category> categories = categoryService.FindAll();
    return View(ViewCategory.MapList(categories));
}
In this action method, a list of categories is passed as the model to the view, but no view name is provided. This means that this action will render the default view named List. If you want to make sure that this action always returns an empty view name, you can write a test like Figure 10.
Figure 10 Testing Action Results
[Fact]
public void ListActionReturnsViewResultWithDefaultName()
{
    // Arrange
    var mockService = new Mock<ICategoryService>();
    var controller = new CategoryController(mockService.Object);

    // Act
    var result = controller.List();

    // Assert
    var viewResult = Assert.IsType<ViewResult>(result);
    Assert.Empty(viewResult.ViewName);
}
This test mocks the CategoryService to create the controller class. Then the test invokes the List action to get the ActionResult object. The test finally asserts that the result is of type ViewResult and the name of the view is empty. It would be very easy to test the view name against some known string value, or in cases where the return type is something a bit more complex (JSON format, for example), to check the Data property on the result to ensure that it contains the expected information as returned by a call to the action method.

Recommended Reading
  • Agile Principles, Patterns, and Practices in C# by Robert C. Martin and Micah Martin (Prentice Hall, 2006)
  • Patterns of Enterprise Application Architecture by Martin Fowler (Addison-Wesley Professional, 2002)
  • Microsoft .NET: Architecting Applications for the Enterprise by Dino Esposito and Andrea Saltarello (Microsoft Press, 2008)
Wrapping Up
The ASP.NET MVC team has invested a great deal of effort into creating a flexible architecture that allows for easy testing. Developers can now more easily test their systems because of features like pluggable controller factories, action result types, and wrappers around the ASP.NET context types. All this provides ASP.NET MVC developers with a good starting point, but the onus is still on developers to design and construct applications that are loosely coupled and testable. I hope this article helps as you progress down this path. If you are interested, I've listed these in the Recommended Reading sidebar.

Justin Etheredge is a Microsoft C# MVP, author at CodeThinked.com, and founder of the Richmond Software Craftsmanship Group. He is a senior consultant at Dominion Digital in Richmond, Virginia, where he provides guidance in designing and building systems of all shapes and sizes.


Editor's Note
Viva la Evolution!
Howard Dierking

In this issue of MSDN Magazine, we will take a more focused look at the state of Web development. This is actually a pretty relevant topic for me at the moment, as I've been in and out of meetings over the past month in which we've been trying to define and come to consensus around what MSDN (not just the magazine) should be and how it should evolve. As such, I want to give you my perspective as a content publisher on how the problem domain of the Web has evolved and how Web applications are going to need to evolve to solve them.
It's interesting to see how far the pendulum has swung in terms of the fundamental problems related to content and the Web. Not too long ago, the major challenge was making content available. Evolution happened quickly, however—and handwritten HTML was replaced by WYSIWYG editors, and then the whole editing environment was supplanted entirely by blogs and wikis. The problem of publishing effectively disappeared. Anyone with an idea and an Internet connection could publish content for all to consume.
Before the novelty of this newly democratized world of content could sink in, the core problem shifted from making content available to finding the right content. Enter the rise of search engines. Now, I've got no problem with search—I use it as a regular part of doing business. For example, have you ever submitted an article idea and received a response similar to, "There's already a sufficient amount of coverage on this topic?" You can blame your search engine for that. For all of its effectiveness in finding content, however, I think that search has effectively enabled folks in the content business to gloss over some more fundamental problems in our approach to publishing and managing content on the Web—particularly with respect to information architecture. As I look over all of the content that can be found today on MSDN, I am overwhelmed at both the sheer volume of content and the lack of cohesion among the various content elements. I'm also bothered by the fact that I can search for MSDN Magazine articles on WCF and be presented with an article that was based on an early CTP of Indigo. I'm not suggesting that such an article should be outright pulled down—there may be value in the conceptual explanations. However, there should absolutely be more attention given to lifetime management policy.
So why am I bringing up issues of content management? For one, it's a domain that I'm pretty familiar with. More important, however, I think it highlights where the problems are now shifting on the Web. For example, we've solved the problem of publishing and we have decent a solution for finding content. The next major evolution is in composing experiences that bring together lots of disparate elements into a single context. This means thinking about how to break apart various application and content silos such that a combination of content and application services can be put together into any context, as decided by the user—in short, this means thinking of everything as a mashup. For me, it means that if my intent—my context—is to read an article about WCF, I shouldn't have to stop what I'm doing so that I can navigate to a different Web application if I have a question to post, only to later rely on the back button to return to the article. I should be able to construct a single context consisting of a content item and a forums application service.
Getting to this next step is going to require some work, in both refactoring to break application silos into services and learning to think of Web applications as compositions. I'm therefore excited to see articles like Shawn Wildermuth's article on composite Silverlight applications (Page 35) and Aaron Skonnard's article on REST and the ASP.NET MVC framework (Page 48). Finally, for more on refactoring Web applications, check James Kovacs' series on brownfield development, aptly titled "Extreme ASP.NET Makeover."

Visit us at msdn.microsoft.com/magazine. Questions, comments, or suggestions for MSDN Magazine? Send them to the editor: mmeditor@microsoft.com.

Thanks to the following Microsoft technical experts for their help with this issue: Adrian Bateman, Sam Bent, Laurent Bugnion, Matt Ellis, Mike Fourie, Steve Fox, Don Funk, Alex Gorev, Aaron Hallberg, Luke Hoban, Robert Horvick, John Hrvatin, Bret Humphrey, Katy King, Brian Kretzler, Bertrand LeRoy, Dan Moseley, Stephen Powell, and Delian Tchoparinov.


Toolbox
Static Analysis Database Tools, Managing Remote Computers, And More
Scott Mitchell

All prices confirmed at press time and are subject to change. The opinions expressed in this column are solely those of the author and do not necessarily reflect the opinions at Microsoft.

Contents
Static Analysis for Your Database Design
.NET Podcasts
Manage Remote Computers from One Program
The Bookshelf

Static Analysis for Your Database Design
Software design standards are an important aspect of building reliable and maintainable applications. Most companies have some sort of coding standards, such as naming conventions and security guidelines. Static code analysis tools, such as FxCop and StyleCop, are useful for evaluating an application's intermediate code or source code to ensure that it conforms to the standards recommended by Microsoft or defined by your company. (FxCop and StyleCop were reviewed in the December 2008 issue, "Static Analysis Tools For .NET, Matt Berseth’s Blog.")
But what about database design and configuration? Many companies have naming conventions for tables and their columns, as well as guidelines for column data types, such as under what circumstances NULLable columns are permissible. The same applies for the use and cascade behavior of foreign key constraints and triggers. There may also be configuration standards that apply to login credentials, backup schedules, and other concerns.
ApexSQL Enforce (version 2008.04) is a static analysis tool for Microsoft SQL Server databases. When you first run ApexSQL Enforce, you are prompted to select the rule base to use. Each rule is associated with a database object type, such as the server, a table, a trigger, a column, or a primary key. The rules are classified further into categories such as Server Configuration, Database Modeling, Performance, and so on. Each rule is assigned one out of six possible severities, ranging from Info to Critical. A Best Practices rule base ships with ApexSQL Enforce and contains more than 80 rules, including ones that apply to database maintenance and administration. The Critical severity rule, for example, requires that the database be backed up at least every seven days. There are also data modeling rules, such as a High severity rule that ensures all tables have a primary key and a Tip rule that recommends against naming tables with a "tbl" prefix.
After selecting the rule base and the particular rules to apply, you choose the database to analyze. ApexSQL Enforce runs the selected rules against the specified database and displays any rule violations in a separate tab. Each rule violation includes a summary, noting the rule that was violated and the database object in violation; a description of the violated rule; and advice on how to remedy the violation. For some rules, ApexSQL Enforce can provide the T-SQL syntax to fix the violation.
ApexSQL Enforce offers a high degree of customization and flexibility. For instance, you can create your own rule bases or modify the built-in Best Practices rule base. Rules are defined using C# or Visual Basic code. Creating and modifying these rules is straightforward thanks to a built-in rule editor that offers syntax highlighting and IntelliSense support. ApexSQL Enforce can be run from its graphical user interface or from the command line, and violation reports can be exported to XML or rendered into an HTML report.
Static analysis is a useful and automated technique for ensuring that your software design adheres to prescribed standards. ApexSQL Enforce is a powerful and customizable tool for applying static analysis to your databases.
Price: $999
www.apexsql.com/sql_tools_enforce.asp
ApexSQL Enforce

.NET Podcasts
Podcasts are audio or video productions that are available for download over the Internet and are typically played on portable MP3 players, such as the Apple iPod or the Microsoft Zune. Unlike streaming audio shows, podcasts are prerecorded and syndicated. You can configure your MP3 player's software to automatically download the latest shows of your favorite podcasts—they are great listening material for your daily commute.
There are a number of very interesting, educational, and well-produced podcasts specifically for Microsoft .NET developers. One of my favorite .NET-focused shows is Hanselminutes, a weekly audio podcast hosted by Scott Hansel man, a senior program manager at Microsoft. Most episodes are around 30 minutes in length, focus on a single topic, and include a guest who is a pioneer or an expert on the topic of discussion. What I like best about the show is the wide range of subject matter, with episodes on specific technologies—such as JavaScript, ADO.NET Data Services, and parallel programming in .NET—as well as shows that discuss software development models like Scrum, test-driven development, and the SOLID principles of object-oriented design.
What sets Hanselminutes apart from many other podcasts is its consistent schedule and level of quality. A new Hanselminutes episode has appeared nearly every single week since January 2006, with over 155 episodes so far. All past episodes (as well as each week's new episode) are available for download in several popular multimedia formats. And Scott does a great job interviewing his guests and keeping the dialogue interesting and on-topic.
Price: Free
hanselminutes.com

Manage Remote Computers from One Program
Tools like Virtual Network Computing (VNC) and the Microsoft Remote Desktop Protocol (RDP) make it easy to log into and manage remote computers from your home or office and have long been used by system administrators to manage remote computer assets. If you are tasked with managing many different computers, or routinely find yourself with multiple remote connections open at the same time, check out Terminals (version 1.7e), an open-source project that consolidates managing and running remote connections. When a remote connection is launched from Terminals, it is displayed in a new tab within the Terminals user interface. This tabbed UI streamlines multiple, simultaneous remote connections into a single window. And Terminals works with a variety of protocols, including VNC, RDP, Virtual Machine Remote Control (VMRC), Remote Access Service (RAS), Telecommunication network (Telnet), and Secure Shell (SSH).
When Terminals is launched for the first time, it searches your computer for remote connection files and adds any discovered connections to the Favorites window. You can edit these automatically added entries, or you can manually add your own remote connections to Favorites. And with a few clicks of the mouse, you can customize these remote connections' display and behavior properties, supply connection credentials, or categorize the connections using tags. Double-clicking one of the remote connections in the Favorites window causes Terminals to connect to that computer in a new tab. There's also a History view that shows what connections were made today, yesterday, in the past week, and so on.
Terminals includes a number of helpful tools and utilities. There's a feature that makes taking screen captures of remote connections as easy as clicking a button, and a manager that catalogues and organizes your screen captures. Terminals also offers a suite of network-related utilities. For example, you'll find tools for performing a Whois or DNS lookup from within Terminals, along with tools for examining the shares on a local or remote computer. Other tools show information about the local computer's Network Interface Controllers (NICs), the open connections, and the packet traffic. There's also one-click access to common system administration and network maintenance configuration. The Terminals toolbar contains shortcut icons to programs like the Registry Editor (regedit.exe), the Computer Management Console, the Control Panel, and the local computer's Internet Properties, Network Connections, and Services Manager, among many others.
Terminals is a nifty application that consolidates working with remote connections into a single, simple interface. If you regularly connect to remote computers, give Terminals a try.
Price: Free, open-source
terminals.codeplex.com
Terminals

The Bookshelf
Most .NET developers are familiar with ADO.NET, the data access library that has been part of the .NET Framework since its inception. One challenge of using ADO.NET is that the developer must always keep the details of the underlying data store in mind. When querying data, the developer must be cognizant of the tables to query, their relationships, what JOINs are needed and whether they are INNER or OUTER JOINs. When retrieving data from a DataSet or a DataReader, the developer must recall the column names and their data types.
Over the past several years, Microsoft has been developing the ADO.NET Entity Framework, a new library for accessing data. When using the Entity Framework, you do not run queries against the database. Instead, you query the Entity Data Model, which is a set of classes in your application that model the database's structure in an object-oriented manner. In addition to the Entity Data Model, the Entity Framework maintains a logical model of the database and a map that indicates how the objects in the logical model correspond to the objects in the Entity Data Model. While the Entity Framework is not a replacement for ADO.NET, it is an important tool that Microsoft is investing in and is being used in technologies like ADO.NET Data Services and ASP.NET Dynamic Data.
One of the best ways to learn about the Entity Framework is to read Julia Lerman's book, Programming Entity Framework (O'Reilly, 2009). Julia's book starts with a solid overview of the design goals of the Entity Framework, its pros and cons, and where it fits into Microsoft's data access story. The reader is shown how to create an Entity Data Model using the Designer, how to query against this model, how to insert, update, and delete entities, and how to display and manage data via the Entity Framework in WinForms, Windows Presentation Foundation (WPF), and ASP.NET applications, as well as in Web Services and Windows Communication Foundation (WCF) services.
At nearly 800 pages, Programming Entity Framework is fairly hefty, but it offers a solid grounding in using the Entity Framework. The book assumes its readers are intermediate to advanced .NET developers who are already familiar with database concepts, ADO.NET, LINQ, and other core .NET features and spends no time introducing these topics. Instead, the book is packed with walkthroughs that illustrate the use of Entity Framework in various scenarios. It also does a great job pointing out what this first version of the Entity Framework can and cannot do and what use cases are difficult or tricky to implement, along with workarounds where appropriate.
Julia's use of real-world examples really helped me to understand and become familiar with using the Entity Framework. In the second chapter, Julia introduces a simple database with a handful of tables, views, and stored procedures. She uses this database over the next several chapters to highlight the features of the Designer and to demonstrate working with entities using both LINQ to Entities and Entity SQL queries. Later, in Chapter 7, Julia unveils a more complex, real-world database that contains many more tables and more types of relationships. She uses this new database throughout the remainder of the book to illustrate more advanced topics, such as customizing entities and the Entity Data Model, transaction processing, handling exceptions raised by the Entity Framework, and so on. These two databases, along with the complete sample code, are available for download from the book's Web site, LearnEntityFramework.com.
Price: $54.99, 792 pages
oreilly.com
Programming Entity Framework

Send your questions and comments for Scott to toolsmm@microsoft.com.

Scott Mitchell, author of numerous books and founder of 4GuysFromRolla.com, is an MVP who has been working with Microsoft Web technologies since 1998. Scott is an independent consultant, trainer, and writer. Reach him at Mitchell@4guysfromrolla.com or via his blog at ScottOnWriting.NET.


CLR Inside Out
Building Tuple
Matt Ellis

This column is based on a prerelease version of the Microsoft .NET Framework 4. Details are subject to change.
Contents
Existing Tuple Types
Interoperability
Using Tuple from C#
Reference or Value Type?
Tuples of Arbitrary Length
Interfaces Implemented
Structural Equality, Comparison, and Equivalence
IStructualEquatable and IStructuralComparable
Partial Equivalence Relations
Worth the Effort
The upcoming 4.0 release of Microsoft .NET Framework introduces a new type called System.Tuple. System.Tuple is a fixed-size collection of heterogeneously typed data. Like an array, a tuple has a fixed size that can't be changed once it has been created. Unlike an array, each element in a tuple may be a different type, and a tuple is able to guarantee strong typing for each element. Consider trying to use an array to store a string and integer value together, as in the following:
static void Main(string[] args) {
            object[] t = new object[2];
            t[0] = "Hello";
            t[1] = 4;

            PrintStringAndInt((string) t[0], (int) t[1]);
        }

        static void PrintStringAndInt(string s, int i) {
            Console.WriteLine("{0} {1}", s, i);
        }
The above code is both awkward to read and dangerous from a type safety point of view. We have no guarantee that the elements of the tuple are the correct type when we go to use them. What if, instead of an integer, we put a string in the second element in our tuple, as follows:
static void Main(string[] args) {
            object[] t = new object[2];
            t[0] = "Hello";
            t[1] = "World";

            PrintStringAndInt((string) t[0], (int) t[1]);
        }

        static void PrintStringAndInt(string s, int i) {
            Console.WriteLine("{0} {1}", s, i);
        }
This code would compile, but at run time, the call to PrintStringAndInt would fail with an InvalidCastException when we tried to cast the string "World" to an integer. Let's now take a look at what the code might look like with a tuple type:
static void Main(string[] args) {
            Tuple<string, int> t = new Tuple<string, int>("Hello", 4);
            PrintStringAndInt(t.Item1, t.Item2);
        }

        static void PrintStringAndInt(string s, int i) {
            Console.WriteLine("{0} {1}", s, i);
        }
With the tuple type, we've been able to remove the cast operators from our code, giving us better error checking at compile time. When constructing and using elements from the tuple, the compiler will ensure our types are correct.
As this example shows, it's obvious that a tuple is a useful type to have in the Microsoft .NET Framework. At first, it might seem like a very easy enhancement. However, we'll discuss some of the interesting design challenges that the team faced while designing System.Tuple. We'll also explore more about what we added to the Microsoft .NET Framework and why these additions were made.

Existing Tuple Types
There is already one example of a tuple floating around the Microsoft .NET Framework, in the System.Collections.Generic namespace: KeyValuePair. While KeyValuePair<TKey, TValue> can be thought of as the same as Tuple<T1, T2>, since they are both types that hold two things, KeyValuePair feels different from Tuple because it evokes a relationship between the two values it stores (and with good reason, as it supports the Dictionary class). Furthermore, tuples can be arbitrarily sized, whereas KeyValuePair holds only two things: a key and a value.
Within the framework, many teams created, each for its own use, a private version of a tuple but didn't share their versions across teams. The Base Class Libraries (BCL) team looked at all of these uses when designing their version of tuple. After other teams heard that the BCL team would be adding a tuple in Microsoft .NET Framework 4, other teams felt a strong desire to start using tuples in their code, too. The Managed Extensibility Framework (MEF) team even took a look at the draft of one of BCL's specs before implementing a version of tuple in their code. They later released this version as part of a consumer technology preview, with a supporting comment that it was a temporary implementation until tuples were added to the Microsoft .NET Framework!
Interoperability
One of the biggest set of customers inside Microsoft for tuple was the language teams themselves. While C# and VB.NET languages do not have the concept of a tuple as part of the core language, it is a common feature of many functional languages. When targeting such languages to the Micrososft.NET Framework, language developers had to define a managed representation of a tuple, which leads to unnecessary duplication. One language suffering that problem was F#, which previously had defined its own tuple type in FSharp.Core.dll but will now use the tuple added in Microsoft .NET Framework 4.
In addition to enabling the removal of duplicate types, having a common type ensures that it is easy to call functions across language boundaries. Consider what would happen if C# had added a tuple type (as well as new syntax to support it) to the language, but didn't use the same managed representation as F#. If this were the case, any time you wanted to call a method from an F# assembly that took a tuple as an argument, you would be unable to use the normal C# syntax for a tuple or pass an existing C# tuple. Instead, you would be forced to convert your C# tuple to an F# tuple, and then call the method. It's our hope that by providing a common tuple type, we'll make interoperability between managed languages with tuples that much easier.
Using Tuple from C#
While some languages like F# have special syntax for tuples, you can use the new common tuple type from any language. Revisiting the first example, we can see that while useful, tuples can be overly verbose in languages without syntax for a tuple:
class Program {
        static void Main(string[] args) {
            Tuple<string, int> t = new Tuple<string, int>("Hello", 4);
            PrintStringAndInt(t.Item1, t.Item2);
        }

        static void PrintStringAndInt(string s, int i) {
            Console.WriteLine("{0} {1}", s, i);
        }
    }
Using the var keyword from C# 3.0, we can remove the type signature on the tuple variable, which allows for somewhat more readable code.
var t = new Tuple<string, int>("Hello", 4);
We've also added some factory methods to a static Tuple class which makes it easier to build tuples in a language that supports type inference, like C#.
var t = Tuple.Create("Hello", 4);
Don't be fooled by the apparent lack of types here. The type of t is still Tuple<string, int> and the compiler won't allow you to treat the elements as different types.
Now that we've seen how the tuple type works, we can take a look at the design behind the type itself.
Reference or Value Type?
At first glance, there isn't much to the tuple type, and it seems like something that could be designed and implemented over a long weekend. However, looks are often deceiving, and there were some very interesting design decisions that needed to be made during its development.
The first major decision was whether to treat tuples either as a reference or value type. Since they are immutable any time you want to change the values of a tuple, you have to create a new one. If they are reference types, this means there can be lots of garbage generated if you are changing elements in a tuple in a tight loop. F# tuples were reference types, but there was a feeling from the team that they could realize a performance improvement if two, and perhaps three, element tuples were value types instead. Some teams that had created internal tuples had used value instead of reference types, because their scenarios were very sensitive to creating lots of managed objects. They found that using a value type gave them better performance. In our first draft of the tuple specification, we kept the two-, three-, and four-element tuples as value types, with the rest being reference types. However, during a design meeting that included representatives from other languages it was decided that this "split" design would be confusing, due to the slightly different semantics between the two types. Consistency in behavior and design was determined to be of higher priority than potential performance increases. Based on this input, we changed the design so that all tuples are reference types, although we asked the F# team to do some performance investigation to see if it experienced a speedup when using a value type for some sizes of tuples. It had a good way to test this, since its compiler, written in F#, was a good example of a large program that used tuples in a variety of scenarios. In the end, the F# team found that it did not get a performance improvement when some tuples were value types instead of reference types. This made us feel better about our decision to use reference types for tuple.
Tuples of Arbitrary Length
Theoretically, a tuple can contain as many elements as needed, but we were able to create only a finite number of classes to represent tuples. This raised two major questions: how many generic parameters should the largest tuple have, and how should the larger tuples be encoded? Deciding on how many generic parameters to have in the largest tuple ended up being somewhat arbitrary. Since Microsoft .NET Framework 4 introduces new versions of the Action and Func delegates that take up to eight generic parameters, we chose to have System.Tuple work the same way. One nice feature of this design is that there's a correspondence between these two types. We could add an Apply method to each tuple that takes a correspondingly sized Action or Func of the same type and pass each element from the tuple as an argument to the delegate. While we ultimately didn't add this in order to keep the surface area of the type clean, it's something that could be added in a later release or with extension methods. There is certainly a nice symmetry in the number of generic parameters that belong to Tuple, Action, and Func. An aside: After System.Tuple was finished being designed, the owners of Action and Func created more instances of each type; they went up to 16 generic parameters. Ultimately, we decided not to follow suit: the decision on sizing was somewhat arbitrary to begin with, and we didn't feel the time we would spend adding eight more tuple types would be worth it.
Once we answered our first question, we still had to figure out a way to represent tuples with more than eight elements. We decided that the last element of an eight-element tuple would be called "Rest" and we would require it to be a tuple. The elements of this tuple would be the eighth, ninth, and so on, elements of the overall tuple. Therefore, users who wanted an eight-element tuple would create two instances of the tuple classes. The first would be the eight-element tuple, which would contain the first seven items of the tuple, and the second would be a one-element tuple that held the last tuple. In C#, it might look like this:
Tuple.Create(1, 2, 3, 4, 5, 6, 7, Tuple.Create(8));
In languages like F# that already have concrete syntax for tuples, the compiler handles this encoding for you.

For languages that provide syntax for interacting with tuples, the names of the properties used to access each element aren't very interesting, since they are shielded from the developer. This is a very important question for languages like C#, where you have to interact with the type directly. We started with the idea of using Item1, Item2, and so on as the property names for the elements, but we received some interesting feedback from our framework design reviewers. They said that while these property names make sense when someone thinks about them at first glance, it gives the feeling that the type was auto-generated, instead of designed. They suggested that we name the properties First, Second, and so on, which felt more accessible. Ultimately, we rejected this feedback for a few reasons: first, we liked the experience of being able to change the element you access by changing one character of the property name; second, we felt that the English names were difficult to use (typing Fourth or Sixth is more work than Item4 or Item6) and would lead to a very weird IntelliSense experience, since property names would be alphabetized instead of showing up in numerical order.
Interfaces Implemented
System.Tuple implements very few interfaces and no generic interfaces. The F# team was very concerned about tuple being a very lightweight type, because it uses so many different generic instantiations of the type across its product. If Tuple were to implement a large number of generic interfaces, they felt it would have an impact on their working set and NGen image size. In light of this argument, we were unable to find compelling reasons for Tuple to implement interfaces like IEquatable<T> and IComparable<T>, even though it overrides Equals and implements IComparable.
Structural Equality, Comparison, and Equivalence
The most interesting challenge we faced when designing Tuple was to figure out how to support the following:
  • structural equality
  • structural comparison
  • partial equivalence relations
We did as much design work around these concepts as we did for Tuple itself. Structural equality and comparison relate to what Equals means for a type like Tuple that simply holds other data.
In F#, equality over tuples and arrays is structural. This means that two arrays or tuples are equal if all their elements are the same. This differs from C#. By default, the contents of arrays and tuples don't matter for equality. It is the location in memory that is important.
Since this idea of structural equality and comparison is already part of the F# specification, the F# team had already come up with a partial solution to the problem. However, it applied only to the types that the team created. Since it also needed structural equality over arrays, the compiler generated special code to test if it was doing equality comparison on an array. If so, it would do a structural comparison instead of just calling the Equals method on Array. The design team iterated on a few different designs on how to solve these sorts of structural equality and comparison problems. It settled on creating a few interfaces that structural types needed to implement.
IStructualEquatable and IStructuralComparable
IStructualEquatable and IStructuralComparable interfaces provide a way for a type to opt in to structural equality or comparison. They also provide a way for a comparer to be used for each element in the object. Using these interfaces, as well as a specially defined comparer, we can have deep equality over tuples and arrays when it is required, but we don't have to force the semantics on all users of the type. The design is deceptively simple:
public interface IStructuralComparable {
        Int32 CompareTo(Object other, IComparer comparer);
    }

    public interface IStructuralEquatable {
        Boolean Equals(Object other, IEqualityComparer comparer);
        Int32 GetHashCode(IEqualityComparer comparer);
    }
These interfaces work by separating the act of iterating over elements in the structural type, for which the implementer of the interface is responsible, from the actual comparison, for which the caller is responsible. Comparers can decide if they want to provide a deep structural equality (by recursively calling the IStructualEquatable or IStructualComparable methods, if the elements implement them), a shallow one (by not doing so), or something completely different. Both Tuple and Array now implement both of these interfaces explicitly.
Partial Equivalence Relations
Tuple also needed to support the semantics of partial equivalence relations. An example of a partial equivalence relation in the Microsoft .NET Framework is the relationship between NaN and other floating-point numbers. For example: NaN<NaN is false, but the same holds for NaN>NaN and NaN == NaN and NaN != NaN. This is due to NaN being fundamentally incomparable, since it does not represent any number. While we are able to encode this sort of relationship with operators, the same does not hold for the CompareTo method on IComparable. This is because there is no value that CompareTo can return that signals the two values are incomparable.
F# requires that the structural equality on tuples also works with partial equivalence relationships. Therefore in F#, [NaN, NaN] == [NaN, NaN] is false, but so is [NaN, NaN] != [NaN, NaN].
Our first tentative solution was to have overloaded operators on Tuple. This worked by using operators on the underlying types, if they existed, and by falling back to Equals or CompareTo, if they did not. A second option was to create a new interface like IComparable but with a different return type so that it could signal cases where things were not comparable. Ultimately, we decided that we would hold off on building something like this until we saw more examples of partial equivalence being needed across the Microsoft .NET Framework. Instead, we recommended that F# implement this sort of logic in the IComparer and IEqualityComparer methods that they passed into the IStructrual variants of CompareTo and Equals methods by detecting these cases and having some sort of out-of-band signaling mechanism when it encountered NaNs.

Worth the Effort
Though it took a great deal more design iteration than anyone expected, we were able to create a tuple type that we feel is flexible enough for use in a variety of languages, regardless of syntactic support for tuples. At the same time, we've created interfaces that help describe the important concepts of structural equality and comparison, which have value in the Microsoft .NET Framework outside of tuple itself.
Over the past few months, the F# team has updated its compiler to use System.Tuple as the underlying type for all F# tuples. This ensures that we can start building toward a common tuple type across the Microsoft .NET ecosystem. In addition to this exciting development, tuple was demoed at this year's Professional Developers Conference as a new feature for Microsoft .NET Framework 4 and received much applause from the crowd. Watching the video and seeing how excited developers are to start using tuples has made all the time spent on this deceptively simple feature all the more worthwhile.

Send your questions and comments to clrinout@microsoft.com.

Matt Ellis is a Software Design Engineer on the Base Class Libraries team responsible for diagnostics, isolated storage, and other little features like Tuple. When he's not thinking about frameworks or programming language design, he spends his time with his wife Victoria and their two dogs, Nibbler and Snoopy.


Basic Instincts
Stay Error Free With Error Corrections
Dustin Campbell

This article is partly based on a prerelease version of Visual Studio. All information is subject to change.
Contents
Introducing Error Corrections
Applying Error Corrections with the Keyboard
Fixing Invalid Code
Using the Right Type Conversions
Correcting Spelling Mistakes
Importing Namespaces
Generating New Types and Members
Conclusion
One of the most useful features of the Microsoft Visual Basic editing experience in Microsoft Visual Studio is background compilation. You're probably already familiar with this feature, as it is similar in spirit to the spelling and grammar checker found in Microsoft Word. As you type code, the Visual Basic compiler runs in the background. When you type an error, it is underlined with a squiggle in the editor and added to the Error List window.
Prior to Visual Studio 2005, the only guidance for fixing errors came primarily from the error messages themselves. When possible, the Visual Basic Compiler generates error messages that are intended to explain not only what the error is, but also how to fix it.
Let's look at an example. Suppose that you have the following Visual Basic code:
Module Module1
  Sub Main()
    Dim i As Integer = "1"c
  End Sub
End Module
The code above produces a compiler error because it isn't clear which conversion from Char to Integer is expected. Should the compiler insert a conversion to produce the ASCII value of "1"c, or should it insert a conversion that produces the numerical value of "1"c? The compiler has no option but to generate this error message:
"'Char' values cannot be converted to 'Integer'. Use 'Microsoft.VisualBasic.AscW' to interpret a character as a Unicode value or 'Microsoft.VisualBasic.Val' to interpret it as a digit."
While the preceding error message goes to great lengths to explain how the problem can be fixed, it requires more coding on your part to actually fix it.

Introducing Error Corrections
To make fixing errors easier, the Error Correction UI was introduced. In Visual Studio 2005 and 2008, when an error is typed in the editor, a small red bar is added to the squiggle underline that indicates that a smart tag is available at that location, as shown in Figure 1.
Figure 1 Error Squiggle with a Smart Tag Indicator
If you hover the mouse over the smart tag indicator, the collapsed smart tag will appear along with a tooltip description. This is pictured in Figure 2.
Figure 2 Collapsed Smart Tag
In Figure 3, clicking on the smart tag expands the error correction UI with the options that are available for this particular code error.
Figure 3 Expanded Smart Tag with Available Error Corrections
The error correction UI makes it easy to fix errors quickly and accurately. The preview windows clearly show what changes will be made to your code, and it's a simple matter of clicking on either of the two hyperlinks to apply a fix.
Sometimes, a particular compiler is fixable in some cases, but not all. In these doubtful instances, the Visual Basic IDE will optimistically create a smart tag indicator for that error, primarily to improve performance. It is much quicker to create a smart tag indicator for errors that can be fixed some of the time than to check each error to determine if it can definitely be fixed before creating the indicator. When you hover over a smart tag indicator that doesn't have any error corrections, you will see the "no correction suggestions" message shown in Figure 4.
Figure 4 No Correction Suggestions

Applying Error Corrections with the Keyboard
Error corrections can be applied by using the keyboard as well as the mouse. If the editor caret is located on an error squiggle with a smart tag indicator, you can press Shift+Alt+F10 to immediately expand the smart tag and show the error correction options. With the smart tag expanded, the Up-Arrow and Down-Arrow keys will navigate the options and you can apply an error correction by pressing the Enter key. If you dislike the Shift+Alt+F10 keyboard shortcut, Ctrl+. will also display the smart tag. (I personally find Ctrl+. much easier to remember and to press!)

Fixing Invalid Code
Often, code will contain an error simply because it has an invalid structure. One common mistake is to write code that has unbalanced parentheses. Can you spot the error in the code below?
Module Module1
  Sub Main()
    Dim quad = Function(a, b, c) _
                 Function(x) (a * x * x) + (b * x) + c

    Dim f = quad(1.0, -79.0, 1601.0)

    Console.Write(f(42.0)
  End Sub
End Module
When code does not compile because it is invalid (e.g., the missing parenthesis in the call to Console.Write above), the Visual Basic IDE will suggest error corrections that make your code valid if applied. In Figure 5, the error correction offers to insert the missing parenthesis.
Figure 5 Error Correction for Inserting Parenthesis
Error corrections for invalid code aren't limited to code within a method body. For example, suppose that you have a read-only property and would like to convert it into a full property with a setter:
Class Person
  Private _name As String

  Public ReadOnly Property Name() As String
    Get
      Return _name
    End Get
  End Property
End Class
To add a setter in the code above, you would
  1. Move the editor caret after End Get.
  2. Press Enter.
  3. Type Set.
  4. Press Enter again.
That would leave you with the following invalid code:
Class Person
  Private _name As String

  Public ReadOnly Property Name() As String
    Get
      Return _name
    End Get
    Set(ByVal value As String)

    End Set
  End Property
End Class
To make the property valid, the ReadOnly keyword needs to be removed. Now, deleting the keyword is trivial, but it is easier and more efficient if you use the error correction to do the job:
  1. Press Up to move the editor caret to the error squiggle.
  2. Press Ctrl+. to display the suggestion error corrections shown in Figure 6.
  3. Press Down to focus the first error correction.
  4. Press Enter to apply.
Figure 6 Error Corrections for a Read-only Property with a Setter
As you can see, not only do error corrections help you write the correct code, they can be a big time saver!

Using the Right Type Conversions
By default, Visual Basic leaves strict typing off. This allows you to take advantage of the Visual Basic compiler's support for implicit data type conversions and late binding:
Module Module1
  Sub Main()
    Dim s As String = 42
  End Sub
End Module
Given the code above, the compiler will properly insert a type conversion from Integer to String.
However, if you use strict typing, Visual Basic error corrections will be available to help you insert the same type conversion that the compiler would have, if strict typing were off. Figure 7 shows the error correction for the code above when strict typing is enabled.
Figure 7 Error Correction to Convert an Integer to a String

Correcting Spelling Mistakes
Sometimes a code error might simply be a spelling mistake. For spelling errors in type names, Visual Basic will provide error corrections that suggest existing types with similar names. Consider the following code, which contains a spelling mistake:
Class Class1
End Class

Class Class2
End Class

Module Module1
  Sub Main()
    Dim c As New Clss
  End Sub
End Module
The code above mistakenly attempts to instantiate a type named Clss, but none exists. In this situation, two error corrections are available, one to change Clss to Class1 and another to change Clss to Class2, as shown in Figure 8.
Figure 8 Error Correction for Spelling Mistake
Currently, the spell checker is fairly simple and works only for type names. However, this is an area that the Visual Basic team would like to improve in a future release.

Importing Namespaces
After shipping Visual Studio 2005, the Visual Basic team received several requests for additional error corrections. Chief among these was an error correction for automatically adding Imports statements. It can be pretty irritating to start using a type and realize that you've forgotten to import its namespace. For example, suppose you were using the System.IO.File class to open and read a file from disk:
Module Module1
  Sub Main()
    Dim fileName = Path.Combine("C:\Temp", "Sizes.txt")
    Using f = File.OpenRead(fileName)

    End Using
  End Sub
End Module
This code results in an error if you haven't imported the System.IO namespace yet. In Visual Studio 2008, there are two possible error corrections for this error:
  1. Import the namespace.
  2. Qualify the reference.
This is shown in Figure 9. By choosing the first suggested error correction, we can easily import the System.IO namespace.
Figure 9 Error Correction for Adding Imports Statements
This begs the question: what if importing a namespace would change the meaning of your code? Suppose that the code above will use the Windows Presentation Framework (WPF) to create a System.Windows.Shapes.Rectangle, using data read from the Sizes.txt file. With the WPF references added, you start by instantiating a new Rectangle:
Imports System.IO

Module Module1
  Sub Main()
    Dim fileName = Path.Combine("C:\Temp", "Sizes.txt")
    Using f = File.OpenRead(fileName)
      Dim r As New Rectangle
    End Using
  End Sub
End Module
Like before, the namespace hasn't been imported yet, so you use the error correction UI pictured in Figure 10 to import it for you. However, this time there's a problem. The System.Windows.Shapes namespace also includes a type named Path, so importing the namespace would change the meaning of your code.
Figure 10 Error Corrections for Importing System.Windows.Shapes
Fortunately, the logic to avoid these situations is built into the error correction for adding Imports statements. The error correction recognizes the problem and displays the Add Imports Validation Error dialog, pictured in Figure 11.
Figure 11 The Add Imports Validation Error Dialog
This dialog gives you two options for tweaking the error correction, so the meaning of your code isn't changed:
  1. Import 'System.Windows.Shapes' and qualify the affected identifiers.
  2. Do not import 'System.Windows.Shapes', but change 'Rectangle' to 'Windows.Shapes.Rectangle'.
By picking the first option, an Imports statement is added for System.Windows.Shapes, and the reference to Path is fully qualified:
Imports System.IO
Imports System.Windows.Shapes

Module Module1
  Sub Main()
    Dim fileName = System.IO.Path.Combine("C:\Temp", "Sizes.txt")
    Using f = File.OpenRead(fileName)
      Dim r As New Rectangle
    End Using
  End Sub
End Module
Again, this error correction is available only in Visual Studio 2008. If you are using Visual Studio 2005, you won't see suggestions for adding Imports statements.

Generating New Types and Members
Visual Basic isn't done with error corrections yet! Visual Studio 2010 will introduce a new feature called Generate from Usage, which allows you to easily generate new types and members. For Visual Basic, this feature is implemented as a set of error corrections, so you can access them through the existing error corrections. In many cases, the Generate from Usage error corrections offer suggestions for compiler errors that previously had none. For example, look back at Figure 4. In Visual Studio 2008, that code has no error corrections available. But in Visual Studio 2010, the new Generate from Usage error corrections are suggested. Figure 12 shows the difference in the error corrections between Visual Studio 2008 and Visual Studio 2010 for the same code.
Figure 12 Generate Class
By choosing the first suggestion, a new class named Customer is generated in a new file. Now, you can continue to write code that uses members of the Customer class and use the error corrections to stub out the members for you. For example, Figure 13 shows the error corrections after you've assigned a value to a member of a class that hasn't been declared yet.
Figure 13 Generate Property or Field
After choosing the first suggestion, the generated Customer class looks like this:
Class Customer
  Property Name As String
End Class
In Visual Studio 2010, you will be able to leverage the Generate from Usage error corrections for maximum efficiency.

Conclusion
Error corrections are an essential part of the Visual Basic coding experience. Not only do they help you immediately spot and fix errors, but you can use them to write code more efficiently. This article only scratches the surface of the hundreds of suggestions offered by Visual Basic. And with Visual Studio 2010, there is an error correction for most coding errors.
Don't forget to use Ctrl+.!

Send your questions and comments to instinct@microsoft.com.

Dustin Campbell is the Microsoft Visual Basic IDE Program Manager on the Microsoft Visual Studio Languages Team. He works primarily on the editor and debugger product features. As a programming language nut, he also contributes to other languages in Visual Studio, such as C# and F#. Before joining Microsoft, Dustin helped to develop the award-winning CodeRush and Refactor! tools at Developer Express Inc. Dustin's favorite color is blue.


Cutting Edge
Comparing Web Forms And ASP.NET MVC
Dino Esposito
Contents
Benefits of ASP.NET Web Forms
Drawbacks of Web Forms
Benefits of ASP.NET MVC
Drawbacks of ASP.NET MVC
The Right Perspective
What's the Perfect Model for ASP.NET?
Undisputable Facts
At the End of the Day
I first saw Microsoft ASP.NET in action in 1999, when it was tentatively named ASP+. At that time, building a Web application on the Microsoft platform was a matter of assembling a bunch of Active Server Pages (ASP).
In a typical ASP page, you find HTML literals interspersed with code blocks. In code blocks, script code (mostly VBScript) is used to incorporate data generated by COM objects, such as components from the ActiveX Data Objects (ADO) framework. Undoubtedly, the introduction of ASP.NET in the late 1990s was a big step forward, as it represented a smart way to automate the production of HTML displayed in a client's browser.
ASP.NET simplified a number of everyday tasks and, more importantly, enabled developers to work at a higher level of abstraction.This allowed them to focus more on the core functions of the Web application rather than on common tasks around Web page design.
Based on server controls, ASP.NET allows developers to build real-world Web sites and applications with minimal HTML and JavaScript skills. The whole point of ASP.NET is productivity, achieved through powerful tools integrated in the runtime as well as the provision of development facilities, such as server controls, user controls, postback events, viewstate, forms authentication, and intrinsic objects. The model behind ASP.NET is called Web Forms and it was clearly inspired by the desktop Windows Forms model (in turn deeply inspired by the Visual Basic Rapid Application Development philosophy).
So why did Microsoft release "another" ASP.NET framework, called ASP.NET MVC? In this article, I'll explore the pros and cons of both ASP.NET Web Forms and ASP.NET MVC.

Benefits of ASP.NET Web Forms
As noted, ASP.NET Web Forms is stable and mature, and it is supported by heaps of third party controls and tools.
One of the keys to the rapid adoption of ASP.NET is certainly the point-and-click metaphor taken from Windows desktop development. With Web Forms, Microsoft basically extended the Visual Basic programming model to the Web. Desktop development, however, is stateful whereas the Web is inherently stateless. So the Web Forms model essentially abstracted a number of features to provide a simulated stateful model for Web developers. As a result, you didn't have to be a Web expert with a lot of HTML and JavaScript knowledgeto write effective Web applications.
To simulate stateful programming over the Web, ASP.NET Web Forms introduced features such as viewstate, postbacks, and an overall event-driven paradigm.For example, the developer can, say, double-click on a button to automatically generate a stub of code that will handle the user's clicking to the server. To get started writing an ASP.NET Web application, you just need to know the basics of .NET development, the programming interface of some ad hoc components, like server controls. Server controls that generate HTML programmatically, and the runtime pipeline, contribute significantly to a fast development cycle.
At the end of the day, key features of ASP.NET Web Forms are just the componentization of some ASP best practices. For example, postback, auto-population of input fields, authentication and authorization before page rendering, server controls, and compilation of the page, are not features devised and created from scratch for ASP.NET Web Forms. All of them evolved from ASP best practices. Ten years ago, ASP developers (including myself) were looking for exactly the set of features that Web Forms ended up providing. Furthermore, ASP.NET Web Forms generally exceeded our expectations by providing a full abstraction layer atop the whole Web stack: JavaScript, CSS, HTML.
To write an ASP page, you did need to know quite a bit about the Web and script languages. To write an ASP.NET page, in contrast, you need to know primarily about .NET and its compiled languages. Productivity and rapid development of data-driven, line-of-business applications have been the selling points of ASP.NET Web Forms. Until now, that is.

Drawbacks of Web Forms
Like many other things in this imperfect world, ASP.NET Web Forms is not free of issues. Years of experience prove beyond any reasonable doubt that separation of concerns (SoC) has not been a natural fit with the Web Forms paradigm.
Automated testing of an ASP.NET Web Forms application is hard, and not just because of a lack of SoC. ASP.NET Web Forms is based on a monolithic runtime environment that can be extended, to some extent, but it is not a pluggable and flexible system. It's nearly impossible to test an ASP.NET application without spinning up the whole runtime.
To achieve statefulness, the last known state of each server page is stored within the client page as a hidden field—the viewstate. Though viewstate has too often been held up as an example of what's wrong with Web Forms, it is not the monster it's made out to be. In fact, using a viewstate-like structure in classic ASP was a cutting-edge solution. From an ASP perspective, simulation of statefulness (that is, postback, viewstate, controls) was a great achievement, and the same was also said at first about how Web Forms isolated itself from HTML and JavaScript details.
For modern Web pages, abstraction from HTML is a serious issue as it hinders accessibility, browser compatibility, and integration with popular JavaScript frameworks like jQuery, Dojo, and PrototypeJS. The postback model that defaults each page to post to itself, makes it harder for search engines to rank ASP.NET pages high. Search engines and spiders work better with links with parameters, better if rationalized to human-readable strings. The postback model goes in the opposite direction. Also, an excessively large viewstate is problematic because the keyword the rank is based on may be located past the viewstate, and therefore far from the top of the document. Some engines recognize a lower rank in this case.

Benefits of ASP.NET MVC
Some of the recognized issues with the Web Forms model can be fixed within ASP.NET 4.0. You can disable or control the size of the viewstate. (Even though very few developers seem to have noticed, the size of the viewstate decreased significantly in the transition from ASP.NET 1.1 to ASP.NET 2.0 when Microsoft introduced a much more efficient serialization algorithm. In ASP.NET 4.0, you should also expect improvements in the way in which viewstate can be disabled and controlled.) You can use an ad hoc HTTP module to do URL rewriting or, better yet, you can use the newest Web routing API from ASP.NET 3.5 SP1. In ASP.NET 4.0, you can minutely control the ID of elements, including scoped elements. Likewise, in ASP.NET 4.0 the integration of external JavaScript frameworks will be simpler and more effective. Finally, the history management API in ASP.NET 3.5 SP1 made AJAX and postback work together while producing a search-engine-friendly page.
In many aspects, the Web Forms model in ASP.NET 4.0 is a better environment that tackles some of the aforementioned flaws. So what's the point of ASP.NET MVC?
You'll find a good introduction to ASP.NET MVC in the March 2008 issue MSDN Magazine ("Building Web Apps without Web Forms"), where Chris Tavares explains the basics of ASP.NET development without Web Forms. In summary, ASP.NET MVC is a completely new framework for building ASP.NET applications, designed from the ground up with SoC and testability in mind. When you write an ASP.NET MVC application, you think in terms of controllers and views. You make your decisions about how to pass data to the view and how to expose your middle tier to the controllers. The controller chooses which view to display based on the requested URL and pertinent data. Each request is resolved by invoking a method on a controller class. No postbacks are ever required to service a user request. No viewstate is ever required to persist the state of the page. No arraysof black-box server controls exist to produce the HTML for the browser.
With ASP.NET MVC, you rediscover the good old taste of the Web—stateless behavior, full control over every single bit of HTML, total script and CSS freedom.
The HTML served to the browser is generated by a separate, and replaceable, engine. There's no dependency on ASPX physical server files. ASPX files may still be part of your project, but they now serve as plain HTML templates, along with their code-behind classes. The default view engine is based on the Web Forms rendering engine, but you can use other pluggable engines such as nVelocity or XSLT. (For more details, have a look at the MVCContrib Web site at mvccontrib.codeplex.com.)
The runtime environment is largely the same as in ASP.NET Web Forms, but the request cycle is simpler and more direct. An essential part of the Web Forms model, the page lifecycle, is no longer necessary in ASP.NET MVC. It should be noted, though, that the default view engine in ASP.NET MVC is still based on the Web Forms rendering engine. This is the trick that allows you to use master pages and some server controls in ASP.NET MVC views. As long as the view engine is based on Web Forms, the view is an ASPX file with a regular code-behind class where you can handle classic events such as Init, Load, PreRender, plus control-specific events such as RowDataBound for a GridView control. If you switch off the default view engine, you no longer need Page_Loador other events of the standard page lifecycle. Figure 1 compares the run-time stack for Web Forms and ASP.NET MVC.
Figure 1 The Run-Time Stack at a Glance
It should be noted that the "Page lifecycle" boxes in Figure 1 have been collapsed for readability and include several additional events each. Anyway, the run-time stack of ASP.NET MVC is simpler and the difference is due to the lack of a page lifecycle. However, this makes it problematic to maintain the state of visual elements across page requests. State can be stored into Session or Cache, but this decision is left to the developer.
Figure 2 illustrates the sequence of an ASP.NET MVC request.
Figure 2 The Sequence Diagram of an ASP.NET MVC Request
The MVC acronym stands for Model-View-Controller. However, you should note that the pattern depicted in Figure 2 doesn't exactly match the classic formulation of the MVC pattern. In particular, in the original MVC paper, Model and View are tied together through an Observer relationship. The MVC pattern, though, is deliberately loosely defined and, even more importantly, was devised when the Web was still to come. Adapting MVC to the Web moved it toward the model in Figure 2, which is also known as Model2. In general, when you talk or read about MVC be aware that there are quite a few slightly different flavors of it within the literature.

Drawbacks of ASP.NET MVC
So ASP.NET MVC brings to the table a clean design with a neat separation of concerns, a leaner run-time stack, full control over HTML, an unparalleled level of extensibility, and a working environment that enables, not penalizes, test-driven development (TDD). Is ASP.NET MVC, therefore, a paradise for Web developers?
Just like with Web Forms, what some perceive as a clear strength of ASP.NET MVC, others may see as a weakness. For example, full control over HTML, JavaScript, and CSS, ASP.NET MVC means that you enter the Web elements manually. Much of this pain can be mitigated, however, with some of the more recent JavaScript libraries and even different view engine. In general, though, there's no sort of component model to help you with the generation of HTML, as there is in the Web Forms approach. Currently, HTML helpers and user controls are the only tools you can leverage to write HTML more quickly. As a result, , some ASP.NET developers may see ASP.NET MVC as taking a step backward in terms of usability and productivity. Another point to be made, regarding the impact of ASP.NET MVC on everyday development, is that it requires some upfront familiarity with the MVC pattern. You need to know how controllers and views work together in the ASP.NET implementation. In other words, ASP.NET MVC is not something you can easily learn by experimenting. In my experience, this may be the source of decreased productivity for the average Web Forms developer.

The Right Perspective
As an architect or developer, it is essential that you understand the structural differences between the frameworks so that you can make a thoughtful decision. All in all, ASP.NET Web Forms and ASP.NET MVC are functionally equivalent in the sense that a skilled team can successfully use either to build any Web solution.
The skills, education, and attitude of the team, though, are the key points to bear in mind. As you may have figured out yourself, most of the features presented as a plus for either framework may also be seen as a minus, and vice versa. Full control over HTML, for example, may be a lifesaver to one person but a nightmare to another. Personally, I was shocked the first time I saw the content of a nontrivial view page in ASP.NET MVC. But when I showed the same page to a customer whose application was still using a significant number of ASP pages, well, he was relieved. If you have accessibility as a strict requirement, you probably want to take full control over the HTML being displayed. And this is not entirely possible with Web Forms. On the other hand, if you're building a heavy data-driven application, you'll welcome the set of data-bound controls and statefulness offered by Web Forms.
Correctly, Microsoft has not positioned ASP.NET MVC as a replacement for ASP.NET Web Forms. Web Forms is definitely a pattern that works for Web applications. At the same time, Ruby-on-Rails has proved that MVC can also be a successful pattern for Web applications; and ASP.NET MVC confirms this.
In the end, Web Forms and ASP.NET MVC have pros, cons, and structural differences that affect various levels. Generalizing, I'd say that Web Forms embraces the RAD philosophy whereas ASP.NET MVC is TDD-oriented. Further, Web Forms goes toward an abstraction of the Web that simulates a stateful environment, while ASP.NET MVC leverages the natural statelessness of the Web and guides you towards building applications that are loosely coupled and inherently testable, search-engine friendly, and with full control of HTML.

What's the Perfect Model for ASP.NET?
After using Web Forms for years, I recognize a number of its drawbacks, and ASP.NET MVC addresses them quite well: testability, HTML control, and separation of concerns. But though I see ASP.NET MVC as an equally valid option at this time, I don't believe it to be the silver bullet for every Web application. In my opinion, ASP.NET MVC today lacks some level of abstraction for creating standard pieces of HTML. HTML helpers are just an interesting attempt to speed up HTML creation. I hope to see in the near future a new generation of MVC-specific server controls, as easy and quick to learn and use as Web Forms server controls, but totally unbound from the postback and viewstate model. My hopes are for a System.Web.Mvc.GridView control that saves me from writing a loop to generate an HTML table, while offering column templates, server-side data-binding events, and styling options. What would be the difference between such an MVC GridView and today's Web Forms GridView? The MVC GridView would only emit HTML plus, optionally, some row-specific JavaScript, but it wouldn't manage things like paging and sorting. Paging and sorting will be delegated to other specific controls or plain links created by the developer. In this way, the MVC GridView could bring some RAD flavor to ASP.NET MVC, speeding up the development of pages without precluding handcrafted pages.
Going back to the root of the problem, the key difference between Web Forms and ASP.NET MVC is the underlying pattern. Web Forms is a model based on the "Page Controller" pattern. Web Forms are UI-focused and centered around the concept of a page: the page gets input, posts back, and determines the output for the browser. The development environment was therefore devised to enable rapid prototyping, via wizards and rich designers. Any user action ends up in a method on the code-behind class of each page. At that point, though, nothing prevents you from using proper SoC and nothing really stops architects from imposing patterns like MVC, Model-View-Presenter (MVP) or even Model-View-View-Model (MVVM).
The Web Forms architecture does not encourage SoC, but it doesn't prevent it either. The Web Forms architecture makes it seductive to opt for drag-and-drop of controls, to code logic right in event stubs without further separation, and to drop data sources right on the page, which couples the UI directly to the database. MVC is neither prohibited nor a blasphemy in Web Forms; it's just that very few developers practice it because it requires working around much of the Web Forms infrastructure.
Testability is a different story. ASP.NET Web Forms doesn't prevent unit testing, but it requires much disciple and repetitive boilerplate coding to do so.As long as you code your way to SoC you can test and reuse presentation and business logic. Sure, you likely don't have the Visual Studio project template to create a test project for you. You need to become familiar with testing and mocking frameworks and manage those projects yourself. But this can be done. From a testability perspective, though, a real difference exists between Web Forms and ASP.NET MVC. In Web Forms, you just don't have the flexibility of ASP.NET MVC. This is a true limitation. ASP.NET MVC is designed with testability in mind,which means that the framework architecture guides the developer to write code that is inherently testable, that is isolated from the context or connected to it via contracted interfaces. Even more importantly, in ASP.NET MVC intrinsic objects are mockable as they expose interface and base classes. From a testing standpoint, the best you can do in Web Forms is to move your logic into separate and easily testable classes. Then, you test the presentation (ASPX and code-behind) by sending HTTP requests and checking the results. You can't do this in Web Forms without spinning up the whole ASP.NET runtime, however. In ASP.NET MVC, the majority of testing is to assure that the data being passed into the view is correct. In addition, you can mock up intrinsic objects and run your tests in a genuinely isolated environment.
We should also note that control over HTML and SEO-friendly URLs, both advantages of ASP.NET MVC, can be achieved to some extent in Web Forms. ASP.NET 3.5 SP1, in particular, includes the URL Routing and History API for SEO. CSS adapters, instead, are the tools to leverage to try to control HTML in Web Forms. Integration with JavaScript and AJAX frameworks is, frankly, no longer an issue in Web Forms.

Undisputable Facts
ASP.NET Web Forms and ASP.NET MVC are not competitors in the sense that one is supposed to replace the other. You have to choose one, but different applications may force you to make different choices. In the end, it's really like choosing between a car and a motorcycle when making a trip. Each trip requires a choice, and having both vehicles available should be seen as an opportunity, not as a curse. Here are some facts about the frameworks:
  • Web Forms is hard to test.
  • ASP.NET MVC requires you to manage the generation of HTML at a more detailed level.
  • ASP.NET MVC is not the only way to get SoC in ASP.NET.
  • Web Forms allows you to learn as you go.
  • Viewstate can be controlled or disabled.
  • Web Forms was designed to abstract the Web machinery.
  • ASP.NET MVC exposes Web architecture.
  • ASP.NET MVC was designed with testability and Dependency Injection in mind.
  • ASP.NET MVC takes you towards a better design of the code.
  • ASP.NET MVC is young and lacks a component model.
  • ASP.NET MVC is not anti-Web Forms.
ASP.NET MVC was not created to replace Web Forms but to partner it. ASP.NET MVC turns some of the weaker elements of Web Forms into its own internal strengths. However, problems such as lack of testability, SoC, SEO, and HTML control can be avoided or reduced in Web Forms with some discipline and good design, though the framework itself doesn't provide enough guidance.

At the End of the Day
We have seen that there are pros and cons in both Web Forms and ASP.NET MVC. Many developers, however, seem to favor ASP.NET MVC because it represents the only way to get SoC and testability into their applications. Is it really the only way? No. However, ASP.NET MVC makes it easier and natural to achieve SoC and write more testable code. ASP.NET MVC doesn't magically transform every developer into an expert architect and doesn't prevent developers from writing bloated and poorly designed code. At the end of the day, both Web Forms and ASP.NET MVC help to build applications that are designed and implemented to deal effectively with the complexity of real-world solutions. No software magic exists, and none is yet supported by the ASP.NET platform.

Send your questions and comments for Dino to cutting@microsoft.com.

Dino Esposito is an architect at IDesign and the co-author of Microsoft .NET: Architecting Applications for the Enterprise (Microsoft Press, 2008). Based in Italy, Dino is a frequent speaker at industry events worldwide. You can join his blog at weblogs.asp.net/despos.


Test Run
Request-Response Testing With F#
James McCaffrey
Code download available from the MSDN Code Gallery
Browse the Code Online
Contents
The Application Under Test
ASP.NET Request-Response Testing with F#
Harness Details
Wrap Up
The F# programming language has several characteristics that make it well-suited for software test automation. In this month's column, I show you how to use F# to perform HTTP request-response testing for ASP.NET Web applications. Specifically, I create a short test-harness program that simulates a user exercising an ASP.NET application. The F# harness programmatically posts HTTP request information to the application on a Web server. It then fetches the HTTP response stream and examines the HTML text for an expected value of some sort to determine a pass/fail result. In addition to being a useful testing technique in its own right, learning how to perform HTTP request-response testing with F# provides you with an excellent way to learn about the F# language. This column assumes you have basic familiarity with ASP.NET technology and intermediate .NET programming skills with C# or VB.NET, but does not assume you have any experience with the F# language. However, even if you are new to ASP.NET and test automation in general, you should still be able to follow this month's column without too much difficulty. To see where I'm headed, take a look atFigures 1 and 2. Figure 1 illustrates the example ASP.NET Web application under test that I use. The system under test is a simple but representative Web application, named MiniCalc.
Figure 1 ASP.NET Web Application Under Test
I deliberately keep my ASP.NET Web application under test as simple as possible so that I don't obscure the key points in the test automation. Realistic Web applications are significantly more complex than the dummy MiniCalc application shown in Figure 1, but the F# testing techniques I describe here easily generalize to complex applications. The MiniCalc Web application accepts two integers and an instruction to add or multiply. It then sends the values to a Web server where the result is computed. The server creates the HTML response and sends it back to the client browser where the result is displayed to four decimal places. Figure 2 shows an F# test harness in action.
Figure 2 Request-Response Testing with F#
My F# harness is named project.exe and does not accept any command-line arguments. For simplicity, I have hard-coded information including the URL of the Web application, test case input, and test case expected results. I will explain how you can parameterize the test harness later. My harness begins by echoing the target URL of localhost:15900/MiniCalc/Default.aspx. Notice that I am using the Visual Studio development Web server rather than IIS, so I specify a port number (15900) instead of the IIS default port 80. In test case 001, my F# harness programmatically posts information that corresponds to a user typing 5 into control TextBox1, typing a 3 into TextBox2, selecting RadioButton1 (to indicate an addition operation), and clicking on Button1 (to calculate). Behind the scenes, the harness captures the HTTP response from the Web server and then searches the response for an indication that 8.0000 (the correct result of 5 + 3) is in the TextBox3 result control. The harness tracks the number of test cases that pass and the number that fail (which is a surprisingly interesting operation in F#) and displays those results after all test cases have been processed.
In the sections of this column that follow, I briefly describe the Web application under test so you'll know exactly what is being tested. Next, I walk you through the details of creating lightweight HTTP request-response automation using the F# language. I wrap up by describing how you can modify the techniques I've presented to meet your own needs. I also present a few opinions about why you should take time to investigate F#. I think you'll find the information presented here interesting and a useful addition to your testing toolset.

The Application Under Test
Let's take a look at the code for the MiniCalc ASP.NET Web application, which is the target of my test automation. I created the MiniCalc application using Visual Studio 2008 to take advantage of the built-in development Web server. After launching Visual Studio, I clicked on File | New | Web Site. In order to avoid the ASP.NET code-behind mechanism and keep all the code for my Web application in a single file, I selected the Empty Web Site option. To avoid using IIS, I selected the File System option from the Location field drop-down control. I decided to use C# for the MiniCalc application, but the F# test harness I present in this column works with ASP.NET applications written in VB.NET. Additionally, with slight modifications the harness can target non-.NET Web applications that are written using technologies such as classic ASP, CGI, PHP, JSP, Ruby, and so on. Because I intend to use the Visual Studio development server, I specified a standard location in the file system, such as C:\MyWebApps\MiniCalc, rather than an IIS-specific location, such as C:\Inetpub\wwwroot\MiniCalc. I clicked OK on the New Web Site dialog to generate the structure of my Web application. Next, I went to the Solution Explorer window, right-clicked on the MiniCalc project name, and selected Add New Item from the context menu. I then selected Web Form from the list of installed templates and accepted the Default.aspx file name. I cleared the "Place code in separate file" option and then clicked the Add button.
Next, I double-clicked on the Default.aspx file name in Solution Explorer to edit the template-generated code. I deleted all the template code and replaced it with the code shown in Figure 3.
Figure 3 MiniCalc Web Application Under Test Source
<%@ Page Language="C#" %>
<script language="C#" runat="server">
  private void Button1_Click(object sender, System.EventArgs e)
  {
    int alpha = int.Parse(TextBox1.Text.Trim());
    int  beta = int.Parse(TextBox2.Text.Trim());

    if (RadioButton1.Checked) {
      TextBox3.Text = Sum(alpha, beta).ToString("F4");
    }
    else if (RadioButton2.Checked) {
      TextBox3.Text = Product(alpha, beta).ToString("F4");
    }
    else
     TextBox3.Text = "Select method";
  }
  private static double Sum(int a, int b) {
    double ans = a + b;
    return ans;
  }
  private static double Product(int a, int b) {
    double ans = a * b;
    return ans;
  }
</script>

<html>
  <head>
    <style type="text/css">
      fieldset { width: 16em }
      body { font-size: 10pt; font-family: Arial }
    </style>
    <title>Default.aspx</title>
  </head>
  <body bgColor="#ffcc99">
    <h3>MiniCalc by ASP.NET</h3>
    <form method="post" name="theForm" id="theForm"
      runat="server" action="Default.aspx">
      <p><asp:Label id="Label1" runat="server">
        Enter integer:&nbsp&nbsp</asp:Label>
      <asp:TextBox id="TextBox1" width="100" runat="server" /></p>
      <p><asp:Label id="Label2" runat="server">
        Enter another:&nbsp</asp:Label>
      <asp:TextBox id="TextBox2" width="100" runat="server" /></p>
      <p></p>
      <fieldset>
        <legend>Arithmentic Operation</legend>
        <p><asp:RadioButton id="RadioButton1" GroupName="Operation"
          runat="server"/>Addition</p>
        <p><asp:RadioButton id="RadioButton2" GroupName="Operation"
          runat="server"/>Multiplication</p>
        <p></p>
      </fieldset>
      <p><asp:Button id="Button1" runat="server" text=" Calculate "
        onclick="Button1_Click" /> </p>
      <p><asp:TextBox id="TextBox3" width="120" runat="server" /></p>
    </form>
  </body>
</html>
In order to keep my source code small in size and easy to understand, I am not using good coding practices in this Web application. In particular, I do not do any error checking and I use a somewhat haphazard design approach by combining server-side controls (such as <asp:TextBox>) with plain HTML (such as <fieldset>). The most important parts of the code listing in Figure 3 for you to note are the IDs of my ASP.NET server-side controls. I use default IDs Label1 (user prompt), TextBox1 and TextBox2 (input for two integers), RadioButton1 and RadioButton2 (choice of addition or multiplication), Button1 (calculate), and TextBox3 (result). To perform automated HTTP request-response testing for an ASP.NET application, you must know the IDs of the application's controls. In this situation, I have the source code available because I am creating the application myself; but even if you are testing a Web application you didn't write, you can always examine the application by using a Web browser's View Source functionality.
To verify that my Web application under test was built correctly, I hit the <F5> key. I clicked OK on the resulting Debugging Not Enabled dialog to instruct Visual Studio to modify the Web application's Web.config file. Visual Studio then started the development server and assigned a random port number to the Web application—in this case 15900, as you can see in Figure 1. If I had wanted to specify a port number, I could have selected the MiniCalc project in Solution Explorer, and then clicked on the View main menu item and selected the Properties Window option. This would display a "Use dynamic ports" option set to a default of True, and I could change the value to False and enter a value in the "Port number" field.
Notice that the action attribute of my <form> element is set to Default.aspx. In other words, every time a user submits a request, the same Default.aspx page code is executed. This gives my MiniCalc Web application the feel of a single application rather than a sequence of different Web pages. Because HTTP is a stateless protocol, ASP.NET accomplishes the application effect by maintaining the Web application's state in a special hidden value type, called the ViewState. As we'll see shortly, dealing with an ASP.NET application's ViewState is the key to programmatically posting data to the application.

ASP.NET Request-Response Testing with F#
Now that we've seen the Web application under test, let's go over the F# test harness program that produced the screenshot in Figure 2. F# is tentatively scheduled to ship with the next version of Visual Studio. For this column, I decided to use the September 2008 Community Technical Preview (CTP) version of F# and Visual Studio 2008. By the time you read this column, you may have other options for using F#. In any case, the CTP version I used was extremely stable, and I installed it without any difficulty. The F# installation process places everything you need to write F# programs into Visual Studio.
I started by launching Visual Studio and then clicking File | New | Project. On the New Project dialog, I selected the Visual F# project type, then selected the F# Application template to create a command-line application. I named my project, "Project." The project name will become the name of the resulting executable (here, project.exe), so a more descriptive name, such as Request-Response-Harness, might have been preferable. After specifying a location for my F# project and clicking OK, I double-clicked on file Program.fs in the Visual Studio Solution Explorer window to open an editing window. The overall structure for my F# harness is listed in Figure 4.
Figure 4 F# Test Harness Structure
#light
open System
open System.Text
open System.Net
open System.IO
open System.Web

printfn "\nBegin F# HTTP request-response test of MiniCalc Web App\n"
let url = "http://localhost:15900/MiniCalc/Default.aspx"
printfn "URL under test = %s \n" url

// define function to get ViewState & EventValidation
// set up test case data
try
  // set numPass & numFail counters to 0
  // iterate and process each test case
  // display number pass & number fail
  printfn "\nEnd F# test run"
  Console.ReadLine() |> ignore
with
  | :? System.OverflowException as e ->
    printfn "Fatal overflow exception %s" e.Message
    Console.ReadLine() |> ignore
  | :? System.Exception as e ->
    printfn "Fatal: %s" e.Message
    Console.ReadLine() |> ignore

// end source
The first line in my F# source code, #light, instructs the F# compiler to use lightweight syntax, where indentation and newlines in part determine program structure. This is standard practice for F# programs. I use the F# open keyword to bring the relevant .NET namespaces into scope, similar to using keyword in C# or the imports keyword in Visual Basic. Notice that because I am using light syntax, I do not use an explicit statement terminator such as the semicolon character used by C#, JavaScript, and other C-related languages. I open System.Text in order to easily use the Encoding class to convert text to bytes. The System.Net and System.IO namespaces house the key classes needed to programmatically post data to a Web application. The System.Web namespace is not visible by default to an F# application, so I explicitly added that namespace by right-clicking on the project name in Visual Studio and then selecting the Add Reference option. I open System.Web so that I can use the HttpUtility class to perform URL-encoding. My next instruction is straightforward:
printfn "\nBegin F# HTTP request-response test of MiniCalc Web App\n"
The printfn() library function displays information to the command shell as you'd expect. Strings in F# are delimited by double-quotes and can contain embedded escape sequences such as \n for a newline. One of the key characteristics of F# is that almost everything revolves around functions, and most functions return a value that must be explicitly dealt with. However, the printfn() function does not return a value. Next I set my target URL:
let url = "http://localhost:15900/MiniCalc/Default.aspx"
I use the let keyword and the = operator to bind a string value to an identifier named url. (Many members of the F# team prefer to use the term symbol rather than identifier.) Notice the port number in the URL string. In this case, I do not specify the data type for identifier url so the F# compiler will have to infer the type. I could have explicitly typed identifier url as a string:
let url : string = " . . . "
Instead of hard-coding the URL into the F# source, I could fetch it as a command-line argument using the built-in Sys.argv array:
let url = Sys.argv.[1]
Sys.argv.[0] is the program name, .[1] is the first argument, and so on. Next I echo the target URL:
printfn "URL under test = %s \n" url
The printfn() function uses C-language style formatting, where %s indicates a string. Other common specifiers include %d for integer, %x for hexadecimal, %.2f for floating point with two decimals, and a generic %A for all types. F# supports exception handling using a try-with construction. If an exception is thrown in the try block, control will be transferred to the with block where the exception will be handled. Notice that with light syntax I do not use curly braces to define begin and end points for a code block. Instead, all statements that are indented the same number of blank spaces (you cannot use tab characters) are part of the same code block. The last line in my try block is a call to ReadLine(), so that my harness will pause execution and hold the command shell on the screen:
Console.ReadLine() |> ignore
ReadLine() returns a string, and in F#, the return value must be accounted for or the compiler will generate an error. Here I use the |> pipe operator to send the return value to the built-in ignore object. As an alternative for discarding a return value in most situations, you can use the special _ (underscore) identifier like this:
let _ = Console.ReadLine()
However, for subtle F# syntax reasons, this approach does not work as the last statement of a code block. My exception handling code uses an interesting F# construction:
| :? System.OverflowException as e ->
    printfn "Fatal overflow exception %s" e.Message
| :? System.Exception as e ->
    printfn "Fatal: %s" e.Message
You can interpret the first part of this code to mean, "If the exception matches type System.OverflowException, then assign the exception to an identifier named e, and then print a string message that includes the exception Message text." The | token is the match operator. In other words, if an exception is thrown, my program attempts to match the exception with two patterns. The :? operator tests for types rather than values.

Harness Details
Now that I've explained the overall structure of my F# test harness, let's look at the details. If you refer to Figure 4, you'll see that I define a function that fetches ViewState and EventValidation information from the MiniCalc application under test. In F#, you must define functions in source code before you call them. As I described earlier, because HTTP is a stateless protocol, ASP.NET uses a special ViewState value to maintain state. A ViewState value is a Base64-encoded string that represents the state of the ASP.NET Web application after every request-response round trip. An EventValidation value is somewhat similar to a ViewState value, but is used for security purposes to help prevent script-insertion attacks. As it turns out, if you want to programmatically post to an ASP.NET Web application, you must send the application's current ViewState value and current EventValidation value. The code for the function that fetches ViewState and EventValidation values is listed in Figure 5.
Figure 5 Function to Fetch ViewState and EventValidation
let getVSandEV (url : string) =
  let wc = new WebClient()
  let st = wc.OpenRead(url)
  let sr = new StreamReader(st)
  let res = sr.ReadToEnd()
  sr.Close()
  st.Close()

  let startI = res.IndexOf("id=\"__VIEWSTATE\"", 0) + 24
  let endI = res.IndexOf("\"", startI)
  let viewState = res.Substring(startI, endI - startI)

  let startI = res.IndexOf("id=\"__EVENTVALIDATION\"", 0) + 30
  let endI = res.IndexOf("\"", startI)
  let eventValidation = res.Substring(startI, endI - startI)
  (viewState, eventValidation)
Notice that I use the let keyword and the = operator to define an F# function. I name my function getVSandEV and specify a single input parameter named url that has type string. My function signature does not explicitly indicate the return type, but I could have done so, as I'll explain in a moment. My function begins by instantiating a WebClient object:
let wc = new WebClient()
Because I placed an open statement to the System.Net namespace that houses the WebClient class, I do not need to fully qualify the class name. Next, I send a priming request to the target URL:
let st = wc.OpenRead(url)
let sr = new StreamReader(st)
let res = sr.ReadToEnd()
I use the OpenRead() method, combined with a StreamReader object and its ReadToEnd() method, to send a request to the target Web application, grab the entire HTML source of the response as a string, and bind that result to an identifier named res. In most cases, I suggest you explicitly type F# identifiers, such as let res : string = sr.ReadToEnd(), but in this situation, I let the F# compiler infer the type of identifier res. At this point, I need to parse out the ViewState and EventValidation values from the string value bound to the res identifier. The part of the string value bound to res that has the ViewState value resembles:
<input type="hidden" name="__VIEWSTATE"
 id="__VIEWSTATE" value="/wEPDwUK . . . Zmv==" />
First, I find the location of the beginning of the ViewState value using the String.IndexOf() method:
let startI = res.IndexOf("id=\"__VIEWSTATE\"", 0) + 24
The 0 argument means begin searching res at index position 0, which is the beginning of the response string. Notice that because my target string contains double-quote characters, I delimit the target string by using an \" escape sequence. Once I find where my target value begins, the actual ViewState value starts 24 characters from that index. Note that "—VIEWSTATE" has two leading underscore characters, not just one. This is a pretty crude way to parse for the initial ViewState value and makes my code brittle. However, in this situation, I am performing quick and easy test automation and I'm willing to accept the possibility that my code may break. Now I find the location within res where the ViewState value ends:
let endI = res.IndexOf("\"", startI)
I search for the first occurrence of any double-quote character after the beginning of the ViewState value I just found (at startI) and bind that location with identifier endI. Now that I know where the ViewState value begins and ends within the response string res, I can extract the value using the SubString method:
let viewState = res.Substring(startI, endI - startI)
The two arguments to the SubString() method are the index within res to begin extracting from, and the number of characters to extract (not the index to end extracting, which is a common mistake). As always with indexing methods, you've got to be very careful to avoid starting or ending one character too soon or too late. The identifier viewState now holds the initial ViewState value for the target ASP.NET Web application. Extracting the EventValidation value follows the same pattern:
let startI = res.IndexOf("id=\"__EVENTVALIDATION\"", 0) + 30
let endI = res.IndexOf("\"", startI)
let eventValidation = res.Substring(startI, endI - startI)
Notice that I reuse my startI and endI identifiers and bind them to new values. This is legal in F# when the code is inside a method definition, as it is here, but not legal in top-level code outside of a method. At this point, I have my two values bound to identifiers ViewState and EventValidation. I use a neat F# feature to effectively return both values simultaneously:
(viewState, eventValidation)
I do not use an explicit return keyword; the last line of an F# function automatically represents the return value. Here I use parentheses to construct an F# tuple, which you can think of as a set of values. As I mentioned above, I could have defined my getVSandEV() function in a way that explicitly indicates the return value:
let getVSandEV (url : string) : (string * string) = . . .
The (string * string) notation means my function returns a tuple of two strings. Now that I've defined my helper function, I set up my test case data:
let testCases =
  [| "001,TextBox1=5&TextBox2=3&Operation=RadioButton1" +
     "&Button1=clicked,value=\"8.0000\",Add 5 and 3"
     "002,TextBox1=5&TextBox2=3&Operation=RadioButton2" +
     "&Button1=clicked,value=\"15.0000\",Multiply 5 and 3"
     "003,TextBox1=0&TextBox2=0&Operation=RadioButton1" +
     "&Button1=clicked,value=\"0.0000\",Add 0 and 0"
  |]
Here I create an immutable F# array named testCases that contains three strings. The [| . . . |] notation is used by F# to delimit an array. Because my three strings are quite long, I break each string into two parts and use the + string concatenation operator to stitch them back together. F# also accepts the ^ character for string concatenation. The first part of the first string in array testCases, 001, is a test case ID. After a comma delimiter, I have TextBox1=5&TextBoxt2=3 that, when posted to the MiniCalc Web application, will simulate a user typing these values. The third name-value pair (Operation=RadioButton1) is a way to simulate a user selecting a RadioButton control item—in this case, the RadioButton that corresponds to addition. You might have incorrectly guessed (as I originally did) at something like RadioButton1=checked. However, RadioButton1 is a value of the Operation control, not a control itself. The fourth name-value pair (Button1=clicked) is somewhat misleading. I need to supply a value for Button1 to simulate that it has been clicked by a user, but any value will work. So, I could have used "Button1=yadda" or even just "Button1=" if I had wanted to. But "Button1=clicked" is more descriptive. The next field (value="8.0000") in my test case data is an expected value in the form of a string that I'll look for in the HTML response stream. The final field (Add 5 and 3) is a simple comment.
Using an F# array to store my test case data is perhaps the simplest approach, but there are several alternatives. I could have replaced the [| . . . |] delimiters with plain square brackets such as: let testCases = [ "001 . . ." ] to create an F# List. Lists are common and thematic with older functional programming languages such as LISP and Prolog, but in this situation, I'd gain no advantage by using a List. Alternatively, I could have created an F# mutable array like this:
let testCases = Array.create 3 ""
testCases.[0] <- "001,. . ."
testCases.[1] <- "002,. . ."
testCases.[2] <- "003,. . ."
The use of mutable arrays is quite rare in F# and, again, I'd gain no advantage by using one here; I mention the possibility mostly to show you mutable array syntax. If you refer back to the overall test harness structure shown in Figure 3, you can see that I am now ready to start processing each test case. I begin by setting up counter identifiers to store the number of test cases that pass and fail:
let numPass = ref 0
let numFail = ref 0
In most cases, I'd simply bind these identifiers to 0, for example, "let numPass = 0". However, I need to initialize the counters outside a function and increment each counter inside the function (as we'll see shortly), but print the final values outside the function. This causes a minor problem, because of scope visibility issues. In awkward situations like this, one approach is to use the ref keyword as I've done here. I'll explain how to work with ref identifiers shortly. Now comes the trickiest syntax part of my F# test harness. I process each test case:
testCases |>
  Seq.iter(fun (testCase : string) ->
  // parse current test case
  // get ViewState and EventValidation
  // send HTTP request and get response
  // check response for expected value
  // print pass or fail
  )
I use the |> pipe operator to send my testCases array into the Seq.iter() method, which will process each test case item in the array. Seq.iter() expects an argument that is a function that will be applied to every item in the sequence. I could write a function explicitly, but a thematic F# approach is to define an anonymous function on the fly using the "fun" keyword. My anonymous function accepts a single-string parameter named testCase, which will be bound to each item in turn in the testCases array. Here, the parameter testCase must be type string because each item in the array testCases is a string, so I could have omitted the explicit typing for testCase. Inside my anonymous function, I parse out the values in the current test case:
let delimits = [|',';'~'|];
let tokens = testCase.Split(delimits)
let caseID = tokens.[0]
let input = tokens.[1]
let expected = tokens.[2]
let comment = tokens.[3]
Notice I use the F# [| . . |] syntax with a semicolon delimiter to specify an array of characters as an argument for the String.Split() method. Next, I call the getVSandEV() function I defined earlier:
let (vs, ev) = getVSandEV url
Recall that getVSandEV() accepts a single-string argument and returns a tuple of two strings. I use parentheses to capture the tuple, deconstruct the tuple values, and bind them to identifiers vs and ev. Notice that in F#, I do not need to use parentheses when calling a program-defined function. Next, I build up my actual POST data:
let data = input +
 "&__VIEWSTATE=" + HttpUtility.UrlEncode(vs) +
 "&__EVENTVALIDATION=" + HttpUtility.UrlEncode(ev)
let buffer = Encoding.ASCII.GetBytes(data)
I take the value bound to identifier input and concatenate the required ViewState and EventValidation values. Because ViewState and EventValidation values are Base64 encoded, they may contain characters that are not valid in an HTTP POST request (in particular, = padding characters), so I use the UrlEncode() method in the System.Web namespace to convert any such troublesome characters into an escape sequence such as %3D. I use the GetBytes() method to convert my string into an array of bytes. Now I can create an HTTP request object:
let req = WebRequest.Create(url) :?> HttpWebRequest
req.Method <- "POST"
req.ContentType <- "application/x-www-form-urlencoded"
req.ContentLength <- int64 buffer.Length
I instantiate an HttpWebRequest object using a factory mechanism of the WebRequest class. I must cast the return value of the Create() method, so I use the downcast :?> operator, which you can interpret to mean "and cast as type xxx". Because the properties of my .NET object are mutable, I use the <- operator to assign values of "POST", "application/x-www-form-urlencoded", and buffer.Length to the Method, ContentType, and ContentLength properties of the request object. Notice that to cast the Length property of identifier buffer as int64, I use syntax similar to C-based languages rather than using the :?> operator. In F#, you use C-style cast syntax with .NET value types, such as int64, and use :?> with reference types, such as HttpWebRequest. With the request object created, I can fire it off to the Web application under test:
let reqSt = req.GetRequestStream()
reqSt.Write(buffer, 0, buffer.Length)
reqSt.Flush()
reqSt.Close()
The Write() method does not actually write its byte array argument, so I explicitly call the Flush() method to do so. Now I can fetch the HTTP response and bind it to an identifier named html:
let res = req.GetResponse() :?> HttpWebResponse
let resSt = res.GetResponseStream()
let sr = new StreamReader(resSt)
let html = sr.ReadToEnd()
In F#, when you call a .NET method that accepts only a single argument, you can omit the parentheses in the call. However, .NET methods with no arguments, those with two or more arguments, and constructor calls all require parentheses. Therefore, the F# team suggests always using parentheses when calling .NET methods. Now I display my test case input:
printfn "============================"
printfn "Test case: %s" caseID
printfn "Comment  : %s" comment
printfn "Input    : %s" input
printfn "Expected : %s" expected
And then I examine the HTML response to look for the expected string:
if html.IndexOf(expected) >= 0 then
  printfn "Pass"
  numPass := !numPass + 1
else
  printfn " ** FAIL **"
  numFail := !numFail + 1
I use the String.IndexOf() method, which returns -1 if its string argument is not found, or the index location of the argument if the argument is found. Notice that in F#, if . . then syntax uses an explicit then keyword. Recall that I declared my two counter identifiers using the ref keyword. We've seen that F# uses = to bind an initial value to an identifier, and the <- operator to update a mutable identifier. This code shows that F# uses the := operator to change the value referenced by an identifier. Notice, too, that because I am working with ref objects, I use the ! operator to dereference and get the value associated with the ref object. After each test case has been processed, I pause for a key-press and then delay execution for 1 second:
let _ = Console.ReadLine()
System.Threading.Thread.Sleep(1000)
) // end anonymous function
Here I use the common F# idiom to discard the return value of Console.ReadLine() by assigning the return to the special_identifier. Instead, I could have piped the return to "ignore", as I explained earlier. Notice that because I did not open namespace System.Threading, I must fully qualify my call to the Thread.Sleep() method. After all test case input in the array testCase has been processed by the anonymous function in Seq.iter(), control is transferred to the end of the F# harness and I can print summary results:
printfn "Number pass = %d" !numPass
printfn "Number fail = %d" !numFail
printfn "\nEnd F# test run"
Now my harness is ready to run. Once I make sure the Visual Studio development Web server is running, I can execute my harness from a command shell, as shown in Figure 2.

Wrap Up
The example F# harness I've presented here should give you a solid base to create a test harness that meets your own particular testing situation. In general, the most difficult problem you'll face is determining what data to post to your Web application under test. One good way to do this is to manually exercise your Web application and capture HTTP request data with a sniffer tool to see what information is being sent to the Web server that is hosting the application. There are many such tools available on the Internet as free downloads.
Let me address why you might want to investigate the F# language. After all, learning any new programming language requires a significant investment of time. Learning F# will require some effort, especially if you are new to functional programming. Here are four reasons I decided to learn F#. First, F# has gotten very good informal technical reviews from several of my colleagues whose opinions I respect. Second, it never hurts to add a new technology to your toolset and resume. Third, I believe that learning a new programming language helps you understand other languages better and use them more effectively. Fourth, I'm finding the F# language interesting and just plain enjoyable to learn.
Acknowledgement: My thanks to Tim Ng, a senior development lead on the F# team, who provided much technical advice for this article.

Send your questions and comments for James to testrun@microsoft.com.

Dr. James McCaffrey works for Volt Information Sciences, Inc., where he manages technical training for software engineers working at Microsoft's Redmond, Washington campus. He has worked on several Microsoft products including Internet Explorer and MSN Search. James is the author of .NET Test Automation Recipes (Apress, 2006). James can be reached at jmccaffrey@volt.com or v-jammc@microsoft.com.


Service Station
More On REST
Jon Flanders
Contents
Which is better, REST or SOAP?
What about security? Isn't SOAP more secure than REST?
What about transactions?
What about interoperability? Isn't SOAP supposed to be about interoperability? Isn't SOAP more interoperable than REST?
But what about metadata? So what if REST is so interoperable—there's no WSDL with REST, and without WSDL, I can't generate a client-side proxy to call a service. REST is hard to use.
What if I want to use a transport other than HTTP?
After all that information, aren't you telling me that REST is good for Internet-facing applications, and SOAP for enterprise applications?
Bottom Line
In the last two columns, I've described the basics of REST and talked about exposing and consuming Web feeds. In this column, I'll answer a number of questions that often come up when I make presentations or conduct training sessions on using REST to build service-based applications.

Which is better, REST or SOAP?
This is one of the most common questions I get about REST, and it is probably the least fair. Both REST and SOAP are often termed "Web services," and one is often used in place of the other, but they are totally different approaches. REST is an architectural style for building client-server applications. SOAP is a protocol specification for exchanging data between two endpoints.
Comparing REST with the remote procedure call (RPC) style of building client-server applications would be more accurate. RPC is a style (rather than a protocol, which is what SOAP is) of building client-server applications in which a proxy (generally generated from metadata) is used in the client's address space to communicate with the server and the proxy's interface mimics the server's interface. Although SOAP doesn't require the RPC style, most modern SOAP toolkits are geared toward (at least they default to) using RPC.
In contrast to RPC, REST lacks the metadata-generated proxy (see the next question for more information), which means that the client is less coupled to the service. Also, because REST relies on the semantics of HTTP, requests for data (GET requests) can be cached. RPC systems generally have no such infrastructure (and even when performing RPC using SOAP over HTTP, SOAP responses can't be cached because SOAP uses the HTTP POST verb, which is considered unsafe). SOAP intentionally eschews HTTP, specifically to allow SOAP to work over other protocols, so it's actually a little disingenuous to call SOAP-based services Web services.
My perspective is that both REST and SOAP can be used to implement similar functionality, but in general SOAP should be used when a particular feature of SOAP is needed, and the advantages of REST make it generally the best option otherwise.

What about security? Isn't SOAP more secure than REST?
This question touches one of my pet peeves because the answer is clearly no. It is just as easy to make a RESTful service secure as it is to make a SOAP-based service secure. In the majority of cases involving either REST or SOAP, the security system is the same: some form of HTTP-based authentication plus Secure Sockets Layer (SSL). Although technically the technology for secure conversations over HTTP is now called Transport Layer Security (TLS), SSL is still the name most commonly used.
What is true is that a SOAP-based service, because of the extra protocols specified in the various WS-* specifications, does support end-to-end message security. This means that if you pass SOAP messages from endpoint to endpoint to endpoint, over the same or different protocols, the message is secure. If your application needs this particular feature, SOAP plus WS-* is definitely the way to go. REST probably wouldn't be an option here because of its dependence on HTTP, and inherently you'd be designing a multiprotocol application. I believe that the fact that SOAP with WS-* enables end-to-end message-level security is the source of the misconception that SOAP-based services are more secure than RESTful services.
Another area in which the WS-* folks have spent a lot of time and effort recently is federated security. The simple idea behind federated identity is to create trust between two companies, where authenticated users from one company can be trusted and considered authenticated by another company without the second company having to maintain the authentication information (username and password, typically). The various WS-* specifications have implementations from all the major vendors, and Microsoft is integrating the ideas into Active Directory through Active Directory Federation Services (ADFS).
In the realm of federated security, the WS-* arena certainly has more standards than the RESTful arena (and this will probably always continue to be the case), but there are efforts to support federated security in the world of REST. OpenID is one such effort. The .NET Service Bus (part of Windows Azure) also contains a federated identity service, which works just as well with HTTP (and therefore REST) as it does with SOAP-based services.

What about transactions?
Here is another area in which SOAP and WS-* have explicit support for an "advanced" feature and REST has none. WS-Atomic Transactions supports distributed, two-phase commit transactional semantics over SOAP-based services. REST has no support for distributed transactions.
Generally speaking, if you want something like transactions in a RESTful system, you create a new resource. (Creating a new resource whenever you run into a problem with a RESTful system generally solves most problems.) You can have a resource called Transaction. When your client needs to do something transactional (such as transferring money between two bank accounts), the client creates a Transaction resource that specifies all the correct resources affected (in my example, the two bank accounts) by doing a POST to the Transaction factory URI. The client can then perform updates by sending a PUT to the transaction URI and close the transaction by sending a DELETE to the URI.
This, of course, requires some amount of hand-coding and explicit control over your system, whereas the WS-Atomic Transactions system is more automatic because (in the case of Windows Communication Foundation) it is tied to your runtime's plumbing.
If your system absolutely needs atomic transactional semantics across diverse systems, WS-Atomic Transactions is probably the way to go. Using distributed transactions in this way may or may not be smart because it increases the coupling between the two systems and creates potential problems if you aren't controlling the code on both ends. But the most important thing is to use the right tool for the right job (once you've figure out what the right job is).
In defense of REST, I think it is fair to say that given today's distributed, service-oriented architectures, coupling two endpoints so tightly using a distributed transaction may not be the best design. On the other hand, some situations call for this type of functionality, and if you need it, use SOAP and WS-Atomic Transactions.

What about interoperability? Isn't SOAP supposed to be about interoperability? Isn't SOAP more interoperable than REST?
If you define interoperability as the technical ability to communicate between two divergent endpoints, I assert that REST wins the interoperability battle hands down.
Since one of the driving points behind creating the SOAP specification was to create an interoperable way to communicate between different platforms and different languages, many people are surprised by this assertion. But a funny thing happened on the way to widespread interoperability: the WS-* specifications (and vendors' implementations of said specifications) made SOAP services less interoperable rather than more interoperable.
The problem in the SOAP and WS-* arena is the large number of different standards (and versions of each of those standards) to choose from. And when a particular vendor chooses to implement a particular standard, that vendor often provides an implementation that is just slightly different from another vendor's (or all others). This leads to problems whenever you have to cross vendor boundaries (languages and operating system).
Of course, even to use SOAP you need a SOAP toolkit on your platform, which most (but not all) platforms have today. And then you have to deal with myriad WS-* specifications and figure out which to use (or not to use) and how that affects interoperability. To be honest, it's kind of a mess out there.
In terms of platforms, REST has the advantage because all you need to use REST is an HTTP stack (either on the client or the server). Since almost every platform and device has that today, I would argue that REST has the widest interoperability. Given that mobile devices, household devices, POS devices, DVD players, and TVs all have Internet connectivity, there are more and more platforms for which having a full SOAP toolkit is impossible or unlikely. And even if you do have a SOAP toolkit for a particular platform, the chance of it working with another platform's implementation is not 100%.

But what about metadata? So what if REST is so interoperable—there's no WSDL with REST, and without WSDL, I can't generate a client-side proxy to call a service. REST is hard to use.
It's true that in the world of REST, there is no direct support for generating a client from server-side-generated metadata, as there is in the world of SOAP with Web Service Description Language (WSDL). A couple of efforts are being made to get such support into REST, one being a parallel specification, known as WADL (Web Application Description Language). The other is a push to use WSDL 2.0 to describe RESTful endpoints. I often say that REST is simple, but simple doesn't always mean easy. SOAP is easy (because of WSDL), but easy doesn't always mean simple.
Yes, using WSDL makes generating a proxy for a SOAP-based service easier than writing the code to call a RESTful service. But once you generate that proxy, you still have to learn the API. Nothing in the WSDL tells you which method to call first or second or whether you need to call the methods in any particular order at all. These are all things you need to figure out after you generate the proxy and are prototyping the code to use the service.
Building a client against a RESTful service means you are learning the service and how it works as you build the client. Once you have finished, you have a complete understanding of the service, its resources, and the interaction you can have with those resources. To me, this is a big benefit. Since RESTful services follow the constraints of REST (at least they are supposed to), there is a convention that you can easily follow as you determine the different parts of the service.
Also, out in the wilds of developer-land, most services are wrapped in something often called a "service agent," which is another layer of indirection to protect clients from changes in the service layer. This may be needed in either REST or SOAP.
Another point is that metadata-generated proxies are part of what SOAP was meant to get away from in the RPC era, namely local-remote transparency. The concept of having an API on the client that matches the API on the server was considered to be a bad idea, but that's exactly what happens in most SOAP-based services. Having a metadata-generated proxy in REST also reduces the chances of taking advantage of hyperlinking. Using hypertext as the engine of application state (HATEOAS) is one of the constraints of REST, and using it requires a more loosely coupled client API.
The last point I'll make is that as support for REST becomes more ubiquitous, building clients will get easier and easier. If you look at the Windows Communication Foundation (WCF) REST starter kit, it includes facilities that head in this direction. The new HttpClient API makes using HTTP much easier than using the .NET WebRequest/WebResponse API. Also, there is a new Paste as XML Serializable tool, which allows you to copy a piece of XML (say from the documentation of a RESTful endpoint) and generate a .NET type that can represent that XML instance in your application. This is similar to what the WCF tools do automatically for the whole service with WSDL. Over time, these tools will become much more sophisticated, further simplifying the client experience in WCF when using RESTful services.

What if I want to use a transport other than HTTP?
The common (somewhat sarcastic) answer from the REST community here is, "Go ahead, there isn't anything stopping you." Realistically, however, REST is currently tied to HTTP, if only because most developers and teams of developers do not have the time for the engineering effort necessary to get the semantics of REST to work over, say, TCP/IP.
The common answer is technically correct, because nothing is stopping you from implementing the concepts of REST over other protocols, but until vendors add support for this, I find it a dubious proposition for most.

After all that information, aren't you telling me that REST is good for Internet-facing applications, and SOAP for enterprise applications?
If you've read the rest of this column, you can probably imagine that I think this statement is generalized and false. Often I hear this sentiment after discussing the lack of explicit distributed transaction support in REST versus the explicit support in WS-Atomic Transactions. My retort is generally something like "Well, ASP.NET doesn't have support for distributed transactions, but does that mean ASP.NET isn't useful for enterprises?"
My point is that not every technology solves every problem, and there are plenty of technologies that don't support the typical features people think of when they think of enterprises but that are incredibly helpful for enterprises nonetheless.
In fact, when I think of enterprise applications, I often think of speed and scalability—scalability being one of the main differences between REST and SOAP. SOAP services are much harder to scale than RESTful services, which is, of course, one of the reasons that REST is often chosen as the architecture for services that are exposed via the Internet (like Facebook, MySpace, Twitter, and so on).
Inside enterprises, applications also often need to scale as well. Using REST means that you can take advantage of HTTP caching and other features, like Conditional GET, that aid in scaling services. Many of these techniques can't be used with SOAP because SOAP uses POST only over HTTP.

Bottom Line
I hope that after you read this column, you'll think that the answer to "Which is better, REST or SOAP?" is "It depends." Both the REST architectural style and SOAP and the WS-* protocols have advantages and disadvantages when it comes to building services. Those of us in the RESTafarian camp (yes, I must give full disclosure here: I am definitely in that camp) believe that for most service situations, REST provides more benefits than SOAP or WS-*. On the other hand, SOAP and WS-* have some features that are easy (and possible) to implement using REST. When you need those specific features, you definitely want to use runtimes and toolkits that can provide those features. Although this column wasn't specifically about WCF, one nice feature of adopting WCF is that it supports both REST and SOAP/WS-*. Moving back and forth between the two worlds becomes easier if you have one programming and runtime model to learn.

Send your questions and comments to sstation@microsoft.com.

Jon Flanders is an independent consultant, speaker, and trainer for Pluralsight. He specializes in BizTalk Server, Windows Workflow Foundation, and Windows Communication Foundation. You can contact Jon at masteringbiztalk.com/blogs/jon.


Extreme ASP.NET
Guiding Principles For Your ASP.NET MVC Applications
Scott Allen
Contents
Simplicity Through Separation
Trouble-Free Controllers
Controllers and Security
Plain Views
HTML Helpers
Strong Typing
Unobtrusive JavaScript
Partial Views
Views and Security
Big Models
Unit Tests
Although the release of Microsoft ASP.NET MVC 1.0 is relatively recent, many of the patterns and principles surrounding the framework have been around for a long time. The Model View Controller (MVC) pattern itself was passed down by Smalltalk developers from the 1970s, and is in use in a variety of frameworks and across a wide range of languages and diverse platforms. Thus, we can learn a lot about how to make the best use of the framework just by looking around our software ecosystem.
In this article, I want to lay out some principles you should follow when working with the ASP.NET MVC framework. These principles are not rules, but ideals and values you should cherish and keep in the forefront of your mind when building ASP.NET MVC applications that need to survive and evolve beyond a single release.

Simplicity Through Separation
When I was a young boy, I used to love jigsaw puzzles. It was a marvelous feeling to build simple scenes, like the picture of an apple, from a collection of complex and irregularly shaped puzzle pieces. This love of complexity is a virus I fight on a daily basis as a software developer.
As developers, we want to work in the opposite direction of the jigsaw puzzle. Instead of making the simple things complex, we should strive to make complex things simple. Many of the technologies around us are in place to help us move toward simplicity; we just have to make effective use of the technologies.
Let's take CSS and HTML as examples, because these are two technologies that every Web developer should be familiar with. If I want to draw a user's attention to required questions they failed to answer on my Web pages, then I might change the background color of the failed questions to red. I could do this by specifying the color red as a style on each failed question, or I could create a CSS rule specifying the color red and point any failed question elements to this style rule.
Although the CSS solution might require a little more work–because I write both CSS and HTML instead of just HTML–in the end it will prove itself a simpler solution. Using a CSS rule removes duplicate style information from my application, and I can easily change the color of all failed questions by modifying a single style rule. The CSS approach also allows me to create a rule whose name reveals its intended usage, e.g., failedValidation is a piece of code that gives me more information than reading #FF0000. These qualities of the CSS approach make the application easier to maintain and change, which is the simplicity we are striving to achieve.
Using CSS in combination with HTML exhibits another characteristic of simplicity, which is how CSS and HTML can have separate and distinct responsibilities. HTML becomes responsible for only the structure of a Web page, and CSS becomes responsible for the look of a Web page. This separation of responsibilities, or "separation of concerns," is an immensely powerful weapon in the battle against software complexity. Have you ever gone in to modify an object that represents a Web page only to find it is responsible for data access, data binding, business rule validation and coloring the background of a failed input field red? Was it easy to modify the object? Was it easy to focus on the one change request you had to implement inside this complex puzzle of logic?
The MVC design pattern has proved itself successful over time in part because the pattern forces a separation of responsibilities. This allows us to focus on specific tasks, hide our implementation details and make changes that don't interfere with other components. In MVC, for example, the view component is only responsible for presenting data. When inside the view, we can focus on presentation and not worry about where data originates. We can make changes to the view without worrying about data access code.
With the goal of simplicity through separation in mind, let's look at specific guidance on each of the three components in the model-view-controller pattern.

Trouble-Free Controllers
In an MVC pattern, controllers are in the middle of the action. Controllers handle incoming requests, interact with the model and select views for rendering. Because of their position, controllers can be difficult to implement while maintaining a separation of concerns. You have to remain diligent and not let your controllers become the centerpieces of your application logic.
As an example, I want to call out a contrast in two different versions of Oxite. Oxite is an open source content management system and blog engine built with the ASP.NET MVC framework and hosted on CodePlex at codeplex.com/oxite/. In an early version of Oxite (circa December 2008), the controller action responsible for saving a blog post was 103 lines of C# code. The action was responsible for validating the post, managing the relationship between a post and its tags, managing the relationship between a post and its parent, deciding if a post is new or an edited version of an existing post and saving the post to a repository. Contrast your mental image of this code with the current version, as shown in Figure 1.
Figure 1 Controller Action
[ActionName("ItemEdit"), AcceptVerbs(HttpVerbs.Post)]
public virtual object SaveEdit(PostAddress postAddress, Post postInput)
{
    Post post = postService.GetPost(postAddress);

    ValidationStateDictionary validationState;

    postService.EditPost(post, postInput, out validationState);

    if (!validationState.IsValid)
    {
        ModelState.AddModelErrors(validationState);
        return Edit(postAddress);
    }

    return Redirect(Url.Post(postInput));
}
It is obvious that the Oxite team has spent some time refactoring this controller action. All of the validation logic and relationship management hides behind an IPostService object, leaving the controller free to focus on its role as a mediator in the request. A good rule of thumb for a controller action is that once an action method exceeds 10 to 15 lines of code, you should consider refactoring to produce a simpler action method. You'll often find that the extra lines of code in the action represent business logic that would lead a happier life inside your business objects.

Controllers and Security
While our primary focus is on simplicity, I'd be amiss if I didn't introduce some important security-related principles for controllers. First, the controller must play a role in avoiding a Cross-site Request Forgery (CSRF). Phil Haack, program manager of the ASP.NET team, recently blogged on this topic in his article "Anatomy of a Cross-site Request Forgery Attack." He detailed how the controller and view can work together to avoid an attack. To summarize Phil's post: Whenever you have actions that authenticated users can invoke, then you should have the view render an antiforgery token to the client, and have the controller action validate this token by applying the ValidateAntiForgeryToken attribute. This solution is simple to implement, but you have to remember to put these safeguards in place.
Second, controllers should make use of the AcceptVerbs attribute to restrict certain actions to the operations of HTTP POST. A controller action that modifies data, like ultimately deleting an Order from the Orders table, should allow itself to execute only during an HTTP POST operation and never during an HTTP GET operation. With an HTTP GET operation, the parameters required for the action live in the URL. This means that a malicious user could send you an e-mail with an image, and point the source of the image to a URL that can delete records. You don't need to push any buttons. You only have to view the image to delete a record. Stephen Walther includes some more details on this scenario in his blog post, "Don't use Delete Links because they create Security Holes."

Plain Views
Views have a clear role when using the MVC design pattern on the Web. They present the model to the user. However, what does "present" mean in this context? Presentation could involve HTML, JavaScript, CSS, JSON, XML, and a heavy dose of server-side code. Views run the risk of becoming complicated with the many modes of presentation. Your job is to keep the views as simple as possible–not only because the view will be easier to maintain, but also because it is the hardest component to test. One of the biggest complexity risks in a view is to turn it into "tag soup."
"Tag soup" is a programmer's term for HTML that is difficult for the programmer to read and maintain, and possibly even difficult for the Web browser to parse. You look at the source code and it looks like soup–the chef stirred all the ingredients together into an illegible sea of broth.
Avoiding tag soup can be as easy as making sure the HTML in a Web form view is both well formed and well formatted. Both of these steps are easy to achieve in Microsoft Visual Studio, which highlights malformed HTML and gives you the option to format HTML (Ctrl K + Ctrl +D is the shortcut to format an entire document). However, there are additional challenges in Web form views, as demonstrated in the code below.
<% if ((bool)ViewData["isLoggedIn"])
   { %>
    <img src="<%= ViewData["loggedInImage"] %>" />
<% }
   else
   {%>
    <img src="<%= ViewData["anonymousImage"] %>"
      onclick="login();" />
<% }%>
This code is an ugly amalgamation of HTML, C#, JavaScript and string literals. There are, however, a few guidelines we can follow to avoid such code.

HTML Helpers
HTML helpers are extension methods that you can use inside a view to encapsulate the creation of HTML and hide some simple presentation logic. In the above code, we have an IF condition that complicates the view. We also have image tags that are complicated by including server-side code inside the attributes. Rob Conery of Microsoft lives by a rule that he explains in his post, "ASP.NET MVC: Avoiding Tag Soup." His rule is, "If there's an IF, make a Helper." He then goes on to show the implementation of an HTML helper to build for a pager that displays links to navigate a paged list of items.
HTML helpers can also help you avoid the ugly intermixing of server-side code and HTML. Fortunately, the MVC framework includes a number of helpers. You can find more of them in the MVC Futures project and in the MVC Contrib project. Make sure to download both to look at the helpers available in these libraries. Some of them are specifically designed to work with strongly typed models, which is our next topic.

Strong Typing
You can put views into one of two categories: those that use the ViewData dictionary and those that use strong typing. Views that use the ViewData dictionary derive from System.Web.Mvc.ViewPage. Our tag soup example uses this approach. Strongly typed view pages derive from System.Web.Mvc.ViewPage<T>, where T is a generic parameter to specify the type of the model. I recommend you use strong typing.
Strong typing means your view knows exactly the type of model you expect it to work with. You don't have to guess at the magic string required to pull a particular piece of information from the ViewData dictionary. Instead, you can just use code like Model.Username and have IntelliSense aid you in the quest for data. In addition, by running the aspnet_compiler, you can catch any errors that you might have made when accessing the model. When you add a new view to an MVC project, the add view wizard makes it easy to select a strongly typed model, so you shouldn't have problems in the setup. In general, you'll find that removing magic string literals and relying on strongly typed views will help you maintain your software in the long run.

Unobtrusive JavaScript
We know that CSS and HTML can work together to separate the structure of a view from the visual presentation of the view in the browser. I strongly encourage you to use CSS as a tool to maintain this separation. However, modern Web pages have three primary concerns: structure, presentation and behavior. JavaScript implements this behavior. Including JavaScript in your view can be just as disruptive as including excessive amounts of style information and server-side code. Pages rich with JavaScript behavior demand a separation of structure from behavior so you can focus on the pieces independently.
Unobtrusive JavaScript is the practice of removing all signs of JavaScript from a view and placing any JavaScript you need into an external .js file. Unobtrusive JavaScript means you do not have any JavaScript functions defined in the view, and you do not have any on-click attributes, including JavaScript code in your HTML. Libraries like jQuery and Microsoft's ASP.NET AJAX libraries make it easy to reach into a page and wire up your events from the outside. All you need to do is add a <link> tag in your view to include the external .js file with your view behaviors.
As an example, the following jQuery code will run after the view renders on the client to wire up the click event of an element with an ID of "loginImage" to a JavaScript function by the name of "login." No on-click attribute required!
$(function() {
    $("#loginImage").click(login);
}

Partial Views
Another technique you can use to manage the complexity of views is partial views. Partial views in the Web forms view engine are user control files with a .ascx extension. Just like in ASP.NET Web forms, we can use partial views to encapsulate HTML and code that we might want to reuse across multiple views (like a login display). We can also use partials to break down a complicated view into smaller pieces.
We can strongly type partial views by deriving from System.Web.Mvc.ViewUserControl<T>. The add new view wizard in an MVC application allows you to select a checkbox to choose between a view and a partial view, and also allows you to select the strongly typed model (see Figure 2). There is also an HTML helper available (RenderPartial) in the framework to make the job of using a partial view easy:
<% Html.RenderPartial("_LoginStatus"); %>
Views and Logic
Figure 2 Add View Wizard
To paraphrase Albert Einstein, views should be as simple as possible, but not simpler. Views that contain any business logic or data access logic violate the spirit of the MVC design pattern and the principle of least surprise. No one familiar with the MVC pattern will expect to find business logic lurking inside a view.
Although the Web forms view engine allows you to create an associated code-behind file for a view, doing so will reduce any benefits you might have otherwise obtained by using MVC. Code-behind can only encourage the practice of putting more logic into a view and, even worse, can introduce the traditional ASP.NET page life-cycle events to a view. Page life-cycle events are one feature of ASP.NET that the MVC framework tries very hard to hide.

Views and Security
One word on security for views: Make sure you protect your application from cross-site scripting attacks (XSS) by HTML encoding output in a view. XSS attacks are enormously popular these days because they are relatively easy to execute. Although not all output technically needs encoding, I suggest you err on the side of safety and encode everything by default. Fortunately, there is already an HTML helper available for HTML encoding:
<%= Html.Encode(Model.Message) %>
In addition, ASP.NET will validate incoming requests by default. This request validation feature will look for requests containing un-encoded HTML input. If ASP.NET finds such a request, it will throw an exception before the request reaches a controller. In some cases, you may find you need to turn this feature off so you can accept HTML from the user. You can turn it off on a controller action by using the ValidateRequest attribute, but be careful with the input that arrives. The people behind XSS attacks have become exceptionally clever at hiding malicious input inside of requests.

Big Models
At last we've reached a place where we aren't building simple pieces of software, right? Doesn't the model represent our business logic with rich behaviors and complex rules?
It depends.
Technically, the model that the controller hands over to a view doesn't need any behavior or rules, because the view shouldn't be using any of these rules or behaviors in the model, if they exist. The view only wants to pick out data from the model to present to the user. Thus, even though you can use your business objects as the models for your views, many developers follow the guidance of creating view-specific models. We also call these types of models ViewModels.
ViewModels are simple data transfer objects–they contain all state but no behavior of any significance. In other words, you'll implement lots of properties on your ViewModels but no methods. ViewModels have the pleasant effect of giving a view exactly the data that it needs to present–no more and no less. While you optimize the design of your business objects for your business logic, you optimize the design of your ViewModels for your views.
Even when you do want to consume business objects from your view, many times you will struggle to introduce functionality that your business layer doesn't require. For example, suppose you need to list the patients in a hospital and include some aggregate calculations on their length of stay, such as minimums, maximums, averages and standard deviations. If your business logic never makes use of this information, you'll find it only clutters your logic with complexity. Remember, our goal is simplicity through separation.
ViewModels are the ideal abstraction to separate and isolate the model that your view requires from the model that your business requires. ViewModels introduce some additional work into your project, because you'll need to define additional classes to represent the ViewModels and map information into the ViewModel properties. However, this additional work can reap tremendous benefits because you are free to change your business logic without breaking the presentation layer, and vice versa. Also, you don't necessarily need a ViewModel class for each view. It's quite common to share a ViewModel class among related views.

Unit Tests
In this article, we've stressed simplicity. The MVC design pattern can guide us toward simplicity, but we still need to follow some principles. We also need to keep an eye out for places where complexity is creeping into our software. A good technique to discover complexity is to write unit tests. Unit tests not only help you maintain the quality of your software, but can also help you spot problems in a design (see Jeremy Miller's article on designing for testability "Design For Testability").
Perhaps you've been reading this article as a longtime Web forms programmer who never felt comfortable writing unit tests. It's possible you found unit tests too difficult to implement in the ASP.NET Web forms environment. This is your chance to start! The ASP.NET MVC team designed the framework with testability in mind. Start simple and let your unit testing experience grow. Eventually, you should find that unit tests are yet another weapon in the battle against the ever-growing complexity of software.

Send your questions and comments to xtrmasp@microsoft.com.

K. Scott Allen is a member of the Pluralsight technical staff and founder of OdeToCode. You can reach Scott at scott@OdeToCode.com or read his blog at odetocode.com/blogs/scott.


Wicked Code
Taking Silverlight Deep Zoom To The Next Level
Jeff Prosise
Contents
Fixing Composer's Panning Logic
Accessing Sub-Images and Metadata
Dynamic Deep Zoom: Supplying Image Pixels at Run Time
DeepZoomTools.dll
After Silverlight Deep Zoom was introduced to the world at MIX 2008, the buzz surrounding it persisted for weeks. An outgrowth of the Seadragon project at Microsoft Live Labs, Deep Zoom is a Silverlight adaptation of a technology for presenting vast amounts of pictorial data to users in a highly bandwidth-efficient manner. Sister adaptations that target Windows Mobile and AJAX are available and serve to increase the reach of the platform.
If you haven't seen Deep Zoom before, drop what you're doing and visit the canonical Deep Zoom site at memorabilia.hardrock.com. Use the mouse to pan around in the scene and the mouse wheel to zoom in and out. Thanks to Deep Zoom, you don't have to download gigabytes (or terabytes) of imagery to browse the Hard Rock Café's vast memorabilia collection. Deep Zoom downloads only the pixels it needs at the resolution it needs, and in Silverlight, the complexity of Deep Zoom is masked behind a remarkable control named MultiScaleImage. Once a Deep Zoom scene is composed (typically with Deep Zoom Composer, which you can download for free from go.microsoft.com/fwlink/?LinkId=148861), presenting the scene in a browser requires little more than declaring a MultiScaleImage control and pointing the control's Source property to Deep Zoom Composer's output. Supporting interactive panning and zooming requires a little mouse-handling code that interacts with the control, but these days Deep Zoom Composer will even provide that for you.
Despite the ease with which a basic Deep Zoom application can be built, you're missing out on the true richness of Deep Zoom if you go no further than Deep Zoom Composer takes you. Did you know, for example, that you can programmatically manipulate the images in a Deep Zoom scene, that you can create metadata and associate it with each image, or that Deep Zoom images can come from a database or be composed on the fly? Some of the truly remarkable Deep Zoom applications out there rely on a little-known feature of Deep Zoom that adds a whole new dimension to the platform.
If you care to take Silverlight Deep Zoom to the next level, here are three ways to do just that.

Fixing Composer's Panning Logic
First things first: if you want to get more out of Deep Zoom, the first thing you should know is not to trust the mouse-handling code emitted by Deep Zoom Composer. The code that pans around the scene in response to MouseMove events "loses" the mouse if you pan too quickly. Try it. Take any Deep Zoom app created by Deep Zoom Composer and position the mouse cursor over an identifiable point or pixel in the scene. Then move the mouse quickly back and forth and up and down a few times. Observe that when you stop and the scene springs back to the cursor position, the cursor is no longer located at the point it was when you started. The more and faster you move, the greater the difference. It's not a deal breaker, but try the same experiment on the Hard Rock Memorabilia site and you'll find that the scene reliably snaps back to the original cursor position no matter how hard you try to fool it.
Figure 1 shows how to modify Deep Zoom Composer's code to fix the problem. First, declare two new fields named lastViewportOrigin and lastMousePosition in the Page class in Page.xaml.cs. (While you're at it, delete the fields named dragOffset and currentPosition, because they're not needed.) Then rewrite the MouseLeftButtonDown and MouseMove handlers as shown. You'll find that the scene snaps back to precisely the original cursor position when you stop moving the mouse, and if you're as fastidious as I am about these things, you'll be able to sleep at night once more.
Figure 1 Fixing Deep Zoom Composer's Panning Code
Point lastViewportOrigin;
Point lastMousePosition;
  ...
this.MouseLeftButtonDown += delegate(object sender, MouseButtonEventArgs e)
{
    mouseButtonPressed = true;
    mouseIsDragging = false;
    lastViewportOrigin = msi.ViewportOrigin;
    lastMousePosition = e.GetPosition(msi);
};

this.MouseMove += delegate(object sender, MouseEventArgs e)
{
    if (mouseIsDragging)
    {
        Point pos = e.GetPosition(msi);
        Point origin = lastViewportOrigin;
        origin.X += (lastMousePosition.X - pos.X) /
            msi.ActualWidth * msi.ViewportWidth;
        origin.Y += (lastMousePosition.Y - pos.Y) /
            msi.ActualWidth * msi.ViewportWidth;
        msi.ViewportOrigin = lastViewportOrigin = origin;
        lastMousePosition = pos;
    }
};

Accessing Sub-Images and Metadata
You may have noticed that when you export a project from Deep Zoom Composer, you're offered the choice of exporting as a composition or as a collection The latter option comes with one very desirable benefit: rather than exporting a Deep Zoom scene containing all the images you added lumped together into one monolithic image, it exports a scene containing individually addressable sub-images. The sub-images are exposed through the MultiScaleImage control's SubImages property, and because they are individually addressable objects, the sub-images can be manipulated, animated, and fumigated (just kidding!) to add sparkle and interactivity to Deep Zoom applications.
Each item in the SubImages collection is an instance of MultiScaleSubImage, which derives from DependencyObject and includes the properties AspectRatio, Opacity, ZIndex, ViewportOrigin, and ViewportWidth. The latter two combine to determine a sub-image's size and position in a Deep Zoom scene. Be aware that when a MultiScaleImage control first loads, its SubImages property is empty. Your first opportunity to iterate over the sub-images is when the control fires its ImageOpenSucceeded event.
One use for the SubImages property is to hit-test individual images in order to display metadata—titles, descriptions, and so forth—in response to clicks or mouseovers. Another use for it is to programmatically rearrange the images in a Deep Zoom scene. The DeepZoomTravelDemo application shown in Figure 2 demonstrates how to do both. When you position the mouse over one of the images in the scene, a partially transparent information panel appears on the right containing an image title and description. And when you click the Shuffle button in the upper left corner, the images rearrange themselves in random order.
Figure 2 DeepZoomTravelDemo
The nine images featured in DeepZoomTravelDemo are photos I snapped on some of my overseas trips. I imported them into Deep Zoom Composer, arranged them in a grid, and exported the scene (making sure to select "Export as Collection"). Then I imported the output from Deep Zoom Composer into a Silverlight project and added zooming and panning logic similar to that in the preceding section. To keep the download size manageable (13MB versus 170MB), I deleted the bottom two layers of the image pyramid that Composer generated before I uploaded the app to the MSDN Code Gallery. The version that you download works just fine, but when you zoom, the images get grainy a lot quicker than they do in the original version.
Displaying image metadata as DeepZoomTravelDemo does presents two challenges to the developer. First, where do you store the metadata, and how do you associate it with images in the scene? Second, how do you correlate the items in the MultiScaleImage control's SubImages collection with images in the scene since the MultiScaleSubImage class provides no information relating the two?
The first task—storing the metadata—is accomplished by entering a text string into the Tag box displayed in the lower right corner of Deep Zoom Composer when an image is selected. I used it to store each image's title and description, separated by plus signs. Composer writes the tags to the Metadata.xml file created when you export the project. Each image in the scene is represented by an <Image> element in Metadata.xml, and each <Image> element contains a sub-element named <Tag> that contains the corresponding tag. Figure 3 shows the <Image> element written into Metadata.xml for the image in the upper left corner of the scene. Composer's tag editing interface is somewhat clumsy since the Tag box is so small, but you can always edit the Metadata.xml file manually as I did to tag each image with a title and description.
Figure 3 An <Image> Element in Metadata.xml
<Image>
  <FileName>
    C:\Users\Jeff\Documents\Expression\Deep Zoom Composer
    Projects\DeepZoomTravelDemo\source images\great wall of china.jpg
  </FileName>
  <x>0</x>
  <y>0</y>
  <Width>0.316957210776545</Width>
  <Height>0.313807531380753</Height>
  <ZOrder>1</ZOrder>
  <Tag>
    Great Wall of China+The Great Wall of China near Badaling, about an hour
    north of Beijing. This portion of the Great Wall has been restored and
    offers outstanding views of the surrounding mountains.
  </Tag>
</Image>
It would be great if the MultiScaleSubImage class had a Tag property that was automatically initialized with the content of the <Tag> element; but it doesn't, so you have to improvise. First, you can write a bit of code that downloads Metadata.xml and parses the tags from it. Second, you can use the <ZOrder> elements in Metadata.xml to correlate <Image> elements with images in the Deep Zoom scene. If the scene contains nine images (and the MultiScaleImage control's SubImages collection therefore contains nine MultiScaleSubImage objects), SubImages[0] corresponds to the image whose <ZOrder> is 1, SubImages[1] corresponds to the image whose <ZOrder> is 2, and so on.
DeepZoomTravelDemo uses this correlation to store image titles and descriptions. At startup, the Page constructor uses a WebClient object to initiate an asynchronous download of Metadata.xml from the server's ClientBin folder (see Figure 4). When the download is complete, the WebClient_OpenReadCompleted method parses the downloaded XML with an XmlReader and initializes the field named _Metadata with an array of SubImageInfo objects containing information about the images in the scene, including titles and descriptions. The class is shown here:
public class SubImageInfo
{
    public string Caption { get; set; }
    public string Description { get; set; }
    public int Index { get; set; }
}
Figure 4 Downloading Metadata.xml and Correlating Metadata with Sub-Images
private SubImageInfo[] _Metadata;
  ...
public Page()
{
    InitializeComponent();

    // Register mousewheel event handler
    HtmlPage.Window.AttachEvent("DOMMouseScroll ", OnMouseWheelTurned);
    HtmlPage.Window.AttachEvent( "onmousewheel ", OnMouseWheelTurned);
    HtmlPage.Document.AttachEvent( "onmousewheel ", OnMouseWheelTurned);

    // Fetch Metadata.xml from the server
    WebClient wc = new WebClient();
    wc.OpenReadCompleted += new
        OpenReadCompletedEventHandler(WebClient_OpenReadCompleted);
    wc.OpenReadAsync(new Uri( "Metadata.xml ", UriKind.Relative));
}

private void WebClient_OpenReadCompleted(object sender,
    OpenReadCompletedEventArgs e)
{
    if (e.Error != null)
    {
        MessageBox.Show( "Unable to load XML metadata ");
        return;
    }

    // Create a collection of SubImageInfo objects from Metadata.xml
    List<SubImageInfo> images = new List<SubImageInfo>();

    try
    {
        XmlReader reader = XmlReader.Create(e.Result);
        SubImageInfo info = null;

        while (reader.Read())
        {
            if (reader.NodeType == XmlNodeType.Element &&
                reader.Name ==  "Image ")
                info = new SubImageInfo();
            else if (reader.NodeType == XmlNodeType.Element &&
                reader.Name ==  "ZOrder ")
                info.Index = reader.ReadElementContentAsInt();
            else if (reader.NodeType == XmlNodeType.Element &&
                reader.Name ==  "Tag ")
            {
                string[] substrings =
                    reader.ReadElementContentAsString().Split('+');
                info.Caption = substrings[0];
                if (substrings.Length > 1)
                    info.Description = substrings[1];
                else
                    info.Description = String.Empty;
            }
            else if (reader.NodeType == XmlNodeType.EndElement &&
                reader.Name ==  "Image ")
                images.Add(info);
        }
    }
    catch (XmlException)
    {
        MessageBox.Show( "Error parsing XML metadata ");
    }

    // Populate the _Metadata array with ordered data
    _Metadata = new SubImageInfo[images.Count];

    foreach (SubImageInfo image in images)
        _Metadata[image.Index - 1] = image;
}
The <ZOrder> values read from Metadata.xml are used to order the SubImageInfo objects in the _Metadata array, ensuring that the order of the items in the _Metadata array is identical to the order of the items in MultiScaleImage's SubImages collection. In other words, _Metadata[0] contains the title and description for SubImages[0], _Metadata[1] contains the title and description for SubImages[1], and so on. Incidentally, I used XmlReader rather than LINQ to XML to avoid increasing the size of the XAP file by introducing an extra assembly required by LINQ to XML (System.Xml.Linq.dll).
Now that _Metadata is initialized with SubImageInfo objects containing titles and descriptions, the next step is to write the code to display the titles and descriptions. That happens in Figure 5. The MouseMove handler that pans the Deep Zoom scene if the left mouse button is down behaves differently if the left mouse button is up: it hit-tests the scene to determine whether the cursor is currently over one of the sub-images. Hit testing is performed by the helper method named GetSubImageIndex, which returns -1 if the cursor isn't over a sub-image or a 0-based image index if it is. That index identifies both a sub-image in MutliScaleImage.SubImages and a SubImageInfo object in _Metadata. A few lines of code copies the title and description from the SubImageInfo object to a pair of TextBlocks and one more line of code triggers an animation that displays the information panel if it's not already displayed. Note that GetSubImageIndex checks the sub-images for hits in reverse order since the final sub-image in the MultiScaleimage control's SubImages collection is highest in the Z-order, the next-to-last sub-image is second highest in the Z-order, and so on.
Figure 5 Hit-Testing the Sub-Images
private int _LastIndex = -1;
  ...
private void MSI_MouseMove(object sender, MouseEventArgs e)
{
    if (_Dragging)
    {
        // If the left mouse button is down, pan the Deep Zoom scene
          ...
    }
    else
    {
        // If the left mouse button isn't down, update the infobar
        if (_Metadata != null)
        {
            int index = GetSubImageIndex(e.GetPosition(MSI));

            if (index != _LastIndex)
            {
                _LastIndex = index;

                if (index != -1)
                {
                    Caption.Text = _Metadata[index].Caption;
                    Description.Text = _Metadata[index].Description;
                    FadeIn.Begin();
                }
                else
                {
                    FadeOut.Begin();
                }
            }
        }
    }
}

private int GetSubImageIndex(Point point)
{
    // Hit-test each sub-image in the MultiScaleImage control to determine
    // whether  "point " lies within a sub-image
    for (int i = MSI.SubImages.Count - 1; i >= 0; i--)
    {
        MultiScaleSubImage image = MSI.SubImages[i];
        double width = MSI.ActualWidth /
            (MSI.ViewportWidth * image.ViewportWidth);
        double height = MSI.ActualWidth /
            (MSI.ViewportWidth * image.ViewportWidth * image.AspectRatio);

        Point pos = MSI.LogicalToElementPoint(new Point(
            -image.ViewportOrigin.X / image.ViewportWidth,
            -image.ViewportOrigin.Y / image.ViewportWidth)
        );
        Rect rect = new Rect(pos.X, pos.Y, width, height);

        if (rect.Contains(point))
        {
            // Return the image index
            return i;
        }
    }

    // No corresponding sub-image
    return -1;
}
In addition to supporting mouseovers, DeepZoomTravelDemo lets you rearrange the images in the scene. If you haven't already, try clicking the Shuffle button in the upper left corner of the scene. (In fact, click it several times; the images will assume a different order each time.) The rearranging is performed by the Shuffle method in Figure 6, which creates an array containing all the images' ViewportOrigins, reorders the array using a random-number generator, and then creates a Storyboard and a series of PointAnimations to move the sub-images to the positions contained in the reordered array. The key here is that the MultiScaleimage control's SubImages property exposes the sub-images to your code, and you can modify a sub-image's ViewportOrigin property to change its position in the scene.
Figure 6 Shuffling the Sub-Images
private void Shuffle()
{
    // Create a randomly ordered list of sub-image viewport origins
    List<Point> origins = new List<Point>();

    foreach (MultiScaleSubImage image in MSI.SubImages)
        origins.Add(image.ViewportOrigin);

    Random rand = new Random();
    int count = origins.Count;

    for (int i = 0; i < count; i++)
    {
        Point origin = origins[i];
        origins.RemoveAt(i);
        origins.Insert(rand.Next(count), origin);
    }

    // Create a Storyboard and animations for shuffling
    Storyboard sb = new Storyboard();

    for (int i = 0; i < count; i++)
    {
        PointAnimation animation = new PointAnimation();
        animation.Duration = TimeSpan.FromMilliseconds(250);
        animation.To = origins[i];
        Storyboard.SetTarget(animation, MSI.SubImages[i]);
        Storyboard.SetTargetProperty(animation,
            new PropertyPath( "ViewportOrigin "));
        sb.Children.Add(animation);
    }

    // Run the animations
    sb.Begin();
}
As I researched this column, I found several blog entries that provided helpful information. One was Jaime Rodriquez's "Working with Collections in Deep Zoom." Another was "Deep Zoom Composer—Filtering by Tag Sample", which was written by a member of the Expression Blend team and presents a technique for filtering Deep Zoom images based on image tags. Implementing mouseovers, rearranging the images in a scene, and filtering images based on tag data are but a few of the features made possible by the ability to address the individual sub-images in a Deep Zoom scene and associate metadata with them.
Making Dynamic Deep Zoom Even Better
I have been fascinated by fractals ever since I discovered them some 20 years ago. I wrote my first Mandelbrot viewer in the early 1990s, if memory serves me correctly. My bookshelf of oldie-but-goodie computer books still contains a pristine copy of a book titled Fractal Image Compression by Barnsley and Hurd that I used in a research project on data compression in the mid-90s. And one of my favorite books of all time is Chaos by James Gleick (Penguin, 2008).
Building an interactive and visually compelling Mandelbrot viewer for browsers is something I've wanted to do since the first day I laid eyes on Silverlight. Dynamic Deep Zoom made it possible. The downside, of course, is that the images are generated on the server and downloaded to the client, leading to unwanted latency and also increasing the load on the server.
Silverlight 2 doesn't include an API for generating bitmaps on the client, but you can generate them anyway using Joe Stegman's Silverlight PNG encoder. Minh Nguyen used it to build Mandelbrot Explorer, which you can read all about it in his blog article "Minh T. Nguyen's Mandelbrot Explorer 1.0 in Silverlight 2.0 with source code." Silverlight 3, which will be in beta by the time you read this, has a bitmap API, but the problem remains that Deep Zoom wants to pull images from the server. It is unclear at the moment whether the next version of Deep Zoom will have a client-side story, but if it does, you can bet that I'll be revising MandelbrotDemo for Silverlight 3 to work entirely on the client.

Dynamic Deep Zoom: Supplying Image Pixels at Run Time
Deep Zoom Composer's export feature generates all the data needed by a MultiScaleImage control. That data includes an XML file (dzc_output.xml) that references other XML files, which in turn reference the individual images in the scene. Composer's output also includes hundreds (sometimes thousands) of image tiles generated from those images. The tiles form an image pyramid, with each level of the pyramid containing a tiled version of the original image, and each level representing a different resolution. The level at the top of the pyramid, for example, might contain a single tile with a 256x256 rendition of the image. The next level down would contain four 256x256 tiles which, put together, form a 512x512 version of the image. The next level down would contain sixteen 256x256 tiles representing different parts of a 1,024x1,024 image, and so on. Deep Zoom Composer generates as many levels as necessary to depict the original image in its native resolution. As a user zooms and pans in a Deep Zoom Scene, the MultiScaleImage control is constantly firing off HTTP requests to the server to fetch image tiles at the proper resolution. It also does some slick blending work to smooth the transition from one level to another.
What you probably don't realize about the MultiScaleImage control is that it doesn't require Deep Zoom Composer. Composer is really just a tool for quickly and easily creating Deep Zoom projects that incorporate scenes built from static images. As an alternative to providing MultiScaleImage with static content, you can generate content at run time in response to requests from MultiScaleImage and download that content to the client.
Why would you ever need to generate Deep Zoom content at run time? Developers ask me how to do this all the time. "Is it possible to supply image data to Deep Zoom dynamically?" The reason is that it enables a whole new genre of Deep Zoom applications that fetch image tiles from databases and that generate image tiles on the fly.
Want an example? Check out the Deep Earth project and an example of Deep Earth at work at deepearth.soulsolutions.com.au/. Deep Earth is referred to as a mapping control powered by the combination of Microsoft's Silverlight 2 platform and the DeepZoom (MultiScaleImage) control. In other words, it's a control you can drop into a Silverlight application to expose the vast amount of geographic data available from Microsoft Virtual Earth through a Deep Zoom front end. You can start in outer space and zoom all the way down to your front lawn. And the zooming is amazingly smooth, thanks to the work done behind the scenes by MultiScaleImage and the Deep Zoom runtime.
Deep Earth isn't driven by a bunch of XML files and image tiles output by Deep Zoom Composer; it supplies image tiles to the MultiScaleImage control dynamically, and it fetches image tiles from Virtual Earth. Users of Deep Earth refer to this as "dynamic Deep Zoom."
The application depicted in Figure 7 demonstrates the basics of dynamic Deep Zoom. MandelbrotDemo provides a Deep Zoom window into the Mandelbrot set—probably the most famous fractal in the world. The Mandelbrot set is infinitely complex, which means that you can zoom in forever and the level of detail will never decrease. Mandelbrot viewers are common in the software world, but few are as slick as the one that uses Deep Zoom. Try it; run MandelbrotDemo and zoom in on some of the swirling regions at the edge of the Mandelbrot set (at the boundary between black and bright colors). You can't zoom in forever because even a dynamic Deep Zoom scene has a finite width and height, but the scene's dimensions can be very, very large (up to 232 pixels per side).
Two Views of the Mandlebrot Set

The first step in implementing dynamic Deep Zoom is to derive from Silverlight's MultiScaleTileSource class, which is found in the System.Windows.Media namespace of System.Windows.dll, and override the GetTileLayers method. Each time the MultiScaleImage control needs a tile, it calls GetTileLayers. Your job is to create an image tile and return it to the MultiScaleImage control by adding it to the IList passed in GetTileLayers' parameter list. Other parameters input to GetTileLayers specify the zoom level (literally, the level of the image pyramid from which tiles are being requested) and the X and Y position within that level of the pyramid of the tile that is being requested. Just as X, Y, and Z values are sufficient to identify a point in 3D coordinate space, an X value, a Y value, and a level, uniquely identify an image tile in a Deep Zoom image pyramid.
Figure 8 shows the MultiScaleTileSource-derived class featured in MandelbrotDemo. The GetTileLayers override does little more than submit an HTTP request for the image tile to the server. The endpoint for the request is an HTTP handler named MandelbrotImageGenerator.ashx. Before we examine the handler, however, let's see how MandelbrotTileSource is wired up to a MultiScaleImage control.
Figure 8 MultiScaleTileSource Derivative
public class MandelbrotTileSource : MultiScaleTileSource
{
    private int _width;  // Tile width
    private int _height; // Tile height

    public MandelbrotTileSource(int imageWidth, int imageHeight,
        int tileWidth, int tileHeight) :
        base(imageWidth, imageHeight, tileWidth, tileHeight, 0)
    {
        _width = tileWidth;
        _height = tileHeight;
    }

    protected override void GetTileLayers(int level, int posx, int posy,
        IList<object> sources)
    {
        string source = string.Format(
             "http://localhost:50216/MandelbrotImageGenerator.ashx? " +
             "level={0}&x={1}&y={2}&width={3}&height={4} ",
            level, posx, posy, _width, _height);

        sources.Add(new Uri(source, UriKind.Absolute));
    }
}
Figure 9 shows an excerpt from MandelbrotDemo's Page.xaml.cs file—specifically, the XAML code-behind class's constructor. The key statement is the one that creates a MandelbrotTileSource object and assigns a reference to it to the MultiScaleImage control's Source property. For static Deep Zoom, you set Source to the URI of dzc_output.xml. For dynamic Deep Zoom, you point it to a MultiScaleTileSource object instead. The MandelbrotTileSource object created here specifies that the image being served up measures 230 pixels on each side and is divided into 128x128-pixel tiles.
Figure 9 Registering a Deep Zoom Tile Source
public Page()
{
    InitializeComponent();

    // Point MultiScaleImage control to dynamic tile source
    MSI.Source = new MandelbrotTileSource((int)Math.Pow(2, 30),
        (int)Math.Pow(2, 30), 128, 128);

    // Register mousewheel event handler
    HtmlPage.Window.AttachEvent( "DOMMouseScroll ", OnMouseWheelTurned);
    HtmlPage.Window.AttachEvent( "onmousewheel ", OnMouseWheelTurned);
    HtmlPage.Document.AttachEvent( "onmousewheel ", OnMouseWheelTurned);
}
The work of generating the image tiles is performed by MandelbrotImageGenerator.ashx back on the server (see Figure 10). After retrieving input parameters from the query string, it creates a bitmap depicting the requested tile and writes the image bits into the HTTP response. DrawMandelbrotTile does the pixel generation. When called, it converts the X-Y-level value identifying the image tile that was requested into coordinates in the complex plane (a mathematical plane in which real numbers are graphed along the X axis and imaginary numbers—numbers that incorporate the square root of -1—are graphed along the Y axis). Then it iterates through all the points in the complex plane that correspond to pixels in the image tile, checking each point to determine whether it belongs to the Mandelbrot set and assigning the corresponding pixel a color representing its relationship to the Mandelbrot set (more on this in a moment).
Figure 10 HTTP Handler for Generating Deep Zoom Image Tiles
public class MandelbrotImageGenerator : IHttpHandler
{
    private const int _max = 128;     // Maximum number of iterations
    private const double _escape = 4; // Escape value squared

    public void ProcessRequest(HttpContext context)
    {
        // Grab input parameters
        int level = Int32.Parse(context.Request[ "level "]);
        int x = Int32.Parse(context.Request[ "x "]);
        int y = Int32.Parse(context.Request[ "y "]);
        int width = Int32.Parse(context.Request[ "width "]);
        int height = Int32.Parse(context.Request[ "height "]);

        // Generate the bitmap
        Bitmap bitmap = DrawMandelbrotTile(level, x, y, width, height);

        // Set the response's content type to image/jpeg
        context.Response.ContentType =  "image/jpeg ";

        // Write the image to the HTTP response
        bitmap.Save(context.Response.OutputStream, ImageFormat.Jpeg);

        // Clean up and return
        bitmap.Dispose ();
    }

    public bool IsReusable
    {
        get { return true; }
    }

    private Bitmap DrawMandelbrotTile(int level, int posx, int posy,
        int width, int height)
    {
        // Create a bitmap to represent the requested tile
        Bitmap tile = new Bitmap(width, height);

        // Compute the number of tiles in each direction at this level
        int cx = Math.Max(1, (int)Math.Pow(2, level) / width);
        int cy = Math.Max(1, (int)Math.Pow(2, level) / height);

        // Compute starting values for real and imaginary components
        // (from -2.0 - 1.5i  to 1.0 + 1.5i)
        double r0 = -2.0 + (3.0 * posx / cx);
        double i0 = -1.5 + (3.0 * posy / cy);

        // Compute increments for real and imaginary components
        double dr = (3.0 / cx) / (width - 1);
        double di = (3.0 / cy) / (height - 1);

        // Iterate by row and column checking each pixel for
        // inclusion in the Mandelbrot set
        for (int x = 0; x < width; x++)
        {
            double cr = r0 + (x * dr);

            for (int y = 0; y < height; y++)
            {
                double ci = i0 + (y * di);
                double zr = cr;
                double zi = ci;
                int count = 0;

                while (count < _max)
                {
                    double zr2 = zr * zr;
                    double zi2 = zi * zi;

                    if (zr2 + zi2 > _escape)
                    {
                        tile.SetPixel(x, y,
                            ColorMapper.GetColor(count, _max));
                        break;
                    }

                    zi = ci + (2.0 * zr * zi);
                    zr = cr + zr2 - zi2;
                    count++;
                }

                if (count == _max)
                    tile.SetPixel(x, y, Color.Black);
            }
        }

        // Return the bitmap
        return tile;
    }
}
Sadly, there is virtually no documentation on Silverlight's MultiScaleTileSource class. Lest you think I'm a genius for figuring all this out (anyone that knows me will attest that I am not), let me give credit where credit is due. As I wrestled with the meaning of the input parameters and how to map Deep Zoom X-Y-level values to the complex plane, I found an excellent blog post by Mike Ormond, Deep Zoom, MultiScaleTileSource and the Mandelbrot Set. His post provided key insights into dynamic Deep Zoom and also referenced another blog post, The Mandelbrot Set, that describes an efficient approach to computing the Mandelbrot set. My work was probably halved by work others had done before me.
One final note on my implementation: virtually every application that renders the Mandelbrot set uses a different color scheme. I chose a scheme that assigns pixels representing coordinates that belong to the Mandelbrot set black, and pixels representing coordinates outside the Mandelbrot set RGB colors. The further a coordinate lies from the Mandelbrot set, the "cooler" or bluer the color; the closer it lies to the Mandelbrot set, the "hotter" the color. Distance from the Mandelbrot set is determined by how rapidly the point escapes to infinity. In the code here, this is the number of iterations it takes DrawMandelbrotTile's while loop to determine that the point is not part of the Mandelbrot set. The fewer the iterations, the further the point lies from the set of points that make up the Mandelbrot set. I factored the code that generates an RGB color value from the iteration count into a separate class named ColorMapper (Figure 11). If you want to experiment with different color schemes, simply modify the GetColor method. You can see the results of the gray-scale rendering by doing the following:
int val  = (count * 255) / max;
return Color.FromArgb(val, val, val);
Figure 11 ColorMapper Class
public class ColorMapper
{
    public static Color GetColor(int count, int max)
    {
        int h = max >> 1; // Divide max by 2
        int q = max >> 2; // Divide max by 4

        int r = (count * 255) / max;
        int g = ((count % h) * 255) / h;
        int b = ((count % q) * 255) / q;

        return Color.FromArgb(r, g, b);
    }
}

DeepZoomTools.dll
A final tidbit of information regarding Deep Zoom that you might find useful involves an assembly named DeepZoomTools.dll. Deep Zoom Composer uses this assembly to generate tiled images and metadata from the scenes that you build. In theory, you could use it to build composition tools of your own. I say "in theory" because there's precious little out there in terms of documentation. Find out more about DeepZoomTools.dll on the Expression Blend and Design blog. And shoot me an e-mail if you come up with some unique, creative uses for Deep Zoom but aren't quite sure how to make it do what you want it to do.

Send your questions and comments for Jeff to wicked@microsoft.com.

Jeff Prosise is a contributing editor to MSDN Magazine and the author of several books, including Programming Microsoft .NET (Microsoft Press, 2002). He's also cofounder of Wintellect (www.wintellect.com), a software consulting and education firm that specializes in Microsoft .NET. Have a comment on this column? Contact Jeff at wicked@microsoft.com.


Foundations
Securing The .NET Service Bus
Juval Lowy
Code download available from the MSDN Code Gallery
Browse the Code Online
Contents
Configuring Authentication
CardSpace Authentication
Password Authentication
Certificate Authentication
No Authentication
Transfer Security
Transport Security
Message Security
TCP Relay Binding and Transfer Security
WS Relay Binding and Transfer Security
One-Way Relay Binding and Transfer Security
Streamlining Transfer Security
In my April 2009 column, I presented the .NET Services Bus and described how you can utilize relay bindings to connect your application and customers across almost all network boundaries. However, if just anyone were allowed to relay messages to your service, or if any service could receive your client calls, the relay service would be a dangerous proposition. You need to protect the transfer of the message from the client to the service via the relay service. In this column, I show you how to secure the .NET Services Bus and also provide some helper classes and utilities to automate many of the details.
The .NET Services Bus mandates that the service must always authenticate itself to receive relayed messages. Clients, on the other hand, may or may not authenticate themselves. Typically (and by default), clients do authenticate, but the relayed service may decide to waive the client's .NET Services Bus authentication.
The .NET Services Bus offers three different authentication mechanisms—CardSpace, password, or certificate—and it is up to the solution administrator to associate these using the solution page shown in Figure 1.
Figure 1 Configuring Solution Authentication Options
A single solution can support multiple authentication options, and for each option the administrator can add multiple credentials. For example, the administrator might configure three passwords, two cards, and a single certificate. Presenting any one of these credentials is enough to authenticate against the relay service. Also, the service and the client can use different authentication methods. For example, the service can use a password, and the client a certificate.

Configuring Authentication
The enum TransportClientCredentialType, shown here, represents the available credential options:
public enum TransportClientCredentialType
{
   CardSpace,
   UserNamePassword,
   X509Certificate
   Unauthenticated,
   FederationViaCardSpace,
   AutomaticRenewal
}
In TransportClientCredentialType, Client refers to a client of the .NET Services Bus—that is, both the client and the relayed service.
The preferred authentication mechanism and the credentials themselves are configured using an endpoint behavior called TransportClientEndpointBehavior, defined in Figure 2.
Figure 2 TransportClientEndpointBehavior
public class TransportClientEndpointBehavior : IEndpointBehavior
{
   public TransportClientCredentials Credentials
   {get;}
   public TransportClientCredentialType CredentialType
   {get;set;}
}
public class TransportClientCredentials
{
   public X509CertificateCredential ClientCertificate
   {get;}
   public UserNamePasswordCredential UserName
   {get;}
}
Using an endpoint behavior (as opposed to a service behavior) provides two advantages. First, a service host can choose a different authentication mechanism for each endpoint. Second, an endpoint behavior offers a unified programming model for the client and the service because the client has only endpoint behaviors.

CardSpace Authentication
CardSpace is the default credential type used by all relay bindings. When the client or the host uses CardSpace authentication, the user is prompted to provide a card on opening either the host or the proxy. After the user provides the card, it is bundled in the connection request message to the relay service. Obviously, such an approach is best suited for interactive applications. These prompts, however, will annoy the user if they occur every time the user opens a new proxy or host. Fortunately, the credential is cached in the app domain, and the user is not prompted again as long as he or she accesses the same endpoint address.

Password Authentication
Like CardSpace authentication, password authentication is best suited for an interactive application, typically in conjunction with a login dialog box. However, there is no need to prompt the user to enter a user name because that is always the solution name. After the user provides the password, you need to programmatically provide the solution name and the password to the TransportClientEndpointBehavior.
On the host side, you need to instantiate a new TransportClientEndpointBehavior object and set the CredentialType property to TransportClientCredentialType.UserNamePassword. The credentials themselves are provided to the Credentials property. You then add this behavior to every endpoint of the host that uses the relay service, as shown in Figure 3.
Figure 3 Providing the Host with the Solution Password
TransportClientEndpointBehavior behavior =
           new TransportClientEndpointBehavior();
behavior.CredentialType = TransportClientCredentialType.UserNamePassword;
behavior.Credentials.UserName.UserName = "MySolution";
behavior.Credentials.UserName.Password = "MyPassword";
ServiceHost host = new ServiceHost(typeof(MyService));

foreach(ServiceEndpoint endpoint in host.Description.Endpoints)
{
   endpoint.Behaviors.Add(behavior);
}

host.Open();
You can encapsulate and automate the steps in Figure 3 by using extension methods such as the SetServiceBusPassword methods of my ServiceBusHelper static class, shown here:
public static class ServiceBusHelper
{
   public static void SetServiceBusPassword(this ServiceHost host, string password);
   public static void SetServiceBusPassword(this ServiceHost host, string solution,string password);
}
Using these extensions, Figure 3 is condensed to the following:
ServiceHost host = new ServiceHost(typeof(MyService));
host.SetServiceBusPassword("MyPassword");
host.Open();
You can see an implementation of the SetServiceBusPassword methods without error handling in the sample code that accompanies this article.
ServiceBusHelper defines the helper private method SetBehavior, which accepts a collection of endpoints and assigns a provided TransportClientEndpointBehavior object to all endpoints in the collection. The private SetServiceBusPassword helper methods accept a collection of endpoints, the solution password, and optionally the solution name. If the solution name is not specified, SetServiceBusPassword extracts it from the address of the first endpoint. SetServiceBusPassword then creates a TransportClientEndpointBehavior, configures it to use the password, and calls SetBehavior. The public SetServiceBusPassword methods simply call the private ones with the collection of endpoints of the host.
The client needs to follow similar steps, except there is only one endpoint to configure—the one the proxy is using, as shown in Figure 4.
Figure 4 Setting the Solution Password on the Proxy
TransportClientEndpointBehavior behavior =
  new TransportClientEndpointBehavior();
behavior.CredentialType = TransportClientCredentialType.UserNamePassword;
behavior.CredentialType = TransportClientCredentialType.UserNamePassword;
behavior.Credentials.UserName.UserName = "MySolution";
behavior.Credentials.UserName.Password = "MyPassword";
MyContractClient proxy = new MyContractClient();
proxy.Endpoint.Behaviors.Add(behavior);

proxy.MyMethod();

proxy.Close();
Again, you should encapsulate this repetitive code with extension methods and offer similar support for working with class factories. Using these extensions, Figure 4 is condensed to this code:
MyContractClient proxy = new MyContractClient();
proxy.SetServiceBusPassword("MyPassword");
proxy.MyMethod();
proxy.Close();
Figure 5 shows the implementation of two of the client-side SetServiceBusPassword<T> extensions. Note the use of the SetServiceBusPassword helper methods by wrapping the single endpoint the proxy has with a collection of endpoints.
Figure 5 Implementing SetServiceBusPassword<T>
public static class ServiceBusHelper
{
   public static void SetServiceBusPassword<T>(this ClientBase<T> proxy,
                                         string password) where T : class
   {
      if(proxy.State == CommunicationState.Opened)
      {
         throw new InvalidOperationException("Proxy is already opened");
      }
      proxy.ChannelFactory.SetServiceBusPassword(password);
   }
     public static void SetServiceBusPassword<T>(this ChannelFactory<T> factory,
                                         string password) where T : class
   {
      if(factory.State == CommunicationState.Opened)
      {
         throw new InvalidOperationException("Factory is already opened");
      }
   Collection<ServiceEndpoint> endpoints =
                                  new Collection<ServiceEndpoint>();

      endpoints.Add(factory.Endpoint);
      SetServiceBusPassword(endpoints,password);
   }
   //More members
}
Because TransportClientEndpointBehavior is just another endpoint behavior, you can also configure it in the config file. Storing the password in a text config file, however, is highly inadvisable.

Certificate Authentication
Using a certificate to authenticate against the .NET Service Bus is the best option for noninteractive applications, and you can set the certificate both programmatically and in the config file.
The main hurdle in using certificates is that the certificate must contain a private key, which entails an elaborate setup sequence by the solution administrator. However, once the solution is configured to use the certificate, the rest of the work is straightforward.
Both the client and the service host use identical configuration entries, as shown in Figure 6.
Figure 6 Solution Certificate in Config
<endpoint behaviorConfiguration = "RelayCert"
         ...
      />
...
<behaviors>
   <endpointBehaviors>
      <behavior name = "RelayCert">
        <transportClientEndpointBehavior credentialType =
                                                   "X509Certificate">
            <clientCredentials>
               <clientCertificate
                  findValue     = "MyRelayCert"
                  storeLocation = "LocalMachine"
                  storeName     = "My"
                  x509FindType  = "FindBySubjectName"
               />
            </clientCredentials>
         </transportClientEndpointBehavior>
      </behavior>
   </endpointBehaviors>
</behaviors>
To programmatically provide the certificate on the host side, you need to follow steps similar to those shown earlier in Figure 3. Besides setting the credentials type to TransportClientCredentialType.X509Certificate, you need to use the SetCertificate method of the ClientCertificate property on Credentials. Here again, you can streamline it using host extension methods, as shown here:
public static class ServiceBusHelper
{
   public static void SetServiceBusCertificate(this ServiceHost host);
   public static void SetServiceBusCertificate(this ServiceHost host, string subjectName);
   public static void SetServiceBusCertificate(this ServiceHost host, object findValue,StoreLocation location,
      StoreName storeName,X509FindType findType);
   //More members
}
For example:
ServiceHost host = new ServiceHost(typeof(MyService));
host.SetServiceBusCertificate("MyRelayCert");
host.Open();
SetServiceBusCertificate defaults the store to MyComputer and the location to My, and it looks up the certificate by name. SetServiceBusCertificate also extracts the solution name from the host endpoints.
The client can also programmatically provide the certificate to use to the proxy by following steps similar to Figure 4, and you can automate this by using these extension methods, which follow the same default values discussed for the host:
public static class ServiceBusHelper
{
  public static void SetServiceBusCertificate<T>(this ClientBase<T> proxy)
                       where T : class;
  public static void SetServiceBusCertificate<T>(this ClientBase<T> proxy,
                       string subjectName) where T : class;
  public static void SetServiceBusCertificate<T>(this ClientBase<T> proxy,
                       object findValue,StoreLocation location,StoreName
                       storeName,X509FindType findType) where T : class;
   //Similar methods for a channel factory
}
Using the extensions on the client side yields this code:
MyContractClient proxy = new MyContractClient();
proxy.SetServiceBusCertificate("MyRelayCert");
proxy.MyMethod();
proxy.Close();

No Authentication
Although the service must always authenticate against the service bus, you might decide to exempt the client and allow it unauthenticated access to the relay service. In that case, the client must set TransportClientEndpointBehavior to TransportClientCredentialType.Unauthenticated. When the clients are not authenticated by the relay service, it is now up to the relayed service to authenticate the clients. The downside is that the service is now less shielded than when the relay service authenticated clients. In addition, you must use message security to transfer the client credentials (as discussed later). To enable unauthenticated access by the client, both the service and the client must explicitly allow it by configuring the relay binding to not authenticate, using the enum RelayClientAuthenticationType, shown here:
public enum RelayClientAuthenticationType
{
   RelayAccessToken, //Default
   None
}
You assign that enum via the Security property.

Transfer Security
The next crucial aspect of security is how to securely transfer the message through the relay to the service. In addition to message transfer security, another important design decision is which client credentials (if any) the message should contain. Transfer security is independent of how the client or the service authenticates itself against the .NET Service Bus.
The .NET Services Bus offers four options for transfer security, represented by the enum EndToEndSecurityMode:
public enum EndToEndSecurityMode
{
   None,
   Transport,
   Message,
   TransportWithMessageCredential //Mixed
}
The four options are None, Transport, Message, and Mixed. None means just that—the message is not secured at all. Transport uses SSL or HTTPS to secure the message transfer. Message security encrypts the body of the message so that it can be sent over nonsecured transports. Mixed uses message security to contain the client's credentials but transfers the message over a secured transport. Figure 7 shows the way the relay binding supports the various transfer security modes and their default values. A bold plus sign (+) marks defaults.
Figure 7 Binding and Transfer Security
Binding | None | Transport | Message | Mixed
TCP (Relayed) | + | + | + | +
TCP (Direct/Hybrid) | + | - | + | -
WS | + | + | + | +
One-Way | + | + | + | -
You configure transfer security in the binding. Although the relay bindings use different default values, all the relay bindings offer at least one constructor that takes EndToEndSecurityMode as a construction parameter. You can also configure transfer security after construction by accessing the Security property and its Mode property.

Transport Security
When it comes to transfer security, transport security is the simplest to set up and configure. When using transport security, all client calls are anonymous—the client messages do not contain any client credentials. While transport security is the easiest to use, it does not provide end-to-end security. It secures only the transfer of the message to the relay service and from the relay service. The journey inside the relay service is not secured.
This means that in theory, the relay service can eavesdrop on the communication between the client and the service and even tamper with the messages. However, I believe that in practice this is impractical given the volume of traffic to the .NET Services Bus. Simply put, this kind of subversion cannot be performed as an aside and requires dedicated resources, planning, staff, and technology. In addition, Microsoft has proven over the years that it has the highest integrity and respect for its customers' privacy, and it has many other areas it could have abused if it were indeed malicious.

Message Security
Message security encrypts the body of the message using a service-provided certificate. Because the message itself is protected rather than the transport, the journey inside the relay is protected as well. The downside to message security is that it requires additional setup steps.
While I think that in practice transport security is enough, it is vital to assure customers and users of the presence of end-to-end privacy and integrity and to guard against even theoretical compromises. I therefore recommend always relying on message security for all relayed communication, which will also provide additional benefits, such as direct connection and the availability of security call context to the service.
Unlike in transport security, in message security the message might contain the client's credentials. The primary use of client credentials by the service is for local authorization of the call to establish some role-based security policy. Whenever the message contains credentials, the service must also authenticate them (even if all it wants is to authorize the client). Note that such authentication is on top of the authentication the relay service has already performed. If the relay service has already authenticated the client, authenticating the call again by the service does not add much in the way of security, yet it burdens the service with managing the client's credentials. If the relay service is not authenticating the client, the service will be subjected to all the unwanted traffic of unauthenticated clients, which could have severe IT operations implications.
For these reasons, I find that the best practice is for the relay service to authenticate the client and to avoid having the service do it again. You should also design your service so that it has no need for the client's credentials. Such a design is aligned with the chain-of-trust design pattern that works well in a layered architecture. That said, there are cases when the service needs the client credentials for a local use other than authorization, such as personalization, auditing, or proprietary integration with legacy systems.

TCP Relay Binding and Transfer Security
The TCP relay binding defaults to transport security, and no special configuration steps are required. It simply uses SSL over port 828. When using transport security, however, you can only use the TCP relay binding connection mode of TcpRelayConnectionMode.Relayed.
Because the call is anonymous, on the service side Windows Communication Foundation (WCF) attaches a generic principal with a blank identity to the thread executing the call, and the ServiceSecurityContext is null.
To protect the transfer of the message, you must configure the service host with a certificate. The client will by default negotiate the certificate (obtain its public key), so there is no need to explicitly list the certificate in the client's config file. However, the client still needs to validate the negotiated certificate. As with regular WCF and message security, the best practice is to validate the certificate using peer-trust, which means installing the certificate beforehand in the client's Trusted People folder. Besides providing true end-to-end transfer security over the relay, using message security also enables the use of the direct and hybrid connection modes.
As discussed previously, the message might or might not contain the client's credentials. If you avoid sending the credentials in the message, WCF will attach to the thread executing the call a Windows principal with a blank identity, which does not make much sense. When using message security without credentials, you should also set the host PrincipalPermissionMode to None to get the same principal as with transport security. To configure the binding for message security with anonymous calls, use MessageCredentialType.None and assign that value to the ClientCredentialType property of MessageSecurityOverRelayConnection, available in the Message property of NetTcpRelaySecurity. Figure 8 shows code that demonstrates this.
Figure 8 Configuring a Binding for Message Security with Anonymous Calls
public sealed class NetTcpRelaySecurity
{
   public EndToEndSecurityMode Mode
   {get;set;}
   public MessageSecurityOverRelayConnection Message
   {get;}
   //More members
}
public sealed class MessageSecurityOverRelayConnection
{
   public MessageCredentialType ClientCredentialType
   {get;set;}
   //More members
}
Figure 9 shows the required host-side config file.
Figure 9 Configuring the Host for Message Security
<service name = "..." behaviorConfiguration = "MessageSecurity">
      <endpoint
         ...
         binding  = "netTcpRelayBinding"
         bindingConfiguration = "MessageSecurity"
      />
   </service>
   ...
      <serviceBehaviors>
         <behavior name = "MessageSecurity">
            <serviceCredentials>
               <serviceCertificate
                  findValue     = "MyServiceCert"
                  storeLocation = "LocalMachine"
                  storeName     = "My"
                  x509FindType  = "FindBySubjectName"
               />
            </serviceCredentials>
            <serviceAuthorization principalPermissionMode ="None"/>
         </behavior>
      </serviceBehaviors>
   <bindings>
      <netTcpRelayBinding>
         <binding name = "MessageSecurity">
            <security mode = "Message">
               <message clientCredentialType = "None"/>
            </security>
         </binding>
      </netTcpRelayBinding>
   </bindings>
On the client side, you must include the service certificate name in the address identity of the endpoint because that name does not match the relay service domain. Figure 10 shows the required config file.
Figure 10 Configuring the Client for Message Security
<client>
   <endpoint behaviorConfiguration = "ServiceCertificate"
      binding  = "netTcpRelayBinding"
      bindingConfiguration = "MessageSecurity"
      <identity>
         <dns value = "MyServiceCert"/>
      </identity>
      ...
   </endpoint>
</client>
<bindings>
   <netTcpRelayBinding>
      <binding name = "MessageSecurity">
         <security mode = "Message">
            <message clientCredentialType = "None"/>
         </security>
      </binding>
   </netTcpRelayBinding>
</bindings>
<behaviors>
   <endpointBehaviors>
      <behavior name = "ServiceCertificate">
         <clientCredentials>
            <serviceCertificate>
               <authentication certificateValidationMode= "PeerTrust"/>
            </serviceCertificate>
         </clientCredentials>
      </behavior>
   </endpointBehaviors>
</behaviors>
If you want to include the client credentials in the message, the service must also authenticate those credentials, using the same setting as with regular TCP calls. In that case, the service principal and primary identity will both have an identity matching those credentials. The credential can be a user name and password, a certificate, or an issued token. You must indicate to both the host and the client in the binding which credential types you expect. For example, for user name credentials, use the following:
<bindings>
   <netTcpRelayBinding>
      <binding name = "MessageSecurity">
         <security mode = "Message">
            <message clientCredentialType = "UserName"/>
         </security>
      </binding>
   </netTcpRelayBinding>
</bindings>
On the host side, if the credentials are user name and password, you must also configure, using behaviors, how to authenticate and authorize the credentials. The default will be Windows credentials, but the more common choice would be using some credentials store such as the ASP.NET providers:
<service name = "..." behaviorConfiguration = "CustomCreds">
   ...
</service>
...
<serviceBehaviors>
   <behavior name = "CustomCreds">
      <serviceCredentials>
         <userNameAuthentication
            userNamePasswordValidationMode = "MembershipProvider"
         />
      </serviceCredentials>
      <serviceAuthorization principalPermissionMode = "UseAspNetRoles"/>
   </behavior>
</serviceBehaviors>
The client has to populate the proxy with the credentials. When using a username and password, the client code would be insert like this:
MyContractClient proxy = new MyContractClient();
proxy.ClientCredentials.UserName.UserName = "MyUserName";
proxy.ClientCredentials.UserName.Password = "MyPassword";

proxy.MyMethod();

proxy.Close();
The client has no way of knowing if the credentials it provides are authenticated on the service side as Windows or custom credentials.
Mixed transfer security is the only way to avoid anonymous calls over transport security. Since transport security cannot pass credentials, you pass the credentials using message security, hence the term mixed. When using mixed transfer security over the TCP relay binding you are restricted to using only relayed connections.
Figure 11 shows how to configure either the service or the client for mixed security.
Figure 11 Configuring for Mixed Security
<endpoint
      binding  = "netTcpRelayBinding"
      bindingConfiguration = "MixedSecurity"
      ...
   />
...
<bindings>
   <netTcpRelayBinding>
      <binding name = "MixedSecurity">
         <security mode = "TransportWithMessageCredential"/>
      </binding>
   </netTcpRelayBinding>
</bindings>
After the messages are received by the service, the host must authenticate the calls as with regular TCP. Once authenticated, the service call will have a principal object matching the credentials provided and a security call context.

WS Relay Binding and Transfer Security
Combining the WS binding with transport security is as easy as changing the address schema from HTTP to HTTPS and setting the binding to use transport security, as shown in Figure 12.
Figure 12 WS Relay Binding with Transport Security
address = "https://MySolution.servicebus.windows.net/..." binding = "wsHttpRelayBinding" bindingConfiguration = "TransportSecurity" ... /> <bindings> <wsHttpRelayBinding> <binding name = "TransportSecurity"> <security mode = "Transport"/> </binding> </wsHttpRelayBinding> </bindings>
Note that the WS relay binding defaults to using message security for transfer security. Since message security requires additional configuration steps, the WS relay binding does not work as-is out of the box, and all calls will fail. However, configuring the WS relay binding to use message (or mixed) security is identical to configuring the TCP relay binding.

One-Way Relay Binding and Transfer Security
The one-way relay binding (and its subclasses) is the only binding that defaults to having no transfer security at all. In addition, it does not support mixed transfer security. Configuring it to use transport security is the same as with the TCP and WS relay bindings. Configuring it to use message security is similar but with one important difference—the one-way relay binding cannot negotiate the service certificate because there may not even be a service, and no direct interaction with the service takes place. When using message security on the client, you must explicitly specify the service certificate, as shown in Figure 13.
Figure 13 One-Way Relay Binding with Message Security
<client>
   <endpoint behaviorConfiguration = "ServiceCertificate"
      ...
   </endpoint>
</client>

<behaviors>
   <endpointBehaviors>
      <behavior name = "ServiceCertificate">
         <clientCredentials>
            <serviceCertificate>
               <scopedCertificates>
                  <add targetUri = "sb://MySolution.servicebus..."
                     findValue     = "MyServiceCert"
                     storeLocation = "LocalMachine"
                     storeName     = "My"
                     x509FindType  = "FindBySubjectName"
                  />
               </scopedCertificates>
            </serviceCertificate>
         </clientCredentials>
      </behavior>
   </endpointBehaviors>
</behaviors>
Another important distinction between the one-way relay binding and the other relay bindings is that if the call is anonymous, with either transport or message security, the call has a security call context whose primary identity is
service bus certificate CN=servicebus.windows.net.

Streamlining Transfer Security
While transfer security offers a slew of details and intricate options, you can and should streamline and automate most of these security configuration decisions. To encapsulate it on the host side, use my ServiceBusHost class, defined as insert the following:
public class ServiceBusHost : ServiceHost
{
   public ServiceBusHost(object singletonInstance, params Uri[] baseAddresses);
   public ServiceBusHost(Type serviceType,params Uri[] baseAddresses);

   public void ConfigureAnonymousMessageSecurity(string serviceCert);
   public void ConfigureAnonymousMessageSecurity(string serviceCert,
                            StoreLocation location,StoreName storeName);
   public void ConfigureAnonymousMessageSecurity(StoreLocation location,
            StoreName storeName,X509FindType findType,object findValue);

   //More members
}
When using ServiceBusHost, no other setting in config or in code is required. Per my recommendation, you can use the ConfigureAnonymousMessageSecurity method to enable anonymous calls over message security. All you need to provide it is the certificate name to use:
ServiceBusHost host = new ServiceBusHost(typeof(MyService));
host.ConfigureAnonymousMessageSecurity("MyServiceCert");
host.Open();
ConfigureAnonymousMessageSecurity will default the certificate location to the local machine and the certificate store to My, and it will look up the certificate by its common name. If you do not call ConfigureAnonymousMessageSecurity, ServiceBusHost will default to using anonymous message security with the solution name for the certificate name:
ServiceBusHost host = new ServiceBusHost(typeof(MyService));
host.Open();
You can also use the overloaded versions that let you explicitly specify some or all of the certificate details.
ServiceBusHost makes use of the ConfigureBinding method of ServiceBusHelper. ConfigureBinding defaults to anonymous calls. If the calls are to have credentials, ConfigureBinding always uses username credentials. With the TCP relay binding, ConfigureBinding uses the hybrid connection mode. ConfigureBinding also always enables reliable messages.
ServiceBusHost also supports message security with credentials via the ConfigureMessageSecurity methods:
public class ServiceBusHost : ServiceHost
{
   public void ConfigureMessageSecurity();
   public void ConfigureMessageSecurity(string serviceCert);
   public void ConfigureMessageSecurity(string serviceCert,
                                        string applicationName);
   public void ConfigureMessageSecurity(string serviceCert,
                                        bool useProviders,
                                        string applicationName);
   //More members
}
ConfigureMessageSecurity defaults to using the ASP.NET membership providers, but it can be instructed to use Windows accounts as well. The implementation of ConfigureMessageSecurity is similar to that of ConfigureAnonymousMessageSecurity.
You can provide clients with an easy way of configuring message security with my ServiceBusClientBase<T>, defined as
public abstract class ServiceBusClientBase<T> : ClientBase<T> where T : class
{
   public ServiceBusClientBase();
   public ServiceBusClientBase(string endpointName);
   public ServiceBusClientBase(Binding binding,
                               EndpointAddress remoteAddress);
   public ServiceBusClientBase(string username,string password);

   public ServiceBusClientBase(string endpointName,
                               string username,string password);
   public ServiceBusClientBase(Binding binding,EndpointAddress address,
                               string username,string password);

   protected virtual void ConfigureForServiceBus();
   protected virtual void ConfigureForServiceBus(string username, string password);

}
ServiceBusClientBase<T> offers two sets of constructors. The constructors that merely take the endpoint parameters all default to using message security with anonymous calls. You can also use the constructors that accept the username and password credentials. If no endpoint address identity is provided, ServiceBusClientBase<T> defaults it to the solution name. You use ServiceBusClientBase<T> like the WCF-provided ClientBase<T>:
[ServiceContract]
interface IMyContract
{
   [OperationContract]
   void MyMethod();
}
class MyContractClient : ServiceBusClientBase<IMyContract>,IMyContract
{
   public MyContractClient()
   {}
   public void MyMethod()
   {
      Channel.MyMethod();
   }
}
The sample code download includes the full implementation of ServiceBusClientBase<T>. ServiceBusClientBase<T> uses peer-trust to validate the service certificate. The bulk of the work is done by passing the endpoint binding to ServiceBusHelper.ConfigureBinding.
The one remaining sore point is the one-way relay binding, with its lack of certificate negotiation. To alleviate that, I wrote OneWayClientBase<T>:
public abstract class OneWayClientBase<T> : ServiceBusClientBase<T>   where T : class
{
   //Same constructors as ServiceBusClientBase<T>

   public void SetServiceCertificate(string serviceCert);
   public void SetServiceCertificate(string serviceCert,
                                     StoreLocation location,
                                     StoreName storeName);
   public void SetServiceCertificate(object findValue,
        StoreLocation location,StoreName storeName,X509FindType findType);
}
OneWayClientBase<T> derives from ServiceBusClientBase<T> and adds the SetServiceCertificate methods. If you never call SetServiceCertificate, OneWayClientBase<T> simply looks up the service certificate from config. SetServiceCertificate offers a simple programmatic way of avoiding the config altogether. It even sets the identity tag of the endpoint address. SetServiceCertificate uses the same defaults as ServiceBusHost, including using the solution name for the certificate name if no certificate is provided. Here's how you use OneWayClientBase<T> :
class MyContractClient : OneWayClientBase<IMyContract>,IMyContract
{
   public MyContractClient()
   {}
   public void MyMethod()
   {
      Channel.MyMethod();
   }
}

MyContractClient proxy = new MyContractClient();
proxy.SetServiceCertificate("MyServiceCert");

proxy.MyMethod();

proxy.Close();
As you can see, using OneWayClientBase<T> is straightforward.

Send your questions and comments to mmnet30@microsoft.com.

Juval Lowy a software architect with IDesign providing WCF training and architecture consulting. His recent book is Programming WCF Services 2nd Edition (O'Reilly, 2008). He is also the Microsoft Regional Director for the Silicon Valley. Contact Juval at www.idesign.net.