April 2009
Lessons Learned: Optimizing A Large Scale Software + Services Application
Udi Dahan explains how his team identified and overcame unforeseen problems while developing a large-scale software + services trading application. Udi Dahan
Dynamic WPF: Create Flexible UIs With Flow Documents And Data Binding
Flow documents offer enormous flexibility in arranging text layout and pagination, but they don’t support data binding, so you can’t dynamically change content. Here we build a component to solve that problem. Vincent Van Den Berghe
Cloud Computing: Building Distributed Applications With .NET Services
We show you how .NET Services within the Azure Services Platform makes it easy to bring workflow apps to the cloud. Aaron Skonnard
Take Control: Use SharePoint to Manage Your Windows Services
In this article, we show you how to integrate a Windows Services-based solution with SharePoint. The results enable you to provision, start, stop, and remove service instances through SharePoint 3.0 Central Administration. Pav Cherny
Sync Up: Manage Your Data Effectively With The Microsoft Sync Framework
Synchronization Services for ADO.NET provide a set of tools to help you synchronize data between two database sources, synchronize files between machines, and synchronize with an RSS or ATOM feed. Learn more here. James Yip
Columns
Editor's Note: What's In Style: From fat to thin to fat again--Howard Dierking chronicles the dieting habits of a Web client and the technologies that continue to fuel the shifts.Howard Dierking | Toolbox: Microsoft Chart Controls, Visual Studio Automatic Code Snippets, And More: In this installment we look at the Microsoft Chart Controls; Snippet Designer, a free, add-in for Visual Studio 2008 for creating and editing Code Snippets; refactoring SQL applications; and this month’s favorite blog.Scott Mitchell | CLR Inside Out: CLR Optimizations In .NET Framework 3.5 SP1: See the changes the CLR team made to the CLR .for NET Framework 3.5 SP1 and the improvements you’ll get running your existing CLR 2.0-based apps against this service pack.Surupa Biswas
Data Points: Using Silverlight 2 With ADO.NET Data Services: ADO.NET Data Services and Silverlight make a powerful combination, but to make them work well together, there are a few things you need to understand. Here, John Papa explains.John Papa | Cutting Edge: Explore Rich Client Scripting With jQuery, Part 2: Achieving cross-browser compatibility for events is no easy task. The jQuery event handling API addresses the differences in event handling across browsers, allowing you to write more predictable JavaScript.Dino Esposito | Patterns in Practice: Persistence Patterns: Here we examine data persistence patterns to help you determine which best suits your needs. We look at a number of patterns, including the Active Record, the Data Mapper, the Repository, the Identity Map, the Lazy Loading, and the Virtual Proxy.Jeremy Miller
Service Station: Creating And Consuming Web Feeds: Jon Flanders demonstrates creating and consuming Web feeds with Windows Communication Foundation and AtomPub.Jon Flanders | Foundations: Working With The .NET Service Bus: The .NET Services Bus is arguably the most accessible, powerful, and useful piece of the new Windows Azure Cloud Computing initiative. See how it manages cloud communications.Juval Lowy | Windows With C++: The Virtual Disk API In Windows 7: This month we look inside the Windows 7 beta to examine the Virtual Disk API and the Microsoft Virtual Hard Disk (VHD) format.Kenny Kerr
.NET Matters: Parallelizing Operations With Dependencies: In this month’s installment, Stephen Toub examines some techniques for enforcing dependencies in the running order of asynchronous operations and builds a DependencyManagement class to help.Stephen Toub | Usability in Practice: The Power of Personas: A persona is a description of a fictional person representing an amalgamation of traits found in a segment of your users. Emplolying personas arms you with a powerful foundation on which to base design decisions.Dr. Charles B. Kreitzberg and Ambrose Little | { End Bracket }: Translate This Page: This month we examine the Microsoft translation Web service and show you how you can incorporate translation services into your own Web application.Sandor Maurice & Vikram Dendi


Lessons Learned
Optimizing A Large Scale Software + Services Application
Udi Dahan

This article discusses:
  • WCF and 3-tier service models
  • Dealing with occasional connectivity
  • Threading and usability
  • Synchronization domains
This article uses the following technologies:
WCF, Software + Services
Contents
Always Up To Date
Trouble with 2-Tier
WCF and 3-Tier
Scalability Problems
Trouble in Paradise
Occasional Connectivity Affects Servers
Threading and Usability
Client-side WCF
Object-Graph Dependencies
Synchronization Domains
View-Controller Interaction
Thread-Safe Data Binding
Two-way DataBinding
Client-side Repositories
Performance
Lessons Learned
Designing rich, interactive desktop client software has never been easier. With Visual Studio, Windows Presentation Foundation (WPF), and the Composite Application Guidance for WPF (Prism), developers are better equipped than ever.
Unfortunately, it is not enough.
When working on a large-scale, rich-client software + services application, my team found out the hard way that developing occasionally connected, multithreaded, smart clients that don't deadlock or generate garbage through data-races is far from trivial. It's not a failing in the toolset, though. We found that these tools need to be employed in very specific patterns to achieve systems that are both responsive and robust.
In this article I highlight some problems we ran into, and explain how we overcame them. Hopefully you can harness this information to avoid our mistakes and make the best use of these tools when building your own software + services applications.

Always Up To Date
One of the first challenges we faced was the need for users to always be kept up to date with what all other users were doing, as well as events occurring in other systems. This real-time system behavior allowed users to act on events as they happened on large quantities of data. The previous version of the system allowed them to search, sort, and filter, but users just couldn't act on that information in time.
During the user experience design process, many of the grids in the previous version of the system were replaced by Messenger-like pop-up messages ("toast") that informed the user of important events. Other changes enabled users to set various thresholds on properties of entities that, when exceeded, popped up toast messages. The toast often contained links that, when clicked, opened a form showing the user the affected entity—some with a before and after view.
While thinking through ways to scale the regular request/response patterns that we had experience with, our key stakeholder came in and reminded us: "This ability to surface events from the world to the user in real time is critical for our knowledge workers to support the collaborative, real-time enterprise we're building."
In short, it was clear that we needed some kind of publish/subscribe capability. Trying to support two-second user visibility on events with hundreds of users polling a central database just wasn't going to work (it broke down at around 60 users).
On top of it all, our user population was mobile—some of them disconnecting and reconnecting every few seconds as they moved in and out of Wi-Fi zones, others working offline for an hour or two while telecommuting, and some performing intensive offline work for up to a week.
We had to juggle occasional connectivity, data synchronization, and publish/subscribe all at the same time. We learned that we couldn't solve all problems either client-side or server-side, but rather that an integrated approach was needed since any changes on one side needed corresponding changes on the other side. In this article, I'll describe this process starting from the server-side working forward to the client.

Trouble with 2-Tier
Our original deployment model was the traditional 2-tier model found in many rich client applications. The difficulty we had with this model was pushing out notifications from the database to the clients.
One option that we tried was to have all interaction with the database done via stored procedures that, after committing their transactions, would call out to a Web service hosted on the database server. It was the responsibility of that Web service to notify clients of what happened by passing them the name of the stored procedure that was invoked as well as the arguments that were passed to the stored procedure.
That didn't work out so well. There were two critical problems with this approach—one logical, the other physical.
The logical problem was that a single stored procedure could be invoked by all sorts of paths in the code meaning different things at different times. When a client received notification of the activation of a stored procedure, it wasn't always clear what that meant and what toast to pop up to the user.
The physical problem was that we needed each client to expose its own Web service, which the Web service on the database server would call. This was quickly vetoed by the security professionals as a gaping security hole, as well as by the regulatory auditors who were (rightly) concerned about users making decisions in real time on data whose origins couldn't necessarily be traced.

WCF and 3-Tier
To solve the logical problems with the 2-tier solution we realized that we needed to be more explicit about our service contract—stating the name of the stored procedure that ran and its parameters was explicit about what happened, but not why it happened.
As we began designing our Windows Communication Foundation (WCF) service contracts, it became clear that it wasn't enough to just focus on the appropriate naming and scoping of our service methods. We needed to be explicit about the contract of notifications—the way the server called back to the clients. WCF callback contracts enabled us to take the same amount of care on server-to-client messages as the regular service contract. (To read more about WCF callback contracts, see Juval Lowy's article from the October 2006 issue, "What You Need To Know About One-Way Calls, Callbacks, And Events.")
Each command/event pair was modeled as follows:
[ServiceContract(CallbackContract =
  typeof(ISomethingContractCallback))]
interface ISomethingContract {
  [OperationContract(IsOneWay = true)]
  void DoSomething();
}

interface ISomethingContractCallback {
  [OperationContract(IsOneWay = true)]
  void SomethingWasDone();
}
To enable our WCF service to call back to clients other than the one that invoked the current method, we had to host the service in a process separate from that of the client and deploy that process to its own server, in essence moving to a 3-tier deployment.
While it was suggested we put the service on the same box as the database, our database admins were concerned that the service might take away precious resources, thereby hurting the performance of the database. The added benefit of having a separate tier for our stateless WCF service was that we could easily scale it out to more machines without requiring any tinkering with the database server.
Unfortunately, it wasn't as easy as we thought.

Scalability Problems
We ran into two kinds of scalability problems—logical and physical, as before.
The logical scalability problem manifested itself as the system gained more functionality. When we first started development, we had only a single server contract containing all methods on it, and a single callback contract with all the corresponding methods on it. We quickly ran into the brick wall of too many developer chefs stirring the same pot. After moving each command/event pair to its own service/callback contract pair, that problem was solved. Yet the solution introduced another, more insidious problem.
When taking the decision to have multiple service/callback contract pairs, we thought the main issue would be having an unmanageable number of contracts. That actually didn't turn out to be much of a problem—the modularity between business domains in the app mitigated that very well. The problem was the "pair."
One command could result in multiple kinds of notifications, and one kind of notification could be caused by many types of commands. The clean one-to-one mapping we had before was overly simplistic and needed to evolve into a many-to-many mapping. Not only were we scaling the number of commands and notifications in the system, we needed to scale the number of relationships between them. It looked like the one-to-one representation supported by WCF callback contracts wasn't going to be able to take us forward.
We ran into a physical scalability problem when scaling out our WCF service tier. We needed some way to share the list of client callback contract subscribers. As we worked through the guidance provided in Juval Lowey's October 2006 MSDN Magazine article, we created the relevant infrastructure pieces including the pub/sub service. We found that a single pub/sub service wasn't able to handle the amount of notifications it needed to push from all publishers to all subscribers, in essence constituting a bottleneck in publisher to subscriber communication. Also, different notifications had different priorities—something that was difficult to bend the infrastructure to support.
After going back and forth on the topic several times, the best structure of pub/sub services we came up with was to have a single piece of pub/sub infrastructure per logical business domain. Since each domain also had sets of commands and notifications clumped around it, it served as a good clean boundary. This partitioning solved many of the priority issues we previously had while automatically creating the first level of pub/sub infrastructure scale out.

Trouble in Paradise
One of the advantages of WCF is its support for multiple bindings on various technologies like HTTP and TCP. We originally chose to work with WS HTTP since it was the most feature rich, though not considering all the implications of that decision.
As we rolled out the system to our users, everything seemed to be going fine, but that feeling was short lived. After about an hour, we started getting calls from our help desk folks that "servers were refusing connections."
We quickly checked and saw that all our servers were up and running, but they didn't seem to be doing much. CPU usage was low, same with memory, IO, and everything else. We checked the database for deadlocks and other nasties, but everything was clear there, too.
So we started up another server process in debug mode and began watching it to see what it did. It didn't take long for the problem to show itself.
Every 10 to 20 seconds, a thread that was publishing an event to a client would hang for about 30 seconds. You can imagine what this did to our scalability. Because we were fairly close to the recommended thread pool size for the number of clients we were supporting, we were running out of threads. At that point, WCF started refusing to accept new connections from clients.
We thought maybe we had a bug in our client app that caused it to block the server.
We went hunting for the specific client machines that caused the problems (using the IP addresses we picked out from the server logs). We talked to the users of those machines to see if they had experienced any odd behaviors in the application at around the time of the server problem. They didn't report anything out of the ordinary. But one of them made an interesting observation: "The app tends to get stuck the way Outlook does, right around the time my WiFi connection cuts out."

Occasional Connectivity Affects Servers
We started collecting logs from several client and server machines and saw the same behavior over and over again. Any time a client went offline, calls to it would block for 30 seconds.
This ran counter to our understanding of the IsOneWay attribute on the OperationContract. All our event notification methods returned void—there was no reason for the server threads to get blocked.
As we drilled deeper into the behavior of WsHttpBinding we began to understand how it worked in one-way operation contracts. When the server goes to notify a client by invoking a one-way method on its proxy, if that proxy was previously connected and has in its caches all the underlying channel objects, it makes use of them and tries to call the client over HTTP. Even though the call is one-way, the underlying channel waits until an HTTP connection can be established and the HTTP request can be sent. It does not wait for the HTTP response. Unfortunately, if the client is offline for whatever reason, the HTTP connection waits the default HTTP timeout (30 seconds) before giving up.
Realizing that we couldn't fix this behavior, we needed to find an alternative binding that would be robust in the face of clients disconnecting. We found the answer in the Microsoft Message Queuing (MSMQ) bindings—specifically NetMsmqBinding. Luckily, with WCF, swapping out one binding for another isn't a big deal.
After verifying that our server threads were not getting stuck any more when client connectivity went in and out, we turned our sights back to the client.

Threading and Usability
When designing rich clients that interact with servers in a request/response manner, thread safety wasn't ever much of a concern for us. As the servers we developed got more features and became more powerful, the amount of time it took them to respond grew as well. This is known to cause usability problems when the application hangs until the server responds. The common solution is to change the client so that it calls the server asynchronously. At that point, developers find out that when callbacks from the server are handled on a background thread, UI controls tend to throw exceptions at them. Finally, the code is changed so that the server callbacks switch to the foreground thread and everything works again.
The thing is, when the client receives an endless stream of notifications from multiple servers, those patterns don't serve us as well.
Since every notification arriving at the client was being processed on the foreground thread, and all UI interaction was also done on the foreground thread, these two tasks ended up continuously fighting for control. You could actually see the mouse erratically jump on the screen as you tried to move it. When typing into textboxes, the characters would fill in just as erratically.
I noticed this when spending some time in our load testing lab. I remember looking at the client showing all the various notifications popping up in real time, very pleased with how our architecture was working out. I took the mouse to click on a link in one of the toasts and it kept getting stuck as I moved it. It reminded me of the way wireless mice behave as their batteries die. But the mouse was a regular wired USB mouse.
I winced. We were only two weeks away from a release. All our functional tests were passing, and the load tests were showing that the system could handle everything we threw at it. The only problem was that the system wasn't exactly functional under load—usability nightmare would have been a better description.

Client-side WCF
Before going back to the drawing board on our client, we looked for something—anything—that could prevent the imminent rewrite. We pored over guidance in MSDN on how to use WCF in smart client environments (see "Writing Smart Clients by Using Windows Communication Foundation") and wrote more proof of concept code than ever before, but somehow nothing covered all the bases. It seemed we were stuck between the deadlock rock and the unusable hard place.
One strategy that looked promising was based on safe controls that encapsulate the interaction with the Windows Forms synchronization context (reference) in such a way that even if they are accessed by a background thread, they marshal the call back onto the UI thread.
Since not every notification that arrives at the client involves updating the UI, we could gain a great deal in usability by performing most client-side notification processing on a background thread. Occasionally, when the notification involved updating the UI, the safe controls would ensure that the actual UI rendering was done on the correct thread. Technologically, it looked like a solid solution.
After going forward and implementing the needed safe controls and forms, we spent a good amount of time in the test lab performing functional tests while the load tests were running in the background. We had taken all the logging on the client and made it asynchronous as well so that we could keep log levels high without slowing down the UI.
In this financial application, multiple traders would collaborate on a single investment portfolio to achieve various goals in terms of risk, commission, and return—sometimes collaborating on a single trade. When we had several testers simulating this behavior, in one of the runs they had a terribly negative return. While this isn't necessarily surprising in and of itself (let's face it, if a tester could really do the work of a trader, they wouldn't be a tester), the fact that it was so different from the outcomes of the other runs made us take notice. Our previous experiences developing this system taught us that when we witnessed something unusual, it meant that some assumption we made in our programming turned out to be false.
Sifting through the piles of logs, we were looking for the moment in that one run when the financial return took a dip. Surprisingly, that was all too clear—there was one clear point where the return went into the red. As we worked our way back and forth through the log entries around that point in time, nothing stood out. Everything looked pretty much like it did when the return was positive.
One of our DBAs, an old-time UNIX hacker, bet me that with some regex (regular expressions), he could find the core difference in an hour. Since we were already 3 hours into it, I quickly conceded and, 45 minutes later, he resurfaced with a grin.
It was a context switch, and at the worst possible time, and it ended up causing a data race. One thread was setting the trade to (roughly) 90 million Yen, and the other was setting it to 1 million US dollars, one property at a time. Unfortunately, the trade ended up in the state of 1 million Yen, or $11,000 USD. That explained the dip in the financial return.
Preventing multiple threads from working with the same object at the same time isn't rocket surgery. Each thread just needs to lock the object before working with it (see Figure 1). This required a thorough pass through a lot of the client code to make sure we had locked everything we needed. It then required a fair amount of testing to shake out the deadlocks that resulted from us locking more than we needed.
Figure 1 Locking Objects
//Thread 1
void UserWantsToDoSomethingToTrade(
    Guid tradeId, double value, Currency c) {
  Trade t = InMemoryStore.Get(tradeId);
  lock(t) {
    t.Value = value;
    t.Currency = c;
  }
}

//Thread 2
void ReceivedNotificationAboutTrade(
    Guid tradeId, TradeNotification tn) {
  Trade t = InMemoryStore.Get(tradeId);
  lock(t) {
    t.Value = tn.Value;
    t.Currency = tn.Currency;
  }
}
One of the things we (very reluctantly) gave up on was data binding our in-memory objects to user-editable views. We couldn't have the user locking the object for the duration of the form being open since that could block a background thread waiting for that object from processing all the other notifications.
With a fair amount of trepidation, we put the system through the previous battery of tests, waiting for the inevitable "something else" that we didn't know about that would knock the project of its feet. Again.
As our tester-traders worked the system, it looked like the previous issues had been solved. As deeper and more involved scenarios were run through, more users and more types of users interacted with the same investment portfolio—changing risk profiles, performing what-if projections and historical comparisons. The testers really banged on the system from every direction and it held. Half-disbelieving that this might actually be it, we came back to the business with good news.
Not that they believed us. I mean, our track record wasn't particularly impressive at that point. 120% late delivery tends to erode confidence that way. But they were in dire need of the new system so that Tuesday we rolled into beta.
And on Thursday, we rolled back out.

Object-Graph Dependencies
When the profitability of a single test run is grossly different than other test runs, even financial novices like developers and testers take notice. When more delicate investment and trading rules are violated, but those don't have immediate or large-scale impact, novices don't see it. Experts do.
I won't get into the nitty gritty financial rules here, but technically the problem was that our single-object locking strategy was too simplistic for rules involving multiple objects.
It was tricky.
You see, when our calling code locked and updated one object, that object could raise an event that would be handled by multiple other objects. Each one of those objects could choose to update itself and raise events of its own, with this process percolating out affecting many objects. Of course, our calling code couldn't know how far those ripples would go so those other objects would not have been locked. Once again, we had multiple threads updating the same objects without locks.
There was talk of giving up on events and other loosely coupled communication mechanisms so that we could get some thread safety, but the thought of having to re-implement all our complex rules (that took us so long to get right) without the strengths of .NET was too much to bear.
And it wasn't just domain objects either. Controller objects could get called back as well, changing their state, too, disabling and enabling toolbar buttons and menus, popping up toast, you name it.
We needed a single global lock, yet memories of an unusable UI made us wary of such a solution. There was also the concern that even if such a lock existed, we ' d have to review every single line of code in the system to ensure that the lock was taken and released appropriately—not only for this version of the software, but for every single maintenance release and patch thereafter.
It was a case of damned if you do, damned if you don't.
And that's when we discovered synchronization domains.

Synchronization Domains
The synchronization domain provides automatic synchronization of thread access to objects declaratively. This class was introduced as a part of the infrastructure supporting .NET remoting. Developers wishing to indicate that a class is to have access to its objects synchronized must have the class inherit from ContextBoundObject and mark it with the SynchronizationAttribute like so:
[Synchronization]
public class MyController : ContextBoundObject {
  /// All access to objects of this type will be intercepted
  /// and a check will be performed that no other threads
  /// are currently in this object's synchronization domain.
}
As expected, all this magic comes with some performance overhead, both in object creation and access. Another annoying caveat is that classes involved in a synchronization domain cannot have generic methods or properties, although it can call and otherwise make use of generics from other classes.
At this point in the project, when we'd practically exhausted all other options, we gave it a shot.
We planned to have a single synchronization domain in which all logic would run. This meant controller objects, domain objects, and client-side WCF objects would need to be in the synchronization domain. In fact, the only objects that would have to be outside the synchronization domain were the Windows Forms themselves, their controls, and any other visual GUI elements.
The interesting thing we discovered was that not all objects in the synchronization domain had to inherit from ContextBoundObject or have the SynchronizationAttribute applied to them. Rather, we only needed to do so for objects on the boundaries of the synchronization domain. This meant all our domain objects could remain as before—a big performance boost.
Controller classes required just a bit more care.

View-Controller Interaction
In our use of the Model-View-Controller (MVC) pattern, controllers interacted with views only on the UI thread. This was a different approach than the safe controls previously described, where the controller could call views on the background thread as well.
We also knew that not every notification received from the server required updating the UI, and it was the responsibility of the controller objects to make that decision. As such, controllers would need to handle notifications on a background thread, and if updating the UI was required, would be responsible for switching threads.
One small thing to keep in mind, though, is to always switch threads asynchronously—otherwise you might deadlock your system or cause severe performance problems (speaking from experience).
A bit later we created a controller base class that encapsulated the threading and invoking to keep application code simple (see Figure 2).
Figure 2 Controller Base Class
[Synchronization]
public class MyController : ContextBoundObject {
  // this method runs on the background thread
  public void HandleServerNotificationCorrectly()
   {
  // RIGHT: switching threads asynchronously
  Invoker.BeginInvoke( () => CustomerView.Refresh() );

  // other code can continue to run here in the background

  // when this method completes, and the thread exits the
  // synchronization domain, the UI thread in the Refresh
  // method will be able enter this or any other synchronized object.
   }

   // this method runs on the background thread
   public void HandleServerNotificationIncorrectly()
   {
  // WRONG: switching threads synchronously
  Invoker.Invoke( () => CustomerView.Refresh() );

  // code here will NOT be run until Refresh is complete

  // DANGER! If Refresh tries to call into a controller or any other
  //         synchronized object, we will have a deadlock.
   }

   // have the main form injected into this property
   public ISynchronizeInvoke Invoker { get; set; }

   // the view we want to refresh on server notification
   public ICustomerView CustomerView { get; set; }
}
One thing we really wanted back, though, was data binding. You can hardly say you're doing MVC if your model is a collection of strings, doubles, and ints.

Thread-Safe Data Binding
The problem that we had before with data binding was that our view objects held references to model objects allowing the UI thread to update the same objects as were being updated by the background thread. As we began putting in place the ViewModel pattern, many things became much simpler—just having independent control of the structure of these objects made all the difference.
Our next step in bringing back data binding then, was to have controller objects pass clones to their views like so:
public class CustomerController : BaseController {
  // this method runs on the background thread
  public void CustomerOverdrawn(Customer c) {
    ICustomerOverdrawnView v = this.CreateCustomerOverdrawnView();

    v.Customer = c.Clone(); // always remember to clone

    this.CallOnUiThread( () => v.Show() );
  }
}
Although this technically worked, there were a couple of problems with it. The first problem was maintainability—how could we ensure that all developers remembered to clone their domain objects before passing them to views? The second problem was more technical—domain objects referenced each other so just cloning one didn't mean the others were cloned.
In short, we needed domain objects to be deep cloned as they were passed to views. It was also important that we didn't move any of this complexity into the views themselves. What we needed was to create a generic proxy of the view in CreateCustomerOverdrawnView, and in that proxy inspect all method calls and property setters for parameters that were domain objects, perform a deep clone, and then pass that clone into the view itself.
There are so many technologies that enable you to perform this proxying and each one does things different. Some use aspect-oriented programming techniques, others more straightforward hooks, but the tactics themselves aren't important. Just know that you need to create a proxy. In the proxy, include a method for the deep cloning and the accompanying dictionary for holding the working set of clones. Figure 3 shows our solution.
Figure 3 Cloning Objects for the View
// dictionary of references from source objects to their clones
// so that we always return the same clone for the same source object.
private IDictionary<object, object> sourceToClone =
  new Dictionary<object, object>();

// performs a deep clone of the given entity
public object Clone(object entity) {
  if (entity.GetType().IsValueType)
  return entity;

  if (entity is string)
  return (entity as string).Clone();

  if (entity is IEnumerable) {
    object list =
      Activator.CreateInstance(entity.GetType()) as IEnumerable;
    MethodInfo addMethod = entity.GetType().GetMethod("Add");

    foreach (object o in (entity as IEnumerable))
      addMethod.Invoke(list, new object[] {Clone(o)});

    return list;
  }

  if (sourceToClone.ContainsKey(entity))
    return sourceToClone[entity];

  object result = Activator.CreateInstance(entity.GetType());
  sourceToClone[entity] = result;

  foreach(FieldInfo field in
    entity.GetType().GetFields(BindingFlags.Instance |
    BindingFlags.FlattenHierarchy | BindingFlags.NonPublic |
    BindingFlags.Public)) field.SetValue(result,
    Clone(field.GetValue(entity)));

  return result;
}
This method goes through all properties and fields of the object, cloning them as necessary. If it finds a reference to an object it has previously cloned in the dictionary, it doesn't clone again, but returns the first clone. In this manner, the method creates a mirror image of a given graph of objects, preventing the view from gaining access to an object that may be used on a background thread.
After all this was done, our views could now freely bind to the given domain objects. What we could no longer count on was two-way data binding of domain objects automatically updating bound views.

Two-way DataBinding
In regular data binding scenarios, when the bound object is changed, it raises events letting the view know that it should be refreshed. This really helps decouple a system as the parts that handle communication with the server don't need to update any views when they update a domain object. In our new thread-safe architecture, since the client-side WCF objects don't update the same instances of domain objects as those that are bound to the views, we lose some of the benefits of two-way data binding.
It is important to understand that in a multithreaded environment we have to give up on two-way data binding. If a background thread were to update a domain object bound to the UI, the INotifyPropertyChanged (reference) behavior would cause the background thread to update the UI directly and the application to crash.
Controllers now have to take on the responsibility of knowing which view needs to be updated when. For example, when a user has a form open showing the details of a pending trade, and the client receives notification about changes to the trade, the relevant controller should update the form. Here's how we did it originally:
public class TradeController : BaseController {
  public void Init() {
    Commands.Open<Trade>.Activated += (args => {
      TradeForm f = OpenTradeForm(args.Trade);

      args.Trade.Updated += this.CallOnUiThread(
        () =>  f.TradeUpdated(args.Trade)
      );
    });
  }
}
This code handles the generic open command for a trade by opening a form and showing the requested trade. It also specifies that when the trade is updated, the form is passed the updated trade.
We were well-pleased with this clean, simple, and straightforward code.
That is, until we realized it had a bug in it.
When the user opened their second trade (or any trade after that), when any of the previous trades would be updated, the form would show the updated trade—even though the user didn't care about it anymore. We needed to be more careful in the disposal of our callbacks:
public class TradeController : BaseController {
  public void Init() {
    Commands.Open<Trade>.Activated += (args => {
      TradeForm f = OpenTradeForm(args.Trade);

      Delegate tradeUpdated = this.CallOnUiThread(
        () =>  f.TradeUpdated(args.Trade)
      );

      args.Trade.Updated += tradeUpdated;

      f.Closed += () => args.Trade -= tradeUpdated;
    });
  }
}
The difference here is that we're holding on to the reference of the delegate so that we can unsubscribe from the trade update when the form closes. Bug fixed.
Except for one little thing.
This code would be correct in a single-threaded system, but in the harsh clone-war environment of our multithreaded client, references aren't always what you think.
The trade object in eventargs came from somewhere—the activation of a command, to be specific. Commands are activated by users, on the UI thread, as the result of the user doing something—in this case, double-clicking a trade in a grid. But, if the trade is shown in a grid, that means a controller had to give it to that view, and in the process the trade would have been cloned.
In short, since any notifications from the server pertaining to that trade would not work directly with the cloned object in the grid, the Updated event the controller subscribes to above would never get raised. As such, the form showing the details of the trade would not get refreshed.
Something's missing from the solution.

Client-side Repositories
Our controllers need some way to find out when a specific instance of an entity gets updated, but without relying on object references.
If every entity had an identifier, and there was an in-memory repository of these entities on the client that could be queried, controllers could use it to get the authoritative reference for an entity based on identifiers coming from the UI.
Here is what our trade controller looks like when using the repository.
public class TradeController : BaseController {
  public void Init() {
    Commands.Open<Trade>.Activated += (args => {
      TradeForm f = OpenTradeForm(args.Trade);
      Delegate tradeUpdated = this.CallOnUiThread(
        (trade) =>  f.TradeUpdated(trade) );
      this.Repository<Trade>.When((t => t.Id == args.Trade.Id))
       .Subscribe(tradeUpdated);
      f.Closed +=
       () => this.Repository<Trade>.Unsubscribe(tradeUpdated);
    });
  }
}
Our controller is now using the repository to subscribe to changes on the specific trade instance with the identifier provided by the UI. The last piece of the puzzle is simply to have our client-side WCF objects use that same repository to update the client-side domain objects.

Performance
After putting all the pieces in place, rewriting significant parts of our client application, introducing supporting frameworks, and going through our performance testing, we discovered that there were still problems.
Under heavy load, when many objects had been updated at around the same time, large notifications being processed on the client-side caused the UI to become sluggish. Our instrumentation showed that the larger the notification, the longer the synchronization domain was held by the background thread—during which the user could not perform any actions requiring controller logic.
We tried optimizing the client-side code, refactoring domain objects so that graphs would be smaller taking less time to clone, and everything else we could think of. Nothing we did on the client helped.
And that's when one of the junior server developers spoke up (a little hesitantly), suggesting we could change the server code to publish more than one notification message. Rather than putting all changed entities in one message, we could do one entity per message, or anything else, possibly even making it configurable.
And it made all the difference in the world.
Since between processing one notification and the next the background thread on the client retreated from the synchronization domain, this allowed the UI thread to get in and do some work on behalf of the user. The fact that it took a bit longer for the large notifications to be processed one message at a time on the client was perfectly acceptable.

Lessons Learned
When we started out on the development of this project, we assumed it would be just like any other rich-client/database system. The challenges we ' d faced both architecturally and technically were greater than anything else we ' d seen. Dealing with low-level threading issues both server and client, understanding how occasional connectivity affects scalability, and maintaining an acceptable level of user interactivity while avoiding deadlocks and race conditions—there were so many pieces that had to click together just right for the whole thing to work. All the supporting technologies were there, it was all in how we put them together.
In the end, though, as we watched our users collaborating in real time across the globe, we understood that it couldn't be any other way. Companies whose systems relied on users pulling, sorting, and grouping information just wouldn't be able to compete. Software + services, occasionally connected clients, and the multicore revolution would mean ever greater productivity and profitability for an organization able to make the leap.
Our stakeholder was right. The ability to surface events from the world to the user in real time really is critical for knowledge workers to support collaborative, real-time enterprises.
After finishing the project I was a little concerned that all the patterns and techniques I'd picked up wouldn't serve me at all as I transitioned in to more line-of-business style application development. I've got to tell you that I was pleasantly surprised.
On a more personal note, I can tell you that nothing does better for a developer's career than line-of-business managers raving about your app, and the development itself is much more interesting. Give it a try.

Udi Dahan is The Software Simplist, an MVP and Connected Technologies Advisor working on WCF, WindowsWF, and "Oslo." He provides training, mentoring, and high-end architecture consulting services, specializing in service-oriented, scalable, and secure .NET architecture design. Udi can be contacted via his blog: www.UdiDahan.com.


Dynamic WPF
Create Flexible UIs With Flow Documents And Data Binding
Vincent Van Den Berghe
Code download available from the MSDN Code Gallery
Browse the Code Online

This article discusses:
  • Flow Documents
  • Data binding issues
  • Building a data-bound control
  • Using templates
This article uses the following technologies:
WPF, .NET 3.5 SP1
Contents
Objective
The Bindable Run
Templates for FrameworkContentElements
The ItemsContent Implementation
Conclusion
Flow documents are ideal for displaying read-only data in Windows Presentation Foundation (WPF). They offer enormous flexibility in arranging text layout and pagination. In addition, flow document controls provide you with annotations, printing support and clipboard functionality almost for free. Doing this with traditional WPF controls (TextBlock, ItemsControl and derivatives) is much more difficult.
While there are many great features in flow documents, if your documents are generated from dynamic data, you have a bit of a problem: there is no support for data binding in flow documents. The flow document elements (Section, Table, Run, Paragraph and the like) are dependency objects, but don't define any dependency properties that would allow you to dynamically change or generate content.
Any update to portions of the flow document must be done by the component that generated the flow document in the first place, since flow documents do not support data binding directly. In this respect, flow documents are much less flexible than the other WPF framework elements.
Adding the missing dependency properties looks like an easy solution but sadly, this isn't the case. As often is the case, the devil is in the details, and you'll have to get quite a few details right to make it work well.

To make this problem more concrete, consider the following simple XML document sample contained in an XmlDataProvider:
<XmlDataProvider x:Key="DataSource">
    <x:XData>
        <NorthwindNames >
            <Person FirstName="Nancy" LastName="Davolio" />
            <Person FirstName="Andrew" LastName="Fuller" />
            <Person FirstName="Janet" LastName="Leverling" />
            <Person FirstName="Margaret" LastName="Peacock" />
            <Person FirstName="Steven" LastName="Buchanan" />
        </NorthwindNames>
    </x:XData>
</XmlDataProvider>
Displaying this data using normal data binding methods and our trusty ListView control is a piece of cake. Here's the code:
<ListView ItemsSource="{Binding Source={StaticResource DataSource},  XPath=NorthwindNames/Person}">
    <ListView.View>
        <GridView>
            <GridViewColumn Header="First name"
              DisplayMemberBinding="{Binding XPath=@FirstName}" />
            <GridViewColumn Header="Last name"
              DisplayMemberBinding="{Binding XPath=@LastName}" />
        </GridView>
    </ListView.View>
</ListView>
The result is as expected, as you can see in Figure 1.
Figure 1 The Data in a ListView
Now I want to show this as a table in a flow document. Ideally, I would like a component similar to ListView, but which understands binding to an item's source, and which can generate the table content dynamically inside a FlowDocument. In other words, I need a kind of ItemsControl, but for flow documents. And no cheating with InlineUIContainer or BlockUIContainer: although these allow you to embed any WPF control like ListView, you'll lose their content when copying to the clipboard. Embedding controls this way doesn't magically turn them into flow document elements.
Such a component doesn't exist, so I'll need to write it myself. I'll call it ItemsContent, to reflect the fact that it generates flow content for data items. To get a better idea about what I need to design, let's think about what the markup of that component would look like. Inspired by features ItemsControl provides, something like Figure 2 would fit the bill nicely.
Figure 2 The ItemsContent Control
<ItemsContent ItemsSource="{Binding Source={StaticResource DataSource},  XPath=NorthwindNames/Person}" >
    <ItemsContent.ItemsPanel>
        <DataTemplate>
            <Table BorderThickness="1" BorderBrush="Black">
                <TableRowGroup IsItemsHost="True">
                    <TableRow Background="LightBlue">
                        <TableCell>
                            <Paragraph>First name</Paragraph>
                        </TableCell>
                        <TableCell>
                            <Paragraph>Last name</Paragraph>
                        </TableCell>
                    </TableRow>
                </TableRowGroup>
            </Table>
        </DataTemplate>
    </ItemsContent.ItemsPanel>
    <ItemsContent.ItemTemplate>
        <DataTemplate>
            <TableRow>
                <TableCell>
                    <Paragraph>
                        <Run Text="{Binding XPath=@FirstName}"/>
                    </Paragraph>
                </TableCell>
                <TableCell>
                    <Paragraph>
                        <Run Text="{Binding XPath=@LastName}"/>
                    </Paragraph>
                </TableCell>
            </TableRow>
        </DataTemplate>
    </ItemsContent.ItemTemplate>
</ ItemsContent>
As you can see, the markup follows the pattern of the existing ItemsControl closely. There's an ItemsPanel template which determines how the generated flow document content will be embedded.
The ItemsPanel tells the control to generate a two-column table with fixed header information in the first row, with a light blue background. Additional rows will be appended to the TableRowGroup containing IsItemsHost="True" (which happens to be that same table row group as our header, which is OK). This is similar to how you mark a panel hosting items in the ItemsPanel template of a ItemsControl.
The ItemTemplate will determine the content to be generated for each item in our ItemsSource.
These rows will be appended to the TableRowGroup in our ItemsPanel as explained above.
Executing this markup against the XML document would generate the FlowDocument fragment shown in Figure 3.
Figure 3 FlowDocument Excerpt
<Table BorderThickness="1" BorderBrush="Black">
    <TableRowGroup>
        <TableRow Background="LightBlue">
            <TableCell><Paragraph>First name</Paragraph></TableCell>
            <TableCell><Paragraph>Last name</Paragraph></TableCell>
        </TableRow>
        <TableRow>
            <TableCell><Paragraph>Nancy</Paragraph></TableCell>
            <TableCell><Paragraph>Davolio</Paragraph></TableCell>
        </TableRow>
        <TableRow>
            <TableCell><Paragraph>Andrew</Paragraph></TableCell>
            <TableCell><Paragraph>Fuller</Paragraph></TableCell>
        </TableRow>
        <TableRow>
            <TableCell><Paragraph>Janet</Paragraph></TableCell>
            <TableCell><Paragraph>Leverling</Paragraph></TableCell>
        </TableRow>
        <TableRow>
            <TableCell><Paragraph>Margaret</Paragraph></TableCell>
            <TableCell><Paragraph>Peacock</Paragraph></TableCell>
        </TableRow>
        <TableRow>
            <TableCell><Paragraph>Steven</Paragraph></TableCell>
            <TableCell><Paragraph>Buchanan</Paragraph></TableCell>
        </TableRow>
    </TableRowGroup>
</Table>
That code, in turn, renders the table in Figure 4.
Figure 4 The Data in a Flow Document
Figure 5 BindableRun
public class BindableRun : Run
    {
        public static readonly DependencyProperty BoundTextProperty =
          DependencyProperty.Register("BoundText", typeof(string), typeof(BindableRun),
          new PropertyMetadata(OnBoundTextChanged));

        public BindableRun()
        {
            Helpers.FixupDataContext(this);
        }

        private static void OnBoundTextChanged(DependencyObject d,
            DependencyPropertyChangedEventArgs e)
        {
            ((Run)d).Text = (string)e.NewValue;
        }

        public String BoundText
        {
            get { return (string)GetValue(BoundTextProperty); }
            set { SetValue(BoundTextProperty, value); }
        }
    }
Wouldn't it be nice if we had such a thing? As you can see, this component is remarkably flexible. Besides data binding, it also enables the use of templates in flow documents. It doesn't solve every flow document data binding problem out there, but if we can pull this off, all other data binding problems will look almost trivial in comparison.
In the remainder of the article I'll show how to build such a beast, or at least something that resembles it closely. In addition, I hope to provide sufficient background information for you to tackle any other flow document data binding problem. Read on.

The Bindable Run
If you search the Web for flow documents and data binding examples, you're bound (so to speak) to stumble across BindableRun (fortes.com/2007/03/bindablerun). It comes in many flavors, and in its simplest form looks like Figure 5.
The implementation is straightforward: we inherit from Run, define a dependency property BoundText, and synchronize Run's Text property with its value. Run is a dependency object, but its Text content isn't a dependency property. BoundText is simply the dependency property version of Text, which allows us to use data binding expressions. It's that simple.
Its usage is therefore straightforward. Instead of <Run …/>, you use the following code where flowdoc is the XML namespace where your definitions reside:
<flowdoc:BindableRun BoundText="{Binding …}" />
Unfortunately, this class will sometimes fail. Specifically, the exception "Collection was modified; enumeration operation may not execute" will be thrown if the binding expression for BoundText depends on the value of an inherited dependency property such as DataContext, and binding evaluation was performed during inheritance propagation. (See the MSDN forum thread about data flow for an explanation of that error.)
In the light of the component we're trying to develop, it's important to fully understand the mechanism that causes this exception, because you'll face it again. For this, you need to look deeply into WPF to see what happens during property value inheritance for objects whose type derives from FrameworkContentElement. We can restrict ourselves to classes that derive from FrameworkContentElement, since all flow document elements derive from it. (For a discussion about FrameworkContentElement and FrameworkElement see wpfdisciples.wordpress.com/2008/10/09.)
When the value of an inheritable dependency property like DataContext is set on some logical ancestor of a flow document element, the following actions happen:
  • DependencyObject.SetValue is called to set the value of the dependency property on the ancestor object.
  • DependencyObject calls its internal NotifyPropertyChange method.
  • NotifyPropertyChange calls the virtual method OnNotifyPropertyChange, which is overridden by FrameworkContent-Element.
  • FrameworkContentElement's implementation of OnNotifyPropertyChange realizes that an inheritable property has changed, and it needs to notify all its (logical) descendants of that fact.
For this purpose, the internal TreeWalkHelper.InvalidateOnInheritable method is called, which recursively enumerates all the descendants (using the internal class DescendantsWalker) and visits each one, calling TreeWalkHelper.OnInheritablePropertyChanged for each.
So far so good. As long as you're working with standard flow document elements, the above steps will always succeed. But if one of your descendants in the inheritance chain is the BindableRun defined earlier and your BoundText depends on the inherited DataContext value, then the following happens during value propagation:
  • The value for the dependency property BoundText is changed due to the reevaluation of its associated binding expression.
  • BindableRun.OnBoundTextChanged is fired and sets the Text property.
  • The setter for Text calls BeginChange on the Run's TextContainer and TextContainer increments its generation number (essentially an internal version number used to track changes to the container).
  • The current active enumerator TreeWalkHelper was using (a RangeContentEnumerator) detects the change of generation number during its next call to MoveNext() and fails with the exception "Collection was modified; enumeration operation may not execute."
You can't solve this problem, since the above process is baked into WPF and the crucial types and methods implementing it are internal. You can, however, circumvent the problem by "breaking" the value propagation. One way of doing this is to bind BindableRun's DataContext to the corresponding property of a FrameworkElement ancestor. This is so useful that I've put it in its own helper class:
public static void FixupDataContext(FrameworkContentElement element)
{
    Binding b = new Binding(
      FrameworkContentElement.DataContextProperty.Name);
    b.RelativeSource = new RelativeSource(
      RelativeSourceMode.FindAncestor,
      typeof(FrameworkElement), 1);
element.SetBinding(FrameworkContentElement.DataContextProperty, b);
}
Potentially, this workaround needs to be applied for all the flow document elements we derive from.
This works, as long as a FrameworkElement always exists up in the logical parent chain, and the dependency property (BoundText in case of BindableRun) doesn't depend on any other inherited property propagated by the system.
By design, the first point will always be true (reading the next section will make you understand why). However, you can't always be sure of the second; clearly, some data binding scenarios will cause this workaround to fail, and you'll have to revisit it later.

Templates for FrameworkContentElements
To implement the control, you need the flexibility of templates. Ideally, you want to be able to define fragments of flow documents in data templates. With BindableRun already at your disposal, you want to write the code in Figure 6. Here flowdoc is the chosen namespace where you defined the new classes.
Figure 6 New Classes in flowdoc
<DataTemplate>
    <TableRow>
        <TableCell>
            <Paragraph>
                <flowdoc:BindableRun BoundText="{Binding XPath=@FirstName}" />
            </Paragraph>
        </TableCell>
        <TableCell>
            <Paragraph>
                <flowdoc:BindableRun BoundText="{Binding XPath=@LastName}"/>
            </Paragraph>
        </TableCell>
    </TableRow>
</DataTemplate>
Try this in your favorite designer (using DataTemplate or ControlTemplate, it doesn't matter), and you'll get the following error:
"Property 'VisualTree' does not support values of type 'TableRow'."
VisualTree is the default content property of FrameworkTemplate, the common base type of both DataTemplate and ControlTemplate. The documentation for FrameworkTemplate is sparse, but its description clearly states that it enables the instantiation of a tree of FrameworkElement and/or FrameworkContentElement objects.
Figure 7 FrameworkElement and FrameworkContentElement
This description is misleading or incomplete at best. It turns out that a FrameworkTemplate can instantiate only a tree whose root node is a FrameworkElement. If you need to instantiate a tree whose root is a FrameworkContentElement, you're out of luck. As the error message indicates, the VisualTree property is the key to understanding this: it points to a FrameworkElementFactory, which can only produce FrameworkElements, at least as root nodes.
This, by the way, is why a FrameworkElement always exists up in the logical parent chain, as noted in the previous section.
You may wonder why such restriction exists. Indeed, this need not be a conceptual limitation; one can easily see the usefulness of templates that are able to generate instances of both classes. Moreover, the public and protected members of both classes are very similar, and they implement many of the same interfaces (IFrameworkInputElement, IInputElement, ISupportInitialize).
One of the key differences that prevents factoring out their commonalities is the fact that they occur at different points in the inheritance hierarchy, as you see in Figure 7.
This looks like a job for mix-in classes, but for this you need multiple inheritance, which isn't possible in .NET. Maybe there's truth in the old saying that you don't need multiple inheritance often, but if you do, you need it badly.
Still, one wonders if the design couldn't have been better. A closer examination of the implementation of FrameworkElementFactory shows a hardcoded knowledge of types like Grid, GridViewRowPresenter, RowDefinition, ColumnDefinition and Visual3D. One would expect the knowledge of constructing specific instances of types to be abstracted from the implementation of their common factory. Otherwise, you end up with a very rigid and inextensible factory implementation, which, in addition, will force you to revisit it every time you add another special type to the system (and you should somehow know which types are special). This smells like a violation of the Open/Closed design principles.
Since we have insufficient information to ascertain what should have been done (and we can't change a thing anyway), I'll leave this discussion here and focus on a solution: how do we define templates of FrameworkContentElements? The easiest solution, requiring the least amount of code, is to build a bridge between the two types.
Such bridges already exist in WPF: The BlockUIContainer is a flow document element for embedding UIElements in flow documents. So it's a bridge, but we need one in the opposite direction.
Another existing bridge is a TextBlock: a FrameworkElement that can contain a collection of inlines, which are a special kind of FrameworkContentElement. If you restrict yourself to inlines, this would be perfect, but you don't want this restriction. That bridge is too small for your purposes.
It turns out that the bridge class is easy to write. Let's call it Fragment, because it will hold fragments of flow documents (see Figure 8).
Figure 8 The Fragment Class
[ContentProperty("Content")]
public class Fragment : FrameworkElement
{
    private static readonly DependencyProperty ContentProperty = DependencyProperty.Register("Content",
    typeof(FrameworkContentElement), typeof(Fragment));

    public FrameworkContentElement Content
    {
        get
        {
            return (FrameworkContentElement)GetValue(ContentProperty);
        }
        set
        {
            SetValue(ContentProperty, value);
        }
    }
}
As you can see, there's nothing earth-shattering here: it's a simple class deriving from FrameworkElement (of course), with a dependency property holding a FrameworkContentElement root as default content.
With this class, you can now write something like this:
<DataTemplate>
    <flowdoc:Fragment>
        <TableRow>…</TableRow>
    </flowdoc:Fragment>
</DataTemplate>
To make use of these template definitions, you need to be able to load it at some point. You need a way to specialize the template-loading mechanism and return the content of the fragment. You can take care of this once and for all in another helper function, which is shown in Figure 9.
Figure 9 Helper Function
public static FrameworkContentElement LoadDataTemplate     (DataTemplate dataTemplate)
{
    object content = dataTemplate.LoadContent();
    if (content is Fragment)
        return (FrameworkContentElement)((Fragment)content).Content;
    else if (content is TextBlock)
    {
        InlineCollection inlines = ((TextBlock)content).Inlines;
        if (inlines.Count == 1)
            return inlines.FirstInline;
        else
        {
            Paragraph paragraph = new Paragraph();
            while (inlines.FirstInline != null)
                paragraph.Inlines.Add(inlines.FirstInline);
            return paragraph;
        }
    }
    else
        throw new Exception("Data template needs to contain a <Fragment> or <TextBlock>");
}
This helper function also handles the existing TextBlock bridge. If the TextBlock contains only one inline element, that element is returned. Otherwise, the entire inline collection is nicely wrapped in a Paragraph. This wrapping is needed, because an InlineCollection is itself not a FrameworkContentElement.
Note that the obvious way to move inline elements from one text container to another does not work:
foreach (var inline in inlines)
    paragraph.Inlines.Add(inline);
The code will throw the exception "Collection is modified, enumeration operation may not execute" as described before, and for similar reasons: adding an element from one text container (a TextBlock) to another (a Paragraph) implicitly removes it from the first text container, causing its generation number to change. Since a TextElementEnumerator, like a RangeContentEnumerator, also checks for its TextContainer generation number, the same exception will be thrown.
The difference between this situation and the previous one is that you now have sufficient control to circumvent the problem at the source. That's why you can write the following, which accomplishes the same thing, but without using an enumerator:
while (inlines.FirstInline != null)
    paragraph.Inlines.Add(inlines.FirstInline);

The ItemsContent Implementation
You almost have all the pieces of the puzzle for your implementation, but there's one design decision left to make. You need to decide whether your flow content element will be a block-level element or an inline-level element. The decision is arbitrary, but one needs to make it, since no control can be both.
In this article, the ItemsContent control will be a block-level element. The inline version is left as an exercise for the reader. I won't derive from Block directly, but from Section, which has a convenient Blocks collection property, to which I'll add my dynamic content. Section also doesn't apply any default formatting to the elements it contains, which is exactly what I need for a custom control.
Be careful about which base class you derive from. You may be tempted to derive from Block directly, but you won't get far. Crucial helper classes like BlockCollection (a derivative of the generic TextElementCollection<>) have internal constructors and are therefore unusable in your own code.
Basically, the implementation of ItemsContent is straightforward: just a bunch of dependency properties, and the usual suspects to track their changes. The real action happens in the GenerateContent method, which is the guts of the control and deserves closer inspection (see Figure 10). (Note, the remainder of the code can be found in the code download.)
Figure 10 The GenerateContent Method
private void GenerateContent(DataTemplate itemsPanel, DataTemplate   itemTemplate, IEnumerable itemsSource)
    {
        Blocks.Clear();
        if (itemTemplate != null && itemsSource != null)
        {
            FrameworkContentElement panel = null;

            foreach (object data in itemsSource)
            {
                if (panel == null)
                {
                    if (itemsPanel == null)
                        panel = this;
                    else
                    {
                        FrameworkContentElement p = Helpers.LoadDataTemplate(itemsPanel);
                        Blocks.Add((Block)p);
                        panel = Attached.GetItemsHost(p);
                        if (panel == null)
                            throw new Exception("ItemsHost not found. Did you forget to specify
                                                Attached.IsItemsHost?");
                    }
                }
                FrameworkContentElement element = Helpers.LoadDataTemplate(itemTemplate);
                element.DataContext = data;
                Helpers.UnFixupDataContext(element);
                if (panel is Section)
                    ((Section)panel).Blocks.Add(Helpers.ConvertToBlock(data, element));
                else if (panel is TableRowGroup)
                    ((TableRowGroup)panel).Rows.Add((TableRow)element);
                else
                    throw new Exception(String.Format("Don't know how to add an instance of {0}
                    to an instance of {1}", element.GetType(), panel.GetType()));
            }
        }
    }

    private void GenerateContent()
    {
        GenerateContent(ItemsPanel, ItemTemplate, ItemsSource);
    }

    private void OnItemsSourceChanged(IEnumerable newValue)
    {
        if (IsLoaded)
            GenerateContent(ItemsPanel, ItemTemplate, newValue);
    }

    private void OnItemTemplateChanged(DataTemplate newValue)
    {
        if (IsLoaded)
            GenerateContent(ItemsPanel, newValue, ItemsSource);
    }

    private void OnItemsPanelChanged(DataTemplate newValue)
    {
        if (IsLoaded)
            GenerateContent(newValue, ItemTemplate, ItemsSource);
    }

    private static void OnItemsSourceChanged(DependencyObject d,
        DependencyPropertyChangedEventArgs e)
    {
        ((ItemsContent)d).OnItemsSourceChanged((IEnumerable)e.NewValue);
    }

    private static void OnItemTemplateChanged(DependencyObject d,
        DependencyPropertyChangedEventArgs e)
    {
        ((ItemsContent)d).OnItemTemplateChanged((DataTemplate)e.NewValue);
    }

    private static void OnItemsPanelChanged(DependencyObject d,
        DependencyPropertyChangedEventArgs e)
    {
        ((ItemsContent)d).OnItemsPanelChanged((DataTemplate)e.NewValue);
    }

    private void GenerateContent(DataTemplate itemsPanel, DataTemplate     itemTemplate,
        IEnumerable itemsSource)
    {
        Blocks.Clear();
        if (itemTemplate != null && itemsSource != null)
        {
            FrameworkContentElement panel = null;

            foreach (object data in itemsSource)
            {
                if (panel == null)
                {
                    if (itemsPanel == null)
                        panel = this;
                    else
                    {
                        FrameworkContentElement p = Helpers.LoadDataTemplate(itemsPanel);
                        if (!(p is Block))
                            throw new Exception("ItemsPanel must be a block element");
                        Blocks.Add((Block)p);
                        panel = Attached.GetItemsHost(p);
                        if (panel == null)
                            throw new Exception("ItemsHost not found. Did you forget to specify
                            Attached.IsItemsHost?");
                    }
                }
                FrameworkContentElement element = Helpers.LoadDataTemplate(itemTemplate);
                element.DataContext = data;
                Helpers.UnFixupDataContext(element);
                if (panel is Section)
                    ((Section)panel).Blocks.Add(Helpers.ConvertToBlock(data, element));
                else if (panel is TableRowGroup)
                    ((TableRowGroup)panel).Rows.Add((TableRow)element);
                else
                    throw new Exception(String.Format("Don't know how to add an instance of {0} to
                    an instance of {1}", element.GetType(), panel.GetType()));
            }
        }
    }
}    }
The first order of business when generating or regenerating the content is to clear the Blocks collection. A simple Blocks.Clear(); effectively clears the content of the section control.
Next, you need to determine the panel you'll use to host your content. If an ItemsPanel template hasn't been specified, the ItemsContent control itself will be the host:
if (itemsPanel == null)
    panel = this;
Otherwise, the ItemsPanel template will be loaded and added to the final content, and the element specifying IsItemsHost will be used as the panel to host the content. Note that because the control is a block element, the panel is also assumed to be a block element.
FrameworkContentElement p = Helpers.LoadDataTemplate(itemsPanel);
if (!(p is Block))
   throw new Exception("ItemsPanel must be a block element");
Blocks.Add((Block)p);
panel = Attached.GetItemsHost(p);
if (panel == null)
   throw new Exception("ItemsHost not found. Did you forget to specify Attached.IsItemsHost?");
The IsItemsHost is defined as an attached property, because you want to be able to specify any (block) element as a host for your items. This has been neatly encapsulated in the Attached class, whose trivial implementation I won't discuss here.
All this is performed only once, if there is at least one item in the ItemsSource. For every item in the items source, the ItemTemplate is loaded, and the data context of the element is set to our current item:
FrameworkContentElement element = Helpers.LoadDataTemplate(itemTemplate);
element.DataContext = data;
Helpers.UnFixupDataContext(element);
The crucial thing to do at each iteration is to set the data context to the "current" item. This will enable the familiar per-item binding scenarios. The assignment is necessary but not sufficient: remember that for items like BindableRun, we've changed the DataContext binding behind the scenes. As a result, the DataContext property for these items will never have the intended value.
To make it work correctly, you need to remove all these bindings. This is the task of the Helpers.UnFixupDataContext function. That helper function traverses the logical tree, removing all bindings that were set by Helpers.FixupDataContext.
Note that the order of execution is extremely important. If you called Helpers.UnFixupDataContext before assigning the data context, the "Collection was modified; enumeration operation may not execute" exception would raise its ugly head again. You need to set the DataContext first, and then remove all your implicit bindings, one item at a time.
This makes the implementation of Helpers.UnFixupDataContext a little unusual, because the logical tree traversal is careful enough not to use any enumerators that could fail. There's one function that removes a single binding and then returns. It's shown in Figure 11.
Figure 11 InternalUnFixupDataContext
private static bool InternalUnFixupDataContext(DependencyObject dp)
{
// only consider those elements for which we've called
// FixupDataContext():
// they all belong to this namespace
if (dp is FrameworkContentElement && dp.GetType().Namespace ==
    typeof(Helpers).Namespace)
    {
        Binding binding = BindingOperations.GetBinding(dp,
            FrameworkContentElement.DataContextProperty);
        if (binding != null
            && binding.Path != null && binding.Path.Path ==
            FrameworkContentElement.DataContextProperty.Name
            && binding.RelativeSource != null && binding.RelativeSource.
            Mode == RelativeSourceMode.FindAncestor && binding.RelativeSource.
            AncestorType == typeof(FrameworkElement) && binding.RelativeSource.
            AncestorLevel == 1)
                   {
                       BindingOperations.ClearBinding(dp, FrameworkContentElement.
                       DataContextProperty);
                       return true;
                   }
    }
    // as soon as we have disconnected a binding, return. Don't continue
    //the enumeration,
    // since the collection may have changed
    foreach (object child in LogicalTreeHelper.GetChildren(dp))
        if (child is DependencyObject)
            if (InternalUnFixupDataContext((DependencyObject)child))
                return true;
    return false;
}
If a binding was undone, the function returns true, otherwise it returns false. The function is continually called until no bindings are left to undo, as you see here:
public static void UnFixupDataContext(DependencyObject dp)
{
    while (InternalUnFixupDataContext(dp))
        ;
}
It's a little inefficient, but doesn't harm any enumerators in the process.

Conclusion
I set out to write a control that would enable you to use data binding and templates in flow documents. I even wrote the markup I would like to use. The control has been developed, and Figure 12 shows the final markup for the example.
Figure 12 The Final Markup
<flowdoc:ItemsContent ItemsSource="{Binding Source=  {StaticResource DataSource},XPath=FortressGuys/Person}" >
    <flowdoc:ItemsContent.ItemsPanel>
        <DataTemplate>
            <flowdoc:Fragment>
                <Table BorderThickness="1" BorderBrush="Black">
                    <TableRowGroup flowdoc:Attached.IsItemsHost="True">
                        <TableRow Background="LightBlue">
                            <TableCell>
                                <Paragraph>First name</Paragraph>
                            </TableCell>
                            <TableCell>
                                <Paragraph>Last name</Paragraph>
                            </TableCell>
                        </TableRow>
                    </TableRowGroup>
                </Table>
            </flowdoc:Fragment>
        </DataTemplate>
    </flowdoc:ItemsContent.ItemsPanel>
    <flowdoc:ItemsContent.ItemTemplate>
        <DataTemplate>
            <flowdoc:Fragment>
                <TableRow>
                    <TableCell>
                        <Paragraph>
                            <flowdoc:BindableRun BoundText="{Binding XPath=@FirstName}" />
                        </Paragraph>
                    </TableCell>
                    <TableCell>
                        <Paragraph>
                            <flowdoc:BindableRun BoundText="{Binding XPath=@LastName}"/>
                        </Paragraph>
                    </TableCell>
                </TableRow>
            </flowdoc:Fragment>
        </DataTemplate>
    </flowdoc:ItemsContent.ItemTemplate>
</flowdoc:ItemsContent>
As you can see, this markup is quite close to what I wished for originally. Improvements are always possible, but for the amount of code we had to write, this is a very good result indeed. Mission accomplished. The accompanying code in the code download shows the component in action.

Vincent Van Den Berghe holds Masters degrees in Computing Science and Artificial Intelligence. He is a software engineer working for Bureau van Dijk Electronic Publishing. His current work involves developing LOB applications with WCF and WPF. Vincent is an ACM (Association for Computing Machinery) professional member.


Cloud Computing
Building Distributed Applications With .NET Services
Aaron Skonnard

This article is based on a prerelease version of .NET Services. All information is subject to change.
This article discusses:
  • Understanding .NET Services
  • Confi guring the .NET Access Control Service
  • Communicating Through the .NET Service Bus
  • Building a cloud workfl ow
This article uses the following technologies:
Azure Services Platform, .NET Services
Contents
.NET Services
What's in .NET Services?
Creating a .NET Services Solution
Installing the .NET Services SDK
The .NET Access Control Service
Configuring a Service
The .NET Service Bus
Communicating Through the .NET Service Bus
The .NET Workflow Service
Building a Cloud Workflow
At the 2008 Professional Developers Conference (PDC) in Los Angeles, Microsoft announced an ambitious new cloud computing strategy that will unfold over the next few years. The Microsoft cloud platform—officially known as the Azure Services Platform—makes it easy for .NET developers to move their applications (or portions thereof) to the cloud using the same tools and APIs they're already familiar with.
Windows Azure lays the foundation of the Microsoft cloud platform. Think of Windows Azure as a Windows-based cloud operating system. It provides a highly-scalable execution environment for running .NET applications and storing data in Microsoft data centers throughout the world. Building applications on Windows Azure can shield you from many of the costly and troublesome infrastructure aspects of your app, allowing you to focus instead on development and your business.
Microsoft provides several service offerings built on the Windows Azure foundation, including .NET Services, SQL Services, Live Services, SharePoint Services, and more. Combining these service offerings with the Windows Azure foundation forms the complete Azure Services Platform (see Figure 1). Each of these service offerings includes multiple individual services that you can choose to call upon in your applications. Microsoft is actively building on the Azure Services Platform in various consumer-facing applications such as Windows Live, Microsoft Office Live, Microsoft Exchange Online, Microsoft SharePoint Online, as well as others. You have the opportunity to do the same, taking advantage of whatever Azure services provide value to you.
Figure 1 The Azure Services Platform
Throughout the rest of this article,I am going to dive into the .NET Services offering within the Azure Services Platform, based on the November/December 2008 CTP release. As you can see from Figure 1, this is only one small piece of the broader cloud platform strategy but it's one of particular interest to .NET developers moving towards the cloud.

.NET Services
If you consider yourself a Microsoft connected systems developer using technologies like Windows Communication Foundation (WCF), Windows Workflow Foundation (WF), and BizTalk Server, you'll want to pay particular attention to .NET Services. This is where most of the technologies you care about will appear within the Azure Services Platform. (It's interesting to note that the original name for the incubation project was "BizTalk Services." The official name—.NET Services—was announced at the PDC along with Windows Azure.)
If you like to think of Windows Azure as "Windows in the cloud," you can think of .NET Services as "the Microsoft .NET Framework in the cloud." Today, .NET developers rely heavily on the .NET Framework for building applications targeting the Windows platform. The .NET Framework provides common building blocks required by many applications, making it easier to get them up and running quickly. .NET Services plays a similar role the Azure Services Platform by providing some common building blocks that make it easier to write cloud-based applications.
Despite the similarities, there's also a striking difference between the .NET Framework and .NET Services. While the .NET Framework provides building blocks in the form of .NET assemblies, .NET Services provides building blocks in the form of hosted services running within Microsoft data centers. When using .NET Services, there's a clear boundary between your on-premise logic and the .NET Services running in the cloud. It's your job to compose these services into your business solutions. Microsoft will host, manage, and maintain the hosted services that your applications depend on.
You program against .NET Services by integrating with the individual services it provides. Although it's called ".NET" Services, you don't actually have to use .NET to accomplish this; you can integrate with .NET Services through the standard SOAP and REST interfaces it exposes. Microsoft provides a .NET Services SDK that optimizes the .NET developer experience, and there are even Java and Ruby SDKs available from the community.

What's in .NET Services?
If you consider what it would take to move your application to a cloud platform, there are a few common requirements you'll most likely run into. First, you'll need a way to describe and package your business processes, or workflows, so they can be executed and managed in the cloud. Second, you'll need a way to communicate between your cloud-based workflows and your on-premise applications, traversing any firewalls or network address translation (NAT) devices that might be in the way. And third, you'll need a way to secure communication and control access to your various cloud-based resources.
Most cloud applications need to deal with at least one of these requirements. If you had to build this type of infrastructure yourself, it would drastically change the overall value proposition. These are precisely the areas that .NET Services focuses on in the November/December 2008 CTP version.
Specifically, .NET Services fulfills these cloud infrastructure needs through three individual building block services: the .NET Workflow Service, the .NET Service Bus, and the .NET Access Control Service (see Figure 2 for details).
Figure 2 .NET Services components
Service | Description
.NET Workflow Service | This component provides infrastructure for hosting and managing WF workflows within the Azure Services Platform. It also provides cloud-centric activities and tools for deploying, managing, and tracking running workflow instances.
.NET Service Bus | This component provides a relay service that makes it possible to establish connectivity through the cloud across organizational boundaries. This crucial infrastructure allows cloud-based workflows to communicate with on-premise applications by traversing firewalls and NAT devices.
.NET Access Control Service | This component provides a claims-based access control mechanism in the cloud that composes with WS-Security features. It also meets the federation requirements inherent in most cloud scenarios, including interoperability with identity providers like Active Directory and Windows Live ID.
The .NET Service Bus relies on the .NET Access Control Service to control access to the relay service by both senders and listeners. This means all senders and listeners must first obtain a token from the .NET Access Control Service before they can use the .NET Service Bus. The .NET Workflow Service integrates with the .NET Service Bus to make it possible to transmit messages through the relay service, enabling a variety of interesting communication scenarios within your cloud-based workflows. Together these services provide a compelling development fabric for building applications in the cloud.

Creating a .NET Services Solution
Before you can get started with .NET Services, you'll need to visit the Azure Services Platform portal and create a solution. This article is based on the November/December 2008 CTP release, for which you'll need an invitation token before you can create a .NET Services solution. You can obtain an invitation token by following the "Try it now" links on the Azure Services Platform portal.Windows Azure and .NET Services require different invitation tokens, so make sure you request a .NET Services token, too. Once approved, you'll receive your .NET Services invitation token via e-mail.
Once you've received an invitation code, you can browse to the .NET Services area within the portal and create a new solution. You'll have to enter a valid invitation code and specify a solution name, then it will provision a new .NET Services solution and provide you with a solution password. (The solution name serves as the username for authentication purposes.)
During the provisioning process, you'll be required to sign in using a Windows Live ID (WLID) so the new solution can be associated with your account. Multiple solutions can be associated with a single WLID, but each solution requires a unique invitation code today. Whenever you login into the portal with your WLID, you'll see all of your solutions listed under "My Solutions" on the right side of the page. When you select a specific solution, it will take you to a page for managing different aspects of .NET Services within that specific solution (see Figure 3).
Figure 3 Managing a Solution
A solution is basically a top-level container for managing your various .NET Services assets. For example, it's a container for your .NET Service Bus endpoints, your .NET Workflow Service types and instances, and your .NET Access Control Service identities and claims transformation rules.

Installing the .NET Services SDK
You'll also need to download and install the .NET Services SDK, which you can also obtain from the Azure Services Platform portal. When you install the SDK, it will add several .NET assemblies to your machine and some Visual Studio add-ins that make it easier to integrate with .NET Services programmatically.
You'll find the new assemblies in the installation directory, which is located by default in \Program Files\Microsoft .NET Services SDK. The key assemblies include Microsoft.ServiceBus.dll, Microsoft.Workflow.Activities.dll, and Microsoft.AccessControl.Management.dll. The installation directory also contains samples illustrating how to use each service and the key features provided by each service. Be sure to check out the various samples as you begin your journey.
If you start Visual Studio, you'll also notice a new project template called CloudSequentialWorkflow (under the CloudWorkflow project type). Use this project template to create WF workflows that you want to host in the .NET Workflow Service. The SDK also installs a Visual Studio add-in that makes it easy to deploy your workflows to the .NET Workflow Service.
It's interesting to note that the implementation of .NET Services actually derives fromWCF and WF in the .NET Framework 3.5. The .NET Services SDK is able to build on that synergy to make the consumer developer experience as straightforward as possible for those already familiar with the WCF and WF programming models. If you're in that camp, the mechanics of programming .NET Services will feel very natural to you. In the end, it's mostly a matter of learning some new WCF bindings (for the .NET Service Bus), configuring those bindings, and understanding some new activities (for the .NET Workflow Service).
In the remaining sections, I'll take a quick look at each service and walk through an example of using each one. By the end, you should feel comfortable with how to get started on your own.

The .NET Access Control Service
Let's start by looking at the .NET Access Control Service. For the past several years, Microsoft has been moving towards a claims-based identity model that allows you to factor authentication and authorization decisions out of your applications and into an external service that can be centrally maintained by security experts. Under this model, the security experts control the process of authenticating users and issuing claims about the users. Your applications can simply trust the claims presented by the service and make decisions based on those claims (avoiding authentication).
When using a claims-based identity model, the user presents his identity to your application as a set of claims. Claims are simply assertions about the user—they can be anything like a name, an e-mail address, or a feedback rating. The claims are supplied by an identity provider that knows how to authenticate the user and his attributes (perhaps from an enterprise directory). The client application works transparently with the issuing authority to obtain these claims and present them to the application.
The Microsoft .NET Access Control Service is a centralized cloud-based service that makes this model easy to realize within the Azure Services Platform. Today, the .NET Access Control Service can act as an identity provider (by authenticating users via the solution credentials assigned during the provisioning process), but that's not really what it's meant to do. It was designed to primarily rely on existing identity providers such as WLID and the"Geneva" Server security token service or any identity provider that supports the standard federation protocols. This makes single sign-on a natural outcome.
The primary responsibility of the .NET Access Control Services is to provide a set of claims that are useful to your application. This typically means translating the input claims (that come from an identity provider such as WLID or the "Geneva" Server) into a set of output claims that have meaning to your application. You can think of it as a configurable claims transformation engine in the cloud.

Configuring a Service
You configure the .NET Access Control Service through the administration portal provided within a particular solution (see Figure 4). This is where you configure the rules that determine how it will issue claims for the users it knows about or as a result of transforming claims from other providers.
Figure 4 The .NET Access Control Service Administration Portal
Instead of configuring a sample service of my own, I'm going to show you how the .NET Access Control Service is configured for the .NET Service Bus. If you click on the Advanced button within the administration portal, you'll see a drop-down of solution names that represent the owners of the various scopes. A scope is a collection of claim transformation rules. When I select the Service Bus solution for my account, it shows a scope of
http://servicebus.windows.net/services/pluralsight/
When using the .NET Service Bus, you'll configure endpoints that use this Service Bus scope as the base URI (yours will be customized to your account, of course). Every solution comes preconfigured with a set of access control rules for both the .NET Service Bus and the .NET Workflow Service.
If you click on Manage, you can inspect the list of rules configured for a particular scope (see Figure 5). In this particular example, there are two rules that look for an incoming Username claim containing a value of pluralsight. One produces an output claim of Send and the other produces an output claim of Listen. The .NET Service Bus was developed to look for these claims to control access to its endpoint namespace. Any user that presents a Send claim will be allowed to send messages to the scope URI, and any user that presents a Listen claim will be allowed to create a listen on the scope URI. If I were to delete the rule that generates the Send token, my pluralsight account would no longer be able to send messages through the .NET Service Bus within this scope—it would only be able to listen.
Figure 5 Confi guring Rules for a Scope
It's easy to add similar support to your own services. You simply define new scope URIs within the administration portal, then define the necessary rules to produce the claims expected by your service.Within your service logic, you'll need to write code to inspect the incoming claims and to make authorization decisions based on what claims are present and what they contain. Both WCF and the new "Geneva" Framework make this possible through their claims-based programming models. For a complete example, see the .NET Access Control Service Getting Started sample in the SDK.

The .NET Service Bus
The primary focus of the .NET Service Bus is to provide bidirectional connectivity at Internet scope, which can be challenging due to ever-so-common firewalls and NAT devices that restrict inbound traffic in most environments. The .NET Service Bus accomplishes this by providing a centralized relay service in the cloud that provides the necessary network traversal logic (see Figure 6).
Figure 6 .NET Service Bus Relay
The relay makes it possible for a sender to communicate with a receiver through a rendezvous address. The receiver connects to the relay through an outbound port and creates a bidirectional socket for communication specifying the rendezvous address it wants to listen on. The sender can then transmit messages to the relay specifying the same rendezvous address as the receiver. When the relay receives a message, it relays the message to the corresponding listener (or listeners, in the case of multicast) that share the same rendezvous address. The relay transmits messages to the receiver through the bidirectional socket already in place, which means no inbound ports are required by the receiver. This explains why the mechanism works through firewalls and NAT devices (like a typical chat application).
The .NET Service Bus supports a variety of messaging styles including one-way, request-response, and even publish-subscribe. It supports both HTTP and TCP for communications, depending on whether you care about interoperability or performance. The relay even provides a mode for negotiating a direct TCP connection between two peer nodes based on a port prediction algorithm. Bypassing the relay allows for higher throughput when transmitting large messages. Overall, the .NET Service Bus provides a great deal of flexibility in adapting to a variety of today's most common communication scenarios.
It's important to understand how to structure the URIs for your .NET Service Bus endpoints. When you expose a TCP-based endpoint, you'll need to structure your addresses as follows:
sb://servicebus.windows.net/services/{solution}/{name}/{name}/...
When you expose an HTTP based address, simply replace the sb protocol scheme with http. Notice that you specify your solution name as part of the address in order to distinguish your endpoints from those used by other solutions throughout the .NET Service Bus. This is the same address that was used as the scope URI within the .NET Access Control Service configuration. After the solution name, you have complete control to specify whatever URI name hierarchy you'd like to use for your endpoints.
Senders and receivers will need to present the Send or Listen claim to the .NET Service Bus (acquired from the .NET Access Control Service) in order to send or listen on a particular address. Since the .NET Service Bus has a trust relationship with the .NET Access Control Service, it's able to read the security tokens that it issues and process those claims. Without those claims, you can't use the relay (unless a particular endpoint has been configured to allow for anonymous send, which is possible).
The easiest way to integrate with the .NET Service Bus relay is through the new WCF relay bindings that ship with the SDK. There is an equivalent relay binding for most of the built-in WCF HTTP/TCP bindings (see Figure 7). There are also a few new ones that don't have a clear counterpart, like NetOneWayRelayBinding (for aggressive one-way traversals) and NetEventRelayBinding (for one-way multicast scenarios, typically used for publish/subscribe). When you use the relay bindings instead of the standard bindings, the underlying WCF channel components take care of communicating with the .NET Access Control Service and the relay behind the scenes, and your code might not even need to change.
Figure 7 WCF Relay Bindings
Standard WCF Binding | Equivalent Relay Binding
BasicHttpBinding | BasicHttpRelayBinding
WebHttpBinding | WebHttpRelayBinding
WSHttpBinding | WSHttpRelayBinding
WS2007HttpBinding | WS2007HttpRelayBinding
WSHttpContextBinding | WSHttpRelayContextBinding
WS2007HttpFederationBinding | WS2007HttpRelayFederationBinding
NetTcpBinding | NetTcpRelayBinding
NetTcpContextBinding | NetTcpRelayContextBinding
N/A | NetOnewayRelayBinding
N/A | NetEventRelayBinding
The .NET Service Bus also provides a service registry in the form of an Atom feed. This feed is available at the base address of the solution through standard HTTP GET requests. The feed will automatically contain information on all of the active listener endpoints within a particular solution.

Communicating Through the .NET Service Bus
Now let's walk through a complete example of communicating through the .NET Service Bus using a publish/subscribe model. First, assume I have the following service contract:
[ServiceContract(Namespace = "")]
public interface ITweetNotifier {
  [OperationContract(IsOneWay = true,
    Action = "urn:DisplayTweet")]
  void DisplayTweet(string status);
}
And assume I have an application hosting the service (called TweetNotifierApp) that simply prints the incoming status text to the console window—there's nothing special about it.
I can configure the host application to listen through the .NET Service Bus by defining an endpoint using one of the relay bindings. Since I want to implement publish/subscribe (with potentially multiple listeners), I'll want to use the NetEventRelayBinding as illustrated in Figure 8.
Figure 8 NetEventRelayBinding
<configuration>
  <system.serviceModel>
    <behaviors>
      <endpointBehaviors>
        <behavior name="Default">
          <transportClientEndpointBehavior
            credentialType="UserNamePassword">
            <clientCredentials>
              <userNamePassword
                userName="pluralsight"
                password="{password}"/>
            </clientCredentials>
          </transportClientEndpointBehavior>
        </behavior>
      </endpointBehaviors>
    </behaviors>
    <services>
      <service name="TweetServiceLibrary.TweetService">
       <endpoint address="sb://servicebus.windows.net/services/pluralsight/tweet"
            behaviorConfiguration="Default"
            binding="netEventRelayBinding"
            bindingConfiguration=""
            contract="TweetServiceLibrary.ITweetNotifier" />
      </service>
    </services>
  </system.serviceModel>
</configuration>
Notice I'm also using a special behavior that tells WCF what credentials to send to the .NET Access Control Service to authenticate and acquire the necessary .NET Service Bus claims. You'll want to replace the username and password with your own credentials if you attempt to run this example.
When I run the host application, the WCF hosting infrastructure automatically authenticates with the .NET Access Control Service, acquires claims, and then opens an outbound port to the .NET Service Bus and registers a listener on the specified address. At that point, the locally hosted service will be ready to receive messages relayed through the .NET Service Bus on the specified address. I can also browse to the base address of the solution at this point to access the service registry feed and any active listener endpoints will appear in the feed.
Now I can write a client application to send messages through the .NET Service Bus on the same rendezvous address. Here's what my client program looks like:
static void Main(string[] args) {
  ChannelFactory<ITweetNotifier> cf =
    new ChannelFactory<ITweetNotifier>("tweetService");
  ITweetNotifier tweetNotifier = cf.CreateChannel();

  Console.WriteLine("Enter a status update: ");
  string status = Console.ReadLine();
  while (!status.Equals("")) {
    tweetNotifier.DisplayTweet(status);
    status = Console.ReadLine();
  }
}
The client configuration file will need to look just like the host configuration file. Only the endpoint definition will need to appear within the <client> section. Other than that, it should look about the same, including the <transportClientEndpointBehavior> configured on the client endpoint.
With this in place, I can run multiple instances of the host application followed by a single instance of the client application, and I see all of the messages relayed in a multicast fashion (see Figure 9). The relaying will work even if the host application is behind a firewall or NAT device.
Figure 9 Running the .NET Service Bus Demo
This is just one example of many possible communication scenarios supported by the .NET Service Bus. For more examples, check out the various .NET Service Bus samples provided in the .NET Services SDK.

The .NET Workflow Service
As you move towards cloud computing, workflow provides a simplified approach for coordinating complex service interactions in the composite cloud solutions you build.
The .NET Workflow Service provides a scalable hosting environment for running and managing WF workflows in the cloud. Because the hosting environment is built on Window Azure, it's capable of scaling on demand, and because the WF runtime is being used, workflow instances are not pinned to any particular server—they are free to move from one server to another (within Windows Azure) for each episode of execution. The .NET Workflow Service relies on a WF persistence service that leverages Microsoft SQL Services to save the state of running workflows and to ensure recovery capabilities.
You build workflows for the cloud using Visual Studio and the same workflow designer that you've always used. You ultimately create XAML workflows and rules files. These XML files are then deployed to the .NET Workflow Service where they can be used to create workflow instances.
The .NET Services SDK includes a project template for creating a SequentialCloudWorkflow that is a specialized version of the standard SequentialWorkflow template. When defining workflows to be run in the cloud, there are also restrictions on what activities you can use in the workflow. You may use only a subset of the activities in the WF base activity library as well as a suite of new custom cloud activities provided as part of the .NET Services SDK (see Figure 10). These cloud activities make it possible to send, receive, and process messages, but that's about it today. More activities will be added in future versions to enhance the capabilities of your cloud-based workflows.
Figure 10 Cloud Workflow Activities
Activity | Description
CloudHttpReceive | Receive HTTP requests posted to a specific URL for the workflow instance
CloudHttpSend | Invoke HTTP GET or POST operations on a specified URL and get the response
CloudServiceBusSend | Send a message to a specific endpoint on the .NET ServiceBus
CloudXPathRead | Reads specified data from an input XML document
CloudXPathUpdate | Sets specified data in an input XML document
CloudDelay | Waits for a specified time span
Like the other services, the .NET Workflow Service comes with an administration portal for managing workflow types and instances. The .NET Services SDK also comes with a client management API that allows you to programmatically accomplish the same thing.
Figure 11 Complete Workflow Design

Building a Cloud Workflow
To see how the .NET Workflow Service operates, let's build a workflow that consumes the public Twitter feed and sends the latest entry to any subscribed TweetNotifierApp instances through the .NET Service Bus.
The first thing I need to do is create a new CloudSequentialWorkflow project in Visual Studio 2008. I'll call it MonitorTwitterFeed. At this point, you should see the traditional WF designer. If you expand the activity toolbox, you'll see the restricted set of activities that you're allowed to use.
I'll need to use a While activity to continually poll the public Twitter feed every 60 seconds. So first I drag the While activity onto the workflow design surface, and then specify that the condition with be a Declarative Rule Condition. For the purposes of this example, I make the condition always return "true." Next, I drag a Sequence activity into the While activity to define the sequence of steps that I want to repeat.
Now, I want to delay for 60 seconds, so I drag a CloudDelay activity into the sequence and specify 00:01:00 for the Timeout value. Then I need to retrieve the public Twitter feed using an HTTP GET request, so I place a CloudHttpSend activity right below the CloudDelay activity and configure it appropriately (setting the Method to GET and the URL to http://twitter.com/statuses/public_timeline.xml).
Next,I need to read the latest status entry from the top of the feed, which is made possible through the CloudXPathRead activity. After placing this in the sequence, I bind the InXml property to the Response property of the previous activity. I also set InXPathExpression to /statuses/status/text to specify the XPath expression.
Next,I need to build an appropriate XML message to send to the TweetNotifierApp through the .NET Service Bus. I can accomplish this through the CloudXPathUpdate activity. The target service is expecting a message that looks like this:
<DisplayTweet><text> status goes here </text></DisplayTweet>
So after placing the CloudXPathUpdate activity into the sequence, I need to enter the XML into the InXml property and "/DisplayTweet/text" for InXPathExpression. I also need to bind InNewValue to the OutReadValue property on the previous activity. This essentially tells the activity how to construct a new XML document by inserting an input value (the latest status) into the XML template.
Finally, I need to instruct the workflow to send the message through the .NET Service Bus. This is where the CloudServiceBusSend activity comes in. After placing it at the end of the sequence, I set the Action to urn:DisplayTweet, the ConnectionMode to Multicast, and the address to sb://servicebus.windows.net/services/pluralsight/tweet. I bind the Body property to the OutXml property on the previous activity. With that in place, the workflow is complete. See Figure 11 for a complete visual of the resulting workflow design.
Now, to deploy and test the workflow, I simply right-click on the workflow design surface and select Deploy Workflow. I enter your solution credentials and press Deploy & Run. The add-in will upload your XAML definition to the .NET Workflow Service and start an instance of it. It's also possible to upload the XAML definition manually through a form on the management portal.
After you've deployed the workflow, you can browse to the administration portal and see the workflow type and the running instance. If you have any instances of the TweetNotifierApp running, you'll see Twitter messages appear every 60 seconds.

Aaron Skonnard is a cofounder of Pluralsight, a training provider offering both instructor-led and on-demand Microsoft developer courses. These days Aaron spends most of his time recording Pluralsight On-Demand! courses focused on Cloud Computing, Windows Azure, WCF, and REST. Aaron has spent years writing, speaking, and teaching professional developers around the world. You can reach him at pluralsight.com/aaron.


Take Control
Use SharePoint to Manage Your Windows Services
Pav Cherny
Code download available from the MSDN Code Gallery
Browse the Code Online

This article discusses:
  • SharePoint integration for Windows services
  • Windows service and instance classes
  • Process identity types for Windows services
  • Starting and stopping services
This article uses the following technologies:
Windows SharePoint Services
Contents
A Non-Integrated Solution Prototype
Integrating with SharePoint
Defining Process Identities
Windows Service Dependencies
Adding Configuration Parameters
Final Touches and Testing
Summing Up
All Windows Server operating systems depend heavily on Windows services. This hasn't changed since Microsoft first introduced services with Microsoft Windows NT 3.1 in 1993 and it likely will not change in future operating systems either. Even SharePoint couldn't exist without Windows services, such as Internet Information Services (IIS) and additional services for SharePoint-specific tasks. You can take advantage of the built-in services infrastructure through custom jobs for the Windows SharePoint Services Timer (SPTimerV3) service, but if you want extensive data processing, continuous system monitoring, virus scanning, network communication, or agent-based backup and restore operations, it's still best to create your own separate Windows services. It isn't difficult to build a Windows service. Microsoft Visual Studio 2008 includes the necessary project templates and wizards to get you started and you can use C/C++ as well as managed languages to implement the service logic. However, it is not as straightforward to integrate a Windows service with SharePoint. The Windows SharePoint Services (WSS) 3.0 Software Development Kit (SDK) does not cover this topic very well, there are no wizards, and you must ensure that the integration results do not jeopardize SharePoint security.
In this article, I'll show you how to integrate a Windows services–based solution with SharePoint. The results enable you to provision, start, stop, and remove service instances through SharePoint 3.0 Central Administration and the SharePoint administration object model, maintain service settings centrally in the SharePoint configuration database, and ensure that all service instances in a SharePoint farm use the same security account and configuration parameters. When you change configuration settings in SharePoint, you can apply the changes consistently across all servers in the farm. Of course, it is also possible to configure parameters separately for individual service instances, if necessary. For my sample solution, I chose to perform a sensitive operation on front-end servers to highlight SharePoint-specific security considerations. The companion material includes source code and compiled files in various stages of completion according to the sequence of steps I'll discuss here. The companion material also includes step-by-step worksheets if you want to follow my explanations in your own development environment.

A Non-Integrated Solution Prototype
It is a best practice to start a development cycle by gathering requirements, outlining a general solution design, and delivering proof of concept in the form of a representative prototype. This is particularly true for security-sensitive SharePoint services that require elevated permissions on front-end servers or application servers. While it is not necessary to integrate the prototype with SharePoint for manageability, your prototype must address SharePoint security dependencies right from the start to avoid complex design issues later on. Even seemingly simple solutions might pose tricky challenges in a SharePoint environment.
Take this article's sample solution, for instance. It addresses the requirement to consolidate Security event log entries from front-end servers in a custom SharePoint list. It's a seemingly simple task: The solution registers a handler called EntryWrittenEventHandler in the Event Log subsystem on the local computer to receive an event notification whenever the operating system adds a new entry to the Security event log, and then, if the entry meets a specified filter criterion, such as entry type equals FailureAudit or SuccessAudit, the solution adds a corresponding item to a custom Security Audit list in SharePoint. It isn't difficult to build a basic Windows service and a custom SharePoint list to do this, yet the service account requires write permissions in the SharePoint site to add items to the custom list and administrative permissions on the local server to register EntryWrittenEventHandler—and this is a security issue on SharePoint servers.
While you can satisfy the SharePoint permission requirements by running your Windows service in the context of the SharePoint site's application pool account, you must not grant local administrative permissions to SharePoint security accounts. Granting security accounts administrative permissions on front-end servers jeopardizes SharePoint security, as explained in the TechNet Magazine January 2009 column entitled "SharePoint Security Accounts."
So, how do you avoid the elevation of permissions if your solution must perform a security-sensitive operation? A good technique is to split the solution into multiple components and use a secure interprocess communication mechanism between them. You can then run the component that requires administrative permissions in the context of the local System account, while the other component runs in the context of the SharePoint security account. Microsoft uses this technique in the SPTimerV3 service. SPTimerV3 runs without administrative permissions in the context of the SharePoint farm account and relies on the Windows SharePoint Services Administration (SPAdmin) service to perform administrative tasks on the local server. The SPAdmin service runs in the context of the local System account. SPTimerV3 and SPAdmin use .NET Remoting for interprocess communication, yet you can also use a lighter weight mechanism, such as named pipes, as long as you protect the communication facility by means of access control lists (ACLs). In the sample solution, I use the named-pipe approach.
Take a look at the overall solution architecture in Figure 1. The solution relies on a separate Security Event Handler service that includes the aforementioned EntryWrittenEventHandler callback function for receiving notifications from the local event log subsystem. This service runs in the context of the local System account. Its counterpart is the Security Event Receiver service, which runs in the context of the SharePoint site's application pool account to create content items in a specified security audit list. When you start the Security Event Receiver, the service creates a secure named pipe that grants only the local System account access permissions. The Security Event Handler service uses this named pipe whenever a "Security Event Log Entry Written" event fires to communicate with the Security Event Receiver. This design works without the requirement for elevated permissions and without jeopardizing SharePoint security. It's just a little more involved than the typical monolithic Windows service architecture.
Figure 1 Splitting up a SharePoint Solution
You might notice in the sample application that the Microsoft .NET Framework cannot parse the description of Security entries. This is not critical for the purposes of this article, but consider installing the hotfix described in the Microsoft Knowledge Base article "An application that uses Windows NT security event log APIs cannot read the description of an event log message from a computer that is running Windows Vista or Windows Server 2008."

Integrating with SharePoint
The delivery of a functional prototype is an important milestone; another is to deliver appropriate management tools, and this is a key aspect of SharePoint integration for Windows services. Without integration, it is hard to control deployed service instances or ensure a consistent service behavior across all servers in a farm. With integration, you can use SharePoint 3.0 Central Administration to determine the servers that run your services and configure relevant parameters for all service instances centrally. Figure 2 shows the application after you've completed all integration steps. It might look like a small application, but SharePoint integration gives it all the characteristics of a full-featured SharePoint solution.
Figure 2 Integration with SharePoint
Essentially, you need four components to integrate a Windows service with SharePoint: a class that identifies the service, a class that enables SharePoint to control individual service instances, an administrative tool that adds objects of these two classes to the SharePoint configuration, and a SharePoint solution package to deploy these components.
According to the solution architecture depicted in Figure 1, there are two Windows services: Security Event Handler and Security Event Receiver. So let's create the corresponding service classes in a new class library project. I added this project directly to the SecurityAudit solution I've built in Visual Studio. It's called SecurityEventManagement. After I added a reference to the Windows SharePoint Services library, I created a new class derived from the SPWindowsService class for each Windows service. In the initial implementation of the SecurityEventReceiverService class, the SecurityEventHandlerService class has the same structure; only the service name is different, as you will see if you analyze the code in the Step 2 folder in the companion material.
The service class represents a particular Windows service in a SharePoint farm. It is a global object for all service instances, but you also need a class to associate an instance of the service with a particular SharePoint server. The SharePoint administration object model defines several service base classes and the service instance classes to which they correspond. The SPWindowsService class is the right choice for the Windows services, and thus the SPWindowsServiceInstance class is the right base class for the service instance classes: SecurityEventReceiverServiceInstance and SecurityEventHandlerServiceInstance. Again, the class definitions are relatively uncomplicated.
Now let me show you how to build the administrative tool to add the service and service instance objects to the SharePoint configuration. You can accomplish this through application pages in SharePoint 3.0 Central Administration, Stsadm.exe command extensions, or by any other means, such as through the use of Windows PowerShell. I opted to create a Stsadm.exe command extension because of its low overhead, which means little distraction from the job at hand. For detailed information about Stsadm.exe command extensions, read the article "How to: Extend the STSADM Utility."
The administrative tool must instantiate and persist service and service instance objects. The constructors of the classes reveal how to instantiate the objects. It is noteworthy that SharePoint service classes are derived from the SPPersistedObject class. When you call the Update() method, these objects are persisted. Similarly, if you call the Delete() method after de-provisioning, these objects are removed again. The SecurityEventServiceAdministration.cs code file in the SecurityEventManagement project illustrates these steps.
And that's it! You now can compile the solution and deploy it through the use of a WSS 3.0 solution package (.wsp). For a detailed explanation of how to create a solution package with Visual Studio and MakeCab.exe, I recommend Andrew Connell's article on how to create WSS solution files. Also see the code in the companion material.

Defining Process Identities
The simplicity of SharePoint integration might be a nice surprise, but it's a direct result of having taken full advantage of the SharePoint object model. You can already provision service instances and use the management links in SharePoint 3.0 Central Administration (see Figure 3). For example, you can start and stop the Security Event Receiver service; just the Security Event Handler service isn't as easy. This is the case because SharePoint updates the service configuration when you click the Start link. By default, SharePoint configures the service to run in the context of the Local Service account, which doesn't have permissions to register an EntryWrittenEventHandler. Hence, the Security Event Handler service fails. You need to hardwire the Security Event Handler service to the local System account and should provide an option to provision the Security Event Receiver service with a desired application pool account as well.
Figure 3 SharePoint 3.0 Central Administration
Let's start with the Security Event Handler service because it is straightforward to hardwire the System account. It just takes three lines of code in the service constructor. The first line sets the service's process identity to the System account. The other two lines disable credential deployments and credential updates to prevent administrators from making changes to the account information in SharePoint 3.0 Central Administration. The Service Accounts page (_admin/FarmCredentialManagement.aspx) no longer lists this service in the Windows Service list box.
public SecurityEventHandlerService(SPFarm spFarm)
       : base(ntServiceName, spFarm)
{
   base.ProcessIdentity.CurrentIdentityType = IdentityType.LocalSystem;
   base.ProcessIdentity.IsCredentialDeploymentEnabled = false;
   base.ProcessIdentity.IsCredentialUpdateEnabled = false;
}
The Security Event Receiver service is slightly more complicated because you must handle a variety of security account information during service provisioning. The security account can be a domain user account with a password or a system account without a password. When you deal with a domain user account, the account name must follow NetBIOS name conventions and you should verify the password. In my implementation, the code sets the IsCredentialDeploymentEnabled and IsCredentialUpdateEnabled properties in this class to true so that SharePoint administrators can change the security account in SharePoint 3.0 Central Administration after provisioning the Security Event Receiver service.
Of course, you must also extend the administrative tool to provision the SecurityEventReceiverService object with a user name and password. Check out the SecurityEventServiceAdministration.cs file in the Step 3 companion folder. It includes the necessary modifications to the Stsadm.exe command extension.

Windows Service Dependencies
At this point, you can start and stop provisioned service instances on SharePoint servers and the services retain their security accounts. However, if you stop both service instances and then attempt to start the SecurityEventHandlerService instance without first starting the SecurityEventReceiverService instance on a selected server, you encounter an error that states that "The dependency service or group failed to start." The cause is that the Security Audit Setup program configures the Security Event Handler service to depend on the Security Event Receiver service so that the Service Control Manager (SCM) starts the Security Event Receiver service automatically when you start the Security Event Handler service. However, SCM cannot start a service if its Startup Type is disabled, and SharePoint sets the Startup Type to disabled when you stop a service instance. Consider changing the service installer logic. You can avoid this error if you remove all dependencies and install the services initially with the Startup Type set to Disabled. This ensures a consistent control behavior in SharePoint 3.0 Central Administration.
It's great to avoid unpleasant errors, yet the original dependencies existed for a reason. After all, Security Event Handler service and Security Event Receiver service depend on each other for a functioning Security Audit solution. If you start or stop the one, you should also start or stop the other. You can achieve this behavior by overriding the Provision and Unprovision methods in the service instances. The SecurityEventReceiverServiceInstance attempts to locate its SecurityEventHandlerServiceInstance counterpart on the same server and starts or stops it in addition to its own instance, if found. The code also demonstrates how to customize the Start and Stop action links to display a message box in the user interface to inform the administrator about the affected services.
If you analyze the source code in the Step 4 companion folder, you will notice that the SecurityEventHandlerServiceInstance class does not contain overridden Provision and Unprovision methods. It is sufficient to start and stop the services through the SecurityEventReceiverServiceInstance class. Instead, I marked the SecurityEventHandlerServiceInstance as a system service, which removes the corresponding Start and Stop links and hides the service from the list of configurable services. The SecurityEventHandlerService reference is now visible only in the All view of the Services on the Server page. The following code shows how to mark a service instance as a system service:
public overrid  e bool SystemService
{
    get
    {
        return true;
    }
}

Adding Configuration Parameters
The solution is now an integral part of SharePoint. The next step is to move relevant configuration settings from the local registry to the SharePoint configuration database in order to increase configuration consistency across the entire SharePoint farm. All service instances share the same configuration database. You only need to modify the Windows services to read the parameters from the configuration database instead of the registry. To maintain parameters in the configuration database, use the SPPersistedObject class, as explained in the WSS 3.0 SDK under "SPPersistedObject Class (Microsoft.SharePoint.Administration)."
The SPWindowsService and SPWindowsServiceInstance classes are derived from the SPPersistedObject class and are therefore my SecurityEventReceiverService and SecurityEventReceiverServiceInstance classes. This means that you can add global parameters as persisted properties directly to the service and service instance classes. In my example, these are the parameters SiteURL, ListName, and EventFilter. The SecurityEventReceiverServiceInstance class would be the right choice for instance-specific parameters, but in my solution all service instances are supposed to use the same settings, so I extended the SecurityEventReceiverService class.
To retrieve parameter values, you need access to the configuration database. SharePoint takes care of this for you if you keep the process identity of your service class credential-deployment-enabled (IsCredentialDeploymentEnabled = true). I did this for the Security Event Receiver service class, yet the Windows service must also know how to use the service class. You can take care of this requirement by adding a class-library reference to the Visual Studio project that contains your Windows service. In my example, this is the SecurityEventReceiver project. Make sure you mark the SecurityEventReceiverService class as public so that the Windows service can use it and deploy the class library's assembly in the Global Assembly Cache (GAC) by means of your SharePoint solution package. You need to deploy to the GAC before using the GetValue method of the farm's Services collection to retrieve the service object. Here's how to access the configuration properties of the SecurityEventReceiverService class:
SecurityEventReceiverService EventReceiverService =
    SPFarm.Local.Services.GetValue<SecurityEventReceiverService>(
        SecurityEventReceiverService.ntServiceName);

if (EventReceiverService == null)
    throw new Exception("Unable to locate SecurityEventReceiverService"
                      + " in the local SharePoint farm.");
siteURL = EventReceiverService.SiteURL;
listName = EventReceiverService.ListName;
eventFilter = EventReceiverService.EventFilter;
Now that the Windows service can read the parameters from the configuration database, the remaining task is to set them. The preferred choice for many administrators is a custom application page, added to SharePoint 3.0 Central Administration and tied to the service through the ManageLink property, but you can also use Stsadm.exe command extensions or other methods. The following code uses the ManageLink property, added to the SecurityEventReceiverServiceInstance class.
public override SPActionLink ManageLink
{
    get
    {
      return new
        SPActionLink("SecurityAudit/ManageSecurityAuditSettings.aspx");
    }
}
It converts the service's display name into a hyperlink that opens the _admin/SecurityAudit/ManageSecurityAuditSettings.aspx page. You can find the ManageSecurityAuditSettings.aspx page in a separate class library, which I called ManageSecurityAuditSettings. For details on how to build custom application pages, read Ted Pattison's article "Creating an Application Page in Windows SharePoint Services 3.0." See also the Step 5 companion folder.

Final Touches and Testing
The project is now almost complete, apart from finishing touches and proper solution testing. For example, you might want to change the display name of your services in SharePoint 3.0 Central Administration because the default names SecurityEventManagement.SecurityEventHandlerService and SecurityEventManagement.SecurityEventReceiverService are not very user friendly. However, you won't achieve the desired effect by overriding the DisplayName property in your service classes. The display name corresponds to the TypeName property instead, so never rely on TypeName == GetType().ToString() in a SharePoint solution.
Note also that both service and service instance classes offer a TypeName property because it is inherited from the SPPersistedObject class, but there is a quasi-hierarchical relationship. Service instances use the name of their associated service, by default. Service instance classes inherit an overridden TypeName property from the SPServiceInstance class that returns the TypeName of the associated service class. Of course, you can override the TypeName property in your service instance class again to change the display name according to certain conditions, such as to indicate that a critical component is missing.
SharePoint terminology is not as consistent as it could be, but it's not difficult to determine the purpose of virtual methods and properties regardless of their names. To determine available properties and methods, in Visual Studio, right-click on a base class such as SPWindowsService and select Got To Definition, then right-click SPService, Got To Definition, and so forth through the entire inheritance hierarchy. You might also check the WSS 3.0 SDK. The SPWindowsService and SPWindowsServiceInstance classes are hardly covered, but the lists of class members are useful to some degree (SPWindowsService Members and SPWindowsServiceInstance Members).
Keep in mind, however, that successful testing of service and service instance implementations on a single development computer is not a sufficient release criterion for SharePoint-integrated Windows services. SharePoint 3.0 Central Administration deals with Windows services quite differently on the local computer than on remote computers in a farm. Locally, SharePoint 3.0 Central Administration uses the security context of the logged-on SharePoint administrator, which is most likely a local administrator with all necessary permissions to perform administrative actions on services. Remotely, however, SharePoint 3.0 Central Administration uses timer jobs and the SPTimerV3 service. As I mentioned earlier, the SPTimerV3 service's security account is not a local Administrator on the remote computer, so the SPTimerV3 service uses the SPAdmin service to carry out the actions in the context of the local System account. In order to ensure that the differences in security contexts don't interfere with the operational state of your Windows services, I recommend that you fully test your solution in a farm environment with at least two front-end servers and a separate computer running SQL Server in a restrictive security configuration according to the "Windows SharePoint Services Security Account Requirements" worksheet.

Summing Up
You need to pay special attention to solution design and security when you're building SharePoint-integrated Windows services, but given the proper groundwork, the actual integration with SharePoint is relatively uncomplicated. The SharePoint object model already includes the necessary logic to provision, start, stop, and unprovision service instances on local and remote servers in a SharePoint farm. You need only define corresponding service and service instance classes to integrate your Windows services into the SharePoint configuration. Service and service instance classes are derived from the SPPersistedObject class, which means that you can use these classes to maintain service parameters directly in the SharePoint configuration database instead of the local registry, resulting in improved manageability and configuration consistency.
Overall, a full-featured solution that appears seamlessly integrated with SharePoint must include the Windows services administrative tools to provision service objects, application pages to extend SharePoint 3.0 Central Administration, and a SharePoint solution package to deploy the SharePoint components on all servers in the farm in addition to the actual Windows services. Windows services are vital components on Windows servers, and with the integration capabilities available in SharePoint they can assume critical functions in the SharePoint environment as well. For more information see www.microsoft.com/sharepoint, msdn2.microsoft.com/sharepoint, Windows SharePoint Services SDK Documentation, and blogs.msdn.com/sharepoint.

Pav Cherny is an IT expert and author specializing in Microsoft technologies for collaboration and unified communication. His publications include white papers, product manuals, and books with a focus on IT operations and system administration. Pav is President of Biblioso Corporation, a company that specializes in managed documentation and localization services.


Sync Up
Manage Your Data Effectively With The Microsoft Sync Framework
James Yip

This article discusses:
  • Microsoft Sync Framework
  • Synchronization Services
  • Metadata storage
  • Schema synchronization
This article uses the following technologies:
ADO.NET, Microsoft Sync Framework, SQL Server
Contents
Usage Scenarios
Behind the Microsoft Sync Framework
Synchronization Providers
Metadata Storage Services in the Sync Framework
Sync Services in Action
Synchronizing Data and Schemas
Implementing Custom Synchronization
Wrapping Up
It's never a trivial task to synchronize data between different data stores. Writing your own logic to perform the synchronization is a time-consuming and costly process. But armed with the Microsoft Sync Framework and its constituent APIs, building synchronization logic becomes much simpler. The Microsoft Sync Framework helps you integrate application data from any data store using any protocol over any network.
Together with the Microsoft Sync Framework, Microsoft released Microsoft Synchronization Services for ADO.NET, Synchronization Services for File Systems, and Synchronization Services for FeedSync, all of which enable developers to perform synchronizations for a specific environment, unlike the Microsoft Sync Framework, which is for building synchronization logic within your application.
These Sync Services provide a set of tools to help you synchronize data between two database sources, synchronize files between machines, and synchronize your application with an RSS or ATOM feed. With the help of these services, you can focus more of your effort on your application logic and less on data synchronization.

Usage Scenarios
The Microsoft Sync Framework is useful in a number of scenarios. Let's take a look at some common ones.
Download only Synchronization In this scenario, the client PC will not have rights to determine what to store and how to keep track of the data stored. An example of this would be RSS Sync. The RSS provider determines how the information is available and how frequently it gets updated. The client determines what content is offered and when.
Offline Data Access Often, you'll need to give some Windows applications offline data access so that the application can continue to run properly if the user is not connected to the network. An example is an inventory application. You would want your remote salespeople to be able to enter sales data on their laptops and then later sync with your database.
Peer-to-Peer Data Collaboration Sometimes you'll issue local copies of your database to increase performance on the client. When there are several such local copies floating around, you'll need to update your back-end data repository appropriately so that all changes are accounted for. One typical example of this is a point-of-sale (POS) application. As sales happen, the POS application in each store records the sales transactions and updates the store's inventory. These updates must be reflected in both the central data store and in all the local copies of the database that other shops are using so that salespersons in each shop know the status of the inventory on hand.
These data access scenarios represent the most common uses for Microsoft Sync Framework. Let's now take a look at how it works to solve these offline data access problems.

Behind the Microsoft Sync Framework
The Microsoft Sync Framework uses a session to carry out data synchronization. Within a session, you define a data source, from which the changes originate, and a destination, to which the changes will be replicated. When the synchronization is triggered by a client, the following happens:
  1. A synchronization session is created.
  2. The Sync Framework checks the destination data to see if there have been changes from any other sources committed since the local copy was downloaded.
  3. Any changes found are sent back to the source to have them applied.
  4. The destination will then request that the source send its changes to the destination store.
  5. The source will send out the changes, and they will be applied to the destination data store.
In order for this to work, both source and destination need to maintain some metadata so they can identify the changes that have happened between synchronizations. There are a number of ways to do this, each of which depends on the type of data we are synchronizing.
Depending on the type of application and synchronization you are trying to implement, you may not need to implement custom change tracking because some data does not include ways for tracking changes. But some data, such as files stored in the file system, already contains create and update metadata. Microsoft Sync Framework supports both one-way synchronization and two-way synchronization. Two-way synchronization is actually implemented as two one-way synchronizations between the source and destination.
Microsoft Sync Framework uses the SyncOrchestrator class to manage the data flow between two data sources. You don't need to extend this class in any way unless you want to add custom application logic during the synchronization session.
The direction of the synchronization is controlled by the Direction property of the SyncOrchestrator class. You can choose whether the specific SyncOrchestrator instance is used for performing an upload or download or both synchronizations.
Providers are used to communicate with source and destination data stores. You need to tell SyncOrchestrator which provider is used before you trigger the synchronization. Once you do trigger it, SyncOrchestrator will call methods in the provider to retrieve changes, save them, and resolve conflicts. Figure 1 illustrates how the synchronization works.
Figure 1 The SyncOrchestrator Object

Synchronization Providers
The Microsoft Sync Framework uses a provider to communicate with both the source and the destination. The provider is responsible for communicating with the data source used to store application data in a manner that is compatible with the associated data store. It is also responsible for detecting changes based on information provided by the other side of the sync session, for applying changes received, and for retrieving changes from the data source.
Developing a provider can require significant time and effort. To implement a synchronization provider, you need to implement the KnowledgeSyncProvider abstract class, the IChangeDataRetriever interface, and the INotifyingChangeApplierTarget interface. Within these classes and interfaces, there are a number of events available for implementing the logic for detecting changes and applying them.
You can implement a proxy provider if there is not a direct connection between the client application and the central data stores. The proxy provider receives commands from and relays those commands to other providers in the synchronization session.
Proxy providers are useful in scenarios such as when a client application communicates with a central data store over the Internet. In this case, you might have the client talking to a proxy through HTTPS and then have the proxy talk to SQL Server. This configuration helps to reduce the exposure of internal servers to the Internet but still allows external users to use Sync Framework to synchronize data.
You implement the proxy provider in the same way you implement any other provider. The only difference between the two is that the proxy provider will not be triggered by the client application directly but by another provider.

Metadata Storage Services in the Sync Framework
In some data sources, you cannot store additional information or implement any kind of change tracking. One good example is the Windows file system. In such a case, Microsoft Sync Framework provides a solution where instead of having the developer build a metadata repository, the Sync Framework provides a lightweight data store called Metadata Storage Services.
Stores you create within Metadata Storage Services can contain two types of data, replica-level data and item-level data. They are used to store information regarding a particular destination (a replica) and an item. Each destination needs a replica ID that uniquely identifies the destination.
ReplicaMetadata, ItemMetadata, and MetadataStore are abstract classes that represent replica metadata, item metadata, and a metadata store. You can manipulate your metadata with the help of these classes.
SqlMetadataStore is the concrete implementation of Metadata Storage Services, which comes with Microsoft Sync Framework to help developers manage metadata at replica level. Unfortunately, the Microsoft Sync Framework does not provide an implementation on the item level for metadata support. Instead, you need to create your own implementation of the ItemMetadata class and create MetadataStore objects if want to store item-level metadata. SqlMetadataStore uses SQL Server to store the metadata in a file you define.
To work with SqlMetadataStore, you either open a saved store using the OpenStore method or create a new one using the CreateStore method. Usually, one store is sufficient for one application. But if you like, you can also maintain multiple stores. To retrieve metadata from a store, you will use the GetReplicaMetadata method.
The following shows how to retrieve items from a SqlMetadataStore:
SyncIdFormatGroup idFormat=new SyncIdFormatGroup();
SyncId syncId=new SyncId(1);
SqlMetadataStore metadataStore=SqlMetadataStore.OpenStore(filePath);
ReplicaMetadata item= metadataStore.GetReplicaMetadata(idFormat,syncId);
When using SqlMetadataStore, you need to specify the schema of the data you'll be storing. You can do so by calling the InitializeReplicaMetadata method of the SqlMetadataStore. This method creates and populates the tables to hold information in the underlying SQL database. For example, the following shows how to populate a metadata store with one field:
SyncIdFormatGroup idFormat=new SyncIdFormatGroup();
SyncId syncId=new SyncId(1);
FieldSchema[] fields=new FieldSchema[1];
IndexSchema[] indexes=new IndexSchema[1];
fields[0]=new FieldSchema("LastSync",typeof(string));
indexes[0]=new IndexSchema("LastSync",false);
SqlMetadataStore metadataStore=SqlMetadataStore.CreateStore(filePath);
ReplicaMetadata item= metadataStore.InitializeReplicaMetadata(  idFormat,syncId, fields,indexes );

Sync Services in Action
Now, let's see how you can add synchronization support to your application using Sync Services for ADO.NET. With the help of SQL Server Compact Edition 3.5, you can create a lightweight data store in local file systems. The good thing about SQL Server Compact Edition is that it works like SQL Server but uses a file as the repository, eliminating the need to modify the application to work with a local data store.
Synchronization Services for ADO.NET supports the synchronization of data and schema between SQL Server databases including SQL Server Compact Edition databases. Here, I will show you how to enable an application that uses a central SQL Server database for offline access via a replica maintained in a SQL Server Compact Edition database.
The first thing to do when you want to implement Synchronization Services for ADO.NET is to decide how to track changes in your data. In Synchronization Services for ADO.NET, you can leverage SQL Server 2008's Integrated Change Tracking or you can use custom tracking by managing change tracking yourself in the application database.
Within SQL Server 2008, tables that are enabled for integrated change tracking will log every data change in a change tracking log table and Sync Services will look at this log to identify all changes since the last synchronization. This keeps the developer from having to change the database schema of an existing application.
But sometimes, as is the case for applications using SQL Server 2005, integrated change tracking may not be available. In such cases, you should consider using custom change tracking. The custom change tracking approach identifies the insertion and update of records in a table with the help of columns and identifies deletions with the help of a tombstone table. To help Sync Services identify rows that have been updated or inserted since the last update, you will need to add four columns—Update Originator, Update Time, Create Originator, and Update Time—to each table that you wish to track. You also need to create a table called a tombstone table to keep a log of all rows that are removed. Within the table, you need at least two pieces of information: the time of deletion and the row's original primary key.
The tombstone table is where Sync Services finds entries that must be removed from the destination store because they have been removed from the source. All of this information helps Sync Services to identify the changes since last synchronization.

Synchronizing Data and Schemas
When implementing synchronization between databases, keeping schemas consistent becomes an issue for most applications. As such, Sync Services for ADO.NET also supports synchronizing database schemas. There is a limitation though. Sync Services will create the table in the client database only the first time it performs the sync unless the developer configures it to recreate it every time it synchronizes.
To configure your providers to use Sync Services for ADO.NET, you need to implement the code in the provider to configure the tables to be synchronized and the direction in which you want the synchronization to run. You can choose to synchronize data from the source to the destination, from the destination to the source, or both. You can place the code to configure the synchronization in the constructor of the provider class. You can also separate tables into groups so that you can have more fine-grained control over the individual tables to be synchronized.
With the destination, most of the time you won't really need to explicitly configure the provider because Sync Services for ADO.NET will automatically create the appropriate schemas and load the data. You simply need to specify the location of the destination database. Sync Services for ADO.NET comes with two providers: one is designed to work with SQL Server and one is designed to work with SQL Server Compact Edition. The only real difference is in the underlying library used to communicate with the database engine; the SQL Server provider uses System.Data.SqlClient while the provider for SQL Server Compact Edition uses System.Data.SqlCeClient.
The provider that is used for communicating with SQL Server is called DbServerSyncProvider while the one designed for SQL Server Compact Edition is SqlCeClientSyncProvider. When you are initializing the provider, you will need a SyncAdapter object, which contains the information about how the provider will communicate with the underlying SQL Server database, and the details about change tracking, such as which column is the change originator column, and whether custom SQL change tracking is used. Another important piece of information defined in the SyncAdapter is the direction of the synchronization. Sync Services for ADO.NET provides the ability for developers to define the direction of the synchronization on a per-table basis. Sync Services for ADO.NET comes with a SyncAdapterBuilder that helps you create the required SyncAdapter object and the SQL statements by supplying information such as table name, name of updater column, create originator column, and so on. Figure 2 illustrates how the adapter builder helps you create a SyncAdapter.
Figure 2 SyncAdapterBuilder
sqlSABuilder = new Microsoft.Synchronization.Data.Server.SqlSyncAdapterBuilder(sqlconn);
sqlSABuilder.TableName = "User";
sqlSABuilder.FilterClause = "username='" +   System.Threading.Thread.CurrentPrincipal.Identity.Name + "' ";
sqlSABuilder.TombstoneTableName = "Deleted_"+ sqlSABuilder.TableName;
sqlSABuilder.SyncDirection =   Microsoft.Synchronization.Data.SyncDirection.Bidirectional;
sqlSABuilder.CreationTrackingColumn = "ct";
sqlSABuilder.UpdateTrackingColumn = "ut";
sqlSABuilder.DeletionTrackingColumn = "dt";
sqlSA = sqlSABuilder.ToSyncAdapter(true, true, true, true);
sqlSA.TableName = "User";
destinationProvider.SyncAdapters.Add(sqlSA);
Having said that, most of the time we just need to add logic for populating SyncAdapters on the source provider. You'll need to do both if you are doing a bi-directional synchronization.
To set up database synchronization, create an instance of the SyncAgent object, which is similar to the SyncOrchestrator object I mentioned earlier but designed to carry out synchronization for Sync Services for ADO.NET. Then assign providers to the RemoteProvider and LocalProvider properties of the object. Next, call the Synchronize method of the SyncAgent, which will trigger the synchronization process and call the respective events and methods that are implemented by the providers. The following illustrates how to configure SyncAgent and start synchronization.
SyncAgent syncAgent=new SyncAgent();
syncAgent.LocalProvider = new SqlCeClientSyncProvider ();
syncAgent.RemoteProvider = new DbServerSyncProvider();
syncAgent.Synchronize();
One point to note about Sync Services for ADO.NET is that it's possible to use it with almost any data source supported by ADO.NET, so you're not limited to SQL Server as the source and/or destination database.
Sync Services for ADO.NET uses the SyncTable object to store information about the tables involved in the synchronization. The following code demonstrates how to populate the SyncTable object and configure it with SyncAgent. You can use the SyncGroup class to aggregate SyncTables into a synchronization group that ADO.NET will process as a whole and ensure consistency for all tables in the group.
SyncGroup lookupSyncGroup=new SyncGroup("LookupTables");
SyncTable syncTable = new SyncTable("Customer");
syncTable.CreationOption = syncTable.DropExistingOrCreateNewTable;
syncTable.SyncDirection = syncTable.Bidirectional;
syncTable.SyncGroup = lookupSyncGroup;
syncAgent.Configuration.SyncTables.Add(syncTable);

Implementing Custom Synchronization
What if you want to implement synchronization using your own logic or you want to implement synchronization for data stores that are not supported by the Microsoft Sync Framework? In this case, you need to create your own provider and implement logic for retrieving data from the underlying data store.
To do this, create a class that derives from the abstract class KnowledgeSyncProvider and override the GetChangeBatch method to retrieve the changes. This method is triggered by the SyncOrchestrator object when you initiate the synchronization process. All detected changes are stored in an object called ChangeBatch, which is passed to the ProcessChangeBatch method of the destination provider. The destination provider will process the ChangeBatch object and use its own logic to apply the changes to the destination data store.
The FilterInfo object is used to communicate filtering information between source and destination providers. The source provider is responsible for populating this object and attaching it to the ChangeBatch object. The destination provider can then use it to apply changes to only an appropriate subset of data. Once the custom provider is implemented, you can use it with SyncOrchestrator. Keep in mind, however, that synchronization providers are not thread-safe, so you need to use cloned providers in new threads if you want to have multiple synchronization running under different threads. To do this, create a new provider object and merge it with the existing one by using the Union method. Then configure SyncOrchestrator to use the newly created provider instead of the original one. Otherwise, the synchronization will fail if there is more than one running synchronization session associated with that provider.
Conflict resolution is always problematic when implementing synchronization logic in applications. The Microsoft Sync Framework will determine if there is a conflict on the item using the following logic.
  1. 1.The destination provider determines whether the destination replica's version information for the item is contained in the source replica's knowledge.
  2. 2.If the destination replica's version is not contained in the source replica's knowledge, the object is said to be in conflict.
If the destination version information is not included in the item itself, the Sync Framework will trigger the TryGetDestinationVersion event of the class that implemented the INotifyingChangeApplierTarget interface for each item. You can then add logic in this event to provide the versioning information to the Sync Framework to aid in conflict resolutions.
public bool TryGetDestinationVersion(ItemChange sourceChange, out   ItemChange destinationVersion)
 {
    ...
 }
Microsoft Sync Framework supports some simple conflict resolution by default. You can configure the conflict resolution policy of the provider and the Sync Framework will perform conflict resolution for you. By default, the Sync Framework supports the following five types of conflict resolution policy.
  • Source wins: the source replica always wins if there is a conflict.
  • Destination wins: the destination replica always wins if there is a conflict.
  • Merge: the changes from both source and destination are merged to form a new version of the item, which is then sent to the destination to be applied.
  • Log: conflicts are ignored and the conflicting item information is sent to the SaveConflict event of the class implementing INotifyingChangeApplierTarget.
  • Defer: completely ignore the conflicts and the destination store will not receive information regarding the conflicts.
All of these conflict resolution policies are applicable at item level but only source wins and destination wins apply to session. Sync policy is specified for the provider by setting the ConflictResolutionPolicy property.
destinationProvider.Configuration.ConflictResolutionPolicy =   ConflictResolutionPolicy.DestinationWins;
You can configure the provider to report the progress of the synchronization instead of using the default configuration. By default, the provider will report progress by calling the ProgressChanged event of the associated SyncCallback objects. You can change this behavior by implementing your own progress reporting. To do this, you need to implement events at the item level using the WorkEstimate event of the ItemChange class, or at the Batch level using the BatchWorkEstimate event of the ChangeBatch class. Then within your provider code, you can call the OnProgressChanged method of the provider to report the change whenever you think that is appropriate.

Wrapping Up
The Microsoft Sync Framework is an application programming framework designed to help build synchronization into applications. While the framework itself includes a number of features and libraries that simplify the development work of building synchronization between different data sources, it does not really perform the synchronization: it relies on developers to provide the logic for detecting and applying changes and resolving conflicts.
Sync Services is a set of libraries created to help address the need for synchronization among some commonly used data stores, such as SQL Server, the file system, and RSS. With Sync Services, you do not need to spend time developing the logic for the synchronization; you simply need to adapt the library for your application. The result is fast, easy synchronization. By adapting Microsoft Sync Framework, you can easily bring support of offline data access and collaboration to your own applications.

James Yip MCT, MCITP, MCPD, PMP, is Managing Consultant of Eventus Limited, a Hong Kong–based technologies consulting company. James works as an architect and project manager. He also teaches MOC classes in both Windows Server Systems Administration and .NET development and works as an SME and TR for MOC courses and authors courseware.


Editor's Note
What's In Style
Howard Dierking

Just like music and fashion, it seems that popular trends in development styles, paradigms, and architectures are cyclical. Don't get me wrong—this isn't to say that we don't make progress with each cycle. However, it is just funny to see how the next new thing is always a little eerily familiar; to that end, Raymond Chen nailed it in the title of his book and blog, "The Old New Thing." One of the best illustrations of this cycle in recent history can be found in the design choices around the presentation layer.
When it comes to trends in the presentation layer, we've witnessed some dramatic shifts between the desktop and the Web. As I'm sure you know, when the Web first came along, it was hardly in a position to serve as a viable platform for application development. Its role was to serve up static content pages; the job of creating rich user experiences was still well within the domain of the native Windows application (and yes, I'm purposefully ignoring ActiveX controls for this discussion). However, as the capabilities of Web servers increased, new server-side programming models grew in tandem, giving Web applications enough functionality to, when combined with the simplicity in deployment, cause a dramatic shift away from "thick-client" desktop applications.
The introduction of the .NET Framework, and more specifically ASP.NET, initially accelerated the trend towards 100% Web-based applications. However, successive versions of the framework also introduced a new capability called "click-once" deployment that sought to enable desktop applications to be seamlessly installed and run from a URL. Now you would be able to support all of the rich user experience capabilities in a rich-client application and still deploy it as if it were a Web application. It seemed as though the deployment problem had been solved, and the trend would shift back toward favoring the "rich" desktop application UIs.
However, this shift didn't really happen at the rate you might have expected on the surface, and I suspect that it was in part based on two forces. First, developing UI applications for Windows using metaphors such as clipping rectangles was dramatically different (and arguably more complex) from the hierarchical, container-based model of HTML. Secondly, the rise of AJAX programming (and the various support libraries to further simplify it) was enabling user experiences in Web applications that were comparable with those of desktop applications.
With AJAX continuing to grow in use for Web applications, a paradigm shift was also beginning to pick up speed on the desktop. Desktop applications could now target Windows Presentation Foundation, a framework that incorporated many of the same paradigms as Web applications; one of the single most important of these being composition. And with the introduction of Silverlight, Web applications could be built using not just the same paradigms, but essentially the same technology.
In looking at all of the back and forth over the years, I have two observations. First, both paradigms have pushed each other to be better by incorporating the good characteristics of one into the other. The very positive result from this, other than simply more powerful rendering platforms, is that the paradigms for creating UIs either on the desktop or on the Web are unifying. And this yields the second observation: that the best practices that have emerged around both presentation patterns and more general strategies for creating layered architectures are now directly applicable to both desktop and Web applications.
On that note, I have an announcement. We are excited to welcome Diego Dagum and The Architecture Journal to our MSDN Magazine and TechNet Magazine publishing team. This means that our team now has all three perspectives when it comes to the application of technology: the developer, the IT professional, and now the architect. Look to see even more coordination between the publications.
So while cyclical development trends may not bring back power ballads or parachute pants, they will continue to surface those patterns and technologies that have worked in the past, find what works with those of the present, and produce technologies that will enable the cycle to continue into the future.

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
Microsoft Chart Controls, Visual Studio Automatic Code Snippets, 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
A Chart Is Worth 1,000 Words
Blogs of Note
Create and Manage Code Snippets
The Bookshelf

A Chart Is Worth 1,000 Words
A well-designed chart offers a quick and clear synopsis of data and can reveal cycles, trends, or other patterns that are more difficult to discern from tables of numerical data alone. Until recently, adding charts to a Web page or a Windows client application required using an open-source or third-party charting package. (One such third-party charting component is Dundas Charts, which was reviewed in the January 2006 issue at msdn.microsoft.com/magazine/cc163668). Starting with Visual Studio 2008 and the Microsoft .NET Framework 3.5 SP1, developers can use Microsoft Chart Controls to design and display charts in both ASP.NET and Windows Forms applications.
To get started, download and install the Microsoft Chart Controls and the Chart Controls Add-On for Visual Studio. The first download installs the assemblies that contain the charting library and controls; the second adds Visual Studio Toolbox integration and IntelliSense support. (Note: The Microsoft Chart Controls require the .NET Framework 3.5 SP1; the Visual Studio Add-In is for the non-Express versions of Visual Studio 2008.)
Next, launch Visual Studio and open a Windows Forms or ASP.NET application and drag the Chart control from the Toolbox onto the Design surface. You can specify the chart's size, type, colors, series, legends, and other display-related criteria through its properties. The chart data can be specified statically or can come from a dynamic source such as an array, a database, an XML file, a CSV file, or a Microsoft Excel spreadsheet.
What impressed me most about the Microsoft Chart Controls are the breadth of its features. There are many different chart types available, from the standard line, bar, and pie charts to more exotic ones like radar, histogram, pyramid, Pareto, and bubble charts. The chart data can be grouped, sorted, filtered, and searched. With a single line of code, you can export the chart data to an XML file, or enhance your charts to include moving averages, range indicators, and trend lines. It's similarly easy to add markers, annotations, titles, legends, and other visuals to the chart surface. Furthermore, the chart's output can be customized by creating event handlers for Chart Controls events such as PrePaint and PostPaint.
The Microsoft Chart Controls also include a number of features for interactive charts. For example, when a user clicks on a data point, you can display detailed information about that data point in the same chart area or in a separate chart or grid. The Chart Controls for Windows Forms applications can be configured to allow the user to zoom or scroll through the chart data. And both versions of the Chart Controls support real-time charts, which are charts whose data is continually being generated and whose appearance is continually updated to display the new data. The Chart Controls for ASP.NET applications use the ASP.NET AJAX framework to automatically perform most of its interactive features, meaning that you don't have to be a JavaScript expert. However, you can execute custom JavaScript in response to a user's click, if needed.
There are some shortcomings of the Microsoft Chart Controls, which is to be expected with the first release of any software library. As noted earlier, there are separate downloads for the Chart Controls and the Visual Studio integration instead of a single, consolidated package. Getting the library's documentation and samples environment involves two additional downloads. And at this time, there is no support for Silverlight or Windows Presentation Foundation applications (although the Silverlight Toolkit includes its own Chart control). Finally, there is no wizard to assist with creating and customizing the appearance of the chart. Granted, there are plenty of code samples available and the chart's properties are straightforward and easy to configure, but because there are so many appearance-related properties, it can take a while to unearth the property to change to, say, adjust the font size of the primary X-axis label. These shortcomings will hopefully be addressed in future releases.
Price: Free
go.microsoft.com/fwlink/?LinkId=142580
go.microsoft.com/fwlink/?LinkId=142581
Chart from Microsoft Chart Controls

Blogs of Note
Like most .NET developers, I spend most of my day in Visual Studio. Despite my familiarity with the tool, I am constantly learning about features, options, windows, and wizards that I had no idea existed. I discover some of these previously unknown features through trial and error, but much of my Visual Studio knowledge comes from blogs like the one by Sara Ford, a Program Manager for CodePlex.com. Over the years, she's compiled hundreds of Visual Studio tips and published them on her blog.
Each tip is a concise description of some little-known Visual Studio feature, often complete with a screen shot or two illustrating the tip in action. Some tips are simple keyboard shortcut tips, like Tip #346: You can press Ctrl+Shift+C to jump to the Class View. Others are tips on how to remove certain annoyances, like Tip #168: How to stop the Output window from showing itself during a build. And ones like Tip #239: You can set condition breakpoints, offer debugging tips and tricks.
The information in these tips is invaluable. Next time you have a free hour or two, surf over to Sara's blog and start poking through the tips. I guarantee you will learn something new. (After one and a half years of sharing her Visual Studio tips, Sara wrote her last tip—#382—in December 2008; her blog now focuses on CodePlex and the .NET community.)
blogs.msdn.com/saraford
Sara Ford’s Blog

Create and Manage Code Snippets
Visual Studio includes a bevy of features that provide a surefire way to become a more productive programmer. One of the most powerful productivity enhancements is Code Snippets, which are task-oriented blocks of code that can include replaceable regions. For example, there are Code Snippets that generate LINQ query code, some that add the boilerplate code for a foreach loop, and others that write the code for working with text files. Adding a Code Snippet to a class file injects the Code Snippet's code and allows the developer to specify the text for any replacement regions.
Visual Studio includes several dozen built-in Code Snippets (more for Visual Basic than for C#); you can also import Code Snippets or create your own from scratch. Unfortunately, Visual Studio does not offer any help in creating Code Snippets from scratch—you must type the Code Snippet's code and replaceable regions in a properly formatted XML file and then import the file into Visual Studio.
Creating Code Snippets is a lot easier when using Snippet Designer (version 1.1), a free, open-source Add-In for Visual Studio 2008 for creating and editing Code Snippets directly within the IDE. Once you install it, creating a new Code Snippet is as easy as going to the File menu and creating a new Code Snippet File. This opens a window in Visual Studio where you can type in the Code Snippet's code, specify any replacement regions at the click of a mouse, and customize the Code Snippet's information through the Properties window. Snippet Designer makes it easy to create a new snippet from existing code—select the code to use and then right-click and choose "Export as Snippet" from the context menu. This loads the Code Snippet interface and imports the selected code.
In addition to the integrated Code Snippet editor, Snippet Designer also includes a Snippet Explorer window that is more functional than Visual Studio's built-in Code Snippets Manager window. The Snippet Explorer window allows you to list all snippets in one or more specified languages and includes a textbox for filtering the results. Selecting a Code Snippet from the search results displays the Code Snippet's code. Right-click a Code Snippet and choose Open to edit the Code Snippet in the integrated Snippet Designer editor.
Price: Free
www.codeplex.com/SnippetDesigner
Managing Code Snippets in Visual Studio

The Bookshelf
Each time a new version of C# is released, so are a flurry of books that showcase the language's new features. These books usually do a good job of explaining why each new feature was added and offer examples on how to use it, but often the reader is left with some sinking questions: when does it make sense to use this new feature? How can I best use these new features to implement best practices? Are there hidden pitfalls when using these new features?
A great resource for getting to the bottom of these types of questions is the Effective Software Development series by Addison-Wesley. I was first introduced to this series by Bill Wagner's book, Effective C#. Written in 2004, Effective C# offers 50 detailed guidelines for making the most of C# version 1.0. Bill recently wrote a brand-new book, More Effective C#, which includes another 50 guidelines for writing better C# code using the language features added to C# versions 2.0 and 3.0. For example, there are 10 guidelines on using generics, eight on C# 3.0 language enhancements, and another nine on LINQ.
More Effective C# assumes the reader is already familiar with C# and language features like generics, LINQ, multithreading, and so on. You won't find any discussions on what generics are or the syntax for lambda expressions. Instead, the book states a specific guideline, such as "Distinguish between IEnumerable and IQueryable data sources," and then provides a deep and detailed discussion on the why of the guideline with illuminating prose and helpful code snippets. And each guideline stands on its own and can be read and digested without having first read other guidelines, meaning that you can jump around to what guidelines interest you the most or are the most relevant for your current projects.
The amount of information per page in this book is astounding. There are no callouts, no diagrams, no pictures, no superfluous anecdotes or humorous side stories, and little whitespace to break up the book's text. It's a lot of great information in a very terse and compact format.
More Effective C# is a must-read for experienced C# developers who are already familiar with C# language features such as generics, extension methods, lambda expressions, anonymous types, and LINQ, but who want guidance on how best to use these features.
Price: $44.99
www.informit.com/esds

Improving the responsiveness of a data-driven application often involves using SQL Profiler or other tools to determine which queries take the longest to execute, and then fixing those problem queries by adding new indexes or modifying existing ones. But sometimes indexes only provide a partial solution.
There may still be ways to squeeze out more performance by rewriting the SQL query itself, but where do you start?
There already exists a proven methodology for making small, incremental changes to the source code of an application—refactoring. Refactoring is the process of incrementally improving existing source code without changing the program's overall output or functionality and is a core practice of agile software development.
While refactoring has traditionally been used with object-based languages such as C# and Visual Basic, its tenets can also apply to SQL. In Refactoring SQL Applications (O'Reilly, 2008), authors Stéphane Faroult and Pascal L'Hermite offer guidance on how to improve performance by retooling a data-driven application's existing SQL queries, views, user-defined functions (UDFs), and data-access logic.
Refactoring SQL Applications begins with a discussion on analyzing the impact of refactoring to determine whether it is worth doing. Such an analysis will answer questions like, "Are there multiple SQL queries executed because of a loop construct in the application?" and "Could multiple queries be packaged into a single stored procedure?" Unearthing the answers to these questions involves a deep understanding of the data-driven application that is gained, in part, by logging and scrutinizing the database activity.
There are five chapters with refactoring advice. The first one examines refactoring UDFs and views. Another chapter looks at refactoring SQL statements and provides guidance on how to streamline the FROM clause, tips on when to use subqueries, ways to simplify filtering conditions, and other optimizations. There's also a chapter on refactoring tasks that explores how to improve the way the data-driven applications interact with the database.
Large performance gains are possible by moving data access code outside of loops, using the database's aggregate functions when possible, and fetching all the data you need at once. There's another chapter on how to refactor SQL queries to best take advantage of parallelism. The book concludes with a chapter titled "Refactoring in Practice," which poses a number of questions to ask and items to investigate when tasked with refactoring a SQL application.
When refactoring code, it is imperative to ensure that the changes made while refactoring have not affected the program's existing functionality. Unit tests are commonly used to verify that refactored code still generates the expected output, but they are not always ideal for comparing database results.
The authors offer advice on how to create and use a custom testing framework when refactoring SQL queries. This discussion includes a look at how to generate large amounts of realistic test data and different techniques for verifying that the resultsets returned by the original query and the refactored query are equivalent.
Price: $44.99
oreilly.com
Refactoring SQL Applications
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
CLR Optimizations In .NET Framework 3.5 SP1
Surupa Biswas
Contents
Startup Performance Improvements
JIT Optimizations
NGen and ASLR
The .NET Framework 3.5 Client Profile
Wrapping Up
A surprising amount of work went into the core of the Microsoft .NET Framework for the .NET Framework 3.5 SP1 released in August 2008. Here, I'll provide in-depth information about the changes that we on the CLR team made to the common language runtime (CLR) and the improvements you can expect by simply running your existing CLR 2.0-based applications against this latest service pack. Most of our effort was centered on improving performance, security, and deployment of applications targeting the .NET platform.
Before delving into the details, note that you can download the .NET Framework 3.5 SP1 from the Microsoft Download Center. It is also available through Windows Update. Also, take a look at Figure 1. It answers the perennial question: Which CLR version is inside which version of the .NET Framework?
Figure 1 .NET Versions and CLR Versions
.NET Framework Version | Contains CLR Version
2.0 | 2.0
3.0 | 2.0, 3.0
3.5 | 2.0 SP1, 3.0 SP1, 3.5
3.5 SP1 | 2.0 SP2, 3.0 SP2, 3.5 SP1

Startup Performance Improvements
Improving the startup performance—in particular, the cold startup time of managed applications—was a primary focus of .NET Framework 3.5 SP1.
Managed assemblies in the .NET Framework are largely precompiled via NGen ("The Performance Benefits of NGen"), and the layout of the code and data in the NGen images has a strong impact on the startup performance of applications that use the framework. In particular, since cold startup time is typically bound by the number of pages of the image that need to be read from disk, any effort to reduce it translates into an effort to better pack the image so that only a small subset of its pages are read during startup.
To that effect, the CLR uses a profile-driven engine to optimize the layout of NGen images for assemblies in the .NET Framework. The profile data is collected by running scenarios that we believe are representative of our framework's usage, and then included as a resource in the corresponding assembly when it is being built. During NGen, if such a resource is found in an assembly, it is used to pack the "hot" code and data (those that were accessed when the training scenarios were run) together, thereby moving the "cold" code and data into their own sections in the image.
Furthermore, .NET Framework 3.5 SP1 contains several improvements to our hot/cold splitting infrastructure, which in turn improve the locality of NGen images. In particular, basic blocks in methods that contain various kinds of control flow—switch statements or unconditional branches, for example—are now rearranged such that more cold blocks can be split off and moved to the cold part of the NGen images. We also implemented a better algorithm for merging profile data from multiple training scenarios—we now prioritize packing together data/code that is accessed by the greatest number of scenarios in a given training set. Finally, to further improve spatial locality for code that is executed together temporally, the executable code in the NGen image is partitioned into RunOnce, RunMany, and RunNever sections. These improvements to our profile data collection and usage were made for both 32-bit and 64-bit platforms. As a result of these changes, there was a greater than 50% (sometimes significantly higher) reduction in the number of cold pages touched when a training scenario was re-run on top of a trained .NET Framework.
Unfortunately, our profile data-gathering framework is still internal-only. So while this work benefits all managed applications that use .NET Framework libraries at startup, those that NGen the applications' assemblies could further optimize startup performance by using our training framework. We'd like to make this framework available at some point, so stay tuned!
Note that a somewhat unrelated change ("Strong Name Bypass") also addresses another NGen-related problem that was mentioned earlier in my article "The Performance Benefits of NGen," namely, time spent verifying strong name signatures.

JIT Optimizations
Switching gears a little, .NET Framework 3.5 SP1 also contains improvements to the quality of the code generated by the 32-bit and 64-bit JIT compilers. In particular, the 32-bit JIT can now inline method calls that involve passing, returning, or operating on structs. Prior to this release, the 32-bit JIT simply gave up trying to inline such functions because structs aren't first-class citizens in the x86 JIT and are lowered into byref pointers very early in the compilation process. Once that happens, the JIT is no longer able to identify the structs and cannot do the sort of normal optimizations, such as copy propagation, that are performed on primitive types.
Thus in the following example, the JIT compiler was unable to determine that it simply needs to propagate "a" to the last statement and instead generates code for three sets of redundant copies (b=a; c=b; d=c;).
MyStruct a, b, c, d;
a = new MyStruct(1, 2);
b = a;
c = b;
d = c;
Console.WriteLine(d);
The goal of this work was therefore to allow inlining of functions that use structs and enable subsequent optimizations such as copy prop. The approach taken was to select structs that meet certain heuristics (such as no more than four fields, fields are either primitive types or refs, and so on), "promote" the fields to local variables internally in the compiler, and take advantage of the fact that standard optimizations are already enabled for primitive types and refs. Thus, all operations on the promoted structs are changed to reflect operations on the individual "field locals." More details on this can be found on the blog JIT, NGen, and other Managed Code Generation Stuff. After tuning the inliner heuristic, we ended up with better code quality and lower NGen time, so this work was a win-win. Note that the inliner in the 64-bit JIT is different and wasn't changed dramatically in 3.5 SP1; however, we've made several improvements to it since, which should be available in the upcoming .NET Framework 4.0 release.
In addition to the inliner work, both JIT compilers in 3.5 SP1 are now better at propagating assertions (what is known to be true) in the generated code, which in turn results in better code quality because of eliminated null checks, TypeOf checks, comparisons against constants, comparisons between variables, and so on.
The JIT compiler can now also straighten branches by predicting whether a branch is more likely to be taken or not. Thus, if a taken branch is expected to be more common than the fall-through code path, the fall-through blocks are moved further down, after the blocks in the branch target. (The condition of the branch is also reversed, of course.) Straightening branches in this manner helps branch prediction (forward branches are typically assumed to not be taken when there is no branch history) and improves cache locality. While the outcome of some branches can be predicted statically (exceptional code-paths are assumed to not be executed, for instance), we also use the previously mentioned profile data for the purposes of branch straightening. This work on its own resulted in a greater than 10% improvement in the throughput of some of our ASP.NET benchmarks.
While this isn't a JIT optimization by any means, we did make another major change to the 32-bit JIT compiler in 3.5 SP1. For managed call-stacks, the EBP chain can now be walked (by a debugger or profiler) to determine what functions were called. This simply means that the JIT compiler no longer uses EBP as a scratch register and instead uses it exclusively to store the frame pointer. Note, however, that the JIT compiler doesn't guarantee that it will push or pop EBP to or from the stack for every function call (to avoid the performance cost of doing so for tiny methods). Thus, walking the EBP chain now gives you an ordered list of methods that were invoked, but there can be methods missing from the list. We did choose a conservative heuristic when determining which methods to generate EBP frames for, so it should be reasonably easy to determine the complete list given an understanding of the program's call graph. Of course, in debug mode we push or pop the EBP register for every function call. The primary motivation behind this work was to enable kernel-mode profilers that cannot safely use our managed stack-walking APIs to walk the stack when managed applications are being run.

NGen and ASLR
We made a significant overhaul of the infrastructure that generates and writes out NGen images in 3.5 SP1. It is now more efficient, consumes less memory, and produces images that are more compact. This resulted in improvements in NGen time of more than 100% (when compared to a runtime that uses the old NGen infrastructure) and approximately a 10% improvement in the cold startup time of some large applications such as Expression Blend. The startup time improvement was a side effect that resulted from the fact that data structures persisted in the NGen image were more compact. This work improved .NET Framework set-up time as well since a good portion of the installation time is spent generating NGen images for assemblies in the framework.
Starting with this service pack, we've also opted NGen images into using Address Space Layout Randomization (ASLR), a security feature that was added to Windows in Windows Vista (see "Address Space Layout Randomization in Windows Vista"). ASLR relies on the ability to efficiently load PE images at random locations in the virtual address space, and hence on the ability to efficiently fix up addresses referred to in the images themselves. Unlike unmanaged images, which contain direct references only to locations within the same image, NGen images used to also contain direct references to code/data in other assemblies' NGen images. (See the section on hardbinding in my previous article, "The Performance Benefits of NGen.") Such external references cannot easily be handled by the kernel's fix up logic. Thus, one of the more significant efforts in .NET Framework 3.5 SP1 involved changing the format of NGen images to eliminate the use of such direct pointers without giving up on the performance wins we'd obtained when we introduced hardbinding. Indirect references—and managed code typically contains a lot of them—are expensive not only because of the additional level of indirection involved, but also because they need to be fixed up by default. (And writing to the indirection cells results in private pages that cannot be shared across processes.) These indirect references were strewn all over the NGen image (and resulted in lots of private pages); hence a lot of the effort was centered on restructuring the image such that all the indirection cells were colocated, patched together, and resulted in as few pages written to at run time as was possible. At the end, the performance degradation was measurable in only a few warm startup and throughput scenarios, and even in those cases the impact was minimal.
One of the side effects of the ASLR work is the fact that you no longer need to worry about choosing noncolliding base addresses for your NGen images (see "The Performance Benefits of NGen") when targeting Windows Vista or newer platforms. (It is still an issue on Windows XP and older platforms, however.) In another unrelated security change, all managed applications built with our 3.5 SP1 tool set are now opted into Data Execution Prevention by default.

The .NET Framework 3.5 Client Profile
In the .NET Framework 3.5 SP1, we also tried to address one of the other major problems we've had with the framework—namely, getting it deployed on end user machines. We decided to focus on providing a leaner framework package for certain kinds of applications that made use of only a subset of the functionality provided by the framework. Because the focus of this package was to enable developers to write client applications—primarily WPF-based applications—we call it the Client Profile. Note that the Client Profile is a true subset of the full .NET Framework.
Introducing a new way to split the framework in a service-pack release turned out to be a far more challenging task than we'd originally envisioned it to be. In particular, we already had a "horizontal slicing" of our product; we were now introducing a "vertical slicing."
This lead to interesting scenarios that involved installing old frameworks on top of new partial frameworks, and vice versa. To trim down the set of possible scenarios, we made the following simplifications:
  • The Client Profile can be installed only on machines that don't have any CLR 2.0-based framework installed (since installing the framework on "clean" Windows XP machines was the biggest pain point).
  • Old versions of the framework cannot be installed on top of the Client Profile (thus the ASP.NET stack included in .NET Framework 2.0 cannot be installed on top of the new CLR included in the 3.5 SP1 Client Profile)—there just wasn't a good way for us to test all the resulting combinations of old/new binaries.
We encountered another interesting situation when testing some applications on top of the Client Profile. Some applications that targeted existing .NET Framework versions (2.0/3.0/3.5) seemed to install and run on top of the Client Profile (since they all contain the same compatible 2.0 CLR) and then failed when attempting to call APIs that weren't included in the Client Profile! While the particular application that made us think of this problem had an installer that wasn't looking for the documented install keys for the framework, we quickly realized that this would affect all xcopy-deployed applications as well. As a consequence, we decided to block applications from running on top of the Client Profile unless they were explicitly marked as capable of running on the subset. We then changed the runtime to ensure that non-Client applications failed gracefully, immediately, and with a diagnostic error message (requesting the end user to install the full .NET Framework 3.5 SP1) when they were executed on the Client Profile.
A lot more information about targeting the Client Profile, the subset of functionality that it supports, and so on can be found in the ".NET Framework Client Profile" article on MSDN.

Wrapping Up
Before wrapping up, I'd like to mention another change we made to the runtime in 3.5 SP1, which a lot of users have asked for in the past—the ability to launch managed applications from a local intranet share in full trust without having to manually tweak security settings. This is described in further detail in the .NET Security Blog article, "FullTrust on the LocalIntranet," but seems worthwhile to mention in case you didn't know about this yet, and is something you've wanted for a long time.
This article was simply intended to give you an idea of the changes we made to the CLR in the latest service-pack release of the .NET Framework. Note that there were a lot of changes made to other parts of the .NET Framework as well (an overview can be found in Scott Guthrie's blog post. In conclusion, I hope you are now excited about trying out this release that's been a year in the making.
If you have any questions or comments, don't hesitate to send them our way.

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

Surupa Biswas is a program manager on the CLR team at Microsoft. She works on the runtime's back-end compiler and focuses primarily on pre-compilation technologies.


Data Points
Using Silverlight 2 With ADO.NET Data Services
John Papa
Code download available from the MSDN Code Gallery
Browse the Code Online
Contents
Cross-Domain Communications
Being Smart About Sensitive Data
Getting Started Quickly with EDM
Referencing ADO.NET Data Services from Silverlight
Retrieving Data Using LINQ
Deferred Loading
Saving Data
Retrieving Data in Advance
To Be Continued
ADO.NET Data Services makes it tremendously easy to expose data and allow updates over HTTP using its RESTful (Representational State Transfer) abilities. Your Silverlight applications can take advantage of ADO.NET Data Services to send and receive data using the unique URIs that map to entities. You can also use LINQ queries in the Silverlight client to interact with the entities on the server by using the ADO.NET Data Services Silverlight client library.
ADO.NET Data Services and Silverlight make a powerful combination, but to make them work well together you need a good understanding of a few aspects that may not be immediately obvious. So, here I'll address some steps you can take to ensure a more successful experience when building applications with ADO.NET Data Services and Silverlight.

Cross-Domain Communications
ADO.NET Data Services does not currently support cross-domain communications. Cross-domain communications are supported with standard REST and SOAP services, but not with ADO.NET Data Services. (As a note: the data services team is exploring the space and will post their progress to the Astoria team blog as they go.) This means that a Silverlight 2 client cannot talk to services exposed through ADO.NET Data Services if those services are hosted on a different domain than the domain that hosts the Silverlight client application. For more information on cross-domain policies, please refer to my September 2008 "Data Points" column. In that column, I discuss the file formats and how the policies work.

Being Smart About Sensitive Data
When you are using HTTP communications, all values sent via URIs are clearly visible through a variety of network sniffing tools. One way to combat this is to use SSL to encrypt all HTTP communications. Also, send no sensitive data, such as social security numbers, or any other private data, in the URI. It is a good idea never to use sensitive data as identifiers. Before choosing any RESTful communication, be sure to use a meaningless identifier such as a GUID, a number, or an IDENTITY value. For example, the following sample URI could retrieve employee data using the employee ID of 11:
http://[YourDomainHere]/MyService.svc/Employee(11)
The number 11 is transparent in the URI, which is why it is important not to use sensitive information. Fortunately, in this case the number 11 represents a fabricated identifier, so no personal data is exposed.

Getting Started Quickly with EDM
Perhaps the simplest way to get up and running with ADO.NET Data Services is to expose data from a relational database as a logical entity model using the ADO.NET Entity Framework. The Entity Framework's Entity Data Model (EDM) is fully aware of how to allow read and update access to its entities. This built-in ability of the EDM allows it to work in concert with ADO.NET Data Services with very little setup.
The first step in exposing an EDM created with the Entity Framework is to create the ADO.NET Data Services service from the Visual Studio templates dialog. This creates a template that can easily be modified to expose an EDM from the Entity Framework. The class constructor inherits from the DataService<T> base class. The T represents the data source class, which in this case is the Entity Framework data source class named Entities. The data source class, also known as the object context class in the Entity Framework, is what allows access to the EDM to retrieve and save data. Since the data source class is created automatically with the Entity Framework, creating an ADO.NET Data Service that exposes the EDM is quite simple. In Figure 1, the code shows the service class NWDataService inheriting from the DataService<Entities>.
Figure 1 Creating the DataService
public class NWDataService : DataService<Entities>
//public class NWDataService: DataService< /* TODO: put your data source
//class name here */ >
 {
    // This method is called only once to initialize service-wide
    //policies.
    public static void InitializeService(IDataServiceConfiguration
        config)
    {
        //set rules to indicate which entity sets and service operations
        //are visible, updatable, etc.
        config.SetEntitySetAccessRule("ProductSet", EntitySetRights.All);
        config.SetEntitySetAccessRule("CategorySet",
            EntitySetRights.AllRead);
        config.SetEntitySetAccessRule("SupplierSet",
            EntitySetRights.AllRead);
        config.SetEntitySetAccessRule("OrderSet",
            EntitySetRights.AllRead);
        config.SetEntitySetAccessRule("OrderDetailSet",
            EntitySetRights.All);
        config.SetEntitySetAccessRule("CustomerSet",
            EntitySetRights.AllRead);
        /// The rest of the entity sets are not accessible.
        /// Therefore, no proxy classes are created for them either.
    }
}
The next step is to allow or deny read and write access to each of the entity sets in the EDM as shown in Figure 1. This can be done on all entity sets using the * or on an individual entity set level by specifying each entity set name. The SetEntitySetAccessRule method accepts the name of the entity set that the rule will be applied to and one or more EntitySetRights enum values. Notice in Figure 2 that each of the entity sets for ProductSet, OrderSet, OrderDetailSet, CustomerSet, SupplierSet, and CategorySet allow all access. This means that those six entity sets allow reading, inserting, updating, and deleting. These are service-wide access settings and apply to all requests coming into the system. Any entity set not listed, such as EmployeeSet or RegionSet, is not accessible.
Figure 2 System.Data.Services EntitySetRights Enums
Enum | Description
All | All reads and writes are permitted on the specified entity
AllRead | All reads are permitted
AllWrite | All write operations are permitted
None | No access permitted to the specified entity
ReadMultiple | Reading multiple rows is permitted
ReadSingle | Reading a single row is permitted
WriteAppend | Creating new data is permitted
WriteDelete | Deleting data is permitted
WriteMerge | Merge-based updates are permitted
WriteReplace | Replacing is permitted
The EntitySetRights enum values indicate the type of access allowed for the entity set. Figure 2 shows all of the valid enum values and their descriptions. Permission can be given on a global scale for all entity sets, too. For example, the following line of code would allow all read access to all entity sets, but would not allow write access:
config.SetEntitySetAccessRule("*", EntitySetRights.AllRead);
Rights can be combined to allow more than one right for an entity set, as well. The following code makes the ProductSet entity set accessible for reading and updating only:
config.SetEntitySetAccessRule("ProductSet",
EntitySetRights.AllRead |
EntitySetRights.WriteMerge |
EntitySetRights.WriteReplace);
Following these steps will expose the six entity sets (shown in Figure 1) and make them available via an ADO.NET Data Service. Other entity sets and permissions can be customized too.
Entity models built with other object-relational mappings (ORM)s, such as LINQ to SQL and NHibernate, can also be used with ADO.NET Data Services. The context objects must implement IQueryable for each entity set that will be queried. For create, update, and delete operations, the context object must implement the IUpdatable interface. ADO.NET Data Services has built-in knowledge of the ADO.NET Entity Framework that allows it to support querying and updating via ADO.NET Data Services. It is likely that future versions of other ORMs will also have support for ADO.NET Data Services or at least have helper classes to help jump-start it. But for now, if you want to use an ORM other than Entity Framework with ADO.NET Data Services, you will need to implement the interfaces described above. In fact, ADO.NET Data Services is not specific to relational data. Any data source can be configured via the techniques noted in this paragraph.
Figure 3 Generated Classes from the Service Reference
Referencing ADO.NET Data Services from Silverlight
Once the ADO.NET Data Service has been created and built, a Silverlight application can reference the service and interact with it. An ADO.NET Data Service can be referenced from the Silverlight application by right-clicking the Service References node in the Solution Explorer to open the Add Service Reference dialog window. You can either enter the URI of the service in the Address box or you can click the Discover button, and then click the Go button to locate the service. Once the metadata for the service is retrieved, the service and the entity sets that it exposes will appear in a list. Finally, name the service reference and click the OK button.
This creates a proxy class in the Silverlight client that allows you to interact with the ADO.NET Data Service. If you click the Show All Files button in the Solution Explorer window and expand the NWServiceReference node completely, you will see a Reference.cs file. This file contains the generated proxy class that allows you to interact with the ADO.NET Data Service and the generated classes for the entities that are exposed through the service. The list of classes can also be seen by looking in the Class View window, as shown in Figure 3.
Notice that all of the entities in the Entity Framework's model in the Web project are not listed in the Class View. Only entity sets that are accessible via the data service will have proxy classes generated for them when a service reference is added to the ADO.NET Data Service from a Silverlight client. The six entity sets shown in the Class View were exposed by using the SetEntitySetAccessRule methods in the ADO.NET Data Service, therefore these are the only entity sets available to the Silverlight client. The seventh class in the Class View window, the Entities class, is a proxy class that represents the data service as a whole and facilitates the calls to NWDataService.svc.

Retrieving Data Using LINQ
The next step is to reference the System.Data.Services.Client assembly in the Silverlight project (See Figure 4). This assembly makes it easy to interact with the ADO.NET Data Service using LINQ. For example, the following code creates a LINQ query that selects all of the products using ADO.NET Data Services:
_products.Clear();
  DataServiceQuery<Product> dq = (from p in _ctx.ProductSet select p)
  as
  DataServiceQuery<Product>;
  dq.BeginExecute(new AsyncCallback(FindProduct_Completed), dq);
Figure 4 Referencing the ADO.NET Data Services Client Library from Silverlight
The LINQ query in this code is translated into a URI that ADO.NET Data Services can read. The query is cast to a DataServiceQuery<T>, which is part of the System.Data.Services.Client namespace. The query executes asynchronously, so a valid callback method must be specified to receive the results from the query. When the query in the preceding code sample executes and the data is returned, the FindProduct_Completed method will be invoked.
The FindProduct_Completed method (shown in Figure 5) accepts an IAsyncResult parameter containing the results from the query. The results are read by calling the EndExecute method, which yields a set of Product objects. Each product is then examined and an event handler is assigned to its PropertyChanged event. (In the sample code, I extended the Product class using a partial class to add the INotifyPropertyChanged implementation.) This step ensures that when changes are made to any Product instance in Silverlight, that the Product will notify the DataServiceContext (Entities, in Figure 5) by calling the UpdateObject method. Without this code, DatServiceContext would be unaware of any changes made by the user to a Product instance. Assuming that the _products variable is of type ObservableCollection<Product> and that it is bound to the DataContext of a DataGrid control, the products will appear in the DataGrid control (see Figure 6).
Figure 5 FindProduct_Completed Method
private void FindProduct_Completed(IAsyncResult result)
{
    DataServiceQuery<Product> query = (DataServiceQuery<Product>)result.
         AsyncState;
    try
    {
        var entities = query.EndExecute(result);
        foreach (Product item in entities)
        {
            item.PropertyChanged += ((sender, e) =>
                                         {
                                             Product entity = (Product)
                                                                sender;
                                             _ctx.UpdateObject(entity);
                                         });
            _products.Add(item);
        }
    }
    catch (Exception ex)
    {
        Debug.WriteLine("Failed to retrieve data: " + ex.ToString());
    }
}
Figure 6 Loading Products and Order Details

Deferred Loading
The ADO.NET Data Services client library in Silverlight offers the ability to load objects associated with an object already in the DataServiceContext. For example, when a product is selected in the upper DataGrid in the Silverlight control shown in Figure 6, before the order details for that product can be bound to the lower DataGrid, they must be retrieved. The first step in this process is to assign an event handler to the SelectionChanged event of the productDataGrid. Then when a product is selected, the event handler (shown in Figure 7) uses the BeginLoadProperty method to ask ADO.NET Data Services to get the OrderDetails objects for the selected product.
Figure 7 Asking for Order Details
void productDataGrid_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    Product product = productDataGrid.SelectedItem as Product;
    if (product == null) return;

    _orderDetails.Clear();

    if (product.OrderDetails == null || product.OrderDetails.Count == 0)
    {
        _ctx.BeginLoadProperty(product, "OrderDetails", FindOrderDetail_Completed, null);
    }
    else
    {
        LoadOrderDetails();
    }
}
The BeginLoadProperty method makes a network request to go get the OrderDetails records, and when it returns it will invoke the callback method, FindOrderDetail_Completed. If any additional state needs to be passed from this code to the callback method, it can be passed in the fourth parameter of the BeginLoadProperty method. For example, the same event handler may be used to receive the results from several asynchronous queries. A value could be passed in the state parameter to help the callback method determine whose asynchronous call query results it is receiving.
When the callback is invoked, the results are read into the DataServiceContext object using its EndLoadProperty method, as shown here:
_ctx.EndLoadProperty(result);
Deployment.Current.Dispatcher.BeginInvoke(() => LoadOrderDetails());
The order details are then loaded by the method LoadOrderDetails. Since the code runs as the result of an asynchronous operation completing, there is no guarantee that this code will be running on the UI thread.
If the code is not running on the UI thread, then the new set of order details will not appear in element DataGrid. Basically, any UI operation must run on the UI thread. One way to make sure an operation runs on the UI thread is to use the Dispatcher object's BeginInvoke method. The preceding code uses the Dispatcher to make sure the order details are loaded on the UI thread by calling LoadOrderDetails (shown in Figure 8).
Figure 8 Loading Order Details
private void LoadOrderDetails()
{
    Product product = productDataGrid.SelectedItem as Product;
    if (product == null) return;

    var query = (from od in product.OrderDetails
                 orderby od.OrderID ascending
                 select od);
    foreach (OrderDetail item in query)
    {
        item.PropertyChanged += ((sender, e) =>
        {
            OrderDetail entity = (OrderDetail)sender;
            _ctx.UpdateObject(entity);
        });
        _orderDetails.Add(item);
    }
}
LoadOrderDetails grabs the currently selected Product instance and creates a LINQ query that will select all of the OrderDetails objects from the selected Product. This is possible since the order details were loaded into DataServiceContext using EndLoadProperty. Once the order details are retrieved using the LINQ query in Figure 8, each OrderDetail object instance has its PropertyChanged event handler assigned a lambda expression that tells DataServiceContext if any property values are changed. Assuming the _orderDetails object is an ObservableCollection<OrderDetail> element that is bound to orderDetailsDataGrid, the order details will appear (as you saw in Figure 6).

Saving Data
The sample shown also allows the user to save changes to both the products and the order details. There are two basic steps to allow for saving changes: notifying DataServiceContext when changes occur and issuing the save operation asynchronously.
These hierarchical sets of data each have a partial class in Silverlight that extends the Product and OrderDetail entities. The partial class for Product (shown in Figure 9) implements the INotifyPropertyChanged interface, which requires that the PropertyChanged event be implemented. The partial Product class that is generated by creating the service reference to the ADO.NET Data Service creates partial methods for each of the public properties on the class. Each property gets a method that fires when a property is about the change and one when the property has already changed. For example, the Product class's ProductName property has an OnProductNameChanging partial method and an OnProductNameChanged partial method. Figure 9 shows that the OnProductNameChanged partial method in the custom code (not the generated class) fires the PropertyChanged event. This is the key for tracking all changes to all entities' property values. DataServiceContext needs to know when the property values change and what they change to; otherwise it cannot save the changes.
Figure 9 Implementing Change Notification
public partial class Product :INotifyPropertyChanged
{
    public event PropertyChangedEventHandler PropertyChanged;

    private void FirePropertyChanged(string propertyName)
    {
        var handler = PropertyChanged;
        if (handler != null)
            handler(this, new PropertyChangedEventArgs(propertyName));
    }

    partial void OnProductIDChanged() { FirePropertyChanged("ProductID"); }
    partial void OnProductNameChanged() { FirePropertyChanged("ProductName"); }
    partial void OnDiscontinuedChanged() { FirePropertyChanged("Discontinued"); }
    partial void OnDiscontinuedDateChanged() { FirePropertyChanged("DiscontinuedDate"); }
    partial void OnQuantityPerUnitChanged() { FirePropertyChanged("QuantityPerUnit"); }
    partial void OnReorderLevelChanged() { FirePropertyChanged("ReorderLevel"); }
    partial void OnRowVersionStampChanged() { FirePropertyChanged("RowVersionStamp"); }
    partial void OnUnitPriceChanged() { FirePropertyChanged("UnitPrice"); }
    partial void OnUnitsInStockChanged() { FirePropertyChanged("UnitsInStock"); }
    partial void OnUnitsOnOrderChanged() { FirePropertyChanged("UnitsOnOrder"); }
}
Once the property changed event handlers are set for each property, DataServiceContext will be made aware of any changes and the rest of the work to save the data is relatively simple. When a user clicks the Save button the BeginSaveChanges method is invoked on DataServiceContext, as shown here:
private void SaveButton_Clicked(object sender, RoutedEventArgs e)
{
    _ctx.BeginSaveChanges(SaveChangesOptions.Batch,
        new AsyncCallback(Save_Complete), null);
}
This method makes a POST operation through ADO.NET Data Services, sending all changes that DataServiceContext is aware of. The POST is issued asynchronously, so a callback method is required to process the results. The SaveChangesOption.Batch parameter indicates that all changes should be saved within a transaction in batch mode. If any save operations fail, they will all fail and the transaction will be rolled back. This technique works whether you are saving a single record from one entity or multiple records from multiple associated entities.

Retrieving Data in Advance
Earlier I discussed how to perform deferred loading using the BeginLoadProperty method of DataServiceContext to grab records for an existing entity and attach them to DataServiceContext. This technique is great for getting additional data on demand, especially when the data is not always needed. Deferred loading saves the cost of retrieving data that the user may not want to see, unless the user asks for the data (which happens when the user selects the Product in the productDataGrid control).
Another technique for retrieving hierarchical data is to ask for it all in advance. For example, when retrieving Product records it might be beneficial to also get each Product's Category and Supplier. Otherwise, the Category and Supplier properties of a Product instance will be null. The BeginLoadProperty technique could be used, but that would require making many network requests. A better technique to get all of the data at once is to use the Expand method in the LINQ query, since it would require only a single HTTP request. The following query shows the Expand method asking for all categories and suppliers for the selected products in the LINQ query.
DataServiceQuery<Product> dq = (
    from p in _ctx.ProductSet.Expand("Categories").Expand("Suppliers")
    select p)
    as DataServiceQuery<Product>;
The Expand method comes at a cost as it retrieves additional data. This should be used only when it's necessary to grab all data up front. The Expand method shown in the preceding code grabs child records for each Product entity. In other words, the Category and Supplier are both direct children of a Product. Notice that the name of the property, not the name of the entity set, is passed to the Expand method.
If multiple levels of a hierarchy are required, the syntax of the Expand method can be adapted to get those records too. For example, if you want to grab the OrderDetail element for each Product as well as each of those OrderDetail's Orders, the syntax could look like this:
DataServiceQuery<Product> dq = (
    from p in _ctx.ProductSet.Expand("OrderDetails/Orders")
    select p)
    as DataServiceQuery<Product>;
This code indicates that the query should get the entities for the OrderDetails property of each Product as well as each entity for the Orders. (The Product class has an OrderDetails property and the OrderDetail class has an Orders property.) The OrderDetail records are implied since they are required when getting the Orders property for each Product. This query will return over 8MB of XML data to the Silverlight client application. This is a lot of data and could negatively affect performance on slower connections. I recommend using the Expand method only when the data is needed and even in those cases, use it with the most restrictive filter possible to avoid retrieving data you don't need.

To Be Continued
There is quite a bit of functionality exposed by the combination of ADO.NET Data Services and Silverlight that make for a robust data-driven application. In a future installment of Data Points, I hope to revisit the topic and offer more tips. For now, check out my blog: johnpapa.net, the Silverlight.net Web site, and previous installments of Data Points for more on Silverlight data-centric applications.

Send your questions and comments for John to mmdata@microsoft.com.

John Papa (johnpapa.net) is a Senior Consultant with ASPSOFT and a baseball fan who spends summer nights rooting for the Yankees with his family. John, a C# MVP, Silverlight Insider, and INETA speaker, has authored several books, including his latest titled Data-Driven Services with Silverlight 2 (O'Reilly, 2009). He often speaks at conferences such as Mix, DevConnections, and VSLive.


Cutting Edge
Explore Rich Client Scripting With jQuery, Part 2
Dino Esposito
Contents
The jQuery Eventing Model
Binding Event Handlers
Triggering Events Programmatically
Special Event-Related Methods
Event Helpers
Visual Effects
Custom Animations
AJAX Capabilities
Client Caching
Summing Up
Powerful Web applications require powerful client capabilities. Web developers have traditionally relied upon JavaScript to deliver that power. However, raw JavaScript has its limitations, some of which can be addressed via libraries and object orientation.
There are many JavaScript libraries available, but after a while they all look the same. If you can't decide where to begin, I would suggest you start right here—with jQuery. As I discussed last month, jQuery has some handy capabilities, including selectors, filters, wrapped sets, and the key feature—chained functions. (See "Explore Rich Client Scripting With jQuery, Part 1.") This month, I'll look at some others, including the eventing model, visual effects, caching, and AJAX capabilities.

The jQuery Eventing Model
More often than not, browsers have their own representation of events. Internet Explorer has its own eventing model, as do Firefox and Safari. Therefore, achieving cross-browser compatibility for events is no easy task without the help of a good library. Subsequently, nearly any JavaScript library must provide an abstract model for handling events. The jQuery library is no exception.
The jQuery event handling API is organized into two groups of functions. There are some general event methods to add and remove handlers, plus a long list of helper functions. General methods provide the foundation for helpers to work; and helpers make jQuery programming easy and effective.
Figure 1 lists the methods you can use to bind and unbind event handlers to the matching elements of a wrapped set.
Figure 1 General jQuery Methods for Events
Method | Description
bind | Associates the given function to one or more events for each element contained in the wrapped set.
live | Introduced with jQuery 1.3, the function binds the specified event handler to all current and future elements of the wrapped set. This means that if a new DOM element is added that matches the conditions of the wrapped set, the element will be automatically bound to the handler. The die method does the reverse and removes a live event handler from a wrapped set.
one | Works like bind, except that any event handler is automatically removed after it has been run once.
trigger | Triggers the given event for each element in the wrapped set.
triggerHandler | Triggers the given event on one element in the wrapped set and cancels the default browser actions.
unbind | Removes bound events from each element in the wrapped set.
By the way, it is worth noting that in jQuery vernacular a method is code used to process the contents of the wrapped set. A function, on the other hand, is code that performs an operation that is not specifically aimed at processing the contents of a wrapped set.

Binding Event Handlers
The bind method attaches a handler for a given event to all elements in the wrapped set. The complete signature of the bind method is this:
bind(eventName, eventData, eventHandler)
The first argument is a string and indicates the event to handle. The second argument represents any input data coming with the event. Finally, the third argument is the JavaScript function to bind.
Because jQuery offers an abstract eventing model, it is important to look at the list of supported events. The full list is in Figure 2.
Figure 2 Supported Events in jQuery
Event | Fires When
beforeunload | A browser window is unloaded or closed by the user.
blur | An element loses focus because either the user clicked outside of it or tabbed away.
change | The element loses focus and its value has been modified since it gained focus.
click | The user clicks on the element.
dblclick | The user double-clicks on the element.
error | The window object signals that an error has occurred—usually a JavaScript error has been detected.
focus | An element receives focus either via the mouse or tab navigation.
keydown | A key is pressed.
keypress | A key is pressed and released. A keypress is defined as a successive keydown and keyup events.
keyup | A key is released. This event follows keypress.
load | The element and all of its content has finished loading.
mousedown | A mouse button is pressed.
mouseenter | The mouse enters in the area of an element.
mouseleave | The mouse leaves the area of an element.
mousemove | The mouse is moved while it is over an element.
mouseout | The mouse is moved out of an element. Unlike mouseleave, this event also fires when the mouse moves into or out of child elements.
mouseover | The mouse is moved onto an element. Unlike mouseenter, this event also fires when the mouse moves into or out from child elements.
mouseup | The mouse button is released. This event follows click.
resize | An element is resized.
scroll | An element is scrolled.
select | The user selects some text in a text field.
submit | A form is submitted.
unload | A browser window is unloaded.
Because of the browser differences and the level of abstraction provided by the library, the list is less obvious than it may seem at a first glance. For example, change and select events address very distinct scenarios. The change event refers to a change in the value of an input element, including textboxes and dropdown lists. The select event simply refers to text selection in an input or textarea element.
Subtle differences also exist between the pairs of events mouseover/mouseenter and mouseout/mouseleave. They have nearly the same description and differ only because mouseover and mouseout are also fired when the user moves in and out of child elements. For elements with no children, these events are equivalent.
It is possible for you to register the same JavaScript handler for multiple events. You can do that by separating event names with a blank space. The following example toggles a CSS style when the mouse enters or leaves a DIV tag with a given style:
$("div.sensitiveArea").bind("mouseenter mouseleave",
   function(e) {
        $(this).toggleClass("hovered");
    }
);
The second argument of the bind method is optional and, if specified, indicates any user-defined data to be passed to the handler. Figure 3 illustrates how you can toggle the CSS style of a textbox using a rather generic JavaScript handler.
Figure 3 Toggling Textbox Style
<script type="text/javascript">
  $(document).ready(
     function() {
       $("#TextBox1").bind("focus",
                           {cssStyle: "focusedTextBox"},
                           setCSS);
       $("#TextBox1").bind("blur",
                           {cssStyle: "focusedTextBox"},
                           setCSS);
     }
  );

  function setCSS(e)
  {
     var name = "#" + e.target.name;
     $(name).toggleClass(e.data.cssStyle);
  }
</script>
Note that the preceding code is purely illustrative of the bind function and may not work correctly as a way to toggle styles. It is preferable to use the :focus pseudo-class to add a special style to an element while the element has focus. Most recent browsers will support it. JavaScript handler is a function that declares and receives an event data structure. This object has the members listed in Figure 4.
Figure 4 Members of the jQuery Event Object
Member | Description
type | Returns the name of the event, such as "click"
target | Returns a reference to the DOM element that issued the event
pageX | Returns the X mouse coordinate relative to the document
pageY | Returns the Y mouse coordinate relative to the document
preventDefault | Cancels the default action the browser would take after the event
stopPropagation | Stops the bubbling but doesn't prevent the browser's action
It is worth noting that the target property returns a DOM reference object, not a jQuery wrapped set. To figure out the ID of the element, you must invoke its id or name property. The handler retrieves any custom data you pass through its data expando property.
Two methods complete the definition of the event data object. The preventDefault method stops the browser from taking the default action it would normally take after the event. For example, if you call preventDefault in a submit handler, no form submission would occur. The preventDefault method doesn't stop the bubbling of the event through the object's stack, however.
In contrast, the stopPropagation method stops the event bubbling but doesn't prevent the action. If you want to stop event propagation and prevent the default action, do not call either of these methods; just return false from the event handler.
Any handlers attached through the bind method can be detached using the unbind method. The method takes two optional parameters—the name of the event and the handler. If none are specified, all handlers are removed from all elements in the wrapped set.

Triggering Events Programmatically
The method trigger (see Figure 1) instructs jQuery to invoke any handlers registered with the specified event. To simulate the user clicking on a given button, use this:
$("#Button1").trigger("click");
The code won't do anything if no JavaScript handler is registered with the click event of element.
The method triggerHandler differs from trigger in two ways. First, the method triggerHandler also prevents the browser's default action. Second, the method affects only one element one element, not the whole the wrapped set. If the wrapped set contains multiple matching elements, only the first will have the handler fired for the specified event.
If you use the triggerHandler method to programmatically trigger the focus event on an input field, as you will see next, any registered handler executes but the default action of moving the input focus to the field does not happen.
$("#TextBox1").triggerHandler("focus");
Figure 5 shows what that looks like.
Figure 5 Triggering the Focus Event Programmatically

Special Event-Related Methods
The jQuery library supplies three commonly used event methods: ready, hover, toggle. The ready method takes a function and runs it when the DOM is ready to be traversed and manipulated by code:
$(document).ready(
  function() {
...
  }
);
Libraries need this ability, which replaces the onload event of the browser's window object. The onload event happens too late—when all images have also been loaded. The ready event, on the other hand, fires when the page and the library have been fully initialized.
In the hover function, you place the code you want to execute when the user enters and leaves a set of page elements. The hover function accepts two handlers. The first runs when the mouse hovers over an element in the wrapped set, and the second runs when the mouse leaves the element's area.
Finally, the toggle function performs an even smarter task. It takes two or more handlers and runs them alternately as the user clicks. In other words, the first click on a matching element runs the first handler, the second click runs the second handler, and so on. When the bottom of the handler list is reached, all subsequent clicks run back from the first function in the list.

Event Helpers
To reinforce the idea of its extreme usability, the jQuery library comes with a list of helper methods to simplify the binding of handlers to common events. Helpers come in two forms: with and without a function parameter.
Helpers that accept a parameter receive a JavaScript function to execute when the event is fired. If no parameter is specified, the method just triggers the given event on any element in the wrapped set. Figure 6 shows the list of supported helpers and distinguishes between binder methods and trigger methods.
Figure 6 Binder and Trigger Event Helpers
Trigger Method (Triggers said event on the wrapped set.) | Binder Method (Binds the specified function to the associated event of matching elements.)
blur | blur(fn)
change | change(fn)
click | click(fn)
dblclick | dblclick(fn)
error | error(fn)
focus | focus(fn)
keydown | keydown(fn)
keypress | keypress(fn)
keyup | keyup(fn)
 | load(fn)
 | mousedown(fn)
 | mousemove(fn)
 | mouseout(fn)
 | mouseover(fn)
 | mouseup(fn)
 | resize(fn)
 | scroll(fn)
select | select(fn)
submit | submit(fn)
 | unload(fn)
The following code registers a click event for a given button. The binding between the event and handler occurs as soon as the document is fully loaded and ready to be manipulated programmatically.
$(document).ready( function() {
   $("#btnProcess").click(
       function(e) {
this.text("Please wait ... ");
       }
   );
});
Some events such as the scroll, resize, and mouse events make sense only if triggered by an explicit user action. Such events lack a trigger method, as shown in Figure 6.

Visual Effects
One of the factors most responsible for the popularity of the jQuery library is the built-in engine for visual effects. In the library, you find an effective engine for building custom animations plus a few facilities for quickly implementing common effects such as fading and sliding.
Predefined effects can be divided into three groups according to the CSS attributes they act on: visibility, sliding, and fading. Figure 7 lists all effects natively available.
Figure 7 Visual Effects
Visibility effect | Description
show | Turns on the visibility of any elements in the wrapped set
hide | Turns off the visibility of any elements in the wrapped set
toggle | Toggles the visibility of any elements in the wrapped set
Sliding effect | Description
slideDown | Displays any matching elements by increasing their height progressively
slideUp | Hides any matching elements by decreasing their height progressively
slideToggle | Shows or hides all matching elements inverting the current sliding setting
Fading effect | Description
fadeIn | Fades any matching elements in by reducing their opacity progressively
fadeOut | Fades any matching elements out by increasing their opacity progressively
fadeTo | Fades the opacity of all matching elements to a specified opacity
All methods in Figure 7 apply to any matching element in a wrapped set. Visibility methods act on the display CSS attribute and show or hide elements using a nice built-in animation. For example, the following code unveils an HTML panel as the user clicks the button:
$("btnShowOrders").click(
   function(e) {
      $("#panelOrders").show(2000);
   }
);
The animation takes two seconds to complete. Optional arguments you can specify to visibility methods include the speed of the animation and a callback to invoke upon completion. The type of animation is hardcoded and progressively uncovers the content from the top-left corner.
Sliding methods work on the CSS height attribute of matching elements. The slideDown method increases the height of an element in a loop so that the display happens by revealing the element progressively. The slideUp method does the reverse and hides the element by sliding it up, from the actual height to zero.
Fading methods follow a model analogous to sliding methods. They support optional speed and completion callback and show/hide elements looping on the CSS opacity attribute (see Figure 8).
Figure 8 Fading
$("#btnShowOrders").click(
   function(e)
   {
      // Hide the current panel.
      $("#panelOrders").fadeOut(1000);

      populateOrderPanel();

      // Show new content and when done
      //apply some CSS styles
      // to denote the new content.
      $("#panelOrders").fadeIn(2000,
         function() {
            $("#panelOrders").css(...);
         }
      );
   }
);
The preceding example shows how to fade out an existing HTML panel, refresh it while hidden, and then display it again using fade-in animation. Note that you can indicate the desired speed using an explicit duration in milliseconds or resort to a string representing one of three predefined speeds: slow, normal, or fast.

Custom Animations
All visual effects listed in Figure 6 are implemented on top of the jQuery animation engine. The heart of this engine is the animate function:
function animate( prop, speed, easing, callback )
{
  …
}
The first argument to the function is an array of property/value pairs where the property refers to a CSS attribute. The function simply animates the CSS property of each matching element from its current value to the specified value.
Additional, optional arguments you can specify include the speed of the animation and the completion callback. The easing argument indicates the name of the easing effect that you want to use during transitions. There are two built-in values: linear and swing. Other easing options can be added using a plug-in.
Here's a sample call for the animate method:
$("#Element1").animate(
   { width: "70%",
     opacity: 0.4,
     borderWidth: "10px"
   },
   3000);
At the end of the animation, the matching element will have the specified width, opacity, and border width. The animation will complete in three seconds and vary CSS attributes from their current values up or down to the target value.
Note that CSS properties must be specified using camelCase, namely the first character is lower case and the first character of each following word is upper case. As an example, to animate the border of an element you should use "borderWidth" instead of the CSS original property name of border-width.
The animate method also supports relative animations, such as increasing (or decreasing) a property value by a percentage or by a fixed value. For example, the following code snippet shows how to increase the width of an element by 20 percent and darken its content by a value of 0.4. I've also specified that all changes should be applied in two seconds.
$("#Panel1").animate(
   { width: "+=20%",
     opacity: "-=0.4"
   },
   2000);
Finally, note that all animations in jQuery are automatically queued and execute in order, one after the next. Queued animations are the necessary precondition to be able to chain multiple calls on elements in a wrapped set. Queued animations, however, are just the default behavior. As a developer, you are given the tools to make some animations run in parallel.
To gain some parallelism, you create an animation queue using an overload of the animate method:
function animate( prop, options )
{
   …
}
As in the previous signature, the first argument indicates the set of style attributes that you wish to animate and the values you want to reach.
The second argument indicates a set of options with which to configure the animation. Options include duration, easing, completion callback, and a Boolean value to indicate whether it is a queued animation—true is the default.
By setting the queue attribute to false in the options of the animate call, you run the animation immediately without queuing. Let's consider the following code snippet:
$("#div1").animate({ width: "90%" }, {queue:false, duration:5000 });
$("#div1").animate({ fontSize: '10em' }, 1000);
$("#div1").animate({ borderWidth: 5 }, 1000);
The first animation is not queued and runs immediately. The second is not queued but it is considered the first in the queue so it runs as well. The net effect is that the first two animations start together. The third animation is queued and begins as soon as the second animation terminates—one second later. Because the first animation takes five seconds, the border animation also runs in parallel with the animation that changes the width of the element.

AJAX Capabilities
What would a modern JavaScript library be without a solid infrastructure for AJAX asynchronous calls? In jQuery, the AJAX support is based on the ajax function, through which you can control all aspects of a Web request. Here's a common way of invoking the ajax function:
$.ajax(
 {
   type: "POST",
   url: "getOrder.aspx",
   data: "id=1234&year=2007",
   success: function(response) {
     alert( response );
   }
 }
);
The function accepts a list of parameters grouped in a single object. Feasible options are type, url, data, dataType, cache, async, username, password, timeout, and ifModified.
In particular, the dataType parameter indicates the type of the expected response, whereas the cache parameter (if set to false) forces requested resources not to be cached by the browser. Other parameters such as type, password, username, and url are self-explanatory.
The options for the ajax function also include a number of optional callbacks to be invoked before any of the most relevant steps in the lifecycle of the underlying XMLHttpRequest object. The success callback indicates the completion callback. The callback function receives the response as its sole argument. Other callbacks are error, beforeSend, and complete. The complete callback runs at the end of the request when either the success or error callbacks have been called.
Interestingly, the ajax function lists a callback to preprocess the Web response before it is returned to the calling code. This callback is dataFilter and handles the raw response downloaded by XMLHttpRequest. The purpose of the callback is to filter the response so that only sanitized data compliant with the expected data type is returned to the caller. The callback function receives two arguments: the raw data returned from the server and the value assigned to the dataType parameter.
When using the jQuery library, you hardly use the ajax function directly. You would more often end up using some of the AJAX helpers such as getScript, load, or getJSON.
The following code shows how to load a script file on demand. The script is automatically executed upon loading:
$.getScript("sample.js");
Another quite useful piece of code is the load function. The load function downloads HTML markup and automatically injects it in the current DOM. The following code shows how to populate a menu programmatically:
$("#menu").load("menu.aspx");
The content of the URL is attached to the DOM subtree rooted in any elements that match the selector. The load method defaults to a GET request, but you can change it to POST by simply adding a data argument, as you see here:
$("#links").load(
   "menu.aspx",
   { topElement: "Books" },
   function()
   {
       // completion callback code
   }
);
As shown above, a callback can also be specified to execute upon completion of the download.
It is also possible to specify a jQuery selector in the URL so that the incoming markup is pre-filtered to select only matching elements. The syntax simply entails that you add a selector expression to the URL. Here's an example that extracts all <li> elements from a <ul> element named menuItems:
$("#links").load("/menu.aspx ul#menuItems li");
Finally, you have get, post, and getJSON functions to perform direct GET and POSTs and to get JSON content from a URL.

Client Caching
A client-side cache is essential in nontrivial JavaScript code. In this context, a cache is an array where developers can store data that relates to a given DOM element. In the following code, a URL is invoked to determine whether the content of a textbox is valid, and then the response is cached in an array element named IsValid.
var url = "...";
var contentIsValid = $.get(url);
$("#TextBox1").data("IsValid", contentIsValid);
Each DOM element may have its own local cache. In jQuery, you use the data method on the elements in a wrapped set.
To read back the content of the store, you use the same data function with just one argument—the name of the element:
alert($("#grid").data("Markup"));
Elements added to the cache can be removed by using the removeData function.
It would be nice to know why it's better to use the data function than expando properties. An expando property adds custom information to a DOM element using a nonstandard HTML attribute. It is definitely a type of client-side caching, but some browsers might not like custom attributes. In this case, you typically resort to using standard attributes such as alt or rel in a nonstandard way. A client-side caching framework such as the data function stores data in plain old JavaScript objects and maintains a link to the target DOM element using a dictionary. Done this way, no conflict with browsers is possible.

Summing Up
JavaScript remained nearly unchanged for about ten years. While a significant overhaul of the language is in order, it's anybody's guess when it will be fully defined and, more importantly, whether browsers will support it. Last year, a consensus was reached around a version of the language that sits in between the current language and the proposed new ECMAScript 4 language which was significantly different from today's JavaScript. The new project that should generate JavaScript 2.0 is called Harmony.
Whatever way you look at it, cross-browser libraries seem to be the only reliable way to plan efficient and effective client-side development, at least for the next few years. In this context, jQuery is an excellent library that will be integrated into upcoming Microsoft Web development tools. Take a close look at it; you'll be glad you did! Happy jQuery coding!

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.


Patterns in Practice
Persistence Patterns
Jeremy Miller
Contents
Mapping Objects to Databases
Active Record
Data Mapper
Using a Repository
Identity Map
Lazy And Eager Loading
Virtual Proxy Pattern
Taking the Next Step
Data access is a popular subject among developers. No doubt you've heard plenty of opinions on specific data access technologies and persistence frameworks, but what's the best way to consume these tools in your project? What criteria should you use to select the right tool for your project? What do you need to know conceptually about these tools before you use? What if you've got too much time on your hands and want to write your own persistence tool—what do you need to know?
Unsurprisingly, the answer to all of these questions is to examine the underlying design patterns of persistence.
Domain Models
When you think about how you are going to structure and represent the business logic in your system, you have a couple major choices. In this article, I'm largely assuming that you have chosen the domain model approach to organizing business logic into entity objects.
From the formal description, a domain model is an object model of the domain that incorporates both behavior and data.
For example, my current project involves Customer Relationship Management. (CRM) We have entity objects for Case and User and Solution that contain both data and implement business rules involving that data. A domain model can range from an anemic model that is simply a set of data structures to a very rich model that jealously guards the raw data behind a narrow interface (hardcore Domain-Driven Development). Where your domain model falls in this range is largely a matter of how complicated the business logic in your system really is and how prevalent reporting or data entry are in your system requirements.
An adequate discussion of the Domain Model pattern is beyond the scope of this article. I would strongly recommend reading Chapter 2 of Martin Fowler's Patterns of Enterprise Application Architecture book for a great discussion of the major design patterns for organizing business logic.
Before getting started, let's review the two main ways to perceive the role of the database and data access code in your system:
  • The database is the keystone of the application and a business asset. The data access code and even the application or service code are simply mechanisms to connect the database with the outside world.
  • The business objects in the middle tier and the user interface or service layer are the application, and the database is a means to reliably persist the state of the business objects between sessions.
Personally, I feel like the first, datacentric viewpoint is well understood in the .NET community, so I'd like to focus on the second viewpoint. In the second viewpoint, you're typically working with entity objects in the middle tier. One way or another, you're probably doing Object/Relational Mapping (O/RM) to map data from the business entities to the database tables and vice versa. You might be doing it by hand, but more likely with tools of some sort. Those tools are great and can potentially save a lot of development time, but there are some issues you should be aware of, and it's always nice to understand how a tool works beneath the covers. Hopefully, studying the patterns in this article will help on both accounts.
I'm a big proponent of Agile practices like Test Driven Development, Behavior Driven Development, Lean Programming, and Continuous Design. I say this just to be clear that I have a very specific bias in regards to the patterns I'll be discussing in this article, and it will probably show.

Mapping Objects to Databases
I've decided to model my system in the middle tier with entity objects that have identity, data, and related behavior. My business logic will be implemented either in these entity objects or in domain services that use these entity objects. Great, but how do you seamlessly move data back and forth between the database and the entity objects?
In the case of a relational database, you need to move the fields and properties of our objects to tables and fields in the database. You can write this code completely by hand, writing out separate INSERT, UPDATE, SELECT, and DELETE SQL statements, but you'll quickly realize that you're repeating yourself in the code quite a bit. Namely, you're repeatedly specifying that the data in an object property or field should be stored into a particular column in a database table.
This is where an Object/Relational Mapper (O/RM) steps in. When you use an O/RM, you simply create a mapping of the object properties to the database table and let the O/RM tool use that metadata to figure out what the SQL statements should be and how to move data from the object to the SQL statements.
Let's get concrete and look at a very basic sample. My current project has an Address class that looks like this:
public class Address
{
  public long Id { get; set; }
  public string Address1 { get; set; }
  public string Address2 { get; set; }
  public string City { get; set; }
  public string StateOrProvince { get; set; }
  public string Country { get; set; }
  public string PostalCode { get; set; }
  public string TimeZone { get; set; }
}
When I set up the mapping for the Address class, I need to specify which table the Address class maps to, how the Address objects will be identified (the primary key), and which properties map to which database tables.
For this example, I'm using the Fluent NHibernate tool for mapping Address.
I'm purposely doing the mapping in a longhand manner to show all the details. (In real usage, I employ convention over configuration to eliminate much of the repetitiveness.) Here's the code:
public class AddressMap : ClassMap<Address>
{
  public AddressMap()
  {
    WithTable("Address");
    UseIdentityForKey(x => x.Id, "id");

    Map(x => x.Address1).TheColumnNameIs("address1");
    Map(x => x.Address2).TheColumnNameIs("address2");
    Map(x => x.City).TheColumnNameIs("city");
    Map(x => x.StateOrProvince).TheColumnNameIs("province_code");
    Map(x => x.Country).TheColumnNameIs("country_name");
    Map(x => x.PostalCode).TheColumnNameIs("postal_code");
  }
}
Now that you've made a mapping of the object model to the database model, something has to actually execute the mapping, and you roughly have two choices: Active Record or Data Mapper.

Active Record
When choosing a persistence strategy, the first decision you need to make is where to place the responsibility for carrying out the mapping. You have two very different options: you can either make each entity class itself responsible for the mapping, or you can use a completely separate class to do the mapping to the database.
The first option is known as the Active Record pattern: an object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data. An Active Record approach puts persistence methods directly onto the entity object. In this case, the Address class would probably have methods like Save, Update, and Delete, as well as a static Load method that queries the database for an Address object.
The typical usage of the Active Record pattern is to essentially make a strongly typed class wrapper around a single row in a database table. As such, the Active Record classes are generally an exact mirror of the database structure (this will vary between tools). Many Active Record implementations will generate the entity objects directly from the database structure.
The most famous Active Record implementation is the ActiveRecord tool that comes as part of the Ruby on Rails Web development framework (which is usable in .NET programming with IronRuby; see "Getting Started With IronRuby And RSpec, Part 1"). If I were using ActiveRecord, I would first create a table named addresses in the database. Then, if all I care about is having access to the address data and methods for finding, saving, and inserting address data, the entire Address class would look exactly like this Ruby class:
class Address < ActiveRecord::Base
end
The Ruby implementation is using metaprogramming to dynamically create fields and query methods that match the database table named addresses (pluralized form of the class name Address) at runtime.
With a few exceptions, .NET implementations of the Active Record pattern generally work by using code generation to create .NET classes that map directly to database tables. The benefit of this approach is that it is very easy to keep the database and object model synchronized.
Lean Programming
Lean Programming teaches you to eliminate wasted effort in development projects by favoring "pull" design over "push" design. This means infrastructure concerns like persistence should only be designed and built to satisfy the needs of business requirements (pulled on demand) instead of building the data access layer code that you think the application will need later (pushed).
In my experience, this means you should develop the system incrementally by developing vertically—by building one feature at a time instead of building the system one horizontal layer at a time. By working this way you can be sure that infrastructure development is no more than what you absolutely need by tying all infrastructure code to a feature being built into the system. When you work horizontally by building the data access layer or the database before you write the user interface, service, or business logic layer, you risk the following:
  • Not getting adequate feedback early from project stakeholders because there is no working functionality to demonstrate
  • Writing unnecessary infrastructure code for features that might not actually get built
  • Building the wrong data access code because you don't understand the business requirement early on, or the requirements change before the other layers are created
Pull design also means that your choice of data access strategy should be determined by the needs of the application. Given a choice, I would choose an O/RM for a system where I was modeling the business logic in a domain model. For a reporting application, I would bypass persistence tools altogether in favor of just using SQL and datasets. For a system that is mostly data entry, I might choose an Active Record tool. The point is that the data access and persistence is shaped by the needs of its consumers.

Data Mapper
Nice as the Active Record pattern may be, it is often valuable to have an object structure that varies from the database model. You may want to map multiple classes to the same database table. You might have a legacy database schema that doesn't fit the shape of the objects that you would want to express in some business logic (a common occurrence for me on my last several projects).
This is where I would choose the Data Mapper pattern: a layer of mapper objects that move data between objects and a database while keeping them independent of each other and the mapper classes themselves. The Data Mapper pattern strips most of the responsibility of persistence from the entity objects in favor of classes external to the entities. With a Data Mapper pattern, you access, query, and save entity objects with some kind of repository (discussed later in this article).
How do you choose between the two? My personal bias is very strongly towards the Data Mapper solution. That aside, Active Record is best for systems with simpler domain logic, CRUD-intensive applications (create, read, update and delete, that is), and situations where the domain model doesn't need to diverge much from the database structure. Active Record may be more comfortable for many .NET development teams because it implies a datacentric way of working that is more common for .NET teams and, frankly, much better supported by .NET itself. I would characterize most persistence tools in the .NET space as Active Record tools.
On the other hand, Data Mapper is more appropriate for systems with complex domain logic where the shape of the domain model will diverge considerably from the database model. Data Mapper also decouples your domain model classes from the persistence store. That might be important for cases where you need to reuse the domain model with different database engines, schemas, or even different storage mechanisms altogether.
Most important to me as an Agile practitioner, the Data Mapper approach allows me to design the object model independently of the database with Test Driven Development more efficiently than an Active Record solution could. This is important to teams that want to take an incremental approach to design because it allows a team to work through the design in the object model first where refactoring tools and unit testing techniques are generally more effective, then create the database model later when the object model is stable. The Data Mapper pattern is also more applicable to the Domain Driven Design architectural approach that is gaining in popularity in the .NET community.

Using a Repository
When I was growing up as a developer in the Windows DNA days, I lived in mortal fear of forgetting to close an ADO Connection object in my code. On my first big enterprise project, I coded directly against ADO. Every time I needed to request or save data to the database, I had to do the following:
  1. Find the connection string from some sort of configuration
  2. Open a new connection to the database
  3. Create a command object or a recordset object
  4. Execute the SQL statement or stored procedure
  5. Close the connection to release the database resources
  6. And oh yeah, put some adequate error handling around the data access code
The first problem was the absurd amount of repetitive code I was writing. The second problem was that I had to write the code correctly every single time, because forgetting to close a single connection could, and unfortunately did, drive a mission-critical system offline under a heavy load. Nobody wanted to be the guy whose code collapsed out of poor database connection hygiene, but it still happened too frequently.
In my next project, my coworker and I got smarter. We implemented a single class that would do all the setup, teardown, and error handling code of the ADO Connection object. Any other class in the system could interact with the database by using this central class to invoke stored procedures. We wrote much less code and, better yet, we weren't plagued by problems arising from forgetting to close database connections because we had to get that connection management code right only one time.
What my team did was to create a crude implementation of the Repository pattern that mediates between the domain and data mapping layers using a collection-like interface for accessing domain objects.
Basically, the Repository pattern just means putting a façade over your persistence system so that you can shield the rest of your application code from having to know how persistence works. My current project is using a Repository with a public interface that looks like the one in Figure 1.
Figure 1 Repository interface
public interface IRepository
{
  // Find an entity by its primary key
  // We assume and enforce that every Entity
  // is identified by an "Id" property of
  // type long
  T Find<T>(long id) where T : Entity;

  // Query for a specific type of Entity
  // with Linq expressions.  More on this later
  IQueryable<T> Query<T>();
  IQueryable<T> Query<T>(Expression<Func<T, bool>> where);

  // Basic operations on an Entity
  void Delete(object target);
  void Save(object target);
  void Insert(object target);

  T[] GetAll<T>();
}
When some class in the system needs to access an entity object, it can simply use IRepository to fetch that entity by its ID, or query for a list of entity objects with a LINQ expression.
When I use the concrete class of IRepository, which uses the NHibernate library for O/RM, I'm pulling a connection string from memory, loading the mapping definitions from an assembly, building the NHibernate SessionFactory (once and only once because it's a big performance hit), and wrapping the low-level ISession interface from NHibernate. With some help from the Repository class, NHibernate manages database connection lifecycle issues.
Whew. That's a lot of stuff going on behind the scenes. It's a good thing that I've swept all of the direct interaction with NHibernate behind the IRepository interface. I don't have to know all that bootstrapping NHibernate stuff just to load, save, and query objects. Even better, since every class depends on the abstract IRepository interface for data access and persistence, I can slide in an InMemoryRepository implementation of IRepository that uses LINQ to Objects internally to stub the database during testing.

Identity Map
Let's look at a common scenario. Inside a single logical transaction in some sort of shipping system, you have two completely different classes that work independently, but both classes will need to retrieve the same Customer entity during the transaction. Ideally, you want only a single Customer object inside a single transaction for each logical Customer so that each object is working off of consistent data.
In persistence tooling, preventing duplicate logical references is the job of the Identity Map pattern. As stated by Martin Fowler, an Identity Map ensures that each object gets loaded only once by keeping every loaded object in a map and looks up objects using the map when referring to them.
For the Customer class, you might build a naïve implementation of Identity Map like the one in Figure 2. I'm purposely leaving out thread locking here just to simplify the code. A real implementation would require adequate thread safety measures.
Figure 2 Identity Map Customer class
public class CustomerRepository
{
  public IDictionary<long, Customer> _customers =
    new Dictionary<long, Customer>();

  public Customer FindCustomer(long id)
  {
    if (_customers.ContainsKey(id))
  {
      return _customers[id];
    }

    var customer = findFromDatabase(id);
    _customers.Add(id, customer);

    return customer;
  }

  private Customer findFromDatabase(long id)
  {
    throw new System.NotImplementedException();
  }
}
In this example, a Customer object is identified by its ID. When you request an instance of Customer by ID, the CustomerRepository first checks an internal dictionary to see whether it has that particular Customer. If so, it returns the existing Customer object. Otherwise, CustomerRepository will fetch the data from the database, build a new Customer, store that Customer object in its dictionary for later requests, and return the new Customer object.
Fortunately, you generally won't write this code by hand because any mature persistence tool should include this feature. You do need to be aware that this is happening behind the scenes and scope your persistence support objects accordingly. Many teams will use the lifecycle management feature of an Inversion of Control tool (StructureMap, Windsor, Ninject, and others) to ensure that all classes in a single HTTP request or thread are using the same underlying Identity Map. The Unit of Work pattern is another way to manage a single Identity Map across multiple classes in the same logical transaction.
Just to illustrate this pattern farther, Figure 3 shows an example of how an Identity Map works. The code is written against the architecture of my current project. The instances of the IRepository interface shown in the code below wrap a single NHibernate ISession, which in turn implements the Identity Map pattern. When I run this test the output is this:
1 passed, 0 failed, 0 skipped, took 5.86 seconds.
Figure 3 Using an Identity Map
[Test]
public void try_out_the_identity_map()
{
  // All I'm doing here is getting a fully formed "Repository"
  // from an IoC container and letting an IoC tool bootstrap
  // NHibernate offstage.
  IRepository repository = ObjectFactory.GetInstance<IRepository>();

  // Find the Address object where Id == 1
  var address1 = repository.Find<Address>(1);

  // Find the Address object where Id == 1 from the same Repository
  var address2 = repository.Find<Address>(1);

  // Requesting the same identified Address object (Id == 1) inside the
  // same Repository / Identity Map should return the exact same
  // object
  address1.ShouldBeTheSameAs(address2);

  // Now, let's create a completely new Repository that has a
  // totally different Identity Map
  IRepository secondRepository = ObjectFactory.GetInstance<IRepository>();

  // Nothing up my sleeve...
  repository.ShouldNotBeTheSameAs(secondRepository);

  var addressFromSecondRepository = secondRepository.Find<Address>(1);

  // and this is a completely different Address object, even though
  // it's loaded from the same database with the same Id
  addressFromSecondRepository.ShouldNotBeTheSameAs(address1);
}

Lazy And Eager Loading
One of the best things about using a persistence tool is the ability to load a root object (Invoice, perhaps), then navigate directly to its children (InvoiceLineItem) and related objects just by using properties of the parent class. However, sooner or later you're going to have to care about the performance of your application. Fetching an entire object graph when you may need only the top-level object most of the time or can forgo parts of the object graph isn't efficient.
That's OK. In that case, you can use the Lazy Loading pattern in which you defer initializing the object until just before it's needed.
Let's put this in more concrete terms. Say that you have a class named Customer that references an Address object:
public class Customer : DomainEntity
{
  // The "virtual" modifier is important.  Without it,
  // Lazy Loading can't work
  public virtual Address HomeAddress { get; set; }
}
In most use cases involving the Customer object, the code never needs the Customer.HomeAddress property. In that case, you could set up the database mapping to make the Customer.HomeAddress property lazy loaded like in this Fluent NHibernate mapping:
public class CustomerMap : DomainMap<Customer>
{
  public CustomerMap()
  {
    // "References" sets up a Many to One
    // relationship from Customer to Address
    References(x => x.HomeAddress)
      .LazyLoad() // This marks the property as "Lazy Loaded"
      .Cascade.All();
  }
}
With Lazy Loading turned on, the Customer object is fetched without the Address data. However, as soon as any caller tries to access the Customer.HomeAddress property for the first time, that data will be transparently loaded.
Do note the virtual modifier on the Customer.HomeAddress property. Not every persistence tool does this, but NHibernate implements lazy loaded properties by creating a dynamic subclass of Customer that overrides the HomeAddress property to make it lazy loaded. The HomeAddress property needs to be marked as virtual in order to allow a subclass to override the property.
Of course, there are other times when you request an object and you know that you will most likely need its children at the same time. In this case, you will probably opt for Eager Loading and have the children data loaded at the same time as the parent. Many persistence tools will have some sort of ability to optimize Eager Loading scenarios to fetch a hierarchy of data in a single database round-trip. If you need the Customer.HomeAddress data most of the time you use a Customer object, then you would be better off doing Eager Loading to get the Customer and Address data at the same time.
At this point, I should repeat the old maxim that the only way to reliably tune an application for performance is to use an empirical measurement of performance with a profiler.

Virtual Proxy Pattern
Lazy Loading is often implemented by using a virtual proxy object that looks just like the real object to be loaded later. Let's say that the domain model includes a class named CustomerRepresentative that references a list of Customer objects. Part of that class is shown in Figure 4.
Figure 4 CustomerRepresentative
public class CustomerRepresentative
{
  // I can create a CustomerRepresentative directly
  // and use it with a normal List
  public CustomerRepresentative()
  {
    Customers = new List<Customer>();
  }

  // Or I can pass an IList into it.
  public CustomerRepresentative(IList<Customer> customers)
  {
    Customers = customers;
  }

  // It's not best practice to expose a collection
  // like I'm doing here, but it makes the sample
  // code simpler ;-)
  public IList<Customer> Customers { get; set; }
}
There are many times when the system uses an instance of CustomerRepresentative without needing the list of Customers. In that case, you could simply construct a CustomerRepresentative with a virtual proxy object that looks like an IList<Customer> object and use that virtual proxy class without making any changes to CustomerRepresentative whatsoever. That virtual proxy class might look something like Figure 5. A CustomerRepresentative object could then be created with Lazy Loading as shown in Figure 6.
Figure 5 Virtual proxy for CustomerRepresentative
public class VirtualProxyList<T> : IList<T>
{
  private readonly Func<IList<T>> _fetcher;
  private IList<T> _innerList;
  private readonly object _locker = new object();

  // One way or another, VirtualProxyList needs to
  // find the real list.  Let's just cheat and say
  // that something else will pass it a closure
  // that can find the real List
  public VirtualProxyList(Func<IList<T>> fetcher)
  {
    _fetcher = fetcher;
  }

  // The first call to
  private IList<T> inner
  {
    get
    {
      if (_innerList == null)
      {
        lock (_locker)
        {
          if (_innerList == null)
          {
            _innerList = _fetcher();
          }
        }
      }

      return _innerList;
    }
  }

  IEnumerator IEnumerable.GetEnumerator()
  {
    return inner.GetEnumerator();
  }

  public IEnumerator<T> GetEnumerator()
  {
    return inner.GetEnumerator();
  }

  public void Add(T item)
  {
    inner.Add(item);
  }

  // and the rest of the IList<T> implementation

}
Figure 6 Lazy Loading CustomerRepresentative
public class CustomerRepresentativeRepository
{
  private readonly ICustomerRepository _customers;

  public CustomerRepresentativeRepository(
      ICustomerRepository customers)
  {
    _customers = customers;
  }

  // This method will "find" a CustomerRepresentative, and
  // set up the Virtual Proxy for the Customers
  public CustomerRepresentative Find(long id)
  {
    var representative = findRepresentative(id);
    representative.Customers =
      new VirtualProxyList<Customer>(() =>
      _customers.GetCustomersForRepresentative(id));

    return representative;
  }
}
Like most of the patterns in this article, the virtual proxy isn't something that you're likely to write by hand, but be aware that it's there in the background of your persistence tool.

Taking the Next Step
When I began programming with Windows DNA technologies, I probably spent over half of my time working with raw ADO code. Today, persistence coding and infrastructure is a very small percentage of my team's time. So what changed over the years? We use persistence tools and these design patterns to eliminate so much of the repetitive coding we used to do.
Most of these patterns were taken from Martin Fowler's book, Patterns of Enterprise Application Architecture. I highly recommend reading this book if you have anything to do with writing enterprise applications. Due to length limitations, I was unable to cover some other important patterns like Unit of Work, Specifications, and Persistence Ignorance. In addition, there are quite a number of ways to use the Repository pattern and design considerations (a single generic repository versus specific, "narrow" repository classes, whether a repository should even expose "Save" methods, etc.) I would urge you to research these topics as well, and I may write a follow-up article to continue this discussion.
Lastly, I'd like to say that the .NET ecosystem is richer than just Entity Framework and LINQ to SQL. I'm happy with NHibernate as a Data Mapper that knows relatively little about persistence. SubSonic is a popular Active Record implementation for .NET programming. iBatis.Net is fantastic for existing databases or occasions when you want full control over authoring the SQL statements. LLBLGen Pro is a very mature tool with unique querying abilities. Many of the other tools also have the ability to use LINQ queries.

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

Jeremy Miller, a Microsoft MVP for C#, is also the author of the open-source StructureMap (structuremap.sourceforge.net) tool for Dependency Injection with .NET and the forthcoming StoryTeller (storyteller.tigris.org) tool for supercharged FIT testing in .NET. Visit his blog, "The Shade Tree Developer," part of the CodeBetter site.


Service Station
Creating And Consuming Web Feeds
Jon Flanders
Code download available from the MSDN Code Gallery
Browse the Code Online
Contents
Web Feeds
WCF and Feeds
Feed structure
Exposing a Feed
Implementing the Feed
AtomPub
Consuming Feeds
In the January 2009 issue of MSDN Magazine, I discussed the basics of using Representational State Transfer (REST) as the architecture for building client-server applications. I also started looking at how you could build such applications using the Windows Communication Foundation (WCF) features in the Microsoft .NET Framework 3.5.
This month, I'm going to talk about some additional Web feed capabilities of WCF that are enabled only because of the base support. While reading the previous Service Station column will help you understand this one, you can safely read this one without doing any harm to yourself (although some knowledge of WCF REST basics is helpful).

Web Feeds have been around for almost a decade as a way for applications to pull information from the World Wide Web. Traditionally used to expose articles and information from blogs, feeds are now commonly used to expose other types of data as well because of the simplicity of the architecture.
Feeds are simply XML data exposed via an HTTP URI. A feed reader is responsible for polling the URI at some interval and then processing the retrieved data. The reader, when it is an application intended to expose the feed data to a human, will notify the user that new data is available. In the case of an unattended feed reader (which could be any application code), typically some application action will be triggered by the acquisition of new data.
Considering that many feeds are exposing blog data, why this is the topic of a column about building services? The simplicity of feed formats for exposing data, plus the ubiquity of feed readers (and libraries to parse feeds) has led to many other types of data being exposed as feeds. ADO.NET Data Services, for example, is a service-enabled data layer built completely using feed technology (specifically using a standard built on top of Atom called Atom Publishing Protocol (AtomPub), which I'll discuss later in this article). The Microsoft Windows Azure platform exposes much its data functionality in this way, as do services from a number of other companies.
One reason for the success of feeds is that they use a well-known and mostly standardized XML format. Rather than using a custom format per data provider, the industry has embraced two common feed schemas: Really Simple Syndication (RSS) and Atom. RSS is the older of the two formats, and although Atom has emerged as the broadly adopted standard, many feeds still expose both RSS and Atom versions. If you are building a service, specifically a RESTful service, you would be well served to consider building it using a feed, using RSS or Atom if the service is read-only, or using AtomPub if the service is read/write.

WCF and Feeds
On top of its base support for building RESTful endpoints, WCF in the .NET Framework 3.5 also includes support for exposing feeds. You can create a WCF HTTP-based endpoint and expose feeds using either common feed format. WCF in the .NET Framework 3.5 SP1 adds additional support for feeds by enabling you to easily implement an endpoint that supports the AtomPub specification.
In my opinion, one of the nice features of the feed support in WCF is that it abstracts away the need-to-know deep details of the Atom or RSS formats. WCF provides an object model that you use to build a generic object graph (the object model is more like Atom, since Atom has a somewhat richer model than RSS). You can then take the top level of this object graph and pass it to another framework-provided object known as a formatter. The formatter takes care of serializing the object graph data into the correct feed format. This is how you can easily expose both RSS and Atom from the same endpoint—and it also insulates you from future changes in feed formats, since all that will be needed is a new formatter. Your job is to fill in the object graph with data. The infrastructure takes care of converting your data into the correct feed format.

Feed structure
Before I go further, let me talk a little about the structure of feeds and how it relates to the WCF object model. Feeds are a pretty simple way to expose a collection of data (see Figure 1). A feed (generically) includes a title, a description, a published date, a last-updated date/time, as well as a collection of items. Each of these items is also a fairly simple piece of data, with a published date, a title, and content. The content generally contains the important data, whether that is a blog entry, a newspaper article, or some other piece of information. Each item can have hyperlinks that can link to an individual item or to an alternate representation of the item (like a full HTML page of its data rather than just a summary). See Figure 1 for a visual representation of a feed.
Figure 1 Architecture of a Feed
Imagine I wanted to expose information about MSDN Magazine articles through a feed. First, I need to decide what data to expose via this feed. Although there are a few options, I decided to implement this example as a feed of all the issues and articles published in MSDN Magazine. When a feed reader gets an update, it will show each article published as a separate item, with a small summary of the article as the content.
For this example, I'm going to be extending the code from my last column, where I built a generic RESTful service endpoint to serve up the data from MSDN Magazine. Again, you don't necessarily have to go back and read that article to understand this one, but there is a purpose to my choosing this particular scenario as my example, and it actually applies to both RESTful and SOAP-based Web services. Often, a feed is a good implementation detail to add to an existing service. The nice thing about WCF is that it is straightforward to add a feed endpoint to just about any service you've built with WCF regardless of whether the whole service is RESTful.

Exposing a Feed
The first thing I'm going to do is extend my service contract and definition to include an operation that can expose a feed. To do this, I've added a new method named GetIssuesFeed to my IMSDNMagazineService interface (see Figure 2).
Figure 2 Adding a GetIssuesFeed Method
[ServiceContract]
public interface IMSDNMagazineService {
  [OperationContract]
  [WebGet(UriTemplate="/")]
  IssuesCollection GetAllIssues();

  [OperationContract]
  [WebGet(UriTemplate = "/feed?format={format}")]
  [ServiceKnownType(typeof(Atom10FeedFormatter))]
  [ServiceKnownType(typeof(Rss20FeedFormatter))]
  SyndicationFeedFormatter GetIssuesFeed(string format);

  [OperationContract]
  [WebGet(UriTemplate = "/{year}")]
  IssuesData GetIssuesByYear(string year);

  //remainder of interface commented for clarity
  ...
}
There are a couple of things to note about this method. First, the return type is SyndicationFeedFormatter, part of the WCF feed support I referred to earlier generically as the formatter. It will reference the underlying object that I've filled with data, and it will generate the correct XML feed format depending on the type of the feed object.
The other thing to notice is the UriTemplate property of WebGetAttribute. This indicates to WCF what URI each method should respond to or handle. What is of interest in this case is that the GetIssuesFeed method has a URI template that is a literal: "/feed". GetIssuesByYear (which is the generic RESTful method that has nothing to do with feeds) has a variable path segment ("/{year}") in its URI. Since the URI parsing and routing mechanism turns everything into a string, it appears that these two UriTemplates would be in conflict.
The rules of UriTemplate parsing in WCF require that a literal match will match before a variable match. So if the incoming URI ends with "/feed", it will route to GetIssuesFeed, but any other URI with just that path segment will be routed to GetIssuesByYear. Note that I'm also using a query string to indicate which feed format the client is requesting. (I'll return RSS only if requested specifically; otherwise I'll return Atom.)
The third thing of interest on the GetIssuesFeed method is ServiceKnownTypeAttribute. This attribute is used by WCF to inform its serialization layer of any derived classes of the return value that might be passed as the actual return value (which it needs in order to correctly perform serialization). In this case, I potentially want to return both formats, and so I have two ServiceKnownTypeAttribute declarations, each referencing the appropriate derived class of SyndicationFeedFormatter: AtomFeedFormatter and Rss20FeedFormatter. It is fairly obvious from the class names, but AtomFeedFormatter returns a feed using the Atom format, and Rss20FeedFormatter returns a feed using the RSS 2.0 format. This is just normal WCF infrastructure, but you may not have seen this functionality unless you've tried to do polymorphism with WCF return values before.

Implementing the Feed
Whew, that's all without getting to the implementation. The implementation is actually fairly easy since it just needs to take my data about issues and articles and transfer that data into the WCF object model. The object model isn't based around SyndicationFeedFormatter—remember that's the object that does the formatting. The object model centers around a type named SyndicationFeed (see Figure 3). A SyndicationFeed object can be used to get a valid SyndicationFeedFormatter, and it is the object that holds onto each feed item. The items are part of the SyndicationFeed.Items collection.
Figure 3 SyndicationFeed Object Model
The SyndicationFeed object model follows the idea of a generic feed, although its model is geared slightly towards Atom (with the Authors and Links collections, as well as the Content and Summary properties on SyndicationItem). Figure 4 shows the code that implements the GetIssuesFeed method on my service.
Figure 4 GetIssuesFeed
public SyndicationFeedFormatter GetIssuesFeed(string format) {
  SyndicationFeedFormatter ret = null;
  SyndicationFeed myFeedData = new SyndicationFeed();
  myFeedData.Title = new TextSyndicationContent(
    "MSDN Magazine feed");
  Articles articles = GetAllArticles();

  SyndicationItem sitem = null;
  List<SyndicationItem> list = new List<SyndicationItem>();
  myFeedData.Items = list;
  SyndicationLink altLink = null;
  foreach (var item in articles) {
    sitem = new SyndicationItem {
      Title = new TextSyndicationContent(
        "MSDN Magazine Article: " + item.Title),
      Content = new XmlSyndicationContent(GenerateContent(item)),
      PublishDate = GetPublished(item),
      LastUpdatedTime = GetUpdated(item)
    };
    altLink = MakeLinkForArticle(item);
    sitem.Links.Add(altLink);
    list.Add(sitem);
  }
  ret = new Atom10FeedFormatter(myFeedData);
  return ret;
}
This is uncomplicated code and follows the same basic pattern as all feed code in WCF, which is to create a SyndicationFeed object, set its properties as appropriate, create a list of SyndicationItems, and after associating the list with the SyndicationFeed object (this isn't done automatically), populating the list with SyndicationItems containing your data. (You can download the full code from the MSDN Magazine Web site, so for brevity, I haven't shown all the helper methods here,)
Filling in the SyndicationItem property does introduce a bit of complexity depending on whether you are planning on exposing RSS or Atom (or both). But essentially it's setting the Title, PublishedDate, LastUpdatedDate, and Content properties.
Another thing to note about this code is that LastUpdatedTime and PublishDate are of type DateTimeOffset, a new type that was added in the .NET Framework 3.5 to simplify working with exact dates and times as well as time zones.
Title and Content are a little different than you might expect. Title is of type TextSyndicationContent, and Content is the base SyndicationContent type. These types (and the other main derived type, XmlSyndicationContent) are used to manage the different parts of feeds that have content, but they sometimes vary in the content they contain. For example, the SyndicationItem.Content property could have plain text, some form of XML (even XHTML or HTML), or a link to some sort of binary content (hence the UrlSyndicationContent type). SyndicationContent is a needed layer of indirection that supports all these different types of data inside feed items.
Once I have this feed up and running, I can make a user agent request for it, and Internet Explorer is happy to pick up the feed and allow the user to subscribe to it (as would any feed reader user agent).

Another reason that many sites and services are moving towards Atom is because of Atom Publishing Protocol (AtomPub). Where Atom is a format for feeds, AtomPub is a specification for retrieving, creating, and updating resources. It's a specification built on top of the constraints of REST, so working with it is straightforward once you understand REST. Because most of the interaction is done with Atom instances, the format is also well known and understood.
Most of AtomPub centers around Atom feeds, but there are two new document types: service document and category. The .NET Framework 3.5 SP1 adds support for AtomPub via two new objects that support these new document types. (You could implement AtomPub with just the .NET Framework 3.5, but SP1 adds features that make your job much easier.)
An AtomPub service document is a metadata document that informs a user agent about what workspaces a particular AtomPub endpoint supports. A workspace is a collection of member resources, which are really hyperlinks to particular Atom feeds. While the service document can also specify things such as what media types each feed supports (like images or other binary files), all feeds are expected to support standard Atom entries.
The AtomPub specification also specifies how to use the uniform interface against each feed (member resource). You can see this mapping in Figure 5.
Figure 5 AtomPub Application of the Uniform Interface
Resource | Uniform interface method | Description
Service Document | GET | Once the URI is known by a user agent, the Service Document can be retrieved via GET
Category Document | GET | Used to get the representation of the category
Collection | GET | Gets the representation—an Atom feed
Collection | POST | Creates a new Atom entry
Member | GET | Gets an individual member, which can be an individual Atom entry or a binary file
Member | PUT | Modifies a member
Member | DELETE | Deletes a member
The types added by SP1 are ServiceDocument (similar to SyndicationItem) and AtomPub10ServiceDocumentFormatter (which serves the same purpose as SyndicationFeedFormatter). There also is a type named ResourceCollectionInfo to represent each collection in the service document. This type has a relationship to ServiceDocument somewhat similar to the relationship between SyndicationFeed and SyndicationItem, since ServiceDocument holds onto a list of ResourceCollectionInfos to generate the main content of the service document itself.
To support AtomPub on my endpoint, first I need to add another method to my contract:
[OperationContract]
  [WebGet(UriTemplate = "/servicedoc")]
  AtomPub10ServiceDocumentFormatter GetServiceDoc();
Then I can provide the implementation as shown in Figure 6. This will produce the service document shown in Figure 7.
Figure 6 AtomPub Service Document Implementation
public AtomPub10ServiceDocumentFormatter GetServiceDoc() {
  OutgoingWebResponseContext ctx =
    WebOperationContext.Current.OutgoingResponse;
  ctx.ContentType = "application/atomsvc+xml";
  AtomPub10ServiceDocumentFormatter ret = null;

  //create the ServiceDocument type
  ServiceDocument doc = new ServiceDocument();
  IncomingWebRequestContext ictx =
    WebOperationContext.Current.IncomingRequest;

  //set the BaseUri to the current request URI
  doc.BaseUri = ictx.UriTemplateMatch.RequestUri;

  //create a Collection of resources
  List<ResourceCollectionInfo> resources =
     new List<ResourceCollectionInfo>();

  //create the Blog resource
  ResourceCollectionInfo mainBlog =
    new ResourceCollectionInfo("MSDNMagazine",
      new Uri("feed", UriKind.Relative));

  //add the Accepts for this resource
  //remember this is the default if no accepts if present
  mainBlog.Accepts.Add("application/atom+xml;type=entry");
  resources.Add(mainBlog);

  //create the Pictures resource
  ResourceCollectionInfo mainPictures =
    new ResourceCollectionInfo("Pictures",
      new Uri("pictures", UriKind.Relative));

  //add the Accepts for this resource
  mainPictures.Accepts.Add("image/png");
  mainPictures.Accepts.Add("image/jpeg");
  mainPictures.Accepts.Add("image/gif");
  resources.Add(mainPictures);

  //create the Workspace
  Workspace main = new Workspace("Main", resources);

  //add the Workspace to the Service Document
  doc.Workspaces.Add(main);

  //get the formatter
  ret = doc.GetFormatter()
    as AtomPub10ServiceDocumentFormatter;
  return ret;
}
Figure 7 Defining the Service
<?xml version="1.0" encoding="utf-8"?>
<service xml:base="http://localhost:1355/Issues.svc/servicedoc"
  xmlns="http://www.w3.org/2007/app"
  xmlns:a10="http://www.w3.org/2005/Atom">
  <app:workspace xmlns:app="http://www.w3.org/2007/app">
    <a10:title type="text">Main</a10:title>
    <app:collection href="feed">
      <a10:title type="text">MSDNMagazine</a10:title>
      <app:accept>application/atom+xml;type=entry</app:accept>
    </app:collection>
    <app:collection href="pictures">
      <a10:title type="text">Pictures</a10:title>
      <app:accept>image/png</app:accept>
      <app:accept>image/jpeg</app:accept>
      <app:accept>image/gif</app:accept>
    </app:collection>
  </app:workspace>
</service>
This service document communicates that there is one workspace named Main that has two collections. One collection has the relative URI of "feed" and uses the default media type as its input (the media type for Atom entries). The other collection holds binary files, specifically image files (restricted to the media types listed) and has a URI of "pictures." Given this document, a user agent can easily interact with my AtomPub endpoint following the rules set out in Figure 5.
AtomPub is a useful standard that can be applied to many different scenarios, not just blogs and associated files (like images).

Consuming Feeds
The SyndicationFeed API can also work on the client side for consuming a feed. The various current feed formats (and there probably will be more in the future) make this a nontrivial task using custom code, so this is a very nice addition to the .NET Framework base library. Here's some simple code that demonstrates consuming a feed:
string uri = "http://localhost:1355/Issues.svc/feed";
XmlReader xr = XmlReader.Create(uri);
SyndicationFeed feed = SyndicationFeed.Load(xr);
Console.WriteLine("Feed title:{0}",feed.Title.Text);
foreach (var item in feed.Items) {
  Console.WriteLine("Item {0}",item.Title.Text);
}
Many companies are standardizing as much as possible around AtomPub for building services and frameworks. ADO.NET Data Services uses AtomPub to expose data entities. In turn, ADO.NET Data Services is used for all the table, blog, and queue functionality in Microsoft Azure. Windows Live Services is using AtomPub for most of its exposed services. The point here is that even if you aren't exposing Atom or AtomPub from any applications you are building, the chances are pretty high that you'll need to know how to interact and consume AtomPub services now or sometime in the near future. Hopefully what I've shown you here will help get you started.
ADO.NET Data Services or WCF?

ADO.NET Data Services and WCF in the .NET Framework 3.5 both provide ways to easily expose RESTful services that generate standards-compliant Web feeds. So when should you use ADO.NET Data Services and when should you use the built-in support in WCF?
WCF provides functionality for exposing and calling service endpoints. With WCF 3.5, service endpoints may be standard SOAP-based or follow a simple RESTful service interface style. To expose a RESTful endpoint, you annotate the methods within your service class with the UriTemplate used to define the resource identifier. URIs that match that template result in calls to your method, passing in parameters from the template. The set of annotated methods within your class make up your service contract.
To return results from a WCF service as an RSS or Atom-compatible feed, you create within your method a SyndicationFeed object containing the list of SyndicationItems representing the content you want to return. You then pass that SyndicationFeed in the creation of a SyndicationFeedFormatter of the appropriate type, and return that SyndicationFeedFormatter from your method.
ADO.NET Data Services is built on WCF and provides a queryable REST-based endpoint over an Entity Model, such as a model exposed by the Microsoft Entity Framework or other IQueryable data source. With ADO.NET Data Services, the model becomes the service contract. That model can be queried through standard URIs that, in addition to the service root and resource path, include query options such as filtering, ordering, paging, and graph expansion. In addition, ADO.NET Data Services provides features for controlling access permissions, exposing custom service operations, and customizing how resources are accessed (for example, for implementing user-based security) through query interception.
ADO.NET Data Services supports JSON and AtomPub specifications, including the ability to do inserts, updates, and deletes against the service (as allowed) through standard HTTP verbs. Thus, ADO.NET Data Services can be accessed from any HTTP client.
In addition, Microsoft ships an ADO.NET Data Services Client for the .NET Client Framework, Silverlight, and Ajax that provides a strongly typed, LINQ-based experience for querying and updating data against an ADO.NET Data Service-compliant endpoint (whether that endpoint be implemented using ADO.NET Data Services or a custom implementation, such as Azure Table).
So if you want to expose a REST-based queryable model over a data source such as an ADO.NET Data Provider or IQueryable source (including in-memory collections) and return results in a JSON or AtomPub compatible format that can be consumed through either a simple HTTP client or a strongly typed client, then ADO.NET Data Services provides the most functionality for the least amount of work.
On the other hand, if you want to implement a set of methods that hand-craft a feed based on custom application logic, then the built-in functionality within WCF makes it easy to expose those methods as a RESTful service capable of returning the feed in an RSS or Atom-compatible format.

—Michael Pizzo, Principal Architect, Data Programmability

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 reach Jon at masteringbiztalk.com/blogs/jon.


Foundations
Working With The .NET Service Bus
Juval Lowy
Code download available from the MSDN Code Gallery
Browse the Code Online
Contents
Relay Services to the Rescue
Relay Service Address
The Service Bus Bindings
The One-Way Relay Binding
The Event Relay Binding
Relay Service as an Event Hub
Looking Forward
The .NET Service Bus is arguably the most accessible, powerful, and useful piece of the new Windows Azure Cloud Computing initiative. While the .NET Service Bus is designed to address some tough connectivity issues, it also provides an attractive solution to scalability, availability, and security issues by lowering the technology entrance barrier and making mainstream and mundane what used to be an advanced communication scenario. Specifically, the .NET Service Bus addresses the challenge of Internet connectivity. The truth is that Internet connectivity is difficult. Often, the service is located behind firewalls (both software and hardware firewalls), behind a load balancer; its address is dynamic and can be resolved only on the local network and cannot be translated to outside addressing. Virtualization adds a new dimension to connectivity along with maintaining transport sessions across machines. This situation is depicted in Figure 1.
Figure 1 Internet Connectivity Challenges
Moreover, since it is typically inadvisable to open the intranet to callers from the Internet, businesses often resort to using perimeter networks, but in turn incur the increased complexity of deployment, and of managing multiple sets of client credentials along with the unwanted traffic of unauthorized calls. Commonplace solutions for Internet connectivity from dynamic DNS to static IPs are often cumbersome, do not update in real time, but have scalability and throughput implications, and are potentially insecure unless built by experts.
When it comes to having the service call back to the client, the problem is compounded by all the connectivity issues surrounding the client, virtually a mirror image of Figure 1. And yet, callbacks, events, and peer-to-peer calls are often an integral part of many applications ranging from consumer machines hosting games, interactive communication, media sharing, and so on, to roaming business machines using ad hoc connections, to full-fledged cross-intranet business-to-business applications.

Relay Services to the Rescue
The solution to Internet connectivity challenges is simple—since it is so difficult to connect the client to the service directly, you can avoid doing that (at least initially) and instead use a relay service. The relay service is a service residing in the cloud, whose job is to assist in the connectivity, relaying the client calls to the service. Such a relay solution does require both the client and the service intranets to allow connections to the cloud, but since the cloud constitutes neutral territory for both the client and the service, most environments allow calls out to the Internet.
Figure 2 shows how the relay service operates.
First, both the service and the client must establish connections and authenticate against the relay service. At this point, the relay also records where the service is and how to best call back to it. When the client calls the relay service, the relay service forwards the call (the client message) to the service.
Figure 2 The Relay Service In Action
While the sequence seems straightforward, in practice it involves a considerable amount of intricate network programming, messaging and standards know-how, security expertise, and more. Such a solution is simply out of reach for the vast majority of applications. This is exactly the gap the Microsoft .NET Service Bus is designed to fill. It is a ready-made relay service, hosted and managed at a Microsoft data center. The .NET Service Bus acts as a perimeter network in the cloud, providing a single place to manage credentials of the client and services. The .NET Service Bus is the front end of the service; it encapsulates and isolates the service from malicious callers lurking on the Internet and is responsible for repelling various attacks from denial-of-service to replay attacks, while obscuring the identity and true location of the actual service.
The main difference between connecting to a regular Windows Communication Foundation (WCF) service and using the relay service revolves around hosting. In the relayed case, the service must connect to the .NET Service Bus, authenticate itself, and listen to calls from the relay service before the client sends its requests. This means that you either must launch the host explicitly or use an NT Service as a host, and that you cannot benefit from hosting in Windows Activation Service (WAS) (or IIS) since WAS will launch the host only after the first request comes in, and that will never happen because the host has not connected to the .NET Service Bus in the first place.
The .NET Service Bus supports a WCF-friendly programming model by offering a set of dedicated bindings and behaviors. By and large, except for a few slight twists to the programming model, working with the relay service is no different than working with any other WCF service. The .NET Service Bus supports the core WCF features of reliable messaging, message security, and transport security. It does not support propagation of transactions from the client to the service across the relay service, although that may change in a future release. Beyond mere service endpoints, the .NET Service Bus also supports two additional related programming models: message queuing and message routing. I will address queuing and routing in a future column, since the combination enables yet another set of important design scenarios beyond Internet connectivity.

Relay Service Address
After opening an account with the .NET Service Bus, you need to use the .NET Service Bus administration Web site to create a new solution (see Figure 3). (Before you go any further, note that all the demos accompanying this column and the upcoming columns use MySolution as a placeholder for the solution name. To run the demos, you will need to create your own account with the .NET Service Bus, and replace MySolution with your solution name, and provide your solution credentials. To create an account, go to servicebus.windows.net.)
Figure 3 Creating a Solution
A solution is the equivalent of a machine or domain name in regular network addressing and any available URI-compliant string will do.
Like any other WCF service, every relayed service must have a unique address. The format of the address is always a base address followed by any number of optional URIs:
[base address]/[optional URI]/.../[optional URI]
The format of the base address is always prefixed by the transport schema, then the solution name followed by the service bus address:
[schema]://[solution]/[service bus address]
The service bus address is:
servicebus.windows.net
The format of the schema is either sb, http or https. Here are a few possible addresses:
sb://MySolution/servicebus.windows.net
sb://MySolution/servicebus.windows.net/MyService
sb://MySolution/servicebus.windows.net/MyService/MyEndpoint
sb://MySolution/servicebus.windows.net/AnythingYouLike

http://MySolution/servicebus.windows.net
https://MySolution/servicebus.windows.net/MySolution/AnythingYouLike
Once your service connects to the relay service and starts listening on its address, no other service can listen on any other URI scoped under your service URI.

The Service Bus Bindings
The .NET Service Bus offers multiple bindings for relaying messages, yet the four main bindings I focus on here are the TCP relay bindings, the WS relay bindings, the one-way relay bindings, and the event relay binding (specifically, NetTcpRelayBinding, WSHttpRelayBinding, NetOnewayRelayBinding, and NetEventRelayBinding).
The TCP relay binding is the binding of choice in the majority of cases involving relayed Internet connectivity. It yields the best performance and throughput while minimizing the overhead for both the service and the relay service. It supports request-reply operations, one-way operations, and even duplex callbacks, all through the relay service. For schema, the TCP relay always uses sb:
<endpoint
   address  = "sb://MySolution/servicebus.windows.net/..."   binding  = "netTcpRelayBinding"   contract = "..."/>
The TCP relay binding requires TCP port 808 (or 828 when using transport security) to be open for calls out, something that most environments do support. The TCP relay binding offers unlimited message size (or at least up to the configured message size, as with the regular TCP binding). The TCP relay binding always maintains a transport session, so that with a session-full service, calls made on the same proxy channel always end up reaching the same service instance. However, as this binding uses the TCP binary encoding it is not interoperable—it assumes the other side is also using the TCP relay binding.
The TCP relay binding offers three connection modes: relayed, direct, and hybrid. You configure the connection mode using the TcpRelayConnectionMode enum and the ConnectionMode property of NetTcpRelayBindingBase, as you see in Figure 4.
Figure 4 TCP Relay Connection Modes
public enum TcpRelayConnectionMode
{
   Relayed,
   Direct,
   Hybrid
}
public abstract class NetTcpRelayBindingBase : Binding,...
{
   public TcpRelayConnectionMode ConnectionMode
   {get;set;}
   //More members
}
public class NetTcpRelayBinding : NetTcpRelayBindingBase
{...}
Figure 5 Direct TCP Connection
Figure 6 Duplex TCP Relay Callback

When configured with TcpRelayConnectionMode.Relayed, all calls to the service always go through the relay. Relayed connection is the default mode of the TCP relay binding.
When configured with TcpRelayConnectionMode.Direct, the service first connects to the relay service and authenticated itself (step 1 in Figure 5), and then the client connects and authenticates itself (step 2 in Figure 5). However, at this point, the relay service will promote the connection to a direct connection between the client and the service, by telling the client how to reach the service directly (step 3 in Figure 5). With that is in place, the client can continue to call the service directly (step 4 in Figure 5).
The relay service will try to promote the connection to the most direct connection possible; that is, if the client and the service are part of the same intranet, it will provide the client with "better" coordinates; the same is true if they are on the same machine.
If a direct connection is impossible (typically if the relay service failed to correctly identify the service address), the connection is aborted. For direct connections, the service needs to also open up port 819 on its machine (something that may involve a one-time user prompt).
When the TCP relay binding is configured with TcpRelayConnectionMode.Hybrid, the communication starts as a relay via the relay service. If direct connection between the client and the service is possible, the relay service will promote it to direct connection. Otherwise, it will remain as relayed. The relay service can promote to direct even as the message is being relayed without any loss of data. The hybrid mode should be the preferred connection mode over the TCP relay binding. However, it has one drawback: both the direct and the hybrid modes require the binding to use Message security, and as you will see in the next installment of this column, Message security requires additional configuration and setup. And while these are simple steps, they do preclude hybrid as a working option by default.
I mentioned it already, but it's worth highlighting the fact the TCP relay binding supports duplex callbacks through the relay. Setting up the duplex calls and accessing the callback reference is identical to the regular TCP binding. Presently, the TCP relay binding is the only relay binding that supports duplex callbacks (see Figure 6).
The WS relay binding sends and receives interoperable WCF messages over HTTP (or HTTPS). Like the regular WS binding it uses text encoding by default, and when Message security or reliable messaging is employed, it will maintain the transport session over the relay. The scheme for the address is either http or https.
<endpoint address = "http://MySolution/servicebus.windows.net/..."
binding = "wsHttpRelayBinding"
contract = "..."/>
As far as capabilities and use, the WS relay binding is just like the TCP relay binding, except it supports only relayed connection. You should use this binding either when the TCP ports used by the TCP relay binding are blocked or when you have an explicit need to interoperate.

The One-Way Relay Binding
The one-way relay binding allows the client to send its message to a buffer maintained at the relay service, rather than the service itself, and later have the relay service try to deliver the message to the service. To control the load on the .NET Service Bus, messages sent are limited to 64KB (this limit may change in the future). No reply from the service is possible and in fact, the one-way relay binding verifies that all operations on the endpoint's contract are defined as one-way operations. In the case of both the TCP and the WS relay bindings, when the client calls the relay service, the service itself must be listening or the client will encounter an EndpointNotFoundExcpetion exception, just as with non-relayed WCF (this is the case even when the operations are defined as one-way). In the case of the one-way relay binding, the client can issue the call regardless of the presence of the service, and there may not even be a service listening at all. As a result, you should choose the one-way relay binding whenever the service's state is unknown. The downside is that the client has no guarantee of delivery of its messages, nor is there any guarantee of the order of the calls dispatched to the service. In addition, because of the inherent disconnected nature of the one-way relay binding, there is never a transport session. Just as with the TCP and the WS relay binding, there can be only one service monitoring the relayed address, while there could be any number of clients calling that service. For the schema, the one-way relay always uses sb:
<endpoint   address  = "sb://MySolution/servicebus.windows.net/..."   binding  = "netOnewayrelayBinding"   contract = "..."/>

The Event Relay Binding
The event relay binding is a light but crucial specialization of the one-way relay binding:
public class NetEventRelayBinding : NetOnewayRelayBinding
{...}
It allows any number of services to monitor the same URI in the relay service. Once a client sends a message to the relay, all monitoring services receive it. Given the fact there is no limitation on the number of clients, this in effect provides for N:M communication where both N and M can be any natural number including zero, similar to UDP multicast. Since the specialization is on the service side, the client can use either the one-way relay binding or the event relay binding while the services must use the event relay binding. In addition, unlike any other relay binding, you can also have services listening concurrently on nested URIs. As with the one-way relay binding, there is no guarantee of order of messages or of delivery itself.
Figure 7 Events Relay Service
By far, the canonical case for using the event relay binding is event publishing and subscription, as show in Figure 7. The clients, now called publishers, call the relay service now acting as an events hub, delivering the events to any number of services, now called subscribers.

Relay Service as an Event Hub
The design shown in Figure 7 has the appearance of a general-purpose publish-subscribe pattern (for more on how to implement a full-fledged publish subscribe, see my article "WCF Essentials: What You Need To Know About One-Way Calls, Callbacks, And Events"). In reality, the events relay binding is indented to provide only a lightweight, ready-made, cloud-assisted event distribution solution for delivering events to running services. The more powerful features of administrative support for adding and removing subscribers, events filtering, and events queuing (to enable both queued publishers and queued subscribers) all require the use of queues and routers, which I will discuss in an upcoming column.
If you merely want to publish events to running subscribers over the relay service, then treating the relay service as your events hub will suffice. However, you'll soon run into the lack of support for discrete, operation-level events. Events equate to service endpoints, or more specifically, to the contract. There is no ability for the service to subscribe to a particular operation on the contract, but not to others. This means that the subscribing service still receives events it may not care about simply because it has a matching endpoint. For example, consider the IMyEvents contract:
[ServiceContract]
interface IMyEvents
{
   [OperationContract(IsOneWay = true)]
   void OnEvent1();

   [OperationContract(IsOneWay = true)]
   void OnEvent2(int number);

   [OperationContract(IsOneWay = true)]
   void OnEvent3(int number,string text);
}
If the subscriber defines the endpoint as in the following code, the subscriber will, of course, receive all calls to the endpoint.
<endpoint
   address  = "sb://MySolution/servicebus.windows.net/IMyEvents"
   binding  = "netEventRelayBinding"
   contract = "IMyEvents"
/>
If the subscriber cares only about receiving calls to the OnEvent2 operation, it must still expose an endpoint over the event relay binding, receive the calls to OnEvent2, but also receive all the unwanted traffic for OnEvent1 and OnEvent3 and filter them internally. This is a direct result of subscribing at the contract (or the endpoint) level and not at the discrete operation level.
The only way to manage events at the operation level is to map URIs to operations, not endpoints. Figure 8 shows the publisher view of such endpoints.
Figure 8 Defining Events at the Operation Level
<endpoint name = "OnEvent1"
   address  = "sb://MySolution/servicebus.windows.net/IMyEvents/OnEvent1"
   binding  = "netOnewayBinding"
   contract = "IMyEvents"

/>
<endpoint name = "OnEvent2"
   address  = "sb://MySolution/servicebus.windows.net/IMyEvents/OnEvent2"
   binding  = "netOnewayBinding"
   contract = "IMyEvents"
/>
<endpoint name = "OnEvent3"
   address  = "sb://MySolution/servicebus.windows.net/IMyEvents/OnEvent3"
   binding  = "netOnewayBinding"
   contract = "IMyEvents"
/>
While the publishing client can easily consume the precise endpoint to fire a specific event, setting it up on the subscriber side is not straightforward. First you would want to allow subscribing and unsubscribing to individual events without disturbing other event processing in progress. Second, the subscriber cannot possibly open all the endpoints using the same host, since you would gain nothing; it would still get all the unwanted events. The only way to manage operation-level events is to have as many hosts as operations on the contract, all targeting the same service type. Each host will open a single endpoint, corresponding to a specific event (operation). To subscribe or unsubscribe to a particular event at run time, you must open or close the corresponding host. Because you cannot rely on listing the endpoints in the host config file (this will just make all hosts open all endpoints), you must programmatically add each desired endpoint to the specific host. as shown in Figure 9 in pseudo code. The code in Figure 9 sets up the endpoints exposed to the publisher in Figure 8.
Figure 9 Equating Events with Operations
class MySubscriber : IMyEvents
{...}

ServiceHost hostEvent1;
ServiceHost hostEvent2;
ServiceHost hostEvent3;

Binding binding = new NetEventRelayBinding();
Uri baseAddress = new Uri("sb://MySolution/servicebus.windows.net/IMyEvents/");

//Subscribing to all events:
hostEvent1 = new ServiceHost(typeof(MySubscriber),baseAddress);
hostEvent1.AddServiceEndpoint(typeof(IMyEvents),binding,"OnEvent1");
hostEvent1.Open();

hostEvent2 = new ServiceHost(typeof(MySubscriber),baseAddress);
hostEvent2.AddServiceEndpoint(typeof(IMyEvents),binding,"OnEvent2");
hostEvent2.Open();

hostEvent3 = new ServiceHost(typeof(MySubscriber),baseAddress);
hostEvent3.AddServiceEndpoint(typeof(IMyEvents),binding,"OnEvent3");
hostEvent3.Open();

//Unsubscribe event 2:
hostEvent2.Close();
However, such an approach is tedious, repetitive, and error prone. It is also tightly coupled to the event contract. To streamline, automate, and decouple this programming model I wrote the helper host EventRelayHost shown in Figure 10. The constructors of EventRelayHost all require at least one base addresses to use (with a regular host base addresses are optional).
Figure 10 EventRelayHost
public class EventRelayHost
{
   public EventRelayHost(Type serviceType,string baseAddress);
   public EventRelayHost(Type serviceType,string[] baseAddresses);

   public void SetBinding(NetEventRelayBinding binding);
   public void SetBinding(string bindingConfigName)

   public void Subscribe();
   public void Subscribe(Type contractType);
   public void Subscribe(Type contractType,string operation)

   public void Unsubscribe();
   public void Unsubscribe(Type contractType);
   public void Unsubscribe(Type contractType,string operation);

   public void Abort();
   //More members
}
You can also provide EventRelayHost with the binding to use via the SetBinding methods. EventRelayHost will default to a plain instance of NetEventRelayBinding. The Subscribe and Unsubscribe methods operate very much like the Open and Close methods of a regular host. You can subscribe (or unsubscribe) to all events on all service contracts supported by the service type, to all events on a particular service contract, or to a specific event operation on a particular service contract. Finally, you can call Abort to abort all events processing in progress and ungracefully shut down all hosts. You can see the implementation of EventRelayHost in Figure 11.
Figure 11 Implementing EventRelayHost
//Partial listing without error handling and security
public class EventRelayHost
{
   Dictionary<Type,Dictionary<string,ServiceHost>> m_Hosts =
                            new Dictionary<Type,Dictionary<string,
                                                  ServiceHost>>();
   Type m_SericeType;
   string[] m_BaseAddresses;

   public void Subscribe(Type contractType,string operation)
   {
      m_Hosts[contractType] = new Dictionary<string,ServiceHost>();
      List<Uri> baseAddressesList = new List<Uri>();
      foreach(string address in m_BaseAddresses)
      {
         baseAddressesList.Add(new Uri(address + contractType));
      }
      m_Hosts[contractType][operation] =
                        new ServiceHost(m_SericeType,
                        baseAddressesList.ToArray());
      NetEventRelayBinding binding = new NetEventRelayBinding();
      m_Hosts[contractType][operation].
                               AddServiceEndpoint(contractType,
                                            binding,operation);

      m_Hosts[contractType][operation].Open();
   }
   public void Unsubscribe(Type contractType,string operation)
   {
      m_Hosts[contractType][operation].Close();
   }
   //More members
}
EventRelayHost maintains a dictionary that maps for each event service contract type another dictionary that maps for each operation a dedicated service host. The Subscribe method opens that host, and adds an endpoint for each base address. Subscribe appends for each endpoint address the contract type and the operation name. There is no need for a config file when using EventRelayHost, and the code in Figure 11 is reduced to.
EventRelayHost host = new EventRelayHost(typeof(MyService), "sb://MySolution/servicebus.windows.net/...");

host.Subscribe();
...
host.Unsubscribe(typeof(IMyEvents),"OnEvent2");
While EventRelayHost streamlines the subscriber side, the client now has to maintain as many proxies as event endpoints. To help achieve that I wrote EventRelayClientBase<T>, declared as you see in Figure 12.
Figure 12 EventRelayClientBase<T>
public abstract class EventRelayClientBase<T> : IDisposable where T : class
{
   public event EventHandler Closed;
   public event EventHandler Opened;

   public CommunicationState State
   {get;}

   public EventRelayClientBase(string solutionBaseAddress);
   public EventRelayClientBase(string solutionBaseAddress,
                               NetEventRelayBinding binding)

   public void Open();
   public void Close();
   public void Abort();

   public T Channel
   {get;}
   //More members
}
To use EventRelayClientBase<T>, just derive from it like the regular ClientBase<T>, as I did in Figure 13.
Figure 13 Using EventRelayClientBase<T>
class MyEventsProxy : EventRelayClientBase<IMyEvents>,IMyEvents
{
   public MyEventsProxy(string baseAddress) : base(baseAddress)
   {}

   public void OnEvent1()
   {
      Channel.OnEvent1();
   }
   public void OnEvent2(int number)
   {
      Channel.OnEvent2(number);
   }
   public void OnEvent3(int number,string text)
   {
      Channel.OnEvent3(number,text);
   }
}
EventRelayClientBase<T> offers quasi-support for ICommunicationObject's state and state change notifications. Unlike the regular proxy, EventRelayClientBase<T> requires the subscriber's base address. To that address, it appends the contract name and the operation name, to match the endpoints opened by EventRelayHost. As with the EventRelayHost, there is no need for a client-side config file. While EventRelayClientBase<T> looks to the client as a single proxy, it is in fact an aggregation of proxies—it maintains a proxy per endpoint on the subscriber side.
As shown in Figure 14, EventRelayClientBase<T> has a dictionary that maps an operation to an instance of T—the events service contract provided as a type parameter. When the client opens EventRelayClientBase<T>, it uses reflection to obtain a collection of all the event operations. For each operation, it appends to the base address the contract name and the operation name (to generate the endpoint address), and then uses the channel factory to create the matching proxy.
Figure 14 Implementing EventRelayClientBase<T>
//Partial listing without error handling and state management
public abstract class EventRelayClientBase<T> : IDisposable where T : class
{
   readonly string BaseAddress;
   Dictionary<string,T> m_Proxies = new Dictionary<string,T>();
   public CommunicationState State
   {get;private set;}

   public void Open()
   {
      Binding binding = new NetOnewayRelayBinding();
      MethodInfo[] methods = typeof(T).GetMethods(...);
      foreach(MethodInfo method in methods)
      {
         EndpointAddress address =
                     EndpointAddress(new Uri(BaseAddress+typeof(T) +
                                                       method.Name));
         ChannelFactory<T> factory = new ChannelFactory<T>(binding,
                                                          address);
         m_Proxies[method.Name] = factory.CreateChannel();
         ICommunicationObject proxy = m_Proxies[method.Name]
                                    as ICommunicationObject;
         proxy.Open();
      }
      State = CommunicationState.Opened;
   }
   public T Channel
   {
      get
      {
         if(State != CommunicationState.Opened)
         {
            Open();
         }
         StackFrame frame = new StackFrame(1);
         return m_Proxies[frame.GetMethod().Name];
      }
   }
   public void Close()
   {
      foreach(ICommunicationObject proxy in m_Proxies.Values)
      {
         proxy.Close();
      }
   }
   public void Abort()
   {
      foreach(ICommunicationObject proxy in m_Proxies.Values)
      {
         proxy.Abort();
      }
   }
   //More members
}
The Channel property returns the correct proxy by accessing the stack frame, obtaining the name of the calling operation and using that as the key to look up the correct proxy from the dictionary. Closing EventRelayClientBase<T> closes all the proxies it manages.

Looking Forward
WCF also offers the BasicHttpRelayBinding, WebHttpRelayBinding, WS2007HttpRelayBinding, and WS2007FederationHttpRelayBinding. As their names imply, these bindings are the relayed equivalents of the regular WCF bindings. In addition, WCF provides the NetTcpContextRelayBinding, BasicHttpRelayContextBinding, and WebHttpRelayContextBinding. These context bindings all derive from their corresponding relay bindings but add support for the context protocol.
Security is also an issue. Both the client and the service should authenticate themselves against the relay service and protect the messages while on transfer from the client to the service. I will discuss service bus security, as well as the exciting queuing and routing, in my next columns.

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

Juval Lowy is 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.


Windows With C++
The Virtual Disk API In Windows 7
Kenny Kerr

This article is based on a prerelease version of Windows 7. All information herein is subject to change.
Contents
The VHD Format
Creating Virtual Disks
Opening Virtual Disks
Attaching Virtual Disks
Querying Virtual Disks
What's Next
As I write this, the Windows 7 beta has been available for a few days, and I must say there is a lot to like. As usual, I took a look under the hood to see what is new in the Windows SDK. Windows 7 is very much a minor release as far as the SDK is concerned, and that's a good thing. The fundamentals of writing native C++ applications for Windows 7 have not changed much compared to the way they changed for Windows Vista. Having said that, however, Windows 7 has some completely new features that are sure to interest anyone looking to take advantage of the platform.
One of these features is the Virtual Disk API. Although designed with other formats in mind, the Virtual Disk API in the Windows 7 beta is very much geared toward the Microsoft Virtual Hard Disk (VHD) format popularized by virtualization products from Microsoft such as Hyper-V and Virtual PC.
This really takes me back because I've been involved with virtualization for quite a few years. When I first started working with virtualization technology almost ten years ago, VMware was the clear leader. Then in 2003 Microsoft acquired virtual machine technology from Connectix, and everything changed. All of a sudden there were two big players. It was clear the VHD format that Microsoft acquired from Connectix was well suited to the direction that Microsoft wanted to take with virtualization, namely to turn it into a platform. Whereas the VMware virtual disk formats were proprietary and very convoluted, often changing wildly from one release to the next, the VHD format was from the start straightforward and flexible enough to stand the test of time. In the intervening years, the VHD format has proven itself again and again, having been adopted by other products and technologies within Microsoft and by other software companies, big and small.
For this reason I'm happy to see that Windows 7 supports the VHD format natively. This means that users and administrators can easily create and attach virtual disks as if they were additional physical storage devices, without installing any third-party drivers or tools. You can, for example, use the Disk Management MMC (Microsoft Management Console) snap-in or the DISKPART command-line tool to create and attach virtual disks. You can then partition, format, and use them like any other hard disk on your computer.
In addition, you also gain very granular control over the creation and management of virtual disks. At the heart of these capabilities is VirtDisk.dll, which provides a low-level C API, known as the Virtual Disk API, for creating and manipulating virtual disks. This API provides access to a number of kernel-mode drivers that are needed to actually represent the disk and its volumes in the storage subsystem so that file system drivers can be layered on top without requiring any knowledge of the actual source of the storage.
Disk management tools typically interact with virtual disks via the Virtual Disk Service (VDS) that itself relies on the Virtual Disk API for handling VHD-based storage. Of course Hyper-V has its own Windows Management Instrumentation (WMI)–based API for creating and manipulating virtual machines, and it too relies on the Virtual Disk API.
Before I dive in and show how you can use the Virtual Disk API, I'll quickly describe the basics of the VHD format. You'll see that given this new API, you can now throw away much of the code you needed previously for managing virtual disks.

The VHD Format
The VHD format provides three different image types: fixed, dynamic, and differencing disks. All three disk types include a 512-byte VHD footer residing at the end of the disk file. More on this in a minute.
Fixed disks are the simplest type and provide the best performance because the disk file is fully allocated to accommodate the size requested when the disks are created. A 500-MB fixed disk will be exactly 500 x 1024 x 1024 + 512 bytes in size. Because the footer is at the end of the disk, the disk's storage can align with the beginning of the file to ensure the simplest and fastest possible random access.
Dynamic disks are called sparse disks by the Virtual Disk API, and sparse is a good way to think of them. The disk files are initially created with just enough space to store the VHD footer as well as some additional metadata that is needed to manage the dynamic nature of the storage allocation. As data is written to the disk, additional blocks of storage are allocated at the end of the disk file. Dynamic disks are advantageous because they take up far less space if not used at full capacity, which is the case most of the time. The disadvantage is that the additional indirection and metadata management required to read, write, and grow a dynamic disk on demand takes its toll on performance. For this reason, dynamic disks are favored in testing scenarios, whereas fixed disks are preferred in production scenarios because performance is a high priority.
Differencing disks are very similar to dynamic disks internally, but other characteristics are very different. As with dynamic disks, differencing disks use dynamically allocated blocks, but those blocks contain only modifications related to a parent disk. This type of disk is therefore dependent on a parent disk to function. The parent of a differencing disk can be either a fixed or a dynamic disk. The parent can, in fact, be another differencing disk, allowing a chain or tree of disks to be created. Disks that represent leaf nodes can be freely written to, but nonleaf nodes should be considered read-only because any descendant differencing disks rely on them to fill in the blanks, so to speak, and if they were to change it would very likely result in corrupt virtual disks.
As I mentioned earlier, the different types of disks share a common footer. This footer contains information such as the logical size of the disk, disk geometry, the type of disk, the disk's globally unique identifier, and so on. For dynamic and differencing disks the footer also includes an offset value indicating where the dynamic header resides relative to the beginning of a disk. This secondary structure chiefly contains information that might be required to locate and identify a parent disk, if necessary, as well as another offset indicating where the disk's block allocation table (BAT) resides. This table indicates which blocks have been allocated as well as their absolute offsets in the disk file.
With that introduction out of the way, let's dive in and take a look at the Virtual Disk API.
Keep in mind that the API is designed to allow Microsoft to add support for additional formats in the future. In fact, support for the ISO optical disk image format has been considered but has not been added as of the Windows 7 beta. I hope that the necessary virtual disk support provider will be included in the release build. This would allow users to attach and mount ISO images as read-only hard drives.

Creating Virtual Disks
Virtual disks are represented by opaque handles, much like other system objects such as files, registry keys, and so on. The familiar CloseHandle function is even used to close a virtual disk handle. The Active Template Library's (ATL) CHandle class is a good choice for managing this resource. You can derive a "VirtualDisk" class from CHandle to wrap up some of the boilerplate code necessary to manipulate virtual disks.
Whenever you open or create a virtual disk, you need to specify the disk's storage type. This is accomplished with the VIRTUAL_STORAGE_TYPE structure. Storage types are defined for the ISO and VHD formats. The structure also specifies the vendor that provides the implementation for the particular storage type. Here's how you can identify the VHD storage type:
VIRTUAL_STORAGE_TYPE storageType =
{
    VIRTUAL_STORAGE_TYPE_DEVICE_VHD,
    VIRTUAL_STORAGE_TYPE_VENDOR_MICROSOFT
};
The CreateVirtualDisk function creates all three types of virtual disks. Along with the storage type, you must populate a CREATE_VIRTUAL_DISK_PARAMETERS structure. How this structure is populated depends on the type of virtual disk you would like to create. Many of the Virtual Disk API structures use a versioning scheme to accommodate future updates to the API. The structures begin with a member named Version followed by a union of structures. For example, here's how you can populate the common fields for creating virtual disks:
CREATE_VIRTUAL_DISK_PARAMETERS parameters =
{
    CREATE_VIRTUAL_DISK_VERSION_1
};
parameters.Version1.MaximumSize = size;
parameters.Version1.BlockSizeInBytes = CREATE_VIRTUAL_DISK_PARAMETERS_DEFAULT_BLOCK_SIZE;
parameters.Version1.SectorSizeInBytes = CREATE_VIRTUAL_DISK_PARAMETERS_DEFAULT_SECTOR_SIZE;
The size of the virtual disk is specified in bytes and must be a multiple of 512. The block size and sector size is configurable, but if you need to ensure the greatest level of compatibility across implementations the default values are a good choice. The Version1 structure also provides a UniqueId member, but if you leave this zeroed out, the CreateVirtualDisk function will generate a GUID for you. The SourcePath member may also be specified for all disk types except the differencing disks. This instructs CreateVirtualDisk to copy the contents of the source disk into the newly created virtual disk. The two do not need to be of the same type. In fact, the source disk does not even have to be a virtual disk and can be a physical disk that you would like to make a copy of.
Figure 1 provides the beginnings of a VirtualDisk wrapper class that includes a CreateFixed member function for creating fixed virtual disks. Note that for fixed disks you must specify the CREATE_VIRTUAL_DISK_FLAG_FULL_PHYSICAL_ALLOCATION flag. Creating a dynamic disk is exactly the same as creating a fixed disk except that you must omit this flag and can specify the CREATE_VIRTUAL_DISK_FLAG_NONE flag instead. Creating a differencing disk is also much the same. The difference there is that you must not set the size, as it is inferred from the parent disk, and you must specify the parent with the ParentPath member of the Version1 structure. The SourcePath cannot be set for differencing disks for obvious reasons.
Figure 1 Creating Fixed Disks
class VirtualDisk : public CHandle
{
public:

    DWORD CreateFixed(PCWSTR path,
                      ULONGLONG size,
                      VIRTUAL_DISK_ACCESS_MASK accessMask,
                      __in_opt PCWSTR source,
                      __in_opt PSECURITY_DESCRIPTOR securityDescriptor,
                      __in_opt OVERLAPPED* overlapped)
    {
        ASSERT(0 == m_h);
        ASSERT(0 != path);
        ASSERT(0 == size % 512);

        VIRTUAL_STORAGE_TYPE storageType =
        {
            VIRTUAL_STORAGE_TYPE_DEVICE_VHD,
            VIRTUAL_STORAGE_TYPE_VENDOR_MICROSOFT
        };

        CREATE_VIRTUAL_DISK_PARAMETERS parameters =
        {
            CREATE_VIRTUAL_DISK_VERSION_1
        };

        parameters.Version1.MaximumSize = size;
        parameters.Version1.BlockSizeInBytes = CREATE_VIRTUAL_DISK_        PARAMETERS_DEFAULT_BLOCK_SIZE;
        parameters.Version1.SectorSizeInBytes = CREATE_VIRTUAL_DISK_        PARAMETERS_DEFAULT_SECTOR_SIZE;
        parameters.Version1.SourcePath = source;

        return ::CreateVirtualDisk(&storageType,
                                   path,
                                   accessMask,
                                   securityDescriptor,
                                   CREATE_VIRTUAL_DISK_FLAG_FULL_                                   PHYSICAL_ALLOCATION,
                                   0, // no provider-specific flags
                                   &parameters,
                                   overlapped,
                                   &m_h);
    }
The CreateVirtualDisk function provides a few additional parameters that are worth mentioning. The VIRTUAL_DISK_ACCESS_MASK enumeration provides a set of flags for controlling the access that the API will grant callers through the resulting handle. Although you can specify VIRTUAL_DISK_ACCESS_ALL, this is often undesirable as it prevents you from running certain operations such as querying a virtual disk that is currently attached as a storage device. The other very useful feature is the ability to specify an OVERLAPPED structure. This is supported by a number of the Virtual Disk API functions, and as you would expect has the effect of performing the operation asynchronously. Simply provide a manual reset event and it will be signaled upon completion.

Opening Virtual Disks
The OpenVirtualDisk function can be used to open a virtual disk. As with virtual disk creation, you must provide a VIRTUAL_STORAGE_TYPE structure to identify the storage type. An OPEN_VIRTUAL_DISK_PARAMETERS structure may optionally be provided but is typically only required when manipulating differencing disk relationships.
Figure 2 provides an Open member function to add to the VirtualDisk wrapper class started in Figure 1. Opening virtual disks is typically simpler than creating them, but some of the flags and options must be used in a very particular way to allow certain maintenance operations such as merging and attaching virtual disks.
Figure 2 Opening Virtual Disks
DWORD Open(PCWSTR path,
           VIRTUAL_DISK_ACCESS_MASK accessMask,
           OPEN_VIRTUAL_DISK_FLAG flags, // OPEN_VIRTUAL_DISK_FLAG_NONE
           ULONG readWriteDepth) // OPEN_VIRTUAL_DISK_RW_DEPTH_DEFAULT
{
    ASSERT(0 == m_h);
    ASSERT(0 != path);

    VIRTUAL_STORAGE_TYPE storageType =
    {
        VIRTUAL_STORAGE_TYPE_DEVICE_VHD,
        VIRTUAL_STORAGE_TYPE_VENDOR_MICROSOFT
    };

    OPEN_VIRTUAL_DISK_PARAMETERS parameters =
    {
        OPEN_VIRTUAL_DISK_VERSION_1
    };

    parameters.Version1.RWDepth = readWriteDepth;

    return ::OpenVirtualDisk(&storageType,
                             path,
                             accessMask,
                             flags,
                             &parameters,
                             &m_h);
}

Attaching Virtual Disks
The Windows 7 beta uses the term surface, or surfacing, to mean attaching the disk as a storage device in the operating system. This has subsequently been changed to the more obvious word attach. The AttachVirtualDisk (called SurfaceVirtualDisk in the beta) function attaches the virtual disk. The virtual disk is identified by a handle previously obtained from a call to either CreateVirtualDisk or OpenVirtualDisk. You must make sure that the handle has the appropriate access defined for it. To attach and detach a virtual disk, you must also have the SE_MANAGE_VOLUME_NAME privilege present in your token. This privilege is stripped from an administrator's token when User Account Control is in use, so you may need to elevate your application to gain access to the unrestricted token that includes this privilege.
Figure 3 provides an Attach member function to add to the VirtualDisk wrapper class. The ATTACH_VIRTUAL_DISK_FLAG (called SURFACE_VIRTUAL_DISK_FLAG in the beta) parameter is how you control the method in which the virtual disk is attached.
Figure 3 Attaching Disks
DWORD Attach(ATTACH_VIRTUAL_DISK_FLAG flags,
              __in_opt PSECURITY_DESCRIPTOR securityDescriptor,
              __in_opt OVERLAPPED* overlapped)
{
    ASSERT(0 != m_h);

    return ::AttachVirtualDisk(m_h,
                                securityDescriptor,
                                flags,
                                0, // no provider-specific flags
                                0, // no parameters
                                overlapped);
}
ATTACH_VIRTUAL_DISK_FLAG_READ_ONLY (called SURFACE_VIRTUAL_DISK_FLAG_READ_ONLY in the beta) can be specified to ensure that the attached disk is write-protected. This cannot be overridden by an attempt to make the disk writable with VDS.
ATTACH_VIRTUAL_DISK_FLAG_NO_DRIVE_LETTER (called SURFACE_VIRTUAL_DISK_FLAG_NO_DRIVE_LETTER in the beta) will prevent Windows from automatically assigning drive letters to any volumes present in the virtual disk. You are free then to mount any volumes programmatically or not at all, depending on your needs. The GetVirtualDiskPhysicalPath function can be used to identify the physical path where the virtual disk was attached.
ATTACH_VIRTUAL_DISK_FLAG_PERMANENT_LIFETIME (called SURFACE_VIRTUAL_DISK_FLAG_PERMANENT_LIFETIME in the beta) ensures that the virtual disk remains attached even after the virtual disk handle is closed. Failure to specify this flag results in the virtual disk being detached automatically when the handle is closed. To detach the virtual disk in this case, you need to call the DetachVirtualDisk function (called UnsurfaceVirtualDisk in the beta).

Querying Virtual Disks
The GetVirtualDiskInformation function allows you to query a virtual disk for different classes of information. The information is communicated using the GET_VIRTUAL_DISK_INFO structure, which uses the same version pattern used by many of the other Virtual Disk API structures. For example, to get the disk's size information you set the structure's version to GET_VIRTUAL_DISK_INFO_SIZE. The corresponding Size union member will then be populated. Figure 4 illustrates this.
Figure 4 Getting Size Information
DWORD GetSize(__out ULONGLONG& virtualSize,
              __out ULONGLONG& physicalSize,
              __out ULONG& blockSize,
              __out ULONG& sectorSize) const
{
    ASSERT(0 != m_h);

    GET_VIRTUAL_DISK_INFO info =
    {
        GET_VIRTUAL_DISK_INFO_SIZE
    };

    ULONG size = sizeof(GET_VIRTUAL_DISK_INFO);

    const DWORD result = ::GetVirtualDiskInformation(m_h,
                                                     &size,
                                                     &info,
                                                     0); // fixed size

    if (ERROR_SUCCESS == result)
    {
        virtualSize = info.Size.VirtualSize;
        physicalSize = info.Size.PhysicalSize;
        blockSize = info.Size.BlockSize;
        sectorSize = info.Size.SectorSize;
    }

    return result;
}
The GetVirtualDiskInformation function operates on a virtual disk handle, so again you need to ensure you have the appropriate access. In this case the VIRTUAL_DISK_ACCESS_GET_INFO permission is required. Since some of the information that can be obtained using GetVirtualDiskInformation is variable in length, it provides two additional parameters to specify both how much storage is initially being provided and how much was ultimately populated. For most of the information you will query the size is known ahead of time and the last parameter can be omitted, as is the case in Figure 4.
The notable exception is when querying a differencing disk for the location, or path, of a parent virtual disk. In this case you need to start by determining the amount of memory that is required with an initial call to GetVirtualDiskInformation. This call will fail with ERROR_INSUFFICIENT_BUFFER but provide you with the size of the buffer that needs to be allocated. You can then call the function a second time to actually get the information. The GET_VIRTUAL_DISK_INFO_PARENT_LOCATION version flag is used to get the parent location. It is, however, a little more complicated still. Since maintaining a reference to a parent is so critical for the operation of a differencing disk, the VHD format provides a degree of redundancy that can be exploited should the link to the parent be broken. Suffice it to say that the querying for the parent location involves parsing a sequence of null-terminated strings, terminated by an empty string. This is the same as the REG_MULTI_SZ registry value type. Figure 5 shows you how it's done. The example uses ATL's CAtlArray collection class as well ATL's CString class.
Figure 5 Getting Parent Location
DWORD GetParentLocation(__out bool& resolved,
                        __out CAtlArray<CString>& paths) const
{
    ASSERT(0 != m_h);

    GET_VIRTUAL_DISK_INFO info =
    {
        GET_VIRTUAL_DISK_INFO_PARENT_LOCATION
    };

    ULONG size = sizeof(GET_VIRTUAL_DISK_INFO);

    DWORD result = ::GetVirtualDiskInformation(m_h,
                                               &size,
                                               &info,
                                               0); // not used

    if (ERROR_INSUFFICIENT_BUFFER != result)
    {
        return result;
    }

    CAtlArray<BYTE> buffer;

    if (!buffer.SetCount(size))
    {
        return ERROR_NOT_ENOUGH_MEMORY;
    }

    GET_VIRTUAL_DISK_INFO* pInfo = reinterpret_cast<GET_VIRTUAL_DISK_    INFO*>(buffer.GetData());
    pInfo->Version = GET_VIRTUAL_DISK_INFO_PARENT_LOCATION;

    result = ::GetVirtualDiskInformation(m_h,
                                         &size,
                                         pInfo,
                                         0); // not used

    if (ERROR_SUCCESS == result)
    {
        resolved = 0 != pInfo->ParentLocation.ParentResolved;
        PCWSTR path = pInfo->ParentLocation.ParentLocationBuffer;

        while (0 != *path)
        {
            paths.Add(path);

            path += paths[paths.GetCount() - 1].GetLength() + 1;
        }
    }

    return result;
}

What's Next
The Virtual Disk API provides a few more functions primarily aimed at maintaining or repairing virtual disks. The MergeVirtualDisk function allows you to merge any changes in a differencing disk back into a parent disk. It supports merging with any parent in the chain. Functions are also provided for compacting and expanding virtual disks as well as updating relational metadata in the case of differencing disks.
Note that the Windows SDK for the Windows 7 beta omitted the VirtDisk.lib file necessary to link to the Virtual Disk API functions. This will be corrected for the release. Developers using the beta can use the LoadLibrary and GetProcAddress functions to load and address the functions or generate the lib file yourself.

Send your questions and comments to mmwincpp@microsoft.com

Kenny Kerr is a software craftsman specializing in software development for Windows. He has a passion for writing and teaching developers about programming and software design. You can reach Kenny at weblogs.asp.net/kennykerr.


.NET Matters
Parallelizing Operations With Dependencies
Stephen Toub

Q I have a system where multiple components need to be executed, but those components may have dependencies on each other. I'd like to be able to run these components in parallel where possible. How can I go about doing this?
A This is a fairly common problem in the development of software, whether serial or parallel. In a sequential implementation, a common approach is to model the dependencies as a graph. Each component is represented by a node in the graph, and each dependency is represented by a directed edge between the two nodes sharing the dependency. This creates what's known as a Directed Acyclic Graph (DAG), assuming that there are no cycles (for example, component 1 depends on component 2, which depends on component 3, which depends back on component 1). A topological sort can then be used to create a partial ordering among these components so that, if you execute the components sequentially in that order, all of a component's dependencies will have completed by the time that component is run.
Figure 1 A Directed Acyclic Graph
Let's say you have 8 components, with the following dependencies (I'll refer back to this example throughout this column):
  • Components 1, 2, and 3 depend on nothing else
  • Component 4 depends on component 1
  • Component 5 depends on components 1, 2, and 3
  • Component 6 depends on components 3 and 4
  • Component 7 depends on components 5 and 6
  • Component 8 depends on component 5
A DAG for this set of dependencies is shown in Figure 1. In a sequential application, by running a topological sort over this graph, you might come up with one of several partial orderings, including just running them in ascending order (1,2,3,4,5,6,7,8), which happens to satisfy the dependencies outlined here. Other orderings are of course possible, such as 3,2,1,5,8,4,6,7.
The ability to execute in parallel some of the components in a graph like this one could yield valuable increases in speed. Imagine, just for the sake of illustration, that every component takes one second to execute, that each component is itself sequential in nature, that the application is running on a machine with an infinite number of processing cores, and that there is zero processing required for anything other than executing the components (no overhead). If you were to run all of the components sequentially, it would take eight seconds. But you can do better in parallel. You can run components 1, 2, and 3 concurrently, taking a total of one second. You can then run 4 and 5 concurrently, taking another second. When those are complete, you can run 6 and 8 concurrently, taking another second. And finally you can run 7, for a grand total of four seconds. Using parallelism, you've thus cut the example problem's running time in half.
As mentioned, this kind of problem pops up in a lot of different software problem domains. Consider, for example, MSBuild. Microsoft .NET Framework–based projects frequently reference other .NET projects in the same solution, thus setting up a dependency between those two projects. For the .NET Framework 3.5, MSBuild started offering the /m switch, which uses the available processors in the machine to parallelize the build process, utilizing dependency information like the project references just mentioned.
In the rest of this column, I'll build a small DependencyManagement class to help solve such problems. Here's an outline of the public API:
public class DependencyManager
{
  public void AddOperation(
    int id, Action operation, params int [] dependencies);
  public event EventHandler<OperationCompletedEventArgs>
    OperationCompleted;
  public void Execute();
}
The main entry point into the type is the AddOperation method, which accepts a unique ID you provide to represent an operation, the delegate to be executed for that operation, and a set of dependencies upon whose completion this operation relies. If an operation has no dependencies, the parameter array will be empty.
The OperationCompleted event is raised any time one of the constituent operations completes, providing the ID of the operation as well as the starting and ending times of its execution.
And finally, the Execute method kicks off the process and waits for all of the operations to complete. While the DependencyManager class will be running operations in parallel, the API itself is not meant to be thread-safe, meaning that only one thread should be used to access AddOperation and Execute at a time.
This class allows me to express the previous example problem in the following fashion:
Action oneSecond = () => { ComputeForOneSecond(); };
DependencyManager dm = new DependencyManager();
dm.AddOperation(1, oneSecond);
dm.AddOperation(2, oneSecond);
dm.AddOperation(3, oneSecond);
dm.AddOperation(4, oneSecond, 1);
dm.AddOperation(5, oneSecond, 1, 2, 3);
dm.AddOperation(6, oneSecond, 3, 4);
dm.AddOperation(7, oneSecond, 5, 6);
dm.AddOperation(8, oneSecond, 5);
dm.Execute();
Internally, information about each registered operation is stored in an OperationData class:
private class OperationData {
  internal int Id;
  internal Action Operation;
  internal int [] Dependencies;
  internal ExecutionContext Context;
  internal int NumRemainingDependencies;
  internal DateTimeOffset Start, End;
}
The Id, Operation, and Dependencies fields store the corresponding data passed into the AddOperation method as parameters, and the Context field stores the ExecutionContext captured at the time AddOperation was called (for more information on why this is important, see my last few .NET Matters columns). Additionally, OperationData stores the number of remaining dependencies that need to be completed before it can run. Finally, it keeps track of the start and end time for this operation, and these will be reported to a consumer of DependencyManager when the OperationCompleted event is raised for this particular operation.
Two collections are used to maintain the set of operations added to the DependencyManager instance:
private Dictionary<int, OperationData> _operations  =
  new Dictionary<int, OperationData>();private Dictionary<int, List<int>> _dependenciesFromTo;
The former dictionary contains one entry for each added operation, and maps an operation's ID to its OperationData instance; this makes it fast and easy to look up the data for an operation given its ID. While that first dictionary does contain all of the information you need to do your work, it doesn't contain that information in a format that makes the work easy or efficient. The latter dictionary fixes this by providing a mapping from an operation's ID to all of the IDs of operations that directly depend on it. For instance, in the example problem shown earlier, the entry for ID 1 in this dictionary would map to a list containing IDs 4 and 5, since those two operations directly depend on ID 1 completing. This dictionary makes it quick and easy for a completing operation to send a completion notification to all of the other operations that depend on it.
The DependencyManager class contains three more private fields, in addition to the dictionaries:
private object _stateLock = new object();
private ManualResetEvent _doneEvent;
private int _remainingCount;
The _stateLock field is used during the asynchronous execution of the registered operations in order to protect shared state accessed by the processing of these operations, namely the dictionaries and the data they contain. The ManualResetEvent is simply used as a mechanism for the Execute method to wait for all operations to complete. The last operation to complete will set the event, allowing the Execute method to exit. An operation knows that it's the last to complete because all of the operations decrement the _remainingCount field when they complete. As such, if an operation decrements the value and finds that it's now zero, the operation knows it's the last one and can set the _doneEvent. (As an aside, this kind of countdown logic is commonly found in fork/join parallelism problems, and the new CountdownEvent in the .NET Framework 4.0 makes such problems easier to implement.)
The code for the AddOperation method is simple.
public void AddOperation(
    int id, Action operation, params int[] dependencies) {
  if (operation == null)
    throw new ArgumentNullException("operation");
  if (dependencies == null)
    throw new ArgumentNullException("dependencies");

  var data = new OperationData {
    Context = ExecutionContext.Capture(),
    Id = id, Operation = operation,
      Dependencies = dependencies
  };
  _operations.Add(id, data);
}
After verifying that the arguments are valid, the method captures all of the data into an instance of the OperationData class, and that instance gets stored into the dictionary tracking all operations.
After all of the operations have been added, you can run the Execute method, shown in Figure 2, to get the process going. At the beginning of the method, it sets up dependency information for the run, namely transposing the dependency information stored in each OperationData such that you can easily look up operations that have dependencies on a target operation given that target's ID.
Figure 2 Starting the Process
public void Execute() {
  // TODO: verification will go here later
  // Fill dependency data structures
  _dependenciesFromTo = new Dictionary<int, List<int>>();
  foreach (var op in _operations.Values) {
    op.NumRemainingDependencies = op.Dependencies.Length;

    foreach (var from in op.Dependencies) {
      List<int> toList;
      if (!_dependenciesFromTo.TryGetValue(from, out toList)) {
        toList = new List<int>();
        _dependenciesFromTo.Add(from, toList);
      }
      toList.Add(op.Id);
    }
  }

  // Launch and wait
  _remainingCount = _operations.Count;
  using (_doneEvent = new ManualResetEvent(false)) {
    lock (_stateLock) {
      foreach (var op in _operations.Values) {
        if (op.NumRemainingDependencies == 0)
          QueueOperation(op);
      }
    }
    _doneEvent.WaitOne();
  }
}

private void QueueOperation(OperationData data) {
  ThreadPool.UnsafeQueueUserWorkItem(state =>
    ProcessOperation((OperationData)state), data);
}
The rest of the method then works by finding all of the operations that have zero dependencies and queuing them up for execution to the .NET ThreadPool.
Previously, I noted that the Execute method and the AddOperation are not thread-safe with respect to each other, meaning that these methods are expected to be called sequentially, first using AddOperation to add all of the operations to execute, and then calling Execute. As a result, notice that AddOperation accesses the dictionaries without any locks or other mechanism for shared state synchronization. However, Execute does wrap part of its body in a lock. This is because once it's queued up the first work item to run, that work item may access and modify the dictionaries concurrently with the rest of the Execute body. To prevent such races from happening, the rest of the body of Execute is protected. When all relevant work has been queued, the Execute method blocks waiting for all of the work to complete.
QueueOperation simply queues the ProcessOperation method to the ThreadPool, and ProcessOperation runs the specified operation. This method is shown in Figure 3. The first portion of the method simply executes the delegate stored in the provided OperationData, doing so under the provided ExecutionContext (if one could be captured) and timing the run, storing the results back into the data structure for later reporting. (For more detailed timing information, System.Diagnostics.Stopwatch could be used instead of DateTimeOffset.)
Figure 3 Processing an Operation
private void ProcessOperation(OperationData data) {
  // Time and run the operation's delegate
  data.Start = DateTimeOffset.Now;
  if (data.Context != null) {
    ExecutionContext.Run(data.Context.CreateCopy(),
      op => ((OperationData)op).Operation(), data);
  }
  else data.Operation();
  data.End = DateTimeOffset.Now;

  // Raise the operation completed event
  OnOperationCompleted(data);

  // Signal to all that depend on this operation of its
  // completion, and potentially launch newly available
  lock (_stateLock)
{
    List<int> toList;
    if (_dependenciesFromTo.TryGetValue(data.Id, out toList)) {
      foreach (var targetId in toList) {
        OperationData targetData = _operations[targetId];
        if (--targetData.NumRemainingDependencies == 0)
          QueueOperation(targetData);
      }
    }
    _dependenciesFromTo.Remove(data.Id);

    if (--_remainingCount == 0) _doneEvent.Set();
  }
}

private void OnOperationCompleted(OperationData data) {
  var handler = OperationCompleted;
  if (handler != null)
    handler(this, new OperationCompletedEventArgs(
      data.Id, data.Start, data.End));
}

public class OperationCompletedEventArgs : EventArgs {
  internal OperationCompletedEventArgs(
    int id, DateTimeOffset start, DateTimeOffset end) {
    Id = id; Start = start; End = end;
  }
  public int Id { get; private set; }
  public DateTimeOffset Start { get; private set; }
  public DateTimeOffset End { get; private set; }
}
Once the operation has completed, you need to notify any dependent operations. Here's where the handy_dependenciesFromTo dictionary comes into play. You simply enumerate all of the operations that depend on this particular one, look up their OperationData instances, and decrement their NumRemainingDependencies by one. If their number of remaining dependences becomes zero, they're now eligible for execution, and QueueOperation is used to launch each eligible operation.
You can also do a little housecleaning: Now that the operation has completed, you won't need its entry in_dependenciesToFrom again, so you can remove it.
Finally, you notify the DependencyManager that one more operation has completed, potentially setting the_doneEvent (to wake up the Execute method) if it's the last operation.
No exception handling is shown in this implementation, but adding some could be important depending on how the class is used. As an example, if one of the OperationCompleted event handlers throws an exception, that exception will propagate out of OnOperationCompleted (which just raises the event), preventing any dependencies on this operation from being notified and likely hanging the system. To obtain a robust implementation, that would need to be addressed.
What you've seen until now represents the bulk of the implementation. However, there are still some interesting things that can be done. For example, the implementation assumes that all operations that are dependencies of other operations have been registered by the time Execute is called. If they're not, the relevant notifications of completion will never be raised and Execute will never return because some dependencies won't have been met and thus some operations won't ever run. To address this, you can implement a VerifyThatAllOperationsHaveBeenRegistered method that will catch such misuse and place a call to it at the beginning of the Execute method:
private void VerifyThatAllOperationsHaveBeenRegistered() {
  foreach (var op in _operations.Values) {
    foreach (var dependency in op.Dependencies) {
      if (!_operations.ContainsKey(dependency)) {
        throw new InvalidOperationException(
          "Missing operation: " + dependency);
      }
    }
  }
}
Similarly, you can verify that there are in fact no cycles in the graph. If there were cycles, the Execute method would never complete because some dependencies would remain unsatisfied. For example, imagine that you erroneously input that component 2 depended on component 8. This would cause a cycle (2 => 5 => 8 => 2) that would prevent components 2, 5, 7, and 8 from executing. You can detect such cycles with a method VerifyThereAreNoCycles, again placing a call to this method at the beginning of Execute (after VerifyThatAllOperationsHaveBeenRegistered).
There are several appropriate algorithms for finding cycles in a graph. One is to do a depth-first search on the graph from every entry node in the graph (in the case of this article, that's an operation that has no dependencies, such as components 1, 2, and 3 in my example). As you do a depth-first search, you mark a node when you visit it. If you visit a node that's already been marked, you've found a cycle.
Another solution is based on the topological sort mentioned at the beginning of this column. If the topological sort fails, the graph has a cycle. Since having a topological sort is also useful in general (for example, if you wanted to optionally use DependencyManager to execute sequentially), I've chosen that approach.
Figure 4 shows the implementation of a CreateTopologicalSort method, which returns a partially ordered list of operation IDs. (The code also shows the VerifyThereAreNoCycles method, which simply calls CreateTopologicalSort and throws an exception if the method returned null, indicating that the sort failed.) The first thing to do is convert the operations dictionary into temporary dictionary data structures for the sort operation. These temporary dictionaries map in concept to the dictionaries you saw earlier. In fact, dependenciesToFrom maps an operation ID to the IDs of all of the operations it depends on (inbound edges). In contrast, dependenciesFromTo maps an operation ID to the IDs of all of the operations that depend on it (outbound edges). As the algorithm runs, you'll slowly pare down the contents of these dictionaries until, hopefully, there's nothing left.
Figure 4 Topological Sorting and Cycle Detection
private void VerifyThereAreNoCycles() {
  if (CreateTopologicalSort() == null)
    throw new InvalidOperationException("Cycle detected");
}

private List<int> CreateTopologicalSort() {
  // Build up the dependencies graph
  var dependenciesToFrom = new Dictionary<int, List<int>>();
  var dependenciesFromTo = new Dictionary<int, List<int>>();
  foreach (var op in _operations.Values) {
    // Note that op.Id depends on each of op.Dependencies
    dependenciesToFrom.Add(op.Id, new List<int>(op.Dependencies));

    // Note that each of op.Dependencies is relied on by op.Id
    foreach (var depId in op.Dependencies) {
      List<int> ids;
      if (!dependenciesFromTo.TryGetValue(depId, out ids)) {
        ids = new List<int>();
        dependenciesFromTo.Add(depId, ids);
      }
      ids.Add(op.Id);
    }
  }

  // Create the sorted list
  var overallPartialOrderingIds = new List<int>(dependenciesToFrom.Count);
  var thisIterationIds = new List<int>(dependenciesToFrom.Count);
  while (dependenciesToFrom.Count > 0) {
    thisIterationIds.Clear();
    foreach (var item in dependenciesToFrom) {
      // If an item has zero input operations, remove it.
      if (item.Value.Count == 0) {
        thisIterationIds.Add(item.Key);

        // Remove all outbound edges
        List<int> depIds;
        if (dependenciesFromTo.TryGetValue(item.Key, out depIds)) {
          foreach (var depId in depIds)
{
            dependenciesToFrom[depId].Remove(item.Key);
          }
        }
      }
    }

    // If nothing was found to remove, there's no valid sort.
    if (thisIterationIds.Count == 0) return null;

    // Remove the found items from the dictionary and
    // add them to the overall ordering
    foreach (var id in thisIterationIds) dependenciesToFrom.Remove(id);
    overallPartialOrderingIds.AddRange(thisIterationIds);
  }

  return overallPartialOrderingIds;
}
Once those dictionaries are filled, you start running the algorithm. The idea is that you cull from the graph all nodes that have zero inbound edges—in the context of this article, that means operations that have no dependencies on other operations. When you find such operations, you add them to the end of the sorted results (the order in which you add them to the end doesn't matter, hence the "partial ordering" nomenclature), and you remove them from the graph. You also need to remove all outbound edges from these operations, which you can easily find using the dependenciesFromTo dictionary. You do this process over and over until the graph contains zero nodes, at which point the algorithm is complete and you return the ordering you built up. If, however, you get to a point where all of the nodes in the graph have inbound edges, the graph contained a cycle, and there's nothing more you can do.
With that, the implementation is complete. Toward the beginning of this column, I showed the code that could be used with the DependencyManager class to run the sample problem I've been referring to throughout. If you'll remember, I suggested you could get the running time down to four seconds. Indeed, when I run that sample code on my laptop, I get timings that hover within a few milliseconds of four seconds.
This is partially luck, however. The hypothetical environment I postulated included a machine with an infinite number of cores. My laptop, unfortunately, is not configured as such, and is instead limited to just two cores. However, given the right ordering, the problem can still execute in four seconds with just two processing units. If operations 1 and 2 start running, then a second later 3 and 4 can start running, then a second later 5 and 6 can start running, and a second later 7 and 8 can start running.
But what happens if operations 2 and 3 happen to run first instead of operations 1 and 2? This is certainly possible, given that all of operations 1, 2, and 3 have no dependencies. If operations 2 and 3 run first, then in the next iteration operations 1 and 5 will be available to run. After they go, operations 4 and 8 will be able to go. But on the next iteration, only operation 6 will be available, since operation 7 depends on the completion of operation 6, and thus the entire computation will take approximately five seconds rather than four.
In my sample application, when I changed the order in which I called AddOperation to first register operations 3 and 2, the output time confirmed this issue, with a running time of just over five seconds. If as a developer you have a priori knowledge about how long each operation will take, you can use that to construct a better ordering for how operations are launched. That's left as an exercise for you.
There are of course many other interesting things you could build off of this implementation, using it as a starting point. For operations with no dependencies, you may want those to be able to start running as soon as they're added to the DependencyManager, rather than having to wait until Execute is called. You might want to be able to execute the DependencyManager asynchronously and later wait on its results, or alternatively do something else when it completes. You may want to be able to build up graphs of DependencyManagers. You may want operations to be able to return data that is passed along to dependencies, hence building up large dataflow networks. And so on. There are many interesting and useful possibilities. Enjoy!

Send your questions and comments for .NET Matters to netqa@microsoft.com.

Stephen Toub is a Senior Program Manager Lead on the Parallel Computing Platform team at Microsoft. He is also a Contributing Editor for MSDN Magazine.


Usability in Practice
The Power of Personas
Dr. Charles B. Kreitzberg and Ambrose Little
Contents
The Cognitive View
How to Create Personas
Why Personas Work so Well
Types of Inferences Personas Support
How Many Personas?
Connecting Personas to Screens
What Goes into a Persona
The Software View
Empathy
Clarifying What to Do and In What Order
Clarifying How to Do It
Communication
Shortcuts to Personas
Summary

THE COGNITIVE VIEW
Dr. Charles B. Kreitzberg
If you are designing a UI, you should consider creating personas to guide you. Personas are one of the basic tools of User Experience (UX) design. A persona is a description of a fictional person representing a user segment of the software you are developing. Of course, the word "fictional" applies to the person not the description; that should be as grounded in reality as possible.
Figure 1 shows an example of a simple persona developed for a financial institution. Bill (and his wife Sue) are fictitious composites developed from interviews conducted with the bank's customers. The interviews and other studies revealed that the bank's customers fell into a number of audience segments, each with its own goals, concerns and Internet usage habits. By creating a persona to represent the segment, it becomes easier to formulate design questions and answer them.
Persona creation is not an exact science and it can be difficult to verify how well a persona actually reflects the users. The fact that personas are created through an act of fiction has led some people to question their value entirely. Such criticism is valuable if it serves as a reminder that the personas are built from data that is, by its nature, incomplete and imperfect. But personas are nevertheless quite useful. Among their benefits, personas:
  • Enable designers to make inferences about the needs and desires of audience segments.
  • Serve to communicate user characteristics in a compact and easily understood way.
  • Help keep stakeholders from changing the definition of audience segments to advance narrow interests.
  • Put a face on the person for whom you are designing the UI.
Figure 1 A Simple Persona

How to Create Personas
Like most design elements, personas can be developed iteratively. And like most design elements, there are benefits to creating the personas collaboratively. Involving the stakeholders and other team members increases the accuracy of the persona and creates a level of awareness about the users that helps the team align around them. As people become familiar with the personas, they start talking about them as if they were actual people. When that happens, you have achieved a valuable focus.
Personas do not need to be complex to be useful. I typically begin by creating brief outlines of personas based on conversations with people who know the audience well, such as salespeople or customer service staff. I call these personas "assumptive personas" because they are not based on actual data.
Sometimes, that's all I have time or resources to do. But a better practice is to interview users and use the data collected to validate and refine the personas. In some cases, organizations perform extensive data gathering and analysis, using a variety of ethnographic research techniques, to create highly refined personas.
It's great to have really well researched personas, but even if you can whip together only a few simple assumptive personas, you will find that they are really useful design tools.
An excellent resource to help you understand personas and their construction is the book The Persona Lifecycle: Keeping People in Mind Throughout Product Design by John Pruitt and Tamara Adlin (Morgan Kaufmann, 2006).

Why Personas Work so Well
Personas tap into a fundamental human skill—the ability to make predictions about how other people will react based on mental models of them. One can often predict accurately how a close friend or family member will react to a particular event and decide how to act based on those inferences.
With close friends and family one has the history of experiences that make mental models rich and (usually) accurate. But one is also capable of making inferences about people based on relatively little data. Just looking at someone's attitude or posture as they walk can convince you to cross the street.
Of course, assumptions about how people are going to behave in a particular situation may not be correct and you often make errors of inference. Nonetheless, the ability to reliably predict the behavior of others is essential to survival, and humans are cognitively well-equipped to do so. That's what makes the persona so powerful. When you create models of your audience, you are able to make inferences about how they will react to the design choices you make.

Types of Inferences Personas Support
There are a number of ways that you can use personas to facilitate the design process. You can use them to:
  • Help you choose among multiple design alternatives, selecting the one that your target user is most likely to prefer
  • Help set the priorities for features under consideration, discriminating between what the user needs and what is a nice to have
  • Decide what will engage a user
  • Decide what will offend or cause distrust
  • Determine if a single UI will serve all users or if you need to create multiple UIs
Of course, whenever possible, you should verify the design decisions you make through usability testing or other direct interaction with the user.

How Many Personas?
Most interactive products have multiple audience segments. This suggests that you should construct multiple personas. However, with too many personas, the process can get out of hand. As a rule of thumb, three or four personas are enough for most projects. If you find that you are creating more than five or six, stop and reconsider.
Many experts feel that you should designate one persona as the primary persona and treat the others as secondary. Design decisions would be made with the primary persona in mind and then tested (through a thought experiment) against the secondary personas. You can then add additional design to address any unmet needs of secondary personas. If you are unable to reconcile the primary and secondary personas, it might suggest that you need to consider distinct UIs.

Connecting Personas to Screens
The interaction between a user and an interactive product is governed by the intersection of two models. The first is the design model of the UI, which includes the navigation, interaction design, and information architecture. The second is the mental model the user brings to the interaction. Within the user's mental model is his or her knowledge of the system, of computing in general, and of the subject matter addressed by the product.
Every interaction begins with a goal on the part of the user. The user looks at the screen to determine what actions are possible, and selects the action that will get him or her closer to the desired goal. To the extent that the persona helps you understand the user's mental model, it can be an effective tool to guide design.
For each screen, you can enumerate the goals that your user might have when arriving there. You can then ask whether the design contains all the information that the user needs to process the available options and make the correct choice of action. If the answer is no, then you have a usability problem that requires redesign.

What Goes into a Persona
Many people feel that it is important for the persona to be rich with personal information that may not, at first, seem relevant to the product under development. The value of this, they argue, is that a rich persona enables you to tell stories about the user and this process makes the persona more valuable.
There is truth to this contention but you still need to decide what to include and what to leave out of the persona. A great tool is the Persona Creation and Usage Toolkit developed by George Olsen which you can download at Interaction by Design.
OIsen has developed a comprehensive—perhaps even daunting—list of all the factors you might consider including in your persona description. It's far too extensive to use as a whole, but I've found it to be an excellent starting point for thinking through the process.
Generally, I include the following elements in persona descriptions:
  • Persona name and photo
  • A quote or slogan that captures the personality
  • Demographics (gender, age, marital status, family, where the person lives)
  • Education
  • Work
  • Lifestyle factors and goals
  • Computer competence and usage
  • Values and attitudes
With these as a base, I try to include elements that make sense in the context of the product being developed. So, for example, if I am working on a banking system, I might include financial assets, financial sophistication, major expenses, attitudes toward money, and so forth. Less obviously, I might also consider issues of trust, how the person regards financial institutions, where he or she gets advice and similar emotional or attitudinal factors that might affect the design.
With the basic persona in place, I try to enrich it with personal elements such as likes and pet peeves. If I am doing interviews, I will often ask the respondents what TV shows they like, what magazines they read, and other personal data that helps flesh out the story.
Personas are powerful tools. They may seem too unscientific to some, but they help package user data into a form that can keep the team and stakeholders in alignment while supporting the design process.

THE SOFTWARE VIEW
Ambrose Little
There's a lot of value in just creating personas, assuming you get the right people involved in the process. In fact, it has been suggested that this process of building a persona provides the main value to organizations; however, that does not mean that personas are not valuable beyond the creation phase—you just have to know how and when to use them.
Most developers, if they are familiar with the concept of personas, picked it up from Alan Cooper's The Inmates Are Running the Asylum (Sams—Pearson Educatio, 2004). Cooper is by and large responsible for creating and popularizing the methodology of personas, as such, in software development, and in an interview he calls them the "bright light under which we do design… a powerful, malleable tool to help you look through the eyes of your users," which is as good a description as any I've seen.
In asking how to use personas, it is useful to also consider how not to use them. In their paper, "Quantitative Evaluation of Personas as Information," Christopher N. Chapman et al make the case that personas are not a valid source of actual information about real users. Their demonstration, based on generating persona-like substances from a database of real-life customer attributes, shows an extremely low correspondence in the generated persona-like substances to their source material (in that essentially none of them matched any one of the source customer attribute records). This is good as a sort of quantitative warning—don't be deceived into thinking your personas are real individuals, don't let them substitute for cases where you truly need to have some kind of quantitative input to inform your solutions. (See "Death to Personas! Long Live Personas!.") Don't use personas as substitutes for real data when you need real data—they are a derivative design asset, not actual customer data.
For example, if you needed to make a decision in your product or project as to what operating systems to support, you probably would not want to rely on a persona to inform that decision. Instead, you look at your customer data that tells you what percentage of your target customer base uses which of the various operating systems and make a decision based on the hard data. A persona might capture the use preference for an OS, but it is much better to base such quantitatively informed decisions on quantitative data, if you have it.
Personas are far more useful as qualitative tools that give you persistent insight into how you design solutions as well as what goes into your solutions. Donald Norman, one of the most well known human-centered design gurus, put it this way: "[personas] only need to be realistic, not real, not necessarily even accurate (as long as they accurately characterize the user base)." He identifies two core uses of personas: for communication and for empathy, which seems pretty spot on to me. (See "Ad-Hoc Personas & Empathetic Focus.")

Empathy is about as squishy as it gets and probably seems a bit foreign if you are accustomed to thinking in terms of functional requirements, but empathy is a core value if you want to make something that is good for the people who are going to use it. It's all about putting yourself metaphorically in their shoes.
If you're thinking about what functionality to include, personas can help. They can also help you prioritize the features. If you're thinking about how your target audience would want to achieve a particular goal or task, personas can be an indispensible tool. Even on discrete interfaces, you can use personas to help you both imagine how they should be designed as well as double-check your design against what your personas would want.

Clarifying What to Do and In What Order
A concrete way to include personas in your process is to have your stakeholders prioritize your personas and use that to create a weighted prioritization of capabilities in your solution, as Figure 2 shows.
Figure 2 Prioritizing Features
Capability | Elizabeth | Miranda | Tom | Overall
View Item | 2 | 1 | 2 | 10
Place Order | 0 | 2 | 1 | 4
Weighting: Elizabeth – 3 | Miranda – 1 | Tom - 2
Scale: 2 – Must Have | 1 – Like to Have | 0 – Doesn't Need/Care
This simple table illustrates that the View Item capability is far more important to the solution than the Place Order—from the target audience's perspective. The weightings were established beforehand, probably through the input of marketing, sales, and product management (the business stakeholders). It is important to note that this is not the full picture in prioritizing; the needs and goals of the business itself are not represented.
For instance, it is highly likely that the Place Order capability must be implemented for it to be a viable solution for the company to fund. Both the needs of the business and those of the user should be balanced to create a harmonious solution. (And if you can't find harmony, the solution probably won't be successful, which further illustrates the value of personas in simply validating whether or not to pursue solution ideas.)
The core idea here is that you are using personas to consistently think through and validate the various aspects of the development cycle from the perspective of your target audience. To come to the understanding that Elizabeth values viewing items as a must-have, you have to actually put yourself in her shoes and think about how much she would value that capability. This is far superior to a business analyst, project manager, or even developer generically trying to put a value on the capability using the same scale (which I've observed many times in my career). And it can be used to prioritize bug fixes as well, which again would likely be far more realistic prioritization than a general sense of urgency or severity.

Clarifying How to Do It
Another example of how personas can be used is to think through how a persona might want to use the software. This is especially useful if you are doing something that is new or trying to improve an existing solution or, of course, trying to differentiate based on UX. In fact, even before you get to prioritizing, personas can help you to correctly formulate what to build—instead of starting from a list of competitive features, functional requirements, formal use cases, and the like (or if you already have those, it's not too late; they can be reformulated in a similar way), you start by reframing the question of what to build in terms of the goals and motivations of your personas.
These are two key aspects of personas—they both do more than individual attributes and preferences to help you really gain empathetic insight. If you can stop and ask yourself why the person would want to do something with your solution and what they are trying to achieve, it goes a long way toward the proper focus.
Similarly, if you find yourself in trouble, which happened to me recently, where you have tons of prickly issues poking out of your design, it may just be that you need to zoom out and attack the problem anew from your persona's perspective. Sometimes it's hard to break old ways of thinking about design, and using personas can help you reformulate your approach. In my case, doing this helped me to see that we needed to somewhat dramatically alter our approach in terms of presenting essentially the same functionality to our target audience.
The trick here is not so much using some formula or technique but rather in changing how you formulate your understanding of how to build what you need to build.

Communication
Unless you are the sole individual involved in the creation of your solution, then personas can be a great tool to further refine a common language and understanding of what it is you're going about. One of the core ideas in domain-driven design is the ubiquitous language, and personas can help you better understand both the domain and the language that those in the domain use in order to help get everyone on the same page.
The research that goes into forming personas usually happens early in the process—people are busy and can spare only so much time to provide input in the form of interviews, and so forth. The real people are not avilable later on, but the personas are always available everywhere they need to be.
In short, they are about the best stand-in you can get when talking to real people isn't an option, and sometimes they can be better because they are not susceptible to moods or quirky, unrepresentative opinions (prejudices) that might wrongly skew the answer. Of course, that doesn't make them better all the time, either, since they rely on your interpretation of what the answer would be.
In fact, the need for interpretation can be a good thing. It can stimulate more critical thinking to dialectically come to an agreement on what to do or how to do it. This probably would not occur if the team were relying on an individual who is the undisputed representative of the customer.
And even in cases where the team members are committed to human-centered design, personas can help explain what might otherwise appear to be dictatorial specifications. I've seen this happen more than once, where a design specification was questioned because it didn't make sense to some people on the team. They were looking at it from their own, seemingly intuitive perspective, but the solution wasn't being built for them. The personas provide a known, concrete reference point to explain why the spec is the way it is, which takes the focus of the discussion away from what makes sense to individual team members (or what they prefer) to what makes sense for the people you are building for. And sometimes, the questioning of a requirement or spec comes from the perspective of a persona, and again, that dialectic based on differing interpretations will lead to a better solution than either individual would have proposed on their own.
Figure 3 Persona-based Story
A concrete example of how you can use personas to communicate is via scenarios and stories. "Scenarios" is a pretty overloaded term, so let me be clear on my meaning. A scenario is a descriptive narrative of one or more coherent interactions between a person (preferably a persona) and a product in a specified context from which one can derive design implications. Scenarios focus on how a person experiences the software without specifying the design in detail; that is, they provide the relevant human-oriented perceptions and actions for how a design should work. This is as opposed to what I'd call a "story," which is an overarching, coherent narrative that provides the background for scenarios, with particular focus on needs, goals, and desires. Stories provide more of the why—the human motivations.
You'd start with a story, based on your persona, and then break that out into scenarios, which can directly be used to design your solution and then to verify and validate your design. It can map more or less to goals and interactions/tasks/activities, where the goal provides the context and motivating factor for the story, and the scenarios map more or less to the particular interactions. Figure 3 shows an example of a story in a hypothetical solution.
This is a screen shot from a tool called Scrivener, which has a nifty index card view of document sections. I use that view for these purposes to keep the stories and scenarios short and to the point—they should be concise because busy people need to read and use them. Figure 4 shows some possible scenarios in this overall story.
Figure 4 Persona-based Scenarios
These scenarios cover discrete but coherent interactions from the persona's perspective (Sandra's). The story is a known, based on a real goal that the persona has. The scenarios are where your imagination comes into play—how would Sandra expect to be able to achieve her goal with the solution is the question, and the answer is described without specifying anything more than a narrative of what Sandra does. You see the story carried through from one scenario to the other, and yet you could conceive of these interactions on their own—a starting point, some interaction, and a coherent end point that can be the basis for further action.
Notice that these scenarios are careful not to specify how the interactions materialize in the UI. The reason for this is twofold: first, you don't want to prematurely constrain your UI design—you should be open to iterating over several possible UI solutions to support the interactions (as you should be open to iterating the scenarios themselves), and second, it is far more efficient and effective to design the UI in terms of the UI (with wireframes, mockups, prototypes, and so on.).
You can imagine that the same story and scenarios could be derived simply from user research or from a detailed set of functional or business requirements. You can adapt where such scenarios fit based on your processes, but the key is that they help you to think through how best to design your solution with minimal investment.

Shortcuts to Personas
Figure 5 Persona Shortcuts (Images Blurred Intentionally)
Finally, one aspect of communication, as Charlie covered, is how to communicate the personas themselves. There are many neat ways, and depending on your background, it may take some overcoming of prejudices, i.e., having posters, cards, cardboard cutouts, action figures, and other real, physical objects can very probably be more effective to communicate them and keep them top of mind than, e.g., a digital version like a Word doc or PowerPoint presentation that just sits out on SharePoint. Devs tend to want a technology solution for everything, but with design, including personas, it is often best to prefer a non-technical solution.
However, even if you have these physical artifacts, many folks work in multiple environments (in a coffee shop, at home, wherever) so that you don't always have those around. In such cases, having a backup digital copy can help, and I would suggest keeping a referent to them on your desktop, as shown in Figure 5.
This has the dual benefit of both providing a ready link to reference a digital persona document as well as keeping the personas themselves (image and name) top of mind. It's easy to do, too—just make a shortcut and change the icon to a cropped headshot of your personas. Just a simple way to make personas more usable if you are a traveling type.

Summary
In this installment, we took somewhat detailed tour of personas. First, we covered how to make them—the processes and techniques involved in developing, validating, and maturing the personas themselves, which has a big benefit to the whole team involved in getting a much better understanding of whom the solution is being developed for.
Then we discussed some different uses of personas, how not to use them, as well as how to—chiefly to gain empathy to inform what and how you build so that it makes sense for your target audience as well as a valuable communication tool to keep team members on the same page, speaking the same language, and collaborating in terms of people rather than in terms of technical or hierarchical terms.
For more persona information, see Persona Resources on GUIUI.com and Example Tester Personas on MSDN.

Send your questions and comments for Charlie and Ambrose to magux@microsoft.com.

Dr. Charles Kreitzberg is CEO of Cognetics Corporation (www.cognetics.com), which offers usability consulting and user experience design services. His passion is creating intuitive interfaces that engage and delight users while supporting the product's business goals. Charles lives in Central New Jersey where he moonlights as a performing musician.

Ambrose Little lives with his wife and four children in central New Jersey. He's been designing and developing software for more than 10 years and is honored to be an INETA speaker and Microsoft MVP. Lately, he's shifted from technical design to designing for people and is now a user experience designer for Infragistics.


{ End Bracket }
Translate This Page
Sandor Maurice & Vikram Dendi
Microsoft translation services have been upgraded with the release of a number of translation Web service APIs and tools, along with new of ways to access the service via REST, SOAP, and AJAX APIs, so that you can easily integrate translation into your Web site.
From our widget adoption portal at microsofttranslator.com, you can customize the behavior and appearance of the new translation widget to fit your content, and using a short HTML snippet, have the translation widget appear alongside your existing content.
When invoked, the widget leverages our AJAX API to progressively translate your page's content, in place, without taking the user to a different site. Users can choose from among several viewing options: inline translation with original text tooltips, original text with translated text tooltips, or both, side by side.
Users may also opt for automatic translation, causing all pages they visit that contain the widget to be translated automatically. All user settings are persisted across any site that contains the widget.
Figure 1 Microsoft Translator
For more advanced scenarios in which the widget may not be suitable, you can access the underlying AJAX API that provides complete control over translation triggers and content to be translated. To integrate the AJAX API, simply copy and paste a small HTML snippet from the AJAX API SDK into your HTML. In this case the snippet does not expose any visible content on the site but rather just loads our AJAX API into the browser. You can then invoke the various JavaScript functions supported by our API. For example, in order to translate a specific Document Object Model (DOM) element with an ID of "myElem" from English to Spanish, you would call
Microsoft.Translator.translate(document.getElementById("myElem"), "en", "es");
In order to translate the body of the entire document, one would call
Microsoft.Translator.translate(document.body, "en", "es");
You can programmatically access all the same options that the widget exposes to users. For example, you can create a side-by-side translation on a specific DOM element, call
Microsoft.Translator.setOptions({ "layout": "ss"});
Microsoft.Translator.translate("myElem");
Note that when no language arguments are provided, the API determines the original (source) language by first checking the DOM hierarchy for any HTML lang attributes. Failing that, it falls back to automatic language identification technology. The translation (target) language is determined by the browser accept-language settings of the user, and if no appropriate translation language is supported the API gracefully degrades to a reasonable default. A complete list of supported option names and their respective values can be obtained by calling
Microsoft.Translator.getAllOptions();
You may also control translation behavior declaratively. In addition to a standard HTML lang attribute, elements can be identified as being unsuitable for translation with a translate="no" attribute, in which case the API simply skips over them.
As you will see when you give it a try, the new translation services features let you tailor your content to your users easily and conveniently.
For more information on what we've been up to, read Vikram's installment of End Bracket in the January 2009 issue, "The Emergence Of Machine Translation."

Sandor Maurice is a developer on the Microsoft Translator team. He is responsible for developing the AJAX API and widget.

Vikram Dendi is a Senior Product Manager on the Microsoft Translator team. He is responsible for business strategy and product planning and is working toward empowering developers to help build a Web without walls. He blogs at viks.org and at blogs.msdn.com/translation.