June 2008 June 2008
SAAS: Connect Enterprise Apps with Hosted BizTalk Services
In this article we introduce you to BizTalk Services, new technology that offers the Enterprise Service Bus features of BizTalk Server as a hosted service. Jon Flanders and Aaron Skonnard
Concurrency: Tools And Techniques to Identify Concurrency Issues
Efficient parallel applications aren’t born by merely running an old app on a parallel processor machine. Tuning needs to be done if you’re to gain maximum benefit. Rahul V. Patil and Boby George
Robotics: Simulating the World with Microsoft Robotics Studio
Microsoft Robotics Studio is not just for playing with robots. It also allows you to build service-based applications for a wide range of hardware devices. Sara Morgan
Form Filler: Build Workflows to Capture Data and Create Documents
Learn how to create a workflow that uses InfoPath forms and other office documents for passing data to targeted activities and for use in Office documents. Rick Spiewak
GUI Library: Bring the Simplicity of Windows Forms to Native Apps
In this article, author John Torjo presents a guide to his C++ GUI library called eGUI++ and explains how it makes user interface programming easier. John Torjo
Columns
Editor's Note: In Case You Hadn’t Noticed …: Find out what's new for MSDN Magazine, including a print redesign and the introduction of virtual labs on our web site so you can experiment with our code.Howard Dierking | Toolbox: Cross Browser Testing, Mock Objects, and Raymond Chen: This month test your web site on many platforms and browsers without setting up a test environment, use mock objects for unit testing, and visit Raymond Chen.Scott Mitchell | CLR Inside Out: Large Object Heap Uncovered: This month CLR Inside Out reveals the secrets behind the Large Object Heap—what’s there, when it’s released, how the garbage collector handles the objects there.Maoni Stephens
Cutting Edge: ASP.NET AJAX and Client-side Templates.: AJAX is meant to go beyond mere partial page rendering. Find out where Dino Esposito thinks dynamic pages are headed in the future with ASP.NET AJAX.Dino Esposito | Patterns in Practice: The Open Closed Principle: Extending an existing codebase can be as productive and frustration-free as writing all new code when you employ the Open Closed Principle. We'll show you how.Jeremy Miller | Service Station: Building a WCF Router, Part 2.: Here we present a deep look into the workings of Windows Communication Foundation routers, exploring the details of pass-through router implementations.Michele Leroux Bustamante
Foundations: Bitmaps and Pixel Bits: Charles Petzold takes an inside look at the flexible bitmap pixel formats offered by the retained-mode graphics features of Windows Presentation Foundation.Charles Petzold | Windows With C++: Decoding Windows Vista Icons with WIC: In this month's installment, Kenny Kerr sings the praises of the new Visual C++ 2008 Feature Pack, which brings modern conveniences to Visual C++.Kenny Kerr | Concurrent Affairs: Simplified APM with the AsyncEnumerator: Here Jeffrey Richter introduces his AsyncEnumerator class, which drives an iterator so that different thread pool threads can execute the same code at different times.Jeffrey Richter
Going Places: Adaptable Apps for Windows Mobile.: We show you the techniques for building adaptable applications that can make the best use of different screens and capabilities on Windows Mobile devices.Michael Saffitz | { End Bracket }: Election Results Even Voters Can Trust: Surprisingly, cryptography can be applied to the electoral process to allow every individual voter to check the integrity of an election tally. Find out how here.Josh Benaloh


SAAS
Connect Enterprise Apps With Hosted BizTalk Services
Jon Flanders and Aaron Skonnard

This article is based on a prerelease version of BizTalk Services. All information herein is subject to change.
This article discusses:
  • BizTalk Services as an ESB service
  • WCF apps on BizTalk Services
  • Relayed connectivity options
  • Identity services and token providers
 This article uses the following technologies:
BizTalk Services, .NET Framework 3.0
Contents
Software as a Service
Internet Service Bus
BizTalk Services
BizTalk Services SDK
A Typical WCF Application
Relayed Connectivity Options
Passing through Firewalls with RelayedHttp
Configuring the Identity Services
Custom Token Providers
How to Get Started
Today, more than ever before, businesses require the ability to quickly develop, deploy, and integrate new applications into their existing environments. This growing need for dynamic, loosely coupled applications is one of the primary reasons why many businesses have moved or are currently moving toward Service-Oriented Architecture (SOA) as the new foundation for their applications.
As companies move toward SOA, there is a stronger focus on composing systems from the various applications found throughout the enterprise. In this new world, it's the developer's job to orchestrate business processes from these various application services that are made available on the network by other teams and organizations, who may be using different implementation technologies or line-of-business applications, thereby increasing the overall system complexity. Although SOA simplifies each point-to-point connection, composite applications can become unwieldy to manage and somewhat brittle as the total number of service connections required by the application increases over time (see Figure 1).
Figure 1 Managing Point-to-Point Connections in Composite Applications
This reality has led many companies to embrace a more loosely coupled and sustainable service pattern commonly referred to as the Enterprise Service Bus (ESB). The ESB model has grown in popularity because it helps enterprises manage multiple service connections through a central bus that provides an abstraction layer over the underlying messaging details. For example, an ESB helps broker differences across services in terms of naming convention, identity management, message formats, and communication protocols. Once a service gets on the bus, anything else on the bus can connect to it, even if it wouldn't normally be able to communicate with the service directly (see Figure 2).
Figure 2 Building Composite Applications with an ESB
This model introduces a level of indirection between the various services on the bus and between composite applications and the services they consume. ESBs also provide various messaging features including publish/subscribe functionality, which provides for looser coupling throughout the system. With publish/subscribe, consumers no longer have to be directly connected to services anymore—everything just needs a connection to the bus—and nodes can be added or removed at will. ESBs usually also provide a process flow engine for orchestrating the messaging interactions that make up a business process—this layer is often referred to as orchestration or workflow.
One way to build systems that employ the ESB pattern on the Microsoft platform is to use BizTalk® Server. BizTalk Server provides all of the ESB features we've discussed here out of the box.

Software as a Service
While ESBs have been growing in popularity within the enterprise, another business trend has also been blossoming on the Web that will surely impact enterprise systems in the years ahead. This trend, referred to as Software as a Service (SaaS), revolves around companies exposing complete applications or services on the Web—sometimes referred to as the Internet cloud—that other companies can simply pay to use. This allows consumers to avoid the complexities and costs associated with building or managing a similar piece of software (design, development, operational, and maintenance costs), which usually require large initial investments.
The SaaS model essentially allows consumers to remotely access software hosted by another company with expertise in a particular area (such as CRM, accounting, payroll, data storage, e-mail, and so on), as illustrated in Figure 3. With SaaS, the provider usually offers a complete solution for a particular software need, allowing the consumer to outsource that particular part of the system. The service provider manages the software over time and simply charges the consumer for usage, which means the consumer no longer has to manage those software services locally.
Figure 3 Outsource Software Needs with SaaS
The applications or services offered by SaaS providers typically embrace standard Web protocols and data formats in order to increase their ease-of-use and potential reach. Today they tend to rely heavily on HTTP and on common Web data formats like XML, RSS, and JSON, which are ubiquitous today. Although SaaS does not constrain a provider to these specific choices, reach requirements often force providers in that direction.
Some architects may question how smart it is to take on the external dependencies that are inherent in an SaaS system architecture. Although they might raise concerns around connectivity and service level agreements (SLA), with the ubiquity of Internet connections today, it seems that exposing software on the Web has almost become completely acceptable and even extremely advantageous given the new doors it opens.

Internet Service Bus
Microsoft has embraced these popular ideas—ESB and SaaS—and has blended their most compelling characteristics into a new idea it calls the Internet Service Bus (ISB). The ISB model is similar to ESB in terms of functionality. However, ISB is made available at the broader Internet scope, so it's similar to the SaaS model in terms of standards, reach, and scalability. The Microsoft® ISB, in a nutshell, makes it easier for companies to adopt ESB infrastructure.
Although ESB functionality is compelling to a wide range of companies, it seems that only larger companies have significantly taken advantage of them today. This is mostly due to the upfront investment and financial risk associated with adopting a significant piece of infrastructure like an ESB. Instead, many companies end up creating their own custom—and often more costly—systems integration infrastructure. This happens to be one of the biggest impediments to BizTalk Server adoption today.
Further, companies able to implement an ESB are still challenged with trying to make their ESB talk to their partners' ESBs. No two ESB instances are alike, making cross-enterprise integration difficult, even when embracing the loosely coupled ESB pattern.
The Microsoft ISB platform addresses these realities by placing key service bus components in the Internet cloud for public consumption regardless of the platform using the components. Microsoft is essentially making the service bus available through the SaaS model, thereby allowing companies of any size to jump on the bus. ISB offers a publish/subscribe architecture and the necessary messaging infrastructure for traversing enterprise firewalls and network address translators (NATs). ISB also offers federated identity management and a workflow services layer for hosting custom business processes on the Web, as illustrated in Figure 4.
Figure 4 Building on the New Internet Service Bus
Microsoft is actively working on making ISB a reality, and you can follow its work on the BizTalk Services Web site (see labs.biztalk.net). The current Community Technology Preview (CTP) offers several fundamental services that you can begin experimenting with today. In the years ahead, Microsoft plans for this initiative to blossom into a rich communication fabric capable of providing powerful building blocks for a wide variety of modern connected applications.
However, it's important to remember that, as a CTP, the bits made available today are only meant for experimentation and gathering feedback—they are not meant for production use. Microsoft provides no quality guarantees at this point. Also, Microsoft has not yet announced how it will charge for ISB usage once it's ready for production use.

BizTalk Services
BizTalk Services is the initial implementation of the ISB components that reside on the Web. Today BizTalk Services consists of a few core services including BizTalk Connectivity Services and BizTalk Identity Services. Another key service called BizTalk Workflow Services will become available in the very near future. More services will be added by Microsoft over time, and additional services might also be placed on the ISB by third parties.
Let's discuss each of the current core services in more detail. One of the most challenging problems when creating loosely coupled composite apps is managing how services will connect at the network level. For example, you might have one service that resides in the network perimeter and another service that resides inside the firewall, and they need to communicate with each other. Or you might want to expose a service to business partners, but those partner services are behind firewalls of their own or other network devices such as proxies or NATs.
BizTalk Connectivity Services simplifies many of these communication challenges by providing a universal naming convention for services along with a mechanism for direct/indirect communication between two nodes independent of network topology and configuration. It does this by providing a controlled mechanism for securely relaying connections through network devices. That said, in the cases where a direct connection can be made, BizTalk Connectivity Services can also get out of the way and let the nodes connect without relaying traffic.
You can certainly write this type of code yourself, although it can be challenging and cumbersome. The main advantage of letting BizTalk Services provide this functionality is that you don't have to write or maintain that code, which is often customized per endpoint. This frees you to concentrate on writing the code to solve your business problem rather than coding around these infrastructure problems. BizTalk Connectivity Services also provides other key features such as a global naming convention based on uniform resource identifiers (URIs), a simple publish/subscribe mechanism, and even multicast capabilities.
Another core part of BizTalk Services is the BizTalk Identity Services, a publicly accessible Security Token Service (STS) that conforms to the WS-Trust standard. WS-Trust is an interoperable standard for negotiating security based on trust relationships between parties. For example, one party can authenticate a client and issue a token that contains a set of claims about the client. That token can then be presented securely to other parties who also happen to trust the original party that issued the token. This approach makes it possible to federate valuable identity information across organizational boundaries.
Given this, BizTalk Identity Services can be used as a third-party identity and authentication management service even if you don't employ any other features like BizTalk Connectivity Services. However, when using the other BizTalk Services, BizTalk Identity Services will always be used to authenticate and authorize users.
When using BizTalk Connectivity Services, both the client and the service will be authenticated against BizTalk Identity Services using either a username/password, client certificate, or a managed card. Once authenticated, a set of authorization rules are processed to issue a new token that will be supplied to BizTalk Connectivity Services. The BizTalk Services Web site provides a user interface for managing your authorization rules along with a few programmatic APIs including a RESTful interface.
BizTalk Workflow Services has not yet been released for public consumption. However, a future release of BizTalk Services is expected to provide the capability to host workflow services based on Windows® Workflow Foundation (WF) on ISB. Workflows will activate based on messages received by ISB at a particular URI. These are the only details currently available.

BizTalk Services SDK
The BizTalk Services SDK is a free download available from biztalk.net that will enable you to get started programming against ISB. Before you can get started, you'll need to install the BizTalk Services SDK and create a user account on the BizTalk Services site. BizTalk Services is built on Windows Communication Foundation (WCF). The SDK is just a set of assemblies built on the Microsoft .NET Framework 3.0 that allows you to use ISB via the WCF programming model.
Most of the BizTalk Services SDK is found in the System.ServiceBus assembly. System.ServiceBus uses standard WCF extensibility points to define a new binding named RelayBinding. For those not familiar with WCF, a binding determines what kind of communication will be exposed or used by a service endpoint. Bindings are used by the WCF runtime to create the communication layer, known as the channel stack, for sending and receiving messages. The objects in the channel stack perform the network communication, and they determine how security and other protocols are implemented for a particular endpoint.
On the listener side, the RelayBinding enables you to expose an endpoint that will be accessible through a global URI supported by BizTalk Connectivity Services. When an endpoint using RelayBinding has been opened, the URI will be registered with BizTalk Connectivity Services and from that point forward any authorized client will be able to send messages to that global URI using a similarly configured client. BizTalk Connectivity Services then becomes the conduit for communication between those two endpoints.

A Typical WCF Application
Let's take a closer look at a simple example. Imagine that we're a company and we currently expose a WCF service on our internal network that is called from a rich client application. The client application is used by salespeople to process orders. The application calls the service, and then the service initiates the back-end processing necessary to fulfill the order.
The service is currently configured with a single endpoint using NetTcpBinding, which enables high-speed connections over TCP/IP. NetTcpBinding is generally the best option for services operating within the firewall.
Here's the code that configures the endpoint and starts the service using the standard ServiceHost:
ServiceHost sh = new ServiceHost(typeof(SalesService));
sh.AddServiceEndpoint(typeof(ISalesService),
  new NetTcpBinding(),
  "net.tcp://salesservicehost/SalesService");

sh.Open();
...
This is standard WCF code. The service implementation is the type SalesService and the contract is ISalesServices. The ServiceEndpoint, created when AddServiceEndpoint is called, uses NetTcpBinding and has an address of net.tcp://salesservicehost/SalesService.
Instead of hardcoding the endpoint this way, we could have also configured the endpoint in the application's configuration file (which is how you'd typically do it). But this sample should be easier to follow by keeping everything in code. Here is a sample client application that then invokes the SalesService to process a sale:
static void MakeSale(SaleData sd) {
  EndpointAddress ea = new EndpointAddress(
    "net.tcp://salesservicehost/SalesService");
  ChannelFactory<ISalesService> cf =
    new ChannelFactory<ISalesService>(new NetTcpBinding(), ea);
  ISalesService service = cf.CreateChannel();
  service.EnterSale(sd);
}
As time goes on, the sales force becomes more mobile, and reports begin coming in that some salespeople aren't able to connect to process orders when they are out of the office and attached to random networks (some of which don't allow Virtual Private Network, or VPN, connections).
BizTalk Services is able to solve this problem. Let's see what it takes to expose SalesService via BizTalk Connectivity Services:
ServiceHost sh = new ServiceHost(typeof(SalesService));
sh.AddServiceEndpoint(typeof(ISalesService),
  new RelayBinding(),
  "sb://connect.biztalk.net/services/contososervices/SalesService");

sh.Open();
...
As you can see, in order to expose the service through BizTalk Services, all we have to do is change one line of code—the call to ServiceHost.AddServiceEndpoint. Instead of NetTcpBinding, we use the RelayBinding, which in turn uses BizTalk Connectivity Services to expose this endpoint to the world at the specified URI. Messages sent to that address are then relayed to the local SalesService instance.
Notice the format of the URI—it begins with the "sb" scheme and is followed by the BizTalk Services host name, which is then followed by "services." After that, we add the BizTalk Services identity (the account name we've set up), in this case it's contososervices. Then we can add anything we want to the URI in order to make it unique. Here we've simply appended SalesService.
When you call ServiceHost.Open, the RelayBinding causes WCF to communicate with BizTalk Identity Services in order to authenticate the service identity and to authorize it to listen on the specified URI. The default behavior at this point is for the Windows CardSpace™ selector to appear, asking someone to select a card representing the service's identity.
The fact that a UI appears during authentication is obviously prohibitive for most services since they generally run in headless environments where there isn't someone logged into the machine. However, we can get around this problem with a little code, which we'll show you later, so don't be concerned. For now, we're just going to select a card that will enable SalesService to begin listening. You can manage which identities are allowed to listen on a particular URI with BizTalk Identity Services.
Now let's look at what it will take to update the client so that it can consume the BizTalk Services endpoint:
static void MakeSaleISB(SaleData sd) {
  string uri =
    "sb://connect.biztalk.net/services/contososervices/SalesService";
  ChannelFactory<ISalesService> cf = new ChannelFactory<ISalesService>(
    new RelayBinding(), new EndpointAddress(uri));
  ISalesService service = cf.CreateChannel();
  service.EnterSale(sd);
}
Notice that the client and service stay exactly the same except for using RelayBinding and specifying the service bus (sb://...) URI. The client will also see the Windows CardSpace selector by default, allowing the client to select an identity, which is then sent to BizTalk Identity Services for authentication and authorization. If the client is authorized to send messages to the specified URI, BizTalk Identity Services will return a token indicating that fact, which is then passed to BizTalk Connectivity Services as proof.
Having the Windows CardSpace selector appear in this scenario seems pretty acceptable since it's an interactive client application. Again, you can manage which client identities are allowed to send to a particular URI using BizTalk Identity Services.
When BizTalk Connectivity Services receives an incoming message from an authorized sender, it simply relays the message to an instance of SalesService running locally. You shouldn't really care how it does this because it's an implementation detail that will very likely change in the future. However, under the covers, RelayBinding uses WCF's TcpTransport to connect to BizTalk Connectivity Services. When relaying messages, BizTalk Connectivity Services can tunnel through the existing TCP connection back to the local service instance.
Why was this so simple? Because BizTalk Connectivity Services takes advantage of standard WCF extensibility points to encapsulate the connectivity and relay logic for both the client and the service inside the new RelayBinding. The fact that you can make fundamental communication changes by simply changing the binding (which can be done entirely in configuration) is one of the real advantages of adopting the WCF programming model.

Relayed Connectivity Options
One of the important properties on the RelayBinding object is ConnectionMode. The property's type is an enum named RelayedConnectionMode. This setting determines how the connection to BizTalk Connectivity Services is made. BizTalk Connectivity Services allows for numerous communication modes between senders and receivers that offer a great deal of flexibility for specific communication scenarios (see Figure 5).
Figure 5 RelayBinding ConnectionMode Options
ConnectionMode Value | Description
RelayedOneWay | The connection is set up to accept or send one-way operations only. To use this setting, all methods on your service contract must have an OperationContractAttribute with its IsOneWay property set to true.
RelayedDuplex | The connection is set up to support request-reply contracts (including duplex contracts).
RelayedDuplexSession | Same as RelayedDuplex but configured to use WS-ReliableMessaging.
DirectDuplexSession | Same as RelayedDuplexSession with an optimization. The initial connection between sender and receiver will use BizTalk Connectivity Services, but then it will try to bridge a direct connection between the two nodes if possible. If a direct connection can be made, the sender and receiver will then communicate without BizTalk Connectivity Services in the middle. If a direct connection can't be made, BizTalk Connectivity Services will continue to provide a relay for communication.
RelayedMulticast | The connection is set up to provide publish/subscribe capabilities. Multiple listeners can register with the same address when using this mode. To use this setting, all methods on your service contract must have an OperationContractAttribute with its IsOneWay property set to true.
RelayedHttp | The connection is set up to expose an HTTP endpoint via BizTalk Services that relays back to a service running on a machine on your local network, even if that service would not normally be accessible through the Internet.
RelayedOneWay is meant for one-way messaging scenarios, hence you can only use it with operations marked with IsOneWay=true. RelayedDuplex, on the other hand, is meant for request-reply scenarios including duplex contracts. RelayedDuplexSession is just like RelayedDuplex, but it also enables reliable messaging within the channel stack. This is the default connection mode so it's the one we actually used in the previous examples. Additionally, the DirectDuplexSession mode is an optimization of RelayedDuplexSession in that it attempts to bridge a direct connection between the sender and receiver if possible. If it cannot, it will fall back to relaying the traffic.
We're going to dive into the last two connection modes in more detail. First, RelayedMulticast enables publish/subscribe over WCF, a communication pattern that isn't available from any of the built-in WCF bindings. Additionally, RelayedHttp allows you to expose HTTP-based endpoints from within a corporate firewall or behind a NAT, something that developers have struggled with since the advent of Web services.
BizTalk Connectivity Services allows multiple listeners to register themselves at a URI when RelayedMulticast is specified by the first listener. Each ServiceHost that has an endpoint listening on that same URI implicitly becomes a subscriber. When a client sends a message to that URI, the message is delivered to all service endpoints currently subscribed. The only real constraint when you use RelayedMulticast is that, like RelayedOneWay, all operations must be marked with IsOneWay=true.
Let's return to our previous sales application. Assume that periodically during the day, we update the price of the different items being sold. We want to broadcast new prices to all salespeople so they are instantly aware. To make this happen, each client application can start a ServiceHost and listen to the same URI using the RelayBinding with ConnectionMode set to RelayMulticast:
ServiceHost sh = new ServiceHost(typeof(PriceUpdateService));
sh.AddServiceEndpoint(typeof(IPriceUpdateService),
  new RelayBinding(RelayConnectionMode.RelayedMulticast),
  "sb://connect.biztalk.net/services/contososervices/priceupdate");
sh.Open();
...
Each client runs this code when the application starts, and thus all client applications will be subscribers to messages sent to sb://connect.biztalk.net/services/contososervices/clientupdate. Each client has now become a subscribing service for purposes of this contract and URI. In this scenario, the back-end system plays the role of the WCF client and broadcasts (publishes) a message to all subscribers, as illustrated here:
static void DoPriceUpdate(PriceUpdate pu) {
  EndpointAddress ea = new EndpointAddress(
    "sb://connect.biztalk.net/services/contososervices/priceupdate");
  ChannelFactory<IPriceUpdateService> cf =
    new ChannelFactory<IPriceUpdateService>(
      new RelayBinding(RelayConnectionMode.RelayedMulticast), ea);
  IPriceUpdateService service = cf.CreateChannel();
  service.UpdatePrice(pu);
}
When UpdatePrice is called, the PriceUpdate message is sent to BizTalk Connectivity Services, which then relays the message to all the services currently subscribed to the same URI.

Passing through Firewalls with RelayedHttp
RelayedHttp mode enables you to take an HTTP service running on your local network and expose it through BizTalk Connectivity Services via HTTP on the public Web, even if that service would not normally be directly accessible from outside your network. This feature is especially handy when used in conjunction with the new WCF Web programming model found in the .NET Framework 3.5.
This new Web programming model makes it easier to implement RESTful Web services with WCF. It also provides features that make it easy to integrate your WCF services with existing RSS/Atom and AJAX infrastructure found on the Web today. BizTalk Services doesn't require the .NET Framework 3.5, but given these new WCF features, RelayedHttp mode has more functionality when you have the .NET Framework 3.5 installed.
Going back to the sales application, sometimes salespeople are not running the rich client application, but they still need to be notified of the latest pricing information. One interesting way to expose data that is updated often is through a Web feed—an HTTP endpoint that returns well-known XML formats, such as RSS or Atom, to applications that know how to consume those feeds. Web feeds can be polled for new content on a set schedule by a feed reader (the common name for a program that aggregates Web feeds into a human-facing UI). This enables the end user to receive updates without actively navigating to the site but rather by looking at his feed reader.
Using the WCF Web programming model, we can easily build a Web feed that exposes the price update data. The first thing we need is a contract that uses the new WCF attributes for enabling HTTP invocations. These attributes inform the WCF messaging layer how to route incoming HTTP requests to the methods on the service based on the URI rather than the SOAP Action header. Here's an example:
[ServiceContract]
public interface IPriceUpdateFeed {
  [OperationContract()]
  [WebGet(UriTemplate = "*")]
  Atom10FeedFormatter GetPriceUpdate();
}
Here WebGetAttribute tells WCF that this method should be called whenever an HTTP GET request arrives at the service (in contrast to SOAP requests, which always use HTTP POST).
Also note the UriTemplate property on WebGetAttribute. This tells WCF exactly how to route incoming messages to different methods based on the URI of the incoming request. This example uses a wildcard template ("*") to indicate that we want all GET requests routed to this particular method. You could easily configure multiple methods on a service, each of which handles a different UriTemplate. There's also a WebInvokeAttribute that you can use when you want to respond to other HTTP verbs besides GET (including POST, PUT, DELETE, and HEAD).
The other thing to notice about this contract is the method's return type. The WCF Web programming model includes new types specifically designed to help produce today's standard feed formats. The two major formats supported today are Atom and RSS. The example here uses the Atom format.
Figure 6 shows a simple implementation of the GetPriceUpdate operation that produces an Atom syndication feed. This implementation uses the new SyndicationFeed API for producing a logical feed, which it returns wrapped in an Atom10FeedFormatter object in order to produce the correct XML format.
Figure 6 Producing a Web Feed
public Atom10FeedFormatter GetPriceUpdate() {
  SyndicationFeed feed = new SyndicationFeed("Product Update Feed",
    "", null);
  List<SyndicationItem> items = new List<SyndicationItem>();
  feed.Items = items;
  IEnumerable<Product> products = GetUpdatedProducts();
  string iText = "Product update for {0}. Old price={1}. New Price={2}";
  foreach (var product in products) {
    items.Add(new SyndicationItem("Product update for " + product.Name,
      String.Format(iText, product.Name, product.OldUnitPrice,
      product.UnitPrice),
      null,
      product.Name,
      product.UpdatedTime));
  }
  return new Atom10FeedFormatter(feed);
}
Now we need to configure an endpoint to listen for these requests. WCF 3.5 comes with a new binding class to make configuring the endpoint very easy. The WebHttpBinding class encapsulates the details around creating a RESTful channel stack that won't expect SOAP messages. It simply uses the HTTP transport and the text-based message encoder from WCF, with the message version of the encoder set to None. Here is the code required to get our new endpoint hooked up and running:
ServiceEndpoint se =
  sh.AddServiceEndpoint(typeof(IPriceUpdateFeed),
  new WebHttpBinding(), "http://localhost:8099/ProductFeed");
se.Behaviors.Add(new WebHttpBehavior());
...
Notice that the WebHttpBinding endpoint is configured with an instance of WebHttpBehavior, which injects the necessary HTTP-based dispatching logic into the runtime. Once you have the ServiceHost up and running with this new endpoint configured, you can browse to the HTTP URI the service is listening to at localhost:8099/ProductFeed, and you should see the Atom feed.
Now suppose we want to expose this feed to salespeople who are not on the internal network. Rather than expose this machine through the firewall, we can simply use BizTalk Connectivity Services to relay the HTTP traffic to our local service. We accomplish this by adding another endpoint using the RelayBinding but specifying RelayedHttp for the ConnectionMode, as illustrated here:
ServiceEndpoint se =
  sh.AddServiceEndpoint(typeof(IPriceUpdateFeed),
  new RelayBinding(RelayConnectionMode.RelayedHTTP),
  "http://connect.biztalk.net/services/contososervices/ProductFeed");
se.Behaviors.Add(new WebHttpBehavior());
...
With this in place, our service is now securely exposed on the public Web, but the logic is hosted on an internal server. In Figure 7, you can see this feed exposed through a public, Internet-accessible URI. Of course, the feed looks exactly the same, and now salespeople on the road can subscribe to this feed and get updates without any complications around VPNs, firewalls, or network issues.
Figure 7 Exposing an HTTP Service through BizTalk Connectivity Services

Configuring the Identity Services
Regardless of the connection mode you use with RelayBinding, both the Listener (service) and the Sender (client) must be authenticated and authorized against BizTalk Identity Services. Authentication is the process of identifying the client or requestor given an initial set of claims. Authorization is the process of applying a set of user-defined authorization rules on that initial set of claims.
The authorization rules simply produce a new set of claims through a series of claim transformations (each rule maps a set of input claims to a set of output claims).The initial set of input claims are those presented to BizTalk Identity Services by the requestor. Today BizTalk Identity Services supports three types of initial claim sets: username/password, client certificate, and managed cards. In the case of username/password, the username is the initial claim and the password is the evidence of that claim.
BizTalk Identity Services begins processing the authorization rules using the username claim as the starting point to produce output claims. As new claims are produced, they can serve as input claims for other rules, allowing for a degree of rule-chaining. The final set of output claims is what's contained in the token returned by BizTalk Identity Services. When you're attempting to access BizTalk Connectivity Services, certain output claims must be present.
You can also configure BizTalk Identity Services with a certificate to protect the tokens it produces. When a certificate is configured, the token provided to the requestor will be encrypted with the public key from the certificate, and thus it will be safer traveling on the wire and less susceptible to client tampering in transit.
There are a few ways to configure these authorization rules. One way is through the UI provided on the BizTalk Services Web site (see Figure 8). The other way is programmatically using the Identity Management API found in the SDK. Recently, a RESTful version of that interface was also released.
Figure 8 BizTalk Services Web Site Claim Mapping UI
When you configure your authorization rules, you'll want to think about how you are using BizTalk Identity Services. Again, you can use BizTalk Identity Services as a generic STS or as your BizTalk Connectivity Services access control mechanism.
When using BizTalk Identity Services as a generic STS, you can map incoming username input claims to any output claim. The output claim will be placed in the resulting token that can then be presented to other parties. When using it this way you must have at least one rule where the input claim is username. You can add more rules that cascade based on new output claims—for example, taking the output claim produced by the username rule as the input claim for another output claim—allowing you to build up an arbitrary set of output claims. See the AccessControl samples in the BizTalk Services SDK for a complete example.
In order to authenticate with BizTalk Connectivity Services, you need to make sure you configure BizTalk Identity Services with a few specific rules. As mentioned, you must have at least one rule where the input claim is username, and you may also have cascading rules.
Where BizTalk Connectivity Services is unique, however, is that it will expect to find a Resource#Operation output claim in the final token, where the resource must be the service's listening URI and the operation must be either Listen or Send. For example, {URI}#Listen allows the user to start a service endpoint listening on the specified URI, whereas {URI}#Send allows the user to send a message to the specified URI.

Custom Token Providers
Earlier we mentioned it's usually odd for a server application to have an interactive login screen like the Windows CardSpace selector appear when the server begins listening. This happens because each endpoint that uses RelayBinding employs an object that implements the ITokenProvider interface. The default implementation for this interface is CardspaceTokenProvider, which causes the Windows CardSpace selector to appear when a connection is made to BizTalk Connectivity Services.
In addition to CardspaceTokenProvider, the SDK contains a few more implementations of ITokenProvider. UsernameTokenProvider retrieves a token using a registered username and password from the BizTalk Identity Services. AutomaticRenewalTokenProvider causes the Windows CardSpace selector to appear, but it will automatically get a new token before the current token expires, enabling configure-once endpoints. Both of these implementations are also endpoint behaviors that can be added to a client or service endpoint to replace the default CardspaceTokenProvider.
Our service can now avoid the interactive login by configuring UsernameTokenProvider on its endpoint before calling ServiceHost.Open, as shown here:
ServiceHost sh = new ServiceHost(typeof(SalesService));
ServiceEndpoint se = sh.AddServiceEndpoint(typeof(ISalesService),
  new RelayBinding(),
  "sb://connect.biztalk.net/services/contososervices/SalesService");
UsernameToken token = new UsernameTokenProvider("someusername",
  "somepassword");
se.Behaviors.Add(token);
sh.Open();
...
So now whenever the service process starts, it will automatically authenticate with BizTalk Identity Services without any human intervention. Alternate implementations of ITokenProvider can also be configured on your RelayBinding endpoint by simply adding the implementation as an endpoint behavior (the TokenProvider base class found in the SDK implements both ITokenProvider and IEndpointBehavior).

How to Get Started
If you'd like to get started with BizTalk Services, first browse to labs.biztalk.net and create an account. You'll need to ensure that you have the .NET Framework 3.0 installed, and then you can download and install the BizTalk Services SDK. Once you have an account in place and the SDK installed on your machine, you should be able to recreate the samples we've shown you in this article. Of course, you'll need to change the account name used in the URIs from "contoso" to your account name. Also, the SDK comes with some additional samples for your perusal, which may help better illustrate some of the concepts we've covered. As you get started, if you have additional questions, be sure to check out the FAQ on the BizTalk Services site. Good luck!

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.

Aaron Skonnard is a cofounder of Pluralsight, a premier Microsoft .NET training provider. Aaron is the author of numerous books, white papers, and articles as well as Pluralsight's Applied Windows Communication Foundation, Applied BizTalk Server 2006, and Applied Web Services courses. You can reach him at pluralsight.com/aaron.


Concurrency
Tools And Techniques to Identify Concurrency Issues
Rahul V. Patil and Boby George

This article discusses:
  • Problems in concurrency testing
  • Elusive bugs and their dependencies
  • New tools to find the roadblocks
  • Best practices for designing your tests
This article uses the following technologies:
Dynamic and Static Analysis, Model Checking
Contents
Race Conditions, Deadlocks, and More
Problems from Memory Ordering
Testing Strategies
Concurrency Testing Tools
Performance Testing
Stress Testing
Wrapping Up
In order to satisfy the perpetual need for increased computing power, the hardware industry is steadily shifting toward multi- and many-core processor systems. Unlike the increased application performance attained by faster processors with higher clock speeds, performance improvements in many-core systems can only be achieved by writing efficient parallel programs.
Forms of parallelism have existed in the software industry for a long time. However, creating mainstream software applications that harness the full power of parallel hardware requires significant changes from the practices designed for sequential applications.
Testing parallel applications is not straightforward. For instance, concurrent bugs are difficult to detect due to the nondeterministic behavior exhibited by parallel applications. Even if these bugs are detected, it is difficult to reproduce them consistently. Further, after fixing a defect, it is difficult to ensure that the defect was truly rectified and not simply masked. In addition, parallelization can also introduce new performance bottlenecks that must be identified.
In this article, we'll look at testing techniques for parallel programs and present six helpful tools you can use to locate potentially serious defects. We'll begin with the following categories of concurrency bugs: race conditions, incorrect mutual exclusions, and memory reordering.

Race Conditions, Deadlocks, and More
A race occurs when two or more threads of execution in a multithreaded program try to access the same shared data and at least one of the accesses is a write. Harmful race conditions introduce unpredictability and are often hard to detect. The consequences of a race condition might only become visible at a much later time or in a totally different part of the program. They are also incredibly hard to reproduce. Races are avoided by using synchronization techniques to correctly sequence operations between threads.
Identifying Test Data and Reporting Metrics
For parallel applications, test data is defined by identifying the scalability aspects of the scenario. The scalability exhibited by the application really depends on the parallelizability of the algorithm used. Certain algorithms may produce super-linear speedup for certain problem domains (for example, a search through a non-uniform distribution). Other algorithms may not produce embarrassingly parallel speedup due to limited parallelizability, resulting in total runtime speed increases that aren't proportional to the number of CPUs. Still other algorithms (such as sorts) won't scale linearly across data set size. As you can see, it is important to understand how the performance of the application scales across the following categories:
The Number of Threads or CPU Cores Typical user expectation is that the parallel application will scale linearly as the number of CPUs or threads increases.
Dataset Size Typical user expectation is that the performance of the parallel application should not decrease when the size of the input dataset increases.
Execution Workload As the execution progresses, the amount of work done by the thread may not remain constant. It can increase or decrease, randomly vary, or be normally distributed. The variations in workload as the execution progresses can impact the performance characteristics of the application. The types of workload variations as execution progresses include: constant workload, increasing workload, decreasing workload, random workload and normally distributed workload.
The execution time is the most common metric used for reporting. Other reporting metrics include speedup achieved in comparison with sequential application and speedup across the scalability categories. It's important to define the reporting metric and how it is going to be measured. Some good questions to start with include: What values have to be reported? How will they be reported? Will the instrumentation used to take the measurement affect the performance? Further, when possible, take measurement in parts so it is possible to understand the performance of the sub- parts of the system.
Sometimes races may be safe and intentional. For example, there could be a global flag called done, for which there is only one writer but many readers. The writer thread sets the flag to tell all the threads to terminate safely. All reader threads may be running in a loop using while (!done), repeatedly reading the flag. Once a thread notices that the done flag is set, it will exit its while loop. In most cases, this is a benign race. As we will discussed later in this article, there are tools available for detecting race conditions. However, such tools might warn about races that are in fact benign, reporting errors known as false positives.
A deadlock occurs when two or more threads wait on each other, forming a cycle and preventing all of them from making any forward progress. Deadlocks can be introduced by the programmer while trying to avoid race conditions. For example, incorrect use of synchronization primitives such as acquiring locks in an incorrect order can result in two or more threads waiting for each other. Deadlocks can also occur in cases that don't use locking constructs; any kind of circular wait can result in a deadlock.
Take a look at the following example of a potential deadlock situation. Thread 1 does the following:
Acquire Lock A;
Acquire Lock B;
Release Lock B;
Release Lock A;
Thread 2 proceeds like so:
Acquire Lock B;
Acquire Lock A; // if thread 1 has already acquired lock
                // A and waiting to acquire lock B, then
                // this is a deadlock
Release Lock A;
Release Lock B;
Starvation is an indefinite delay or permanent blocking of one or more runnable threads in a multithreaded application. Threads that are not being scheduled to run even though they are not blocking or waiting on anything else are said to be starving. Starvation is typically the result of scheduling rules and policies. For example, if one schedules a high-priority, non-blocking, continuously executing thread along with a low-priority thread, then, on a single core CPU, the lower thread will never get a chance to run. To help avoid such conditions, the Windows® scheduler intervenes frequently to reduce starvation by occasionally boosting priorities of starving threads.
Livelocks occur when threads are scheduled but are not making forward progress because they are continuously reacting to each other's state changes. The best way to describe this is if two people were to approach each other in a narrow hallway and they step aside for one another, each time blocking the other's path. Such side stepping prevents forward progress and results in a live lock. High CPU utilization with no sign of real work being done is a classic warning sign of a livelock. Livelocks are incredibly difficult to detect and diagnose.

Problems from Memory Ordering
When the compiler is optimizing code, it may decide to reorder pieces of code to improve performance. However, this can cause unexpected behavior in threads monitoring changes to global state. For example, let's say you have two threads of execution: thread 1 and thread 2. Let's also assume two global variables, x and y, both initialized to 0. Thread 1 runs these lines:
x=10;
y=5;
Thread 2 executes the following:
if (y == 5)
{
  Assert(x != 10);
}
Here, the optimizing compiler might observe that y will eventually be reassigned to 5 anyway, and it might reorder the code such that y gets assigned 5 before x gets assigned 10; from the perspective of the single thread executing these two assignments, the ordering doesn't matter. Hence, there is a chance that Thread 2's assert will get fired, since x might not equal 10.
Where necessary, one can avoid compiler memory reordering by using volatile variables and compiler intrinsics. It is also worth mentioning that with common optimization flags turned on, Thread 2 may never see an update to variables y or x. Here the user will have to use volatile variables.
Compiler reordering is not the only complication. Memory access optimizations such as caching and advanced fetching by speculative executions may cause memory operations executed by one thread on one CPU to be perceived to have happened in a different order by another thread on another CPU. This kind of memory reordering perception can only happen in a system with multiple CPUs or multiple CPU cores.
To clarify, suppose there are two threads of execution: thread 1 and thread 2. Further assume m and n are global, both initialized to 0, and a, b, c, d are local variables. Thread 1 (on processor 1) has these instructions:
m = 5;     // A1
int a = m; // A2
int b = n; // A3
Thread 2 (on processor 2) has these:
n = 5;     //A4
int c = n; //A5
int d = m; //A6
Logically (in a sequentially consistent memory world), b == d == 0 can never happen after all of these instructions have executed. However, hardware memory reordering can cause the writes to shared memory (A1 and A4) to be store-buffer forwarded, which can lead the different processors to observe the writes differently.

Testing Strategies
Testing a concurrent application entails testing for correctness, reliability, performance, and scalability. The correctness of the application is determined using techniques such as static analysis, dynamic analysis, and model checking. Performance and reliability are tested for by studying the overheads introduced by parallelism and stress testing. Scalability is tested by analyzing how well the application performs on systems of varying sizes.
Static analysis techniques analyze code without actually executing the program. Usually, static analysis is performed by looking at metadata from a compiled application or annotated source code. The analysis typically includes some formal inspection to ensure that the intent and assumptions of the programmer prevents incorrect behavior. Prefix and Prefast are two of the most popular static analysis tools for native applications, whereas FxCop is very popular for managed code.
There are advantages and disadvantages to static analysis. Among the advantages are the thorough and detailed coverage achieved, the confidence in the product design that such formal analysis helps build, and the precise error reports that make bugs easier to find and fix. However, to deal with concurrency bugs, static analysis requires a great deal of annotation specifying intent. Moreover, these annotations need to be correct themselves. Plus, tools that use static analysis tend to generate a lot of false positives and require a significant effort to minimize the false positives.
In dynamic analysis, bugs are detected by looking at the footprints of execution. There are two types of dynamic analysis: online and offline. Tools that use online dynamic analysis analyze a program while it is executing; tools that use offline dynamic analysis record traces and analyze them later to detect bugs. Dynamic analysis is convenient because it requires little-to-no extra work from the developer at the time of programming, yields fewer false positives, and makes it easier to address the more obvious problems. Since bugs are discovered only in the path of execution, the more frequently traversed paths yield the first set of bugs. This makes it cheaper to improve reliability.
But there are disadvantages, too. You can detect bugs only in the path of execution, and you need to rely on test cases for a good code coverage. In fact, some tools can only catch a race if a race occurred in that run. Thus, if the tool does not report any bugs, you still can't be certain there aren't any. Most dynamic analysis tools rely on some sort of instrumentation that can modify the behavior of runtime, which is another drawback. Due to the complexity, the performance of these tools tends to be very poor.
The final method is model checking—the method for verifying the correctness of a finite state concurrent system. It allows for formal deductive reasoning. A model checker tries to simulate race and deadlock conditions. Using model checking, you can formally prove the absence of races and deadlocks. This method provides superior confidence in design and architecture, provides very high coverage, and requires minimal external drivers.
Like other testing methods, model checking has some disadvantages. In most cases, it is very difficult to automatically extract the model from code (rare cases exist with limited use). Performing the model extraction manually is also quite tedious. There is also too much to verify due to state space explosion, a condition wherein the potential number of possible states is too huge to analyze. State space explosion can be controlled to some extent by applying reduction techniques which utilize complicated heuristics. Such heuristics can also have downsides, such as failing to detect bugs in long-running applications.
Finally, model checking requires disciplined design and implementation planning. Model checking may prove that the design is error free, but the implementation may still be incorrect. In practice, model checking is useful only for small, critical sections of a product. Other hybrid techniques include combining dynamic analysis and model checking. An example is CHESS, which you'll see shortly.
Race Detection Algorithms
The lockset algorithm, used in both static and dynamic analysis tools, reports a potential race when shared memory is accessed by two or more threads without the threads holding a common lock. Fundamentally, the algorithm says that for each shared memory variable v, a non-empty set of locks C(v)that will be held by every thread while accessing the variable. Initially, C(v) is the list of all locks. Each thread also maintains two sets of locks: locks(t) indicating all the locks held and writeLocks(t) indicating all the write locks held. Here's how the algorithm proceeds:
  1. For each shared memory variable v, maintain a set C(v) of locks. Initially C(v) is the list of all locks.
  2. Each thread also maintains two sets of locks: locks(t) indicating all the locks held and writeLocks(t) indicating all the write locks held.
  3. On each read of v by thread t:
    1. Set C(v) = C(v) intersection locks(t).
    2. If C(v) == NULL set, then raise an error.
  4. On each write of v by thread t:
    1. Set C(v) = C(v) intersection writeLocks(t).
    2. If C(v) ==NULL set, then raise an error.
Essentially, as the application progresses, the C(v) of each variable starts shrinking. An error is raised if the C(v) ever becomes null (for example, if the intersection of the threads' locksets are NULL at the time of accessing the shared memory).
Unfortunately, not all races reported by a lockset algorithm are real races. One can write race-free code without using locks either by applying clever programming tricks or using other synchronization primitives such as signaling. This makes finding genuine bugs really hard. Annotations and certain suppressions can help alleviate this problem.
Another algorithm for detecting races is the "happens-before" algorithm, which is based on partial ordering of events in distributed systems. Here is an overview of the algorithm that computes the partial order to determine what events happened before another event (events, in this context, are all instructions, including read/write and locks):
  • Within any single thread, events are ordered in the order of their occurrence.
  • Among threads, events are ordered according to the synchronization primitives' properties. For example, if lock(a) is being acquired by two threads, then the unlock by one thread is said to have happened-before the lock of another thread.
  • If two or more threads access a shared variable, and the accesses are not deterministically ordered by the "happens-before" relationship, then a race is said to have occurred.
The algorithm is illustrated in Figure A.
Thread 1's unlock happened-before Thread 2's lock. Thus, the access to the shared variable can never happen at the same time and there is no race. One major drawback of the algorithm is that monitoring such relationships can be very expensive.
The larger issue is that the ability of this algorithm to detect races totally depends on the scheduling order. The partial order is built only for this specific instance of the scheduling and may miss bugs for the same test on a different day. Figure B will not report any races, but an execution order in Figure C will report races. Many races are known to have occurred only after several years following a product's release. So, this detection does not leave one with a comforting sense of a complete coverage.
On the flip side, happens-before generates very low false positives. Most bugs are real. However, happens-before misses many errors (false negatives) and is very hard to implement efficiently.
Similarly, the lockset algorithm is very efficient, and can detect more errors. However, it tends to generate too many false positives. There have been efforts to combine these algorithms to overcome the disadvantages of both the approaches. Note: these race detection algorithms have evolved over several years, and sources to these can be found by searching the ACM /IEEE portals.
Figure A Happens-Before Algorithm
Figure B Races Will Not Be Reported
Figure C Races Will Be Detected

Concurrency Testing Tools
There are a number of concurrency testing tools on the market to help you deal with potential deadlocks, livelocks, hangs, and all the other issues you experience when running parallel transactions. Each tool we look at here will help in a particular area.
CHESS Created by Microsoft Research, CHESS is a novel combination of model checking and dynamic analysis (see go.microsoft.com/fwlink/?LinkId=116523). It detects concurrency errors by systematically exploring thread schedules and interleaving. It is capable of finding race conditions, deadlocks, hangs, livelocks, and data corruption issues. To help with debugging, it also provides a fully repeatable execution. Like most model checking, the systematic exploration provides thorough coverage.
As a dynamic analysis tool, CHESS runs a regular unit test repeatedly on a specialized scheduler. On every repetition, it chooses a different scheduling order. As a model checker, it controls the specialized scheduler that is capable of creating specific thread interleavings. To control the state space explosion, CHESS applies partial-order reduction and a novel iteration context bounding.
In iteration context bounding, instead of limiting the state space explosion by depth, CHESS limits number of thread switches in a given execution. The thread itself can run any number of steps between thread switches, leaving the execution depth unbounded (a big win over traditional model checking). This is based on the empirical evidence that a small number of systematic thread switches is sufficient to expose most concurrency bugs.
CHESS can detect deadlocks and races (using the Goldilocks lockset algorithm explained at go.microsoft.com/fwlink/?LinkId=116877) but relies on programmer assertions for other state verification. It also expects all programs to terminate and that there is a fairness guarantee (forward progress) for all threads. Thus, if the program enters a state of continuous loop, it reports a livelock.
From the testing view point, you would begin by running CHESS with an iteration context bound of 2. Once there are no more bugs to be found, you would increase the bound to 3 and so on. Empirically, most of the bugs should be detected with a bound of 2 and 3. Hence, this can be a very efficient way to weed out bugs sooner.
For instrumentation, CHESS detours Win32® API synchronization calls to control and intentionally introduces non-determinism. Additionally, it requires developer code to include a lot of asserts to ensure consistency of states (something good code should do anyway). However, like most dynamic analysis tools, it requires a good test suite for broad coverage. CHESS is a boon for all those developers and testers who had to solely rely on stress for better interleaved testing. It takes regular unit tests and methodically simulates interesting interleavings.
The Intel Thread Checker This is a dynamic analysis tool for finding deadlocks (including potential deadlocks), stalls, data races, and incorrect uses of the native Windows synchronization APIs (see go.microsoft.com/fwlink/?LinkId=115727). The Thread Checker needs to instrument either the source code or the compiled binary to make every memory reference and every standard Win32 synchronization primitive observable. At run time, the instrumented binary provides sufficient information for the analyzer to construct a partial-order of execution. The tool then performs a "happens-before" analysis on the partial order. Please refer to the "Race Detection Algorithms" sidebar for more information on happens-before analysis.
For performance and scalability reasons, instead of remembering all accesses to a shared variable, the tool only remembers recent accesses. This helps to improve the tool's efficiency while analyzing long-running applications. However, the side effect is that it will miss some bugs. It's a trade-off, and perhaps it's more important to find many bugs in long-running applications than to find all bugs in a very short-lived application.
The only other big drawback of the tool is that it can't account for synchronization via interlocked operations, such as those used in custom spin locks. However, for applications that use only standard synchronization primitives, this is probably one of the best-supported test tools available for concurrency testing native applications.
RacerX This flow-sensitive static analysis tool is used for detecting races and deadlocks. It overcomes the requirement to tediously annotate the entire source code. In fact, the only annotation requirement is that users provide a table specifying APIs used to acquire and release locks. The locking primitives' attributes such as spinning, blocking, and re-entrancy can also be specified. This table will typically be very small, 30 entries at most. This tremendously reduces the burden of source annotation for large systems.
In the first phase, RacerX iterates over each source code file and builds a Control Flow Graph (CFG). The CFG has information related to function calls, shared memory, use of pointers, and other data. As it builds the CFG, it also refers back to the table of synchronization primitives and marks calls to these APIs.
Once the complete CFG is built, the analysis phase kicks in, which includes running the race checker and deadlock checker. Traversing the CFG can be lengthy, but appropriate reduction and caching techniques are utilized to minimize the impact. As the context flow is traversed, the lockset algorithm is used to catch potential races (refer to the "Race Detection Algorithms" sidebar for details about the algorithm). For deadlock analysis, it computes locking cycles every time locks are taken.
The final phase involves post-processing all the reported errors in order to prioritize by importance and harmfulness of the error. As can be expected with static analysis, the authors spent a lot of time trying to reduce the false positives and present bugs with high confidence. The results of this tool have been impressive, and it seems very practical from a test engineering standpoint.
Chord This is a flow-insensitive, context-sensitive static analysis tool for Java. Being flow-insensitive allows it be far more scalable than other static tools, but at the cost of losing precision. It also takes into account the specific synchronization primitives available in Java. The algorithm used is very involved and would require the introduction of many concepts. (See go.microsoft.com/fwlink/?LinkId=116526 for more on Chord.)
KISS Developed by Microsoft Research, this model checker tool is for concurrent C programs. Since state space explodes quickly in a concurrent system, KISS transforms a concurrent C program into a sequential program that simulates the execution of interleaving. A sequential model checker is then used to perform the analysis.
The application is instrumented with statements that convert the concurrent program to a sequential program, with KISS assuming the responsibility of controlling the non-determinism. The non-determinism context switching is bounded by similar principles described in CHESS above. The programmer is supposed to introduce asserts which validate concurrency assumptions. The tool does not report false positives. The tool is a research prototype and has been used by the Windows driver team, which primarily uses C code (see go.microsoft.com/fwlink/?LinkId=115723).
Zing This tool is a pure model checker meant for design verification of concurrent programs. Zing has its own custom language that is used to describe complex states and transition, and it is fully capable of modeling concurrent state machines. Like other model checkers, Zing provides a comprehensive way to verify designs; it also helps build confidence in the quality of the design since you can verify assumptions and formally prove the presence or absence of certain conditions. It also contends with concurrent state space explosion by innovative reduction techniques.
The model that Zing uses (to check for program correctness) has to be created either by hand or by translators. While some specific domain translators can be written, we have yet to come across any complete and successful translators for native or CLR applications. Without having translators, we believe Zing cannot be used in large software projects, except for verifying the correctness of critical subsections of the project (see go.microsoft.com/fwlink/?LinkId=115725.)

Performance Testing
Performance testing is an integral and essential part of the concurrency testing process. After all, one of the key motivations for developing parallel applications is to deliver superior performance in comparison to sequential applications. As postulated in Amdahl's law and Gustafson's law, the performance gain achieved by a parallel application is greatly influenced by its algorithm's parallelizability aspects, amount of sequential parts in the program, the parallelization overhead and the data/workload characteristics. Conducting performance testing allows stakeholders to understand and analyze the performance characteristics of parallel applications.
The general methodology for conducting performance testing of parallel applications remains the same as that of performance testing sequential applications. The following section describes how some of the key performance testing steps are to be adapted for concurrent applications. For an understanding of the most helpful factors to measure, see the "Identifying Test Data and Reporting Metrics" sidebar.
The most important step in performance testing is defining the objectives or purpose of the test. For parallel applications, valid test objectives include understanding the parallelizability/scalability of the algorithm used, understanding the performance characteristics of various design alternatives, discovering the synchronizations and communication overheads, and validating that performance requirements are met.
It should be noted that the objective and scope of the performance testing could also vary based on who is conducting the test. For example, customers deploying a parallel application would perform performance testing to ensure that business needs are met, while the development team would be interested in conducting exhaustive performance testing to identify bottlenecks and to improve the parallelizability of the program. Further, the test objectives can vary throughout the software development cycle. During the design and implementation phase, the test objective might be to understand and improve the performance characteristics of the application, while during testing and release phases (stabilization phases), the objective might be to ensure that performance does not regress across builds.
Defining test scenarios and setting goals for them is another important step in the performance testing process. Development teams interested in understanding the performance characteristics of a parallel application should define three types of test scenarios—customer scenario tests, key performance indicator (KPI) tests, and micro benchmark (MBM) tests.
The relationships between these different types of performance tests can be considered as equivalent to that which exists between system tests, integration tests, and unit tests. In other words, a customer scenario tests spawns a set of KPI tests and a KPI test spawns a set of MBM tests. Understanding the relationship between these different test types enables developers to understand performance relationships among various sub-parts of a parallel application. Gaining this understanding also permits better prioritization of performance bugs and, more importantly, allows the development team to respond to customer performance complaints with result-oriented suggestions.
Setting performance goals for any non-trivial application is hard, let alone for parallel applications. One approach in setting goals is to derive the goal by triangulating metrics obtained from an expected algorithmic or theoretical performance metric for each component and sub-component of the application, from comparative analysis (comparison candidates include similar competitor applications) and from profiling the existing implementation/application (if one exists).
As with test goals, every test scenario should define a set of acceptance criteria (set of values that validate the test results). For parallel test scenarios, the following variables can be used as acceptance criteria.
Variance in Test Results This is indicative of an unstable application. The variance in test results can be understood by calculating the standard deviation of results.
CPU Utilization Low CPU usage could be a sign of concurrency bugs such as deadlocks and synchronization overheads. Conversely, a high CPU utilization does not necessarily indicate success, as livelocks result in high CPU utilization.
Garbage Collections For managed applications, too many memory management operations can hinder actual work execution and could point to faulty design or implementation.
Total Thread Execution Time This enables you to approximate the total execution time if the program was to be executed sequentially. Comparing the total thread execution time to the elapsed time of sequential implementation of the same algorithm program is a way to understand the parallelization overheads (and to note whether the test is valid).
Total Memory Usage Measuring total memory usage can be valuable in understanding the memory profile of the application. For managed applications, the garbage collector plays a significant role in altering the total memory usage of the application and should be taken into consideration while evaluating the memory usage.
Before you begin performance testing, there are three important steps you can take to ensure more relevant results. First, minimize the variance in the test environment (variance can be introduced by both the application and test environment). Variances in the test environment can be lowered by stopping unnecessary services and applications and reducing network interferences. Variance caused by the application can be reduced by performing warm-up iterations and collecting measurements from multiple iterations of the test.
Second, for managed applications, the untimely execution of the garbage collector can invalidate performance results. As a result, you should minimize the chances of the garbage collector getting invoked during performance measurements by forcibly invoking garbage collection (GC) before or after collecting the measurement and/or changing the GCLatencyMode to LowLatency (this is true only in the Microsoft® .NET Framework 3.5).
Third, always perform warm-up before collecting the metrics. Warming up by executing the test once before collecting the measurement allows for discounting onetime costs such as initialization of variables, JITing cost (in managed applications), and initial cache miss latency. Note that depending on performance scenarios, it might be important to measure the cold startup performance too. (For more information on improving application startup performance, see msdn2.microsoft.com/magazine/cc337892.aspx.)
Further Reading on Concurrency Testing

Using Synchronization
go.microsoft.com/fwlink/?LinkId=115730

Bugslayer: Wait Chain Traversal
msdn2.microsoft.com/magazine/cc163395

No More Hangs: Advanced Techniques to Avoid and Detect Deadlocks in .NET Apps
msdn2.microsoft.com/magazine/cc163618

ReadWriteBarrier (C++)
go.microsoft.com/fwlink/?LinkId=115731

Intel 64 Architecture Memory Ordering
go.microsoft.com/fwlink/?LinkId=115732

Synchronization and Multiprocessor Issues
go.microsoft.com/fwlink/?LinkId=115734

PreFast Step-by-Step
go.microsoft.com/fwlink/?LinkId=115736

Testing Applications with AppVerifier
go.microsoft.com/fwlink/?LinkId=115739

Performance Testing Guidance for Web Applications
go.microsoft.com/fwlink/?LinkId=115741

Stress Testing
Software stress testing often refers to testing the application for robustness, availability, and graceful error handling. Robustness is usually tested by repeatedly invoking the same functionalities or combination of functionalities and ensuring correctness of execution. Availability is tested by executing the application under strenuous resource conditions such as low memory or high CPU load and ensuring that the application does not crash or that it fails gracefully. Graceful error handling is often tested for by introducing errors (fault injection) or by triggering multiple errors.
When conducting stress testing for concurrent applications, more focus should be given to testing the robustness and availability of the application. Due to the nondeterministic behavior of parallel applications, repeatedly invoking the same functionality or combination of functionalities could result in different code paths—which in turn might result in more discovered bugs. Further, testing for availability under strenuous resource conditions (such as creation of numerous threads or multiple threads entering deadlocks/livelocks) is especially important since the probability that a customer will encounter such scenarios is relatively high for parallel applications.
It should be noted that analyzing the root cause for stress-related concurrency bugs and trying to reproduce stress-related bugs in a consistent manner is extremely difficult. However, as the concurrency testing tools are still in a nascent state, stress testing is a very important supplement to functional testing.

Wrapping Up
In order to truly take advantage of all the power that parallel computing can offer, it is imperative that we evolve the current software development practices that were created for developing and testing sequential applications. It's difficult to develop and test concurrent applications due to a new class of bugs introduced by parallelism. This article outlined the various types of concurrent bugs, strategies for finding concurrent bugs, and discussed how to adapt performance testing for concurrent scenarios.

Rahul V. Patil is an SDET Lead with the Parallel Computing Platform team at Microsoft and is responsible for leading the testing effort with the native concurrent framework.

Boby George is also an SDET with the Parallel Computing Platform team at Microsoft and is responsible for the performance testing effort with managed parallel computing framework.


Robotics
Simulating The World With Microsoft Robotics Studio
Sara Morgan

This article discusses:
  • Building the robot animation
  • Building the environment
  • Driving a robot or simulation
  • Creating entities
 This article uses the following technologies:
C#, Robotics Studio
Code download available at: RoboticsStudio2008_06.exe (646 KB)
Browse the Code Online

Contents
What is a Simulation?
Getting Started
Running a Simulation
Entities and Entity Types
Programmatically Adding a New Entity
Defining a New Entity in VSE
Creating an Entity Class
Creating a Mesh
Convert the Mesh to Binary Format
Creating a Simulation Service
Populating the Simulation Scene
Creating a Manifest
Running the Simulation
Building an Entity without a Differential Drive
Don't let the name fool you. Microsoft® Robotics Studio (MSRS) is more than just a way to play with robots. Released almost two years ago by Microsoft Research and virtually ignored by everyday business application developers, MSRS allows you to build service-based applications for a wide range of hardware devices. The toolkit includes a runtime that should be instantly familiar to Windows® Communication Framework (WCF) developers. Additionally, it features a Visual Programming Language (VPL) tool and Visual Simulation Environment (VSE).
MSRS offers a service-oriented runtime, along with the tools needed to design and deploy robotics-based applications. It includes visual authoring tools, tutorials, and documentation designed to jump-start developers new to the world of robotics. Commercial developers must purchase the toolkit for a small fee, but hobbyists and academic researchers are able to download and use it free of charge.
The MSRS runtime is composed of two lower-level runtimes that sit atop the CLR 2.0. These two runtimes are the Decentralized Software Services (DSS) and the Coordination and Concurrency Runtime (CCR). DSS is a lightweight, service-oriented runtime that is based on the Representation State Transfer (REST) principles, which are used to power the Web. CCR is a Microsoft .NET Framework library that supports asynchronous processing. This is extremely important for robotics applications, as data is constantly being sent and received from numerous sensors and actuators.
Along with the runtime, the MSRS toolkit includes a VPL tool that allows you to build robotics applications by simply dragging and dropping elements onto a design surface. MSRS also includes a VSE which allows you to experiment with complex simulations involving multiple robots and obstacles. This is the portion of MSRS I will focus on in this article. I'll cover the visual simulation environment and walk through the steps for creating a simulation using a new robotic entity. The good news is that you do not need a robot to work with the code from this article. That's what makes simulations so attractive; they provide an opportunity to learn without an investment in expensive hardware.﻿

What Is a Simulation?
If you're not familiar with simulations, imagine a flip book—a little book with an image on each page that "moves" when you flip quickly through the pages. Simulations work in a similar manner. A simulation contains one or more entities and each of these entities is rendered inside a frame. The frame is equivalent to a page of paper in the flip book. The rate at which the frames are rendered depends on the hosting machine's graphics card.
The fundamental difference between the flip book and a simulation is that the flip book is static or predictable and the simulation is not. Each frame of a simulation is rendered dynamically and the forces that an entity encounters within each frame are not always known in advance. This is what makes simulations so useful. You can act out a scenario with a robot and see how the robot would interact with the world.

Getting Started
If you have not already done so, now would be a good time to download and install the MSRS toolkit (available at go.microsoft.com/fwlink/?LinkId=113902). The MSRS Web site currently offers a refresh installation for its 1.5 version. This includes the full version of MSRS 1.5, along with all available updates.
MSRS provides templates for Visual Studio® 2005, but even if your machine is running Visual Studio 2008, you can still run the samples included with this article. Your development machine will need a graphics card that is compatible with DirectX® 9.0. Specifically, the card must support vertex shader VS_2_0 or higher and pixel shader PS_2_0 or higher. Most high-end desktop and laptops capable of running today's graphics games will already have this.
If you are not sure what your graphics card supports, you can go to go.microsoft.com/fwlink/?LinkId=113904 for a list of graphics cards, along with the shaders they support. Additionally, you can install MSRS and use the help menu in VSE to view your supported pixel and vertex shaders. If you try to run one of the simulations included with MSRS or this article and your screen is blank, then your graphics card is not compatible.
MSRS uses the AGEIA PhysX engine to provide physics for the simulation environment. Without physics, your simulation would be useless, since it would in no way represent the world it was trying to simulate. For example, entities would be able to float around without gravity. If you read the documentation that accompanies MSRS, you will see that it mentions the use of an optional accelerator card provided by AGEIA (see ageia.com). It is not necessary for you to purchase and install this physics card in order to work with the simulations in this article; physics will still be available to your simulation through the AGEIA PhysX software engine.

Running a Simulation
At this point, you are probably anxious to see a simulation. Before you create your own simulation, you should try running one of the simulations provided with MSRS. Once installed, MSRS creates a menu folder that contains seven simulations. The first simulation in this folder, Basic Simulation Environment, will render a scene similar to Figure 1.
Figure 1 Basic Simulation Environment
You might think that the basic simulation includes only two entities: a world globe and a box. In fact, the simulation scene also includes entities that represent the main camera, the ground, sky, and sun. You can see which entities are included by clicking Mode and Edit from the VSE menu.
Edit mode, shown in Figure 2, includes a left-hand pane where you can modify properties associated with each entity. These properties control everything from the name of the entity to its position in the simulation environment. Furthermore, they also allow you to precisely control how the entity is rendered, affecting how it appears in the simulation.
Figure 2 Edit Mode for Modifying Entity Properties
If you return to Run mode, you can move around the simulation by using the mouse or arrow keys. This changes the point of view for the main camera, which is your view into the simulation. Another important point to mention is that VSE allows you to render the scene in different modes. Visual mode is the default and is a realistic view of the simulation scene. However, the Render menu item allows you to choose from Wireframe, Physics, Combined, or No Rendering modes.
The No Rendering option is included because rendering is just one aspect of a simulation. What is most valuable about running a simulation is the interaction among various entities. Since rendering entities within a simulation scene is expensive in terms of resources, the No Rendering option can be useful when there are a large number of entities involved.

Entities and Entity Types
An entity type allows you to define a new instance of a particular type of entity. For example, the world globe included in the basic simulation environment is a single shape entity type. The entity type acts as a template for the new entity in that it specifies properties associated with a particular type of entity. The values for these properties can be changed once the entity is created, but the entity type defines which properties are included.
VSE requires an entity type in order to add an entity to a simulation. For example, to add a robot such as the Create by iRobot, you would add a new entity from within VSE by clicking Entity and New, while in Edit mode. This will bring up the New Entity dialog box (see Figure 3).
Figure 3 Insert New Entity in New Entity Dialog Box
The Create by iRobot is one of the robots for which MSRS provides an entity type. This means you can add a new Create robot to your simulation by simply using the New Entity dialog box. From the New Entity dialog box, you would select iRobotCreate as the Type and enter a unique name, such as "Create Entity." Once you press OK, the Create robot would appear in the simulation scene.

Programmatically Adding a New Entity
MSRS offers more than one way to create and work with simulations. In addition to VSE, you can add entities programmatically to a simulation by creating a DSS service project. MSRS provides a Visual Studio template that can be used to create a new DSS service. Once MSRS is installed, just select Simple Dss Service (1.5) as the template when creating a new Visual Studio project (see Figure 4).
Figure 4 Create New DSS Service in the Visual Studio 2005 Template
Creating a new DSS service using the template will result in the creation of two class files. The implementation class, which by default has the same name as the project, is where you will add code to create a new entity. Simulations created programmatically will require access to assemblies not included with the Simple DSS Service template. Therefore, you will need to add references to the assemblies listed in Figure 5.
Figure 5 Assemblies Included with Simulation Project
Assembly Name | Description
PhysicsEngine | Provides access to the underlying AGEIA software physics engine.
RoboticsCommon | Provides access to the PhysicalModel namespace, which is used to define the physical characteristics of robots.
SimulationCommon | Provides access to type definitions used when working with the simulation and physics engines.
SimulationEngine | Provides access to the simulation engine.
SimulationEngine.proxy | Represents a proxy for the simulation engine, which is used when loading the simulation engine as a partner.
After adding the references, you will need to add the following namespace declarations to the implementation class file:
using Microsoft.Robotics.Simulation;
using Microsoft.Robotics.Simulation.Engine;
using engineproxy = Microsoft.Robotics.Simulation.Engine.Proxy;
using Microsoft.Robotics.Simulation.Physics;
using Microsoft.Robotics.PhysicalModel;
To understand what code is needed for your simulation, you should first examine the simulation tutorials provided with MSRS. The samples provided in the \samples\simulation tutorials directory from the MSRS installation correspond to the simulations available from the MSRS installed menu. For example, the basic simulation environment is the same as the SimulationTutorial1 project.
If you open the SimulationTutorial1 project using Visual Studio 2005, you can view the code used to create the basic simulation environment. The first thing to notice is the Start method, which is called automatically when a service is started:
protected override void Start()
{
      base.Start();
      // Orient sim camera view point
      SetupCamera();
      // Add objects (entities) in our simulated world
      PopulateWorld();
}
The Start method is where you add code to define your simulation environment. For the SimulationTutorial1 project, this involves setting up the camera and populating the simulation scene with entity objects.
In addition to the main camera, the basic simulation environment contains entities used to represent the sky, ground, box, and world globe. The code to insert the world globe, or textured sphere, is listed in Figure 6.
Figure 6 Insert the World Globe
void AddTexturedSphere(Vector3 position)
{
    SingleShapeEntity entity = new SingleShapeEntity(
       new SphereShape(
          new SphereShapeProperties(10, // mass in kg
          new Pose(), // pose of shape within entity
          1)), //default radius
       position);

    entity.State.Assets.Mesh = "earth.obj";
    entity.SphereShape.SphereState.Material =
       new MaterialProperties("sphereMaterial", 0.5f, 0.4f, 0.5f);

    // Name the entity
    entity.State.Name = "detailed sphere";

    // Insert entity in simulation.
    SimulationEngine.GlobalInstancePort.Insert(entity);
}
The first line of code in the AddTexturedSphere method creates an instance of the SingleShapeEntity. This type represents an entity with a single geometric shape, such as a sphere, and it is useful when you need to add an entity with a very simple physical geometry. In this case, I am creating an entity with a mass of 10 kilograms, or approximately four and one half pounds.
The mesh assigned to this entity is an object file, which has an .obj file extension. The object file is created with a 3D graphical editing tool and exported into an alias object format. MSRS requires that the mesh object file is in this format. The last thing you do in the AddTexturedSphere method is to insert the sphere entity into the simulation environment.

Defining a New Entity in VSE
Now let's create a new robot entity to represent the Boe-Bot by Parallax. The Boe-Bot is a small wheeled robot that supports a two-wheel differential drive system (for a photo, see Figure 7). For more information about the Boe-Bot, visit the Parallax Web site at parallax.com.
Figure 7 Boe-Bot by Parallax
The Boe-Bot is one of several robot platforms supported out-of the-box by MSRS. This means the MSRS installation includes the basic services used to operate the Boe-Bot's drive system and built-in contact sensors. While MSRS includes the platform services for the Boe-Bot, it does not actually include a Boe-Bot entity type.

Creating an Entity Class
To create a new entity type for the Boe-Bot, I need to add a class that derives from the DifferentialDriveEntity. By deriving from the DifferentialDriveEntity class, I'm able to reuse code that defines how the Boe-Bot should behave when it is moving through a simulation. The code used to create the BoeBot entity type is shown in Figure 8.
Figure 8 Create BoeBot Entity Type
[DataContract]
public class BoeBot : DifferentialDriveEntity
{
    Port<EntityContactNotification> _notifications =
           new Port<EntityContactNotification>();

    // Default constructor, used for creating the entity from XML
    public BoeBot() { }

    // Custom constructor for building model from hardcoded values.
    // Used to create entity programmatically
    public BoeBot(Vector3 initialPos)
    {
        MASS = 0.454f; //in kilograms  (around 1 pound)
        // the default settings approximate the BoeBot chassis
        CHASSIS_DIMENSIONS = new Vector3(0.09f, //meters wide
                                         0.09f,  //meters high
                                         0.13f); //meters long
        FRONT_WHEEL_MASS = 0.01f;
        CHASSIS_CLEARANCE = 0.015f;
        FRONT_WHEEL_RADIUS = 0.025f;
        CASTER_WHEEL_RADIUS = 0.0125f;
        FRONT_WHEEL_WIDTH = 0.01f;
        CASTER_WHEEL_WIDTH = 0.008f;
        FRONT_AXLE_DEPTH_OFFSET = 0.01f; // distance from center of robot

        base.State.Name = "BoeBot";
        base.State.MassDensity.Mass = MASS;
        base.State.Pose.Position = initialPos;

        // chassis position
        BoxShapeProperties motorBaseDesc =
            new BoxShapeProperties("BoeBot Body", MASS,
                new Pose(new Vector3(
                0, // Use 0 for X axis offset
                CHASSIS_CLEARANCE + CHASSIS_DIMENSIONS.Y / 2,
                0.03f)), // minor offset in the z/depth axis
                CHASSIS_DIMENSIONS);

        motorBaseDesc.Material =
             new MaterialProperties("high friction", 0.0f, 1.0f, 20.0f);
        motorBaseDesc.Name = "Chassis";
        ChassisShape = new BoxShape(motorBaseDesc);

        // rear wheel is also called the castor
        CASTER_WHEEL_POSITION = new Vector3(0, // center of chassis
             CASTER_WHEEL_RADIUS,              // distance from ground
             CHASSIS_DIMENSIONS.Z / 2);        // at the rear of the robot

        RIGHT_FRONT_WHEEL_POSITION = new Vector3(
             +CHASSIS_DIMENSIONS.X / 2,// left of center
             FRONT_WHEEL_RADIUS,       // distance from ground of axle
             FRONT_AXLE_DEPTH_OFFSET); // distance from center, on z-axis

        LEFT_FRONT_WHEEL_POSITION = new Vector3(
             -CHASSIS_DIMENSIONS.X / 2,// right of center
             FRONT_WHEEL_RADIUS,       // distance from ground of axle
             FRONT_AXLE_DEPTH_OFFSET); // distance from center, on z-axis

        MotorTorqueScaling = 30;

        // specify a default mesh
        State.Assets.Mesh = "boe-bot.bos";
}
The constructor for the BoeBot class is used to set values for several variables defined in the DifferentialDriveEntity class. For example, the Mass is set with a value of 0.454, which represents the mass in kilograms. Additionally, the Boe-Bot chassis is defined in terms of the width, length, and height. These measurements were obtained by weighing the actual robot and measuring it using a metric tape measure.
The position of the Boe-Bot is defined through a set of coordinates that are passed in when the entity is created. These coordinates represent the X, Y, and Z axis points. The MSRS simulation engine uses a right-handed coordinate system, which affects the direction toward which the Z axis points.
The BoeBot constructor also defines the position of the chassis and the wheels within the entity. The DifferentialDriveSystem class makes the assumption that your robot will have two main wheels and a small rear wheel that is mostly used for balancing. Power will be assigned to the left and right motors, which control the main wheels. The difference between the power levels assigned to each wheel determines whether it moves forward, backward, left, or right. This is the same method used to drive the physical robot.
What makes the simulation so attractive is that, in theory, it does not matter whether your robot is virtual or physical—the code used to power the robot and receive data from the sensors will be the same. Some of the code that is used in the simulation project can be reused when working with the actual robot. Now, you may have noticed that I said "in theory." This is because the simulation cannot completely simulate a real-world environment. The simulation cannot account for noise—the stuff you do not expect, such as obstacles being in the wrong location.
What the simulation can do is give you a fairly realistic opportunity to experiment with a new robot design or simulate the interaction of multiple robots. This can be very useful in academic environments where resources are limited and the number of students is high.

Creating a Mesh
Each entity can be associated with a mesh, which is what makes the entity appear realistic. For example, in the case of the globe, the mesh is what makes the globe entity appear like the planet Earth. Strictly speaking, it is not necessary to associate an entity with a mesh, but in the case of complex entities, such as robots, a mesh object is preferable.
Just about any 3D graphical editing tool can be used to create the mesh. For this article, I was fortunate enough to have a colleague, Steve Grand, create a Boe-Bot mesh for me using a 3D package called SoftImage (see softimage.com for more information about this tool). The files associated with this mesh are included with the downloadable .zip file that accompanies this article. To follow along with the article, download the .zip file, extract the files, and copy the contents of the Boe-Bot folder to the /store/media directory associated with your local MSRS installation.
SoftImage is capable of exporting the image to the .obj format. Not all packages are capable of doing this. For example, SolidWorks (see solidworks.com) is a 3D package recommended by MSRS on its Channel9 Wiki (go.microsoft.com/fwlink/?LinkId=114031). Unfortunately, SolidWorks is not capable of exporting to the .obj format, so it recommends a tool named Blender (blender.org) to do the actual conversion. Keep this in mind when selecting a graphics package to create your mesh file.
The details involved with creating the Boe-Bot mesh are beyond the scope of this article, but you should know that it was created by joining multiple polygon mesh shapes. For example, the metal chassis began as a cube shape that was modified to represent the size and shape of the Boe-Bot. Additional cylinder shapes were then added to represent the wheels. A hierarchy was established to bind the wheels to the chassis and allow the entire object to function as a single shape. The result (as seen in Figure 9) is an image that represents the physical Boe-Bot.
Figure 9 Using SoftImage to Create the Boe-Bot Mesh File

Convert the Mesh to Binary Format
MSRS offers a command-line tool that is capable of converting an .obj file to an optimized binary file with a .bos file extension. The benefit of this type of file is that it loads more quickly than the .obj file. The command-line tool, called Obj2bos.exe, can be accessed using the command prompt menu item included with the MSRS installation.
When working with a mesh it is important to remember that materials are used to color physical objects and each entity can be associated with one or more materials. Therefore, when you create your .obj file, it will likely include additional material files with a .mtl extensions. It may also include image files used to create textures. These files must be copied to the same location as the .obj file before using the mesh conversion tool.
The .obj file and all associated files should be placed in the /store/media directory associated with your local MSRS installation. The files associated with the Boe-Bot mesh, which are included with the code download, are: Aluminum.png, Boe-bot.mtl, Boe-bot.obj, BoebotWheel.png, and Pcb.png. Once placed in the media directory, open the MSRS command prompt and type the following:
Obj2bos.exe /i:"store\media\Boe-bot.obj"
The conversion tool will create a file named Boe-bot.bos, and it will reside within the media directory. Leave the file here, as it will be referenced later.

Creating a Simulation Service
Now I'm ready to create the Boe-Bot simulation service. If you are following along from the code download that accompanies this article, make sure you have already installed MSRS and have placed the downloaded code in the \samples folder for the local MSRS installation.
If you are creating the project from scratch, you will need to create a new DSS service using the Visual Studio 2005 template. You can name the project SimulatedBoeBot. In addition to the assembly references mentioned earlier, you will need to add a reference to the Microsoft.Xna.Framework and to add the following namespace references to the top of the SimulatedBoeBot.cs class file:
using xna = Microsoft.Xna.Framework;
using xnagrfx = Microsoft.Xna.Framework.Graphics;
using xnaprof = Microsoft.Robotics.Simulation.MeshLoader;
The Xna framework is used by MSRS to render the entities. The Xna references will be used in the code that defines the Boe-Bot entity type. All the entity types included with MSRS are contained in the Microsoft.Robotics.Simulation.Engine namespace.

Populating the Simulation Scene
One of the primary tasks for every simulation service is to insert entities into the simulation scene. This should be done when the service starts, so typically a call to a method named PopulateWorld is added to the Start method. For the Boe-Bot simulation, the PopulateWorld method will look like this:
private void PopulateWorld()
{
     AddSky();
     AddGround();
     AddBoeBot(new Vector3(1, 0, 1));
     AddBox(new Vector3(2, 1, 1));
}
The AddSky and AddGround methods are used to set up the environment where the BoeBot will reside. For the AddSky method, a new SkyDomeEntity type is created and inserted into the simulation. A directional light, which is meant to represent the sun, is also inserted into the simulation (the code for this method is shown in Figure 10).
Figure 10 Add Sky
void AddSky()  {
    // Add a sky using a static texture. We will use the sky texture
    // to do per pixel lighting on each simulation visual entity
    SkyDomeEntity sky = new SkyDomeEntity("skydome.dds",
                                          "sky_diff.dds");
    SimulationEngine.GlobalInstancePort.Insert(sky);

    // Add a directional light to simulate the sun.
    LightSourceEntity sun = new LightSourceEntity();
    sun.State.Name = "Sun";
    sun.Type = LightSourceEntityType.Directional;
    sun.Color = new Vector4(0.8f, 0.8f, 0.8f, 1);
    sun.Direction = new Vector3(0.5f, -.75f, 0.5f);
    SimulationEngine.GlobalInstancePort.Insert(sun);
}
The AddGround method utilizes the HeightFieldEntity type to create a large horizontal plane at zero elevation. A texture image, provided with the MSRS installation, is used to represent the ground. The code for this method is seen in the following:
void AddGround()
{
    // create a large horizontal plane, at zero elevation.
    HeightFieldEntity ground = new HeightFieldEntity(
        "simple ground", // name
        "03RamieSc.dds", // texture image
        new MaterialProperties("ground",
            0.2f, // restitution
            0.5f, // dynamic friction
            0.5f) // static friction
        );
    SimulationEngine.GlobalInstancePort.Insert(ground);
}
The next thing to add is the Boe-Bot entity. The AddBoeBot method accepts an incoming Vector3 parameter which is used to represent the robot's position. This position will be passed to the BoeBot entity constructor, which was created earlier. The AddBoeBot method will also start the simulated Boe-Bot drive service as an entity partner. The code for this method is shown here:
void AddBoeBot(Vector3 pos)
{
     BoeBot boeBot = new BoeBot(pos);
     boeBot.State.Name = "SimulatedBoeBot";

     // Start simulated Boe-Bot Drive service
     CreateService(
        drive.Contract.Identifier,
          Microsoft.Robotics.Simulation.Partners.CreateEntityPartner(
           "http://localhost/" + boeBot.State.Name));

     SimulationEngine.GlobalInstancePort.Insert(boeBot);
}
The last entity to add is a solid box used to represent an obstacle. The AddBox method will create a box-shaped entity from the SingleShapeEntity type. See Figure 11 for the code for this method.
Figure 11 Create a Box-Shaped Entity
void AddBox(Vector3 position)
{
    Vector3 dimensions =
        new Vector3(0.2f, 0.2f, 0.2f); // meters

    // create simple movable entity, with a single shape
    SingleShapeEntity box = new SingleShapeEntity(
        new BoxShape(
            new BoxShapeProperties(
              100, // mass in kilograms.
              new Pose(), // relative pose
              dimensions)), // dimensions
              position);

    box.State.MassDensity.Mass = 0;
    box.State.MassDensity.Density = 0;

    // Name the entity. All entities must have unique names
    box.State.Name = "box";

    // Insert entity in simulation.
    SimulationEngine.GlobalInstancePort.Insert(box);
}

Creating a Manifest
Most services will partner with other services to access data and functionality needed by the service. These partner services are referenced at the top of the implementation class using the Partner attribute. For example, the Boe-Bot simulation service will partner with the simulation engine service. The code to include this partner declaration looks like this:
//Simulation Engine Port
[Partner("Engine",
     Contract = engineproxy.Contract.Identifier,
     CreationPolicy = PartnerCreationPolicy.UseExistingOrCreate)]
private engineproxy.SimulationEnginePort _engineStub =
     new engineproxy.SimulationEnginePort();
DSS services use an XML-based file known as a manifest to list the partner services associated with a base service. This tells the MSRS runtime how the base service should load and interact with these partner services. Even though the manifest is an XML-based file and can be edited with a text-based editor, it is best to use the DSS Manifest editor that is included with MSRS. The DSS Manifest editor is a visual tool that allows you to drag and drop partner services onto a design surface. Before using the DSS Manifest editor, you will need to successfully compile the base service. This will create the assembly files used by the DSS Manifest editor.
Once the DSS Manifest editor is loaded, a list of all available services will be included in the left-hand pane. To begin, you will need to locate the base service in the list of available services and drag an instance of it onto the design surface. If you do this for the Boe-Bot simulation service, the design surface will include a node for the SimulatedBoeBot service and a sub node for the simulation engine service.
The MSRS installation includes several services in the \samples folder. One such service, the SimpleDashboard, can be used as a control panel for simulated robots. The SimpleDashboard allows you to start other services used to control specific functionality for your robot. For example, the code in the SimulatedBoeBot service simply populates the simulation scene with entities, one of which is the Boe-Bot. There is no code in the service that actually moves the robot. You borrow this code from the Drive service.
In order to load and use the simple dashboard, you must add it to the manifest by locating an instance of SimpleDashboard in the list of services and dragging it to the bottom of the design surface. The end result should look like Figure 12. The last thing to do is to save the manifest to the project directory of the SimulatedBoeBot service and overwrite the manifest named SimulatedBoeBot.mainfest.xml.
Figure 12 Final Version of the Manifest in the DSS Manifest Editor

Running the Simulation
You are now ready to run the SimulatedBoeBot service. This can be done by simply clicking Debug and Run from the Visual Studio 2005 menu. At first, a command prompt window should appear.
Once the service has loaded, two additional windows should appear. The interface for the Simple Dashboard is a Windows form that includes several group boxes. The right-hand side of the form (see Figure 13) includes a group box titled Remote Node. To begin, you will need to enter the name of your local machine (localhost) in the machine textbox and click Connect. This will initiate a connection with the SimulatedBoeBot service and will load entity partner services, such as the drive service that is shown in the directory listbox.
Figure 13 Drive the Boe-Bot in a Virtual World
The drive service is used to send power to the wheels that control the Boe-Bot. This allows you to move the Boe-Bot around the simulation using either the virtual joystick control or an actual joystick connected to your computer. To begin, you will need to double-click the SimulatedBoeBot item that appears in the listbox. You can then use your mouse to drag the round virtual joystick control located in the top left-hand corner of the Simple Dashboard form.
It may take you a while to get used to using the virtual joystick control (see Figure 14 to see what the simulation should look like). Practice moving the Boe-Bot around and seeing how it reacts when it collides with the box obstacle. You can then go into edit mode, select one of the entities, and adjust some of the properties to see how the entity is affected. Take some time experimenting with the simulation environment to get a feel for how it works.
Figure 14 Operate a Simulated Boe-Bot in a Virtual World

Building an Entity without a Differential Drive
In this article, I covered how to create a new robot entity named the Boe-Bot. Because the Boe-Bot uses a differential drive system to control the robots wheels, I was able to create an entity type that derived from the DifferentialDriveEntity class. This allowed me to reuse code provided by MSRS to control a robot that uses this type of drive system.
If you wanted to simulate a robot that used a different drive system, you would need to first add a class that represented that drive system. For example, some robots use what is known as a tricycle drive system. In this case, a single front wheel is used to move the robot, and two side wheels connected to a separate motor are used to steer the robot in either direction.
In order to allow for this type of system in the simulated or physical world, you would need to create a class that accounted for this type of drive system. The steps to do this are beyond the scope of this article, but MSRS does allow you to provide for this type of scenario. This type of expandability is part of what makes MSRS so valuable for robotics researchers. MSRS can be expanded to support any type of hardware platform.

Sara Morgan is a 2007 Microsoft MVP for Office Communications Server. Her first book, Building Intelligent .NET Applications, was published in 2005. In addition to co-authoring several Microsoft Training Kits, she recently published Programming Microsoft Robotics Studio. She currently works as a Robotic Software Engineer at CoroWare.com.


Form Filler
Build Workflows To Capture Data And Create Documents
Rick Spiewak

This article discusses:
  • Building custom activities
  • Interfacing with Microsoft Office
  • Passing data into workflow activities
  • Extracting workflow data to Office documents
 This article uses the following technologies:
Windows Workflow Foundation, 2007 Office System , Visual Basic
Contents
Overall Design
Getting Data into the Workflow
Processing the Data
A Sample Workflow
Deciding Which Way to Go
Supporting Players
Finishing Touches
Workflow describes a method for automating business processes. A workflow might be used to handle customer requests, process insurance claims, or redeem shares in a mutual fund. Workflows may start when a document arrives in the mail, a request is received from a Web site, or a customer calls into a support center. Predefined tasks may then be assigned to be completed, either automated or by human actions.
In the past, attempts to provide this type of automation generally relied on monolithic workflow systems, around which the business process was built. Windows® Workflow Foundation (WF) provides a component-based approach that allows you to build workflow to support a business process, rather than the other way around.
Business processes that call for workflow often require that process-related documents be consumed or created. This requirement can occur, for example, when an application (for a loan, say, or redemption of shares) has been approved or rejected during the workflow process. This might occur after examination by a program (automatically) or an underwriter (manually). A letter might need to be written or a spreadsheet showing balances might need to be produced.
In this article, I will talk about techniques for integrating Microsoft® Office applications with WF. I'll discuss how to use InfoPath® forms and other Office documents to capture data, how to pass data to targeted activities, and how to use these data fields for decisions as well as for creating or populating new Office documents.
I used Visual Studio® 2008 to test a number of these WF and Office integration scenarios, including enumerating named fields, extracting their contents, and filling in documents from templates. I was able to write custom workflow activities to support data entry, filling in various document types and displaying finished documents. I also added designer support for these activities so that their appearance is distinct from other WF activities.

Overall Design
Any design for integrating workflow and Office has three basic components: getting data into the workflow, using the data to create or update Office documents, and storing or returning the output documents. To support these needs, I created a set of interfaces to enable support for a handful of discrete workflow tasks over the underlying Office documents and applications.
The first of these tasks was to get the names of data fields in Office documents. While I'll use the generic term field to describe these, in the case of Microsoft Word, these are bookmarks; Microsoft Excel® uses named ranges, InfoPath fields show up as XML nodes, and PowerPoint® has names for shapes. (Prior to the 2007 Office system, there was no way within the UI to rename shapes. In PowerPoint 2007, you can open the Selection Pane to do this.)
Next is the task of populating these fields with data. I chose to accomplish this by accepting an input Dictionary(Of String, String) and matching the contents of the dictionary to fields in the document. In addition, I implemented the IDisposable interface so that I could clean up COM objects.
In implementing activities to fill in the Office documents, I used a base class named OfficeFormFill class. This supports the disposable pattern and includes a shared Designer that lends visual uniformity to the activities. From this base class, I then derived my custom activity classes.
The workflow was built on custom activities called WordFormFill, ExcelFormFill, PowerPointFormFill, and DataEntryActivity. The function of DataEntryActivity is simply to allow for the introduction of workflow-related variables that are not specific to a document into the generic dictionary structure used by the various OfficeFormFill activities. It uses an Office document as a template for this purpose, enumerating the named fields and presenting them to the user to be filled in. The template can be from any of the supported document classes, without regard to the eventual target document or documents to be created and filled in by the workflow.

Getting Data into the Workflow
One of the first challenges I faced in integrating Office documents into workflows was how to surface data contained by an input document from within the workflow. The standard workflow paradigm relies on advance knowledge of the names of properties associated with activities. Dependency properties can be promoted to be made visible to the workflow, and to other activities. I decided that this was too rigid, as it would require that the overall workflow design be tied to specific fields in the input document. In the case of Office integration, the workflow activity is acting as a generic proxy for any Office document. It isn't realistic to try and predetermine the names of the fields in the document, as this would require a custom workflow activity for different types of documents.
Looking at the way arguments are passed into workflows, and by extension activities, you can see that they are passed as a generic Dictionary(Of String, Object). The WF runtime then binds the elements of the dictionary to properties of the workflow itself. To fill in fields in an Office document, you need two pieces of information: the name of the field and the value to insert. The general strategy I have adopted in the past has been to enumerate the named fields in the document and then match them to the WF input parameters dictionary by name. If a document field matches the key in the dictionary, it is passed to the input parameter of the same name. In this case, however, this was not the way I thought they should be handled, because properties would have to be created on the workflow for each of the potential document fields that might be used.
Rather than naming and promoting properties in an activity to correspond with fields in the document, I decided to use a generic Dictionary(Of String, String) to convey these. I named this parameter Fields, and use it in each of the workflow activities. The key is used to match the field name; the value is used to populate the field contents. This Fields dictionary is then passed as one of the entries in the parameters passed to the workflow. So the real parameters, at least as far as Office integration is concerned, are contained in a Dictionary within a Dictionary (see Figure 1).
Figure 1 Passing Fields to the Workflow
Private WithEvents workflowRuntime As WorkflowRuntime = Nothing
Private workflowInstance As WorkflowInstance = Nothing
Private WithEvents waitHandle As New AutoResetEvent(False)
Public Sub main()
   Dim WorkflowType As Type = GetType(Workflow4)
   Dim Params As New Dictionary(Of String, Object)
   Dim Fields As New Dictionary(Of String, String)
   Params.Add("Fields", Fields)
   ' Start the workflow
   workflowRuntime = New WorkflowRuntime
   workflowInstance = _
      workflowRuntime.CreateWorkflow(WorkflowType, Params)
   workflowInstance.Start()
   waitHandle.WaitOne()
I wanted all of the workflow activities to be broadly useful and to have more than one strategy available for specifying the input document or template. To allow for this, all of the activities also have in common the parameter InputDocument. This is a dependency property so it can be promoted as the needs of the workflow dictate. It holds the path to an input document or template. However, the code also provides for using a Field parameter whose name matches the activity's name if it contains a path to a document or template suitable for the target Office application.
Any real workflow will have a source of input data. For demonstration purposes, I used a DataEntry activity, which can draw its template (the fields and default values) from any supported Office document type. It displays an input form, which allows the user to specify a target activity. This can be a particular OfficeFormFill activity, or a composite activity. My example is an IfElseActivity. The code needs knowledge of only the general Fields property used by all OfficeFormFill activities.

Processing the Data
As I noted earlier, each of the Office document types has its own collection of named fields. Each of the OfficeFormFill-derived activities was written to support a particular document type. While it would certainly be possible to combine functions which reference multiple document types (DataEntryActivity was an example of this), there is one caveat: if you reference one of the Office Primary Interop Assemblies (PIAs) in your code and it isn't present on the system your code is ultimately deployed to, you may get an exception even if the execution path doesn't use the specific PIA. For example, a Select Case or If statement that seems to bypass the absent component will still result in an exception. That's why it pays to isolate the calls to Office components. If you decide to create a combined activity, be sure to maintain this isolation. And, of course, always test your application in all potential target environments.
The activities that support each of the Office document types all follow the same pattern. If the InputDocument property is provided, it is used as the path to the document or template. If the InputDocument property is null, the activity looks in the Fields property for a key that matches the name of the activity. If this is found, it is examined to see whether it contains a path with a suffix matching the type of document the activity handles. If these conditions are met, the InputDocument property is set to this value.
Each matching entry from the Fields collection is used to fill in the corresponding field in the document. The result is placed into the output document. This is either passed in as the corresponding dependency property (OutputDocument), or is found in the Fields collection as the Output KeyValuePair entry. In all cases, if the output document has no suffix, an appropriate default suffix is appended. This allows the same value to potentially be used to create different document types or even multiple documents of different types.
The output document will be stored at the path specified. In most workflow environments, this would be a network share or a SharePoint® document library. For simplicity, I used a local path.
Each of the activities also has a field named Visible, to optionally show the document as it's being filled in. Figure 2 shows the code for filling a Word document. Note in particular the line:
WordFiller = New WordInterface(InputDocument, Fields)
Figure 2 Populating a Word Document
<STAThread()> Protected Overrides Function Execute _
  (ByVal executionContext As ActivityExecutionContext) _
  As ActivityExecutionStatus

  Dim Status As ActivityExecutionStatus

  ' Open the target document or template
  If String.IsNullOrEmpty(Me.InputDocument) Then
    If Me.Fields _
      IsNot Nothing AndAlso Me.Fields.ContainsKey(Me.Name) Then
      ' Use a field named for *this* activity if it is a document
      Dim NameValue As String = Fields(Me.Name)
      Select Case System.IO.Path.GetExtension(NameValue).ToLowerInvariant
        Case ".doc", ".docx", ".dot", ".dotx"
          InputDocument = NameValue
        Case Else
          Throw New ArgumentException( _
   "Input Document Invalid or Missing")
      End Select
    End If
  End If

  ' Create or open the required document from an input
  ' document or template
  WordFiller = New WordInterface(InputDocument, Fields)

  ' Production workflow may not want to show the document
  If Me.Fields.ContainsKey("Visible") Then
    Boolean.TryParse(Me.Fields("Visible"), WordFiller.Visible)
  End If

  ' Get success or failure from the Word Interface class
  Dim Success As Boolean = WordFiller.FillInDocument()
  WordApp = WordFiller.WordApp

  If Success Then
    ' Find the target output document
    If String.IsNullOrEmpty(Me.OutputDocument) Then
      If Me.Fields.ContainsKey("Output") Then
        Dim NameValue As String = Fields("Output").ToString

        If NameValue.EndsWith(".doc", _
          StringComparison.CurrentCultureIgnoreCase) _
          OrElse NameValue.EndsWith(".docx", _
          StringComparison.CurrentCultureIgnoreCase) Then

          ' Set the document property to the provided name
          Me.OutputDocument = NameValue
        Else 'Force .doc suffix
          Me.OutputDocument = NameValue & ".doc"
        End If
      End If
    End If

    ' Save the output
    WordApp.ActiveDocument.SaveAs(Me.OutputDocument)

    Cleanup()

    Status = ActivityExecutionStatus.Closed
    executionContext.CloseActivity()
  Else
    Cleanup()

    Status = ActivityExecutionStatus.Closed
    executionContext.CancelActivity(Me)
  End If

  Return Status
End Function
This is where the WordInterface class instance was constructed and passed the path to the document to use as a template, along with the field data. These were simply stored in the corresponding properties for use by the methods of the class.
The WordInterface class provides the functionality to fill in the target document (see Figure 3). If the input document is a template, a new instance of the document is created. If it is a document, it is opened as read-only to prevent accidental overwrite. This class also inherits its Visible property from the base class. Note that the code here omits some error checking for the sake of brevity.
Figure 3 FillInDocument
Public Overrides Function FillInDocument() As Boolean
  Dim Status As Boolean = False
  _WordApp = New Word.Application
  WordApp.Visible = Visible

  ' Check for template
  Select Case Path.GetExtension(Document).ToLowerInvariant
    Case ".dot", ".dotx"
      _WordDocument = WordApp.Documents.Add(Document)
    Case ".doc", ".docx"
      _WordDocument = WordApp.Documents.Open(FileName:=Document, _
        ReadOnly:=True)
  End Select

  ' Determine dictionary variables to use
  ' based on bookmarks in the document matching Fields entries
  If WordDocument IsNot Nothing _
    AndAlso WordDocument.Bookmarks.Count > 0 Then

    Dim BookMark As Word.Bookmark = Nothing
    For i As Integer = 1 To WordDocument.Bookmarks.Count
      BookMark = WordDocument.Bookmarks(i)
      Dim BookMarkName As String = BookMark.Name
      Dim rng As Word.Range = BookMark.Range
      If Me.Fields.ContainsKey(BookMarkName) Then
        rng.Text = Fields(BookMarkName).ToString
        'This results in the bookmark being lost, it needs to be replaced
        WordApp.ActiveDocument.Bookmarks.Add(BookMarkName, rng)
      Else
        ' Handle special case(s)
        Select Case BookMark.Name
          Case "FullName"
            rng.Text = GetFullName(Fields)
        End Select
      End If
    Next
      Status = True
  Else
    Status = False
  End If

  Return Status
End Function
I added a special case field name called FullName. If the document contained a field with this name, I concatenate input fields called Title, FirstName, and LastName to populate it. Since all Office document types have similar needs, this function was moved into the base OfficeInterface class along with some other common properties. The OfficeInterface classes also handled the required cleanup logic to ensure the proper disposal of the COM objects created in order to manipulate the Office documents.
Each of the OfficeFormFill classes has an OutputDocument property. These can be directly set by several means. Within the designer, a property can be bound to a workflow-level parameter (including properties promoted from other activities) or to a constant value. At run time, each of the OfficeFormFill types will look in its OutputDocument property for the path to save its document. If this is not set, it will look within its Fields collection for a key named Output. If the value ends with an appropriate suffix, it is used as-is. If it doesn't have an appropriate suffix, one is added. The Activity then saves the output document. This allows maximum flexibility in deciding where to put the path to the output document. Again, because the suffix is omitted, the same value can be used by any of the OfficeFormFill types to save the document in the correct respective format. (In Word and PowerPoint, the suffix I appended is the compatibility mode version. Excel provides a property, Excel8CompatibilityMode, that can be used to distinguish the document type, so you can decide this directly.)

A Sample Workflow
Figure 4 shows the sample workflow I'll use to demonstrate how the integration works. I'll go through each of the activities in turn, and talk about what they do.
Figure 4 Document Creation Workflow
At the top, EnterCustomerData is an instance of the DataEntryActivity class. It relies on a DataEntryDocument property that was, in this case, simply set at design time (see Figure 5). This property could also have been set by the program that launched the workflow. DataEntryActivity presents a Windows Form with a DataGridView control, which is populated by extracting the named fields from DataEntryDocument. It also shows the path to this document. The user can add or modify the values in the fields.
Figure 5 Bindings for EnterCustomerData Activity
DataEntryDocument can be any of the supported Office document types. For this example, an InfoPath document template is used. To extract the fields from the document, the appropriate OfficeInterface class is called. It loads the target document into the appropriate application and enumerates the fields (and their contents if present). I used a checkbox, set by default, to exclude the default names for shapes in PowerPoint. These have names like TextBox 1. The code behind DataEntryActivityForm includes a routine to exclude field names based on a regular expression, and this was used to skip including these values and names in the DataGridView.
One of the fields provided by DataEntryActivity is TargetActivity. This is just the name of the activity whose Fields property is to be populated with the fields collected from the input document. DataEntryActivity could then target any of the OfficeFormFill derived activities or any CompositeActivity. For this article, the TargetActivity field is shown as pre-populated with CustomerScenario.
The target activity is passed the data from DataEntryActivity. When the target is a composite activity, this process can require walking up the activity tree to find the appropriate Fields property. I created a WorkflowUtilities class to contain routines for locating activities by name or by desired property.

Deciding Which Way to Go
The CustomerScenario activity is an IfElseActivity (which derives from CompositeActivity). The IfElseActivity type executes each branch in turn looking for a return value of True. Once a branch returns True, other branches are not executed.
The CompositeActivity's structure is maintained within the Extensible Application Markup Language (XAML) file called Workflow4.xoml, and its logic is maintained in the code file called Workflow4.xoml.vb. The first part of the CustomerScenario activity is shown in Figure 6.
Figure 6 Excerpt from CustomerScenario
<IfElseActivity x:Name="CustomerScenario">
  <IfElseBranchActivity x:Name="ProcessApproval">
    <IfElseBranchActivity.Condition>
    <CodeCondition Condition="ifElseBranchActivity1Condition" />
    </IfElseBranchActivity.Condition>
    <CodeActivity x:Name="codeActivity1" ExecuteCode=
      "{ActivityBind Workflow4,Path=codeActivity1_ExecuteCode1}" />
    <ns1:WordFormFill Description="Fill in fields in a Word document"
      x:Name="WriteCustomerLetter" Fields="{x:Null}"
      OutputDocument="{x:Null}"
      InputDocument=" C:\MSDN Workflow\Templates\Customer Letter.doc" />
</IfElseBranchActivity>
For the code behind the branch to process the decision, a return value is set in the Result property of the event arguments passed to each branch. The decision to continue in a particular branch is made in the code, based on the value of the Status field passed to the activity. The branch labeled ProcessApproval looks for a value of Approved. The ProcessDisapproval branch looks for Disapproved. Any other value is handled by the ProcessUndecided branch. Figure 7 shows the code executed in the ProcessApproval branch.
Figure 7 ProcessApproval
Public Sub ifElseBranchActivity1Condition(ByVal sender As Object, _
  ByVal e As ConditionalEventArgs)
  ' Look for status matching desired value for *this* branch
  If Me.Fields.ContainsKey("Status") AndAlso _
    Me.Fields("Status") = "Approved" Then

    ' Look for a WordFormFill activity as a child to *this* branch
    Dim target As Activity = _
      WorkflowUtilities.FindActivityByType( _
      GetType(WordFormActivity.WordFormFill), _
      (DirectCast(sender, Activity)))

    If target IsNot Nothing Then
      Dim TargetActivity As WordFormActivity.WordFormFill = _
        DirectCast(target, WordFormActivity.WordFormFill)
      TargetActivity.Fields = Me.Fields
      ' Set input document by using field named for target activity
      TargetActivity.Fields.Add(TargetActivity.Name, Me.InputDocument)
      e.Result = True

    Else
      e.Result = False
    End If

  Else
    e.Result = False
  End If

End Sub
The other branches are similar, but pass their data on to a PowerPointFormFill or ExcelFormFill activity type. In a real business process, they might simply use different Word templates to do something like produce a customer letter rather than interfacing with additional Office document types.
The WordFormFill instance executed in this branch has its input (template) document set at design time as shown in Figure 8. Note that the Fields property is initially null. This is because it is set programmatically.
Figure 8 WriteCustomerLetter Properties

Supporting Players
Part of the approach used in the example workflow relies on the ability of one activity to find another. This requires that the activities be child activities of a CompositeActivity, which include the major workflow types: sequential, state machine, and rules-driven. This means that any nontrivial workflow will have this type of relationship among its activities.
The WorkFlowUtilities class provides methods to search a tree of activities for a descendant activity by name or type. It also provides functions to search higher in the tree for ancestor activities with a particular property.
These utility methods support finding target activities to pass parameters to, as well as finding the source for input parameters. So, for example, when the DataEntryActivity is passed a TargetActivity parameter in its Fields collection, it can find it anywhere in the activity tree starting with its own container:
Dim EntryActivity As Activity = Nothing
EntryActivity = WorkflowUtilities.FindActivityByName( _
  TargetActivityName, Me.Parent)

Finishing Touches
The example workflow announces the activity's completion. The activity selected by the Status field creates the output document in the specified location. From here, it can could be picked up by other activities for additional processing.
I've outlined a basic design approach to interfacing workflow with Office client applications. By adhering to the principles of object-oriented design, you can create reusable workflow activities and supporting classes that meet a variety of similar needs.

Rick Spiewak is a Lead Software Systems Engineer with The MITRE Corporation. He is working with the U.S. Air Force Electronic Systems Center on Mission Planning. He has worked with Visual Basic since 1993 and the Microsoft .NET Framework since 2002. He was a beta tester for Visual Studio .NET 2003.


GUI Library
Bring The Simplicity of Windows Forms to Native Apps
John Torjo

This article discusses:
  • The problem with GUI programming
  • Creating window objects
  • Handling events and notifications
  • Forms and controls
This article uses the following technologies:
Win32 API, C++
Contents
It's Native and Portable
No windows.h
Dealing with Each Window
Straightforward Code
Controls Versus Forms
Form Programming
Dealing with Forms
Out with the Old IDs
Events and Notifications
Menus, Shortcuts, and the Like
Tab Controls and Forms
Resizing
Integration with Visual Studio 2005
Implementing Behavior
The problem with GUI programming in C++ is that most libraries are too low level, putting too much of the burden on the programmer. They rely on C-like structs, or their wrapper classes don't hide enough complexity. Also, they don't make event programming simple enough, instead forcing you to have to know about underlying WM_ messages.
In this article, I will show you eGUI++, a C++ library I have written that gives you, the client programmer, a high-level interface for dealing with GUI applications. It hides complexity, making event programming quite simple by completely hiding knowledge of WM_ messages. You won't need to deal with any C-like raw structure; you always deal with classes. All in all, eGUI++ client code is simple to read and simple to write.
eGUI++ is Windows®-only. I don't truly believe in cross-platform GUI applications, unless such an application is either trivial, a simple testing framework, a prototype, or just educational. More importantly, I strongly believe in taking advantage of all the underlying OS is offering. And for Windows XP and Windows Vista® that's quite a bit.

It's Native and Portable
For those looking for CLR code, you already have managed C++. That is a good platform, so there's no need to improve there. For the rest of you craving a good library to generate native Windows code for Windows 2000 and newer operating systems, keep on reading. You'll love the result; the lib is straightforward to use, taking advantage of the OS you're targeting. And you won't need the Microsoft® .NET Framework at all. The code you'll write will feel like C++. Additionally, the code you'll write is not Visual C++ compiler-specific. You can compile it with g++ (GNU C++ Compiler) 4.1 if you wish. Basically, if you wrap the Win32® API, there's nothing preventing you from writing portable code.
That said, for a non-trivial GUI, you'll need a good IDE such as Visual Studio® 2005 or Visual Studio 2008 Express editions. I've tweaked my library to be integrated with Visual Studio 2005 Express and newer and to give you an even better GUI experience. What I really focused on is code completion to make sure that when you create a new GUI class or extend an existing one, the IDE will do its best to help.
I want to enjoy writing GUI applications. Thus, my goals in creating eGUI++ were to make GUI code easy to read and write. For example, I've implemented code completion features wherever possible. GUI programming is now safe (in case there's an error, I catch it at compile time whenever possible; otherwise, a run-time exception is thrown). eGUI++ is resource-editor friendly (it integrates with Visual Studio 2005 and newer versions of resource editor).

No windows.h
The main problem with including windows.h is that it offers too much room for error. What's to stop you from monitoring an event that will never arrive? Imagine you're a button class, but you're waiting for, let's say, a keyboard event; it's not going to happen.
Why should you need windows.h anyway? You should be able to write Windows applications in C++ using regular C++ classes. Thus, you shouldn't need to know the windows.h internals: no WM_LBUTTONDBLCLK, WM_LBUTTONUP, and other lengthy event names. No LPNMITEMACTIVATE, NMHDR, or any other dubious C structure. No more C-style casts either. The primary function of a good C++ GUI library should be to abstract away the Win32 API and allow you to deal with classes.
Have you had enough of dealing with raw C structures like you see in Figure 1? I know I have. So now I write code like this:
wnd<rebar> w = new_(parent);
rebar::item i(rebar::item::color | rebar::item::text);
w->add(i);
Figure 1 Darn that Old Window Code
// The old way
hwndRB = CreateWindowEx(WS_EX_TOOLWINDOW,
  REBARCLASSNAME, NULL,
  WS_CHILD|WS_VISIBLE|WS_CLIPSIBLINGS|
  WS_CLIPCHILDREN|RBS_VARHEIGHT|
  CCS_NODIVIDER,
  0,0,0,0, hwndOwner, NULL, g_hinst, NULL);
...
rbi.cbSize = sizeof(REBARINFO);
rbBand.cbSize = sizeof(REBARBANDINFO);
rbBand.fMask  = RBBIM_COLORS | RBBIM_TEXT |
  RBBIM_BACKGROUND;
rbBand.fStyle = RBBS_CHILDEDGE;
As you can see, eGUI++ hides the complexity: you deal only with C++ classes, You don't need to remember complicated API functions (like CreateWindowEx), constant names (WS_* constants) or complex C structures like REBARPARAMINFO.
eGUI++ targets Windows 2000 and newer. By default, it targets Windows XP SP2. However, you can choose to target a different OS so that less or more features are available. If you want to target a different OS, just #define EGUI_OS to a different OS constant before including any eGUI++ headers (see Figure 2).
Figure 2 Designating the OS
// code from eGUI++
struct os {
 typedef enum type {
 win_2k,
 win_2k_sp4,
 win_xp,
 win_xp_sp2,
 win_vista
 };
};

#ifndef EGUI_OS
#define EGUI_OS os::win_xp_sp2
#endif
You'll be happy to know that there are very few #ifdefs in the code, so it's much easier to read. What you'll notice instead is that some properties are OS-specific:
property<int,os::win_xp> some_prop;
If you target an earlier OS and try to use the property above, for instance, a compile-time error will be issued.

Dealing with Each Window
Usually it's you, the programmer, who decides how long an object lives. But a big problem in GUI programming is that there is a difference between the visual window and the window object—and it's the user who decides when a window is to be closed. In your code, then, you can have a valid pointer or reference to a window object where the window has been destroyed by the user. As this makes it hard to maintain a one-to-one correspondence where a window on the screen represents an object instance and vice versa. One clear restriction that results from this scenario is that you can't have local window instances (which would be destroyed when the scope exists):
{
form f(...);
f.show();
...
}
Assume your form, f, is shown on screen. What should happen when you exit f's scope? You have two choices: you either destroy the (on-screen) form or you leave the form on screen while its corresponding C++ instance is destroyed. Neither choice is reasonable. In the former case, this could confuse the user, leaving him wondering where the form went. In the latter case, you'll leave the form on the screen, but it won't respond to any events because its corresponding C++ instance is gone. In addition, the user might have already closed the on-screen form while f is in scope. Thus you'd end up working with an object that doesn't exist on screen.
The solution: always access the window through (an indirect) pointer. Then, when the user closes the on-screen window, the corresponding C++ instance is marked as invalid; if you try to access it, an exception is thrown. You can always find out if a window is valid or not and you can destroy the window yourself, like so:
wnd<> w = ...;
// is window valid?
if ( is_valid(w) ) w->do_something();
// is window valid?
if ( w) w->do_something();

// destroy the window
delete_(w);
Because each window on the screen has a corresponding C++ instance, you deal with windows using the wnd<> template class, which represents a shared (ref counted) pointer to a window. The wnd<> class has one optional argument: the window type. This is basically what you'd expect. By default, it's window_base. Or it can be a window class such as text, label, rebar, edit, and so forth. Figure 3 shows a few examples of using window objects and casting between them.
Figure 3 Creating Window Objects and Casting
// when constructing a window, you can specify its type
wnd<> w = new_<form>(parent);
w->bg_color( rgb(0,0,0));

// when constructing a window, if you don't specify its type,
// it will guess it, based on who you assign it to
wnd<button> b = new_(w, rect(10,10,200,20) );
b->events.click += &my_func;

// destroying a window
delete_(b);

// casting - if it fails, it throws
wnd<form> f = wnd_cast(w);

// casting - if it fails, returns null
if ( wnd<edit> e = try_wnd_cast(e) )
  e->text = "not nullio";
Note that you create a window using the new_ function and delete it using the delete_ function (again, it's usually the user who closes a window). Additionally, if you have a window of type X (window_base is the default), and you want to know if it's of type Y as well, you can use casting. Casting is always explicit. There are two types of casts: wnd_cast, which, if it fails, throws an exception, and try_wnd_cast, which, on failure, returns a null window.
Sometimes, when developing an eGUI++ class, besides deriving from its base class you'll want to inherit some extra behavior, such as resizability, skinability, and so on. In this case, you can create multiple re-usable behavior classes and additionally derive from them.

Straightforward Code
It's refreshing to see GUI code that's easy to write and read. I've used every trick in the book to make sure code-completion helps as much as possible. Dealing with a big GUI library, there are always things you tend to forget: property names, event names, flags, and so on. I've dealt with each. I've used doxygen for the documentation; it simply shines. The more I use it, the more I love it.
Browsing through the documentation is very easy. For a property name, just type w-> and, as shown in Figure 4, you'll see the methods and properties (the properties are shown as member variables, so they are easy to differentiate). For event names, it's easy to remember the events that a class can handle; just type class_name::ev::, and after the scope operator, code completion jumps in and shows you the events. But dealing with flags is where eGUI++ really shines. For each property that can be a combination of flags, to find out your available flag options, just add "." to the flag property and code completion will come to the rescue again. As a bonus, I added operator overloading for properties. Thus, this code is valid:
w->text = "hello";
w->text += " world";
w->style |= w->style.tiled;
Figure 4 Code Completion
And just in case you forget the list of controls you have at your disposal, I've added a namespace just for that called egui::ctrl.

Controls Versus Forms
If you've done Win32 GUI programming in the past, you're familiar with dialogs. You're also familiar with the fact that the API treats dialog creation (::CreateDialog) very differently from window creation (::CreateWindow[Ex]). As a programmer, you shouldn't need to remember two complicated functions with quite different signatures. They're both types of window. eGUI++ has only one way to create a window: the new_ function.
With regard to different types of windows, the name form is more expressive than the name dialog. It describes a window that shows other controls, those controls containing data. I allow both names, but I prefer form. In fact, in code you'll see this:
typedef form dialog;
Conceptually, there are only two types of windows: controls and forms. A control is a window that displays some data that it might permit the user to modify. Every control class derives from "control" class. A form is a window that hosts one or more controls, and some of its own logic (for example, logic that allows the manipulation of some data).
The available functionality of each window type varies based on what the window is supposed to do. For example, note that the form allows you to enumerate its child controls, while the control doesn't; this way, your code will be less prone to errors. Also, you'll very seldom need to create controls; usually they're already on the form because you've put them there using the resource editor.
Forms themselves come in two flavors: modal dialogs and message boxes. To create a modal dialog, just add the form::style::modal when creating the form. To create a message box, use the msg_box<> function, specifying the buttons as template arguments:
if ( msg_box<mb::ok | mb::cancel>("q") == mb::ok)
    std::cout << "ok pressed";
Additionally, the msg_box<> knows at compile-time whether or not a button combination works:
// ok
   msg_box<mb::yes | mb::no>("q");
   // compile-time error
   msg_box<mb::ok | mb::yes>("q");

Form Programming
To reiterate, a form is what the Win32 API calls a dialog. For Windows Forms, form programming has proven to be a winning strategy. On each form you have some controls, and each form solves a single task. Instead of the old and complicated Single Document Interface (SDI) or Multiple Document Interface (MDI), you can use tabs, which can host controls or other forms. Thus, you won't see any CFrameWnd, CMDIChildWnd, or anything similar; there's no need for them. If you need to host multiple forms on a form, simply use tab_form class. It allows you to add child forms, each on its own tab.

Dealing with Forms
As much as I hate wizards, I do believe a few, now and then, make programming tasks easier. In this case, to create a form I have created a New Class Wizard. In the Class View, select Add Class, and at Categories, select eGUI. On the left, select eGUI Form, click Add. Specify the class name, and that's it (Figure 5). The wizard will create a header file called <dlgname>.h, a source file called <dlgname>.cpp, and an extra header file called <dlgname>_form_resource.h, which eGUI++ will maintain internally.
Figure 5 Add Class
That last header file contains all the names of the controls you're using in the form. Thus, you won't need to create extra control variables and use data exchange, like in MFC. You'll use the controls directly. Assume you have a login dialog, which has two edit boxes (User Name and Password) and two buttons (OK and Cancel), as shown in Figure 6.
Figure 6 Edit Boxes and Buttons
The following files will be generated for you:
// login.h
#pragma once
#include "login_form_resource.h"
struct login : form,
 private form_resource::login {};

// login.cpp
#include "stdafx.h"
#include "login.h"
Note that the code is quite straightforward; there is no wizard-style code like "enum {IDD = ... }" or message maps. You don't need to provide a custom constructor if you don't want one; the default will do just fine.
The login class derives privately from form_resource::login, which is implemented in login_form_resource.h (this file is maintained by the eGUI++ library); the form_resource::login class contains information about the form's controls (their name and type, and the ability to catch notifications from the controls); you can choose to change the type of accessibility for the derivation, although I'd advise against it. Just as your class' member data is usually private, the same is true of form—its controls should usually be private.
Now, the generated form_resource::login will look similar to this:
// login_form_resource.h
#pragma once
struct form_resource::login {
 // ... (code to allow
 // handling of notifications)
 wnd<edit> username;
 wnd<edit> passw;
 wnd<button> ok, cancel;
};
This will allow you to easily manipulate your form's controls. Assume you want to make sure the password is "secretword":
void login::on_button_click(ev::button_click &, ok_) {
 if ( passw->text == "secretword")
 { pass_ok = true; visible = false; }
}
As you can see, just like in Visual Basic®, to hide a form you simply set its visible property to false.

Out with the Old IDs
You've probably dealt with the resource editor before. And you've encountered the many types of resource prefixes, such as ID_, IDD_, IDC_, IDR_, IDS_, and so on. Prefixes are good for the resource editor. However, in code, they're just extra information you neither need to remember nor care about. In an eGUI++ application, you'll never need to remember those prefixes because they're completely ignored.
For instance, the previous names (username, passw, ok, cancel) are shortcuts from the resource editor. The eGUI++ library automatically strips their ID* prefixes. The original names could have been IDC_username, IDC_passw, IDOK, and IDCANCEL.

Events and Notifications
As I've mentioned, you don't need to remember a single WM_ message. That said, events are tough to tame. There are quite a few of them out there and you need an easy way to find out which events you can respond to and respond to them easily. You need easy ways to be notified of events happening on your form's controls, to be able to extend controls, and to add your own events.
Every window class (control or form) can generate events. For each, there's an event handler that catches all events. For each event, a function is defined that handles that event; that function is virtual, and its implementation does nothing. Each event handler function has one argument: the event data.
For existing controls, the corresponding event class is called handle_events::control_name. Each existing eGUI++ window class wnd_name already derives from handle_events::wnd_name. If you extend an existing window class, you can always handle its events. (For simplicity, all event handler functions start with "on_".) For instance:
struct my_btn : button {
 void on_char(ev::char& e) {
 cout << "typed " << e.ch;
 }
};
Those of you who have dealt with other GUI libraries know that life isn't as easy as you might think based on what you just saw. Existing controls don't send events but rather notifications. The notifications are in the form of WM_COMMAND/WM_NOTIFY messages, and they are sent to the control's parent, not to the control itself. That might seem reasonable at first: it's the control's parent (the form) that needs to be notified. However, that makes extending control classes quite difficult. What if you want to make a tree to visualize the current file system? You'd need to catch events, such as item expanding (TVN_ITEMEXPANDING), which are sent to the parent of the control. Then you'd need a way to pass the notification down to the control itself.
With eGUI++, notifications are events. Thus, they are always sent to the control and then to the control's parent. When you extend a control class via inheritance, each notification translates into a different event. For example, if you wanted to create a list control that shows a combobox instead of an edit control when the user is editing the first column, the code would look like this:
struct list_with_combo : list {
 ...
 void on_begin_label_edit(
  ev::begin_label_edit & e) {
 e.allow_default = false;
 combo->rect(...);
 combo->visible = true;
 }
 wnd<combo_box> combo;
};
To handle an event, you overload an event handler function, like so:
struct my_btn : button {
 void on_char(ev::char& e);
};
Here you respond to the character pressed event, or, for you Win32 API lovers, the WM_CHAR message.
Remember that for the on_my_event event handler function, the event argument is always of ev::my_event type. All events your class can handle are an ev:: struct. By simply typing ev::, code completion will show you all events your class can handle (see Figure 7). Note that the easiest way to find out the event information is to type e. and let the code completion show all data related to the event (see Figure 8).
Figure 7 Code Completion Shows Events
Figure 8 Get Event Information
You can browse through the docs for a control's events: just select the control, then its ev class, and you'll see all its events. The library can send the same event to several event handlers (for instance, notifications are sent to the control, and then to the parent of the control).
All events have the .sender property; this is the control that sent the event (it's useful for notifications, specifically in order to know who sent the notification). All events have the .handled property; it can have two values: handled_partially (default) and handled_fully. By setting this property to handled_fully, you can stop event processing; even if there are more event handlers, they won't be called. For instance, if you were extending the edit class and wanted to prevent the parent from being notified of text changes, you'd write the following:
struct independent_edit : edit {
                      void on_change(ev::change &e) {
                      e.handled = handled_fully;
                      }
                     };
Extending controls is simple, as I've shown above. However, handling notifications on forms should be simple as well. When handling a notification, you need to know who sent it (e.sender). But more to the point, you want to be able to act on a notification from a specific control. Therefore, the event handler function gets an extra argument: the control name, followed by an underscore (_). For instance, to find out what the user is typing in the username edit box, you would run this code:
void login::on_change(
 edit::ev::change &e, username_) {
 cout << "name=" << e.sender->text;
}
As an example, assume you want to convert currency between U.S. dollars and Euros. When you enter a value in the EUR box and type something, it updates the USD box. If you enter a value in the USD box and type something, it updates the EUR box, as you see in Figure 9. Here's the code to make it work:
struct convert : form, form_resource::convert {
 double rate;
 convert() : rate(1.5) {}
 int mul_str(const string& a, double b) { ... }
 void on_change(edit::ev::change&, eur_) {
 usd->text = mul_str ( eur->text, rate); }
 void on_change(edit::ev::change&, usd_) {
 eur->text = mul_str ( usd->text, 1/rate); }
};
Figure 9 Currency Converter
The code is self-explanatory; mul_str multiplies a double by a string by converting the string to a double and multiplying it by the conversion rate.
To handle the events as I did above, I had to do quite a bit of work. Assume you have a form with three edit boxes. Each edit box will generate a certain set of events. For each such event (for instance, on_change), I could either generate one overridable function for each control
void on_change(edit::ev::change& e, ctrlname_);
or generate one overridable function:
void on_change(edit::ev::change& e);
I prefer the former solution—the client code is much simpler (and much more analogous to the Visual Basic approach). You can easily see what you're handling (as opposed to the latter solution, where within the implementation of the event you'd have to manually ask what control generated the event via e.sender).
That's why I implemented the first solution. Under the covers, however, there's a lot of work involved. eGUI++ monitors the resource editor. When a new control is added or a control is renamed, it updates all <dlgname>_form_resource.h files. Note that for each <dlgname>_form_resource.h file in the form_resource::<dlgname> class you must override all notifications from existing controls and, for each such overridden notification, find the controls that can send it. The next step is to generate an implementation which will forward to another overridable function for each control. As an example, Figure 10 shows the code for a login form with two edit boxes and two buttons.
Figure 10 Login Form Code
struct form_resource::login {
  wnd<edit> name;
  wnd<edit> passw;
  wnd<button> ok, cancel;

  typedef ... ok_;
  typedef ... cancel_;
  typedef ... name_;
  typedef ... passw_;

  virtual void on_change(edit::ev::change& e, name__) {}
  virtual void on_change(edit::ev::change& e, passw__) {}

  virtual void on_change(edit::ev::change& e) {
    if ( e.sender == name) on_change(e, name__());
    else if ( e.sender == passw) on_change(e, passw__());
  }
  // ... same for other edit notifications

  virtual void on_click(button::ev::click & e, ok__) {}
  virtual void on_click(button::ev::click & e, cancel__) {}
  virtual void on_click(button::ev::click & e) {
    if ( e.sender == ok) on_click(e, ok__());
    else if ( e.sender == cancel) on_click(e, cancel__() );
  }
  // ... same for other button notifications
};
Finally, you can create your own events by deriving from new_event<>. Whether you're sending existing events or your own events, the process is the same: you use the send_event function:
struct hover : new_event<hover> {
 int x,y; // position
 hover(int x,int y) : x(x),y(y) {}
};

w->send_event( hover(x,y) );
The library is thread safe. As a side-note, each window has an m_cs mutex variable (basically, it's a CRITICAL_SECTION), which I use to make sure each method access is thread-safe. When you extend a window class, you can re-use the m_cs variable or create your own—it's your call.

Menus, Shortcuts, and the Like
If you've done GUI programming in the past, you know that both pressing a menu command and pressing a key cause a WM_COMMAND to be sent. As a consequence, when you receive a WM_COMMAND, it's difficult to know whether that event came from a control or from a menu (or keyboard shortcut, for that matter). eGUI++ solves the first part of the problem by placing the menu on the form (dialog) directly. If a command sent to a form is not sent from a button, it's from a menu.
That takes care of menu commands. Now let's look at shortcuts. The problem with shortcuts is that one can be keyed at any time (for instance, when inside an edit box). Keyboard shortcuts (accelerators) are routed first to the immediate window, then to the form hosting the window, then to the form's parent, and up the hierarchy until reaching the top-most window. The first time you find an event handler for that shortcut, processing stops (a given shortcut is not processed by two or more windows).
That leaves toolbars—they go hand-in-hand with menus and shortcuts. When a toolbar button is pressed, the event is translated into a menu command and is routed directly to the form that hosts it—whether the command came from a menu, a shortcut, or a toolbar button is irrelevant.
Assume you're implementing a form to handle a menu command, like so:
void on_menu_command( ev::menu&,
 menu::some_menu_id) { ... }
To handle two menu commands, new_file and open_file, you'll create these handlers:
void on_menu_command( ev::menu&,
    menu::new_file) { ... }
   void on_menu_command( ev::menu&,
    menu::open_file) { ... }

Tab Controls and Forms
Tabs are a very popular GUI paradigm. I've extended the tab control to allow the tab_type property to have values of normal or one_dialog_per_tab (in this case, the control hosts other forms). In the latter case, you can add new forms like this:
tab->add_form<form_type>( new_([args]) );
To add the login form I've talked about, you'd write:
tab->add_form<login>( new_() );
Once you've added at least one form, you can specify the number of tabs this tab form is to hold:
tab->count = 5;
Here I have five tabs. This will take the last added form and duplicate it as many times as needed. Assuming previously there was only one tab, the form on the first tab will be cloned another four times. That's right. You can clone any existing window!
So far I've shown you intrusive handling of events. In other words, you extend a window class and eventually respond to its events (or, if you're implementing a form, you respond to its notifications). Sometimes, however, you need to implement a behavior that applies to several windows (somewhat unrelated to each other).
Take, for instance, resizeability and skinability. You can implement them in an intrusive manner (creating some classes that implement the behavior, and then deriving your GUI classes from them as well). However, this will complicate the code, and it's not always feasible (take skinability for instance). By implementing behavior unintrusively, the behavior can be reused in other applications, and it can also be turned off easily.
For instance, create a non-intrusive event handler class, create an instance of it, and register it. When a new window is created, your handler instance is notified and you can choose to monitor this instance. If you do, you'll need to manually specify which events you want to monitor, like so:
// monitor button clicks
struct btn_handler : non_intrusive_handler {
 void on_new_window_create(wnd<> w) {
 if ( wnd<button> b = try_cast(w)) {
  b->events.on_click += mem_fn(&on_click,this);
 }
 }
 void on_click(button::ev::click&) { ... }
};
Registering the event handler is easy. Simply perform the following:
btn_handler bh;
window_base::add_non_intrusive_handler(bh);

Resizeability can be implemented in many ways, depending on your application. For instance, you could override the on_size event on each form and update the controls' positions based on the new form size (bad idea, lots of work). Or, on each form, you could create relations between the controls, like "a.x = b.x + b.width + 4;" (this is very flexible, but also requires lots of work).
As an alternative, on each form, you can mark controls either as sizeable or moveable on each axis. If a control is marked as sizeable on a certain axis, when the form's size changes, that control's size will update; if a control is marked as moveable on a certain axis, when the form's size changes, that control will be moved. This should suffice for most applications. I borrowed this idea from WTL's CResizeWindow and implemented it using a nonintrusive handler. Assume you have a dialog like in Figure 11. If, when resized, you'd like it to look like Figure 12, then you'll use this code:
resize(name, axis::x, sizeable);
resize(desc, axis::x | axis::y, sizeable);
resize(ok, axis::x | axis::y, moveable);
resize(cancel, axis::x | axis::y, moveable);
Figure 11 Dialog
Figure 12 Dialog Resized
Every GUI operation that fails will trigger an exception. This way, you'll know something went wrong. In debug mode, it will generate a failed assertion and the program will break into debug mode. This is much better than silently ignoring the error, seeing that something is wrong (visually), and then hunting for the bug.

Integration with Visual Studio 2005
Visual Studio is a great IDE, and one of its major advantages is that it can be extended. eGUI++ takes advantage of that; it comes with an Add-in that provides a New Form Class Wizard. It also provides a Visual Basic-like bar that allows you to handle control notifications on forms. To do so, just select a control, then you see a list with the notifications that that control can generate. Note that those that are already handled are shown in bold; click on an event and a handler will be added, if it's not already there—for an example, see Figure 13.
Figure 13 Handle Control Notifications on Forms
Under the hood, eGUI++ monitors the resource editor so that whenever something changes, the _form_resource.h files are updated if needed. And it works with code-completion, as I've already described in detail.

Implementing Behavior
Once you've built your GUI, the next step is to implement behavior and allow for data binding. Many forms are meant only for collecting data. For starters, you can implement a generic form class, which, at construction, gets data to manipulate binds it to the form's controls. Then you can specify a set of rules for validating the data. At destruction, if the validation rules are successful, the original data is updated with the values from the controls; otherwise, the original data remains unchanged. Thus, for each new form, you only need to create the form in the resource editor and then specify a set of rules to use in validating the data (as opposed to creating a new form class and duplicating logic).
Looking ahead, you can bridge the gap between Standard Template Library (STL) arrays and collections, and list controls and tree controls. I'm thinking of having an array of, let's say, employees, and a list control. I can bind the array to the control, like so:
list_ctrl->bind(employees);
As you might expect, this will update the list control. Moreover, any change on a list control's cell will be automatically synchronized with the employees array.
My intention in building eGUI++ was to create a cool library that makes GUI programming fun. If you're a C++ programmer, I certainly hope that you agree. You can download the source and binaries at torjo.com.

John Torjo is a C++ Programmer who is still in love with C++ after 10+ years of programming. John enjoys logging and GUI, and he also enjoys challenges. If you've got one, send him an e-mail. You'll find more information on his site at torjo.com.


Editor's Note
In Case You Hadn't Noticed …
Howard Dierking

As you're reading this, you might be thinking "something seems different." And you would be absolutely correct. Over the past few months, we have been working hard to introduce several new elements into the MSDN Magazine experience, both in print and online. For this month's editor's note, I want to step back from my usual technology pontification and instead point out these features so that you can take advantage of them.
The first—and hopefully most obvious—change is that we've updated our look. The table of contents still lives on our cover, but the columns have a little more real estate, making it easier to scan all of our content. Inside, we've lightened up the colors, fonts, and other graphical elements. Our goal with the redesign was to simplify and freshen our print look while also creating a visual link to another major area of change: our online look.
Inside this issue you'll find two of our new special type of sidebar called Insights. The purpose of this type of sidebar is to enable Microsoft product teams to inject additional details on how a feature or technology works "under the hood" or describe the design decisions that went into that technology. You can find the Insights sidebars in Dino Esposito's Cutting Edge column and in Jeffrey Richter's Concurrent Affairs column.
Finally, I'm happy to announce that we have launched a new feature as a part of our online experience—Virtual Labs. When you launch the Virtual Lab, you'll see a split-pane view containing the lab environment in one window and the magazine article in the other. This will enable you to stay in context of the article while working in the code and vice-versa.
Initially, we are hosting Virtual Labs for articles that discuss technologies that are either not likely part of your current toolset or are complex to configure. (For example, articles covering SharePoint development are great candidates for Virtual Labs.) In this issue, we are running a Virtual Lab to correspond to Charles Petzold's Foundations column where you can experiment with the RenderTargetBitmap and WriteableBitmap classes that make your bitmaps responsive to changes within your application. See his column in this issue for more information about the Virtual Lab, or go directly to the lab at go.microsoft.com/fwlink/?LinkId=117105.
We're also featuring a Virtual Lab for Ethan Wilansky's article on automating SharePoint deployment from the May 2008 issue of MSDN Magazine. You can get started by pointing your browser to go.microsoft.com/fwlink/?LinkId=117106.
I hope that you find the new content additions valuable. As always, please drop us an email at mmeditor@microsoft.com and let us know what think about our new features!

Thanks to the following Microsoft technical experts for their help with this issue: Tim Cahill, Patrick Dussud, Muhammed Abd El Aziz, Joseph Fernando, Steve Fox, Matt Gibbs, Bertrand Le Roy, Ade Miller, Dwayne Need, Dave Reed, Gerhard Schneider, Don Smith, Stephen Toub, Clemens Vasters, and Robert Wlodarczyk.


Toolbox
Cross Browser Testing, Mock Objects, and Raymond Chen
Scott Mitchell

Contents
Better Browser Compatibility Testing
Blogs of Note
Unit Testing with Mocks
The Bookshelf

Better Browser Compatibility Testing
When Web developers sleep at night they dream that all Web browsers follow HTML standards to the letter. They imagine a world where every Web surfer has the same monitor resolution, color depth, and font size. Unfortunately, reality could not be more different. During waking hours, Web developers must design their Web applications to function properly in a seemingly infinite number of configurations.
Creating a thorough Web testing environment can be tedious and time consuming, requiring installation of several different browsers, versions, and operating systems. Remote Web-based testing environments take this burden off the developer.
One such service is Browsershots. After specifying a URL, Browsershots takes and displays screenshots using the selected browser, version, and operating system combinations. There are 53 different combinations available, plus you can specify client settings such as screen size, color depth, and JavaScript support. The Browsershots service is free, but there can be wait times ranging from less than a minute to half an hour or more, depending on the number of requests being processed. For $15 per month, you can sign up for priority processing, which shuttles your requests to the front of the queue.
While screenshots are useful for seeing how a Web site looks in a specific browser, it does not reveal how the site behaves as the user interacts with it. To perform this type of testing, use BrowserCam. BrowserCam offers screenshots like Browsershots, but also includes remote access to a variety of operating systems and browsers. This allows you to log into a machine, configure its settings, and interact with your Web site.
Price: Browsershots (free); BrowserCam ($89.95/month for Premium).
browsershots.org
browsercam.com
Microsoft.com in Browsershots

Blogs of Note
Have you ever wondered why it is that you have to click the Start button to shut down your computer? Or how about why the Windows® operating system debugger is called "Dr. Watson?" Do you know what computer game's inoperability issues threatened to delay the Windows XP SP2 beta release? And does anybody know why the registry is called a "hive?" Raymond Chen knows.
Raymond joined Microsoft in 1992 as a software engineer for Windows 95, and he's a virtual repository of historical Windows information. In his blog, The Old New Thing, he answers these questions and tackles lots of other Windows legacies. Raymond was there when many of the Windows design decisions were made, so he has first-hand knowledge of the thinking behind them. His insider knowledge and dry wit make Raymond's blog an entertaining and educational read.
Oh, and by the way: the Windows registry is called a "hive" because one of the Windows NT® developers hated bees, and the joke was on him. But the really important decisions, however, were made with one goal in mind: to ensure backward compatibility. Raymond does a great job of highlighting the intense effort that has gone into backward compatibility to ensure that your old 16-bit Visual Basic® application or your favorite MS-DOS® game still works as expected in the more modern versions of Windows.
In addition to his blog entries on the history of Windows, Raymond writes the popular Windows Confidential column for TechNet Magazine (.com) and he regularly posts an assortment of tips and tricks for Windows programmers.
go.microsoft.com/fwlink/?LinkId=115142
Raymond Chen’s Blog: The Old New Thing

Unit Testing with Mocks
Good unit tests are terse, execute quickly, and are independent of one another. When testing any functionality that has external dependencies, such as databases, Web services, or configuration files, extra steps must be taken to achieve these goals. One option is to record the state of the external dependency prior to executing each unit test, then restore that state after each test completes. Such excessive setup and teardown tasks can dramatically slow the execution of unit tests and shift the focus from writing unit tests to managing the state of external dependencies.
An alternative option is to simulate calls to the external dependencies using mock objects. During a unit test, the mock object replaces the actual logic used to access the external dependency. Because the code being tested works with the mock object instead of the actual external dependency, there's no need for complicated setup and teardown logic. What's more, mocked objects allow the interactions between your code and the external dependency to be tested explicitly.
There are several open-source and commercial mocking frameworks with varying syntax requirements for mocking objects. Some frameworks use hardcoded strings for specifying the objects to be mocked and the functionality to be simulated. Others use strongly typed objects, which help identify errors at compile time rather than run time.
Typemock Isolator (version 4.2) is a mocking framework that offers you both approaches. Regardless of which approach you decide to choose, the semantics of using mock objects in your unit tests are the same: you begin by defining the mock object, then specify how the tested code will interact with it, execute the code, and then verify that the results are in line with your expectations.
Typemock distinguishes itself from many other mocking frameworks with its tools and integration support. It can be difficult to debug unit tests that use mocked objects because it's not always clear when the mocked object is being used in place of the actual external dependency.
The Trace Utility helps to resolve that difficulty by identifying how the mocked objects are being used. It records and displays the mocked types and all of the calls made to them during the execution of the unit tests. When it's debugging unit tests, Typemock reveals what's being mocked by outlining the mocked members in the IDE. Additionally, Typemock also integrates into the Visual Studio® shell and help systems and includes support for automating your unit tests with NAnt and MSBuild.
Typemock supports the Microsoft® .NET Framework versions 1.1 and later, and it offers a free Community Edition, along with the more feature-rich Professional and Enterprise editions.
Price: Free Community Edition; $449 for Enterprise Edition.
typemock.com
Typemock Trace Utility

The Bookshelf
Since the .NET Framework 2.0, subsequent versions have added new features while keeping the core functionality in place. This poses a dilemma for authors writing books on post-2.0 versions of the .NET Framework: do you focus on just the new features or do you create a book that covers the new features plus the stuff that's been around since version 2.0?
At nearly 1,500 pages, it's eminently clear that Matthew MacDonald and Mario Szpuszta, coauthors of Pro ASP.NET 3.5 in C# 2008 (Apress, 2007), chose the latter. The book's 33 chapters cover it all, from creating the simplest Web Forms to using cutting- edge features like AJAX and Silverlight™.
The book begins with an overview of ASP.NET fundamentals such as Web Forms, Web controls, and state management, then moves on to ADO.NE T, LINQ, ASP.NET AJAX, Silverlight, and more. The authors discuss virtually all the features in ASP.NET, but focuses on those most commonly used.
If you are an intermediate to advanced developer with past Web development experience and are interested in learning ASP.NET 3.5, pick up a copy of Pro ASP.NET 3.5 in C# 2008.
Price: $59.99.
apress.com

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
Large Object Heap Uncovered
Maoni Stephens

Contents
The Large Object Heap and the GC
When a Large Object Gets Collected
LOH Performance Implications
Collecting Performance Data for the LOH
Using a Debugger
The CLR garbage collector (GC) divides objects into small and large categories. When an object is large, some attributes associated with it become more significant than if the object is small. For instance, compacting it—copying the memory elsewhere on the heap—is expensive. In this month's column I am going to look at the large object heap in depth. I will talk about what qualifies an object as a large object, how these large objects are collected, and what kind of performance implications large objects impose.

The Large Object Heap and the GC
In the Microsoft® .NET Framework 1.1 and 2.0, if an object is greater than or equal to 85,000 bytes it's considered a large object. This number was determined as a result of performance tuning. When an object allocation request comes in and meets that size threshold, it will be allocated on the large object heap. What does this mean exactly? To understand this, it may be beneficial to explain some fundamentals about the .NET garbage collector.
As many of you are aware, the .NET garbage collector is a generational collector. It has three generations: generation 0, generation 1, and generation 2. The reason for this is so that in a well-tuned application, you can expect most objects to die in generation 0. For example, in a server app, the allocations associated with each request should die after the request is finished. The in-flight allocation requests will make it into generation 1 and die there. Essentially, generation 1 acts as a buffer between young object areas and long-lived object areas.
From a generation point of view, large objects belong to generation 2 because they are collected only when there is a generation 2 collection. When a generation is collected, all younger generations are also collected. So for example, when a generation 1 garbage collection happens, both generation 1 and 0 are collected. And when a generation 2 garbage collection happens, the whole heap is collected. For this reason, a generation 2 garbage collection is also known as a full garbage collection. In this column I will use the term generation 2 garbage collection instead of full garbage collection, but they are interchangeable.
Generations are the logical view of the garbage collector heap. Physically, objects live on managed heap segments. A managed heap segment is a chunk of memory that the garbage collector reserves from the OS (via calling VirtualAlloc) on behalf of managed code. When the CLR is loaded, two initial heap segments are allocated—one for small objects and one for large objects, which I will refer to as the small object heap (SOH) and the large object heap (LOH), respectively.
Allocation requests are then satisfied by putting managed objects on one of these managed heap segments. If the object is less than 85,000 bytes, it will be put on a SOH segment; otherwise it'll be on a LOH segment. Segments are committed (in smaller chunks) as more and more objects are allocated onto them.
For the SOH, objects that survive a garbage collection are promoted to the next generation; so objects that survive a generation 0 collection will be considered generation 1 objects, and so on. Objects that survive the oldest generation, however, will still be considered in the oldest generation. In other words, survivors from generation 2 will be generation 2 objects; and survivors from LOH will be LOH objects (collected with generation 2). User code can only allocate in generation 0 (small objects) or LOH (large objects). Only the garbage collector can "allocate" objects in generation 1 (by promoting survivors from generation 0) and generation 2 (by promoting survivors from generations 1 and 2).
When a garbage collection is triggered, the garbage collector traces through the live objects and compacts them. For LOH, though, because compaction is expensive the CLR team chose to sweep them, making a free list out of dead objects that can be reused later to satisfy large object allocation requests. Adjacent dead objects are made into one free object.
An important thing to keep in mind is that even though today we don't compact LOH, we might in the future. So if you allocate large objects and want to make sure they don't move, you should still pin them.
Note that the figures shown here are only for illustration purposes. I used very few objects, just to show what happens on the heap. In reality there are many more objects there.
Figure 1 illustrates a scenario where I form generation 1 after the first generation 0 GC where Obj1 and Obj3 are dead; and I form generation 2 after the first generation 1 GC where Obj2 and Obj5 are dead.
Figure 1 SOH Allocations and Garbage Collections
Figure 2 illustrates that after a generation 2 garbage collection in which you saw that Obj1 and Obj2 were dead, I formed one free space out of the memory that used to be occupied by Obj1 and Obj2, which then was used to satisfy the allocation request for Obj4. The space after the last object Obj3 until the end of the segment can still be used to satisfy further allocation requests.
Figure 2 LOH Allocations and Garbage Collections
If I don't have enough free space to accommodate the large object allocation requests, I will first attempt to acquire more segments from the OS. If that fails, then I will trigger a generation 2 garbage collection in hope of freeing up some space.
During a generation 2 garbage collection, I take the opportunity to release segments that have no live objects on them back to the OS (by calling VirtualFree). Memory from the last live object to the end of the segment is decommitted. And the free spaces remain committed though they are reset, meaning the OS doesn't need to write data in them back to disk. Figure 3 illustrates a scenario in which I release a segment back to the OS (segment 2) and decommit more space on the remaining segments. If I need to use the decommitted space at the end of the segment to satisfy new large object allocation requests, I will commit the memory again.
Figure 3 Dead Segments Released on LOH during Garbage Collection
For an explanation on commit/decommit, please see the MSDN® documentation on VirtualAlloc at go.microsoft.com/fwlink/?LinkId=116041.

When a Large Object Gets Collected
To determine when a large object is collected, let's first talk about when a garbage collection happens in general. A garbage collection occurs if one of the following conditions happens:
Allocation Exceeds the Generation 0 or Large Object Threshold Most GCs happen because of allocations on the managed heap (this is the most typical case).
System.GC.Collect Is Called When someone calls GC.Collect on generation 2 (by passing either no arguments to GC.Collect or passing GC.MaxGeneration as an argument), the LOH will get collected right away along with the rest of the managed heap.
System Is in Low Memory Situation This happens when I receive the high memory notification from the OS. If I think doing a generation 2 GC will be productive, I will trigger one.
The threshold is a property of each generation. When you allocate objects into a generation, you increase the amount of memory in that generation and get closer to the generation's threshold. And when the threshold is exceeded for a generation, a garbage collection is triggered on that generation. So when you allocate small or large objects, you consume generation 0's and LOH's respective thresholds. And when the garbage collector allocates into generation 1 and 2, it consumes generation 1 thresholds. These thresholds are dynamically tuned as the program runs.

LOH Performance Implications
Let's look at allocation costs. The CLR makes the guarantee that the memory for every new object I give out is cleared. This means the allocation cost of a large object is completely dominated by memory clearing (unless it triggers a garbage collection). If it takes two cycles to clear 1 byte, it means it takes 170,000 cycles to clear the smallest large object. It's not uncommon for people to allocate large objects that are a bit too large. For a 16MB object on a 2GHz machine, it will take approximately 16ms to clear the memory. That's a rather large cost.
Now let's see about collection costs. As mentioned earlier, LOH and generation 2 are collected together. If either one's threshold is exceeded, a generation 2 collection will be triggered. If a generation 2 was triggered because of the LOH, generation 2 itself won't necessarily get much smaller after the garbage collection. Now, if there's not much data on generation 2, this is not a problem. But if generation 2 is big, it could cause performance problems if many generation 2 garbage collections are triggered. If many large objects are allocated on a very temporary basis and you have a big SOH, you could be spending too much time running garbage collections; not to mention that the allocation cost can really add up if you keep allocating and letting really large objects go.
Very large objects on the LOH are usually arrays (it's very rare to have an instance object that's really, really large). If the elements of an array are reference-rich, the cost is high. If the element doesn't contain any references, I wouldn't need to go through the array at all. For example, if you use an array to store nodes in a binary tree, one way to implement it is to refer to a node's right and left node by the actual nodes:
class Node
{
    Data d;
    Node left;
    Node right;
};

Node[] binary_tr = new Node [num_nodes];
If num_nodes is a large number, it means you will need to go through at least two references per element. An alternative approach is to store the index of the right and the left node:
class Node
{
    Data d;
    uint left_index;
    uint right_index;
};
This way, instead of referring to the left node's data as left.d, you would refer to it as binary_tr[left_index].d. And the garbage collector wouldn't need to look at any references for left and right node.
Out of the three reasons for a collection, the first two are usually more dominant than the third. Therefore, it's best if you can allocate a pool of large objects and reuse them instead of allocating temporary ones. Yun Jin has a good example of such a buffer pool in his blog entry (go.microsoft.com/fwlink/?LinkId=115870). Of course, you would want to make the buffer size larger.

Collecting Performance Data for the LOH
There are a few ways to collect performance data that's relevant to the LOH. But before I explain them, let's talk about why you would want to do it.
Before you start collecting performance data for a specific area, hopefully you have already found evidence that you should be looking at this area or you have exhausted other areas that you know of and didn't find any problems that could explain a performance problem you are observing.
I would recommend reading a blog entry of mine for more explanation (see go.microsoft.com/fwlink/?LinkId=116467). There I talk about the fundamentals of memory and CPU. Additionally, the November 2006 installment of CLR Inside Out on investigating memory issues talks about steps involved in diagnosing performance problems in a managed process that may be related to managed heap (see msdn2.microsoft.com/magazine/cc163528).
.NET CLR Memory Performance counters are usually a good first step in investigating performance issues. The counters that are relevant to the LOH are the number of generation 2 collections and the large object heap size. The number of generation 2 collections displays the number of times generation 2 garbage collections have occurred since the process started. The counter is incremented at the end of a generation 2 garbage collection (also called a full garbage collection). This counter displays the last observed value.
Large object heap size is the current size in bytes, including the free space, of the Large Object Heap. This counter is updated at the end of a garbage collection, not at each allocation.
A common way to look at performance counters is via Performance Monitor (PerfMon.exe). Use "Add Counters" to add the interesting counter for processes that you care about, as you can see in Figure 4.
Figure 4 Adding Counters in Performance Monitor
You can save the performance counter data to a log file in PerfMon. Performance counters can also be queried programmatically. Many people collect them this way as part of their routine testing process. When you spot counters with values that are out of the ordinary, you can then use other means to get more details to help with the investigation.

Using a Debugger
Before I begin, you should note that the debugging commands I'll mention in this section are applicable to the Windows® Debuggers. If you need to look at which objects are actually on the LOH, you can use the SoS debugger extension provided by the CLR, which is explained in the November 2006 installment I mentioned previously. An example output of analyzing the LOH is shown in Figure 5.
The bold sections of Figure 5 say that the LOH heap size is (16,754,224 + 16,699,288 + 16,284,504 =) 49,738,016 bytes. And between address 023e1000 and 033db630, there are 8,008,736 bytes occupied by System.Object[] objects; 6,663,696 occupied by System.Byte[] objects; and 2,081,792 occupied by free space.
Figure 5 LOH Output
0:003> .loadby sos mscorwks
0:003> !eeheap -gc
Number of GC Heaps: 1
generation 0 starts at 0x013e35ec
generation 1 starts at 0x013e1b6c
generation 2 starts at 0x013e1000
ephemeral segment allocation context: none
 segment    begin allocated     size
0018f2d0 790d5588  790f4b38 0x0001f5b0(128432)
013e0000 013e1000  013e35f8 0x000025f8(9720)
Large object heap starts at 0x023e1000
 segment    begin allocated     size
023e0000 023e1000  033db630 0x00ffa630(16754224)
033e0000 033e1000  043cdf98 0x00fecf98(16699288)
043e0000 043e1000  05368b58 0x00f87b58(16284504)
Total Size  0x2f90cc8(49876168)
------------------------------
GC Heap Size  0x2f90cc8(49876168)
0:003> !dumpheap -stat 023e1000  033db630
total 133 objects
Statistics:
      MT    Count    TotalSize Class Name
001521d0       66      2081792      Free
7912273c       63      6663696 System.Byte[]
7912254c        4      8008736 System.Object[]
Sometimes you'll see that the total size of the LOH is less than 85,000 bytes. Why is this? It's because the runtime itself actually uses LOH to allocate some objects that are smaller than a large object.
Since the LOH is not compacted, sometimes people suspect that the LOH is a source of fragmentation. You really need to first clarify what fragmentation means. There's fragmentation of the managed heap, which is indicated by the amount of free space between managed objects (in other words, what you see when you do !dumpheap –type Free in SoS); there's also fragmentation of the virtual memory (VM) address space, which is the memory marked as MEM_FREE and which you can see by using various debugger commands in windbg (see go.microsoft.com/fwlink/?LinkId=116470). Figure 6 shows the fragmentation in the virtual memory space (note the bold text in the figure).
Figure 6 VM Space Fragmentation
0:000> !address
    00000000 : 00000000 - 00010000
                    Type     00000000
                    Protect  00000001 PAGE_NOACCESS
                    State    00010000 MEM_FREE
                    Usage    RegionUsageFree
    00010000 : 00010000 - 00002000
                    Type     00020000 MEM_PRIVATE
                    Protect  00000004 PAGE_READWRITE
                    State    00001000 MEM_COMMIT
                    Usage    RegionUsageEnvironmentBlock
    00012000 : 00012000 - 0000e000
                    Type     00000000
                    Protect  00000001 PAGE_NOACCESS
                    State    00010000 MEM_FREE
                    Usage    RegionUsageFree
... [omitted]
-------------------- Usage SUMMARY --------------------------
    TotSize (      KB)   Pct(Tots) Pct(Busy)   Usage
     701000 (    7172) : 00.34%    20.69%    : RegionUsageIsVAD
   7de15000 ( 2062420) : 98.35%    00.00%    : RegionUsageFree
    1452000 (   20808) : 00.99%    60.02%    : RegionUsageImage
     300000 (    3072) : 00.15%    08.86%    : RegionUsageStack
       3000 (      12) : 00.00%    00.03%    : RegionUsageTeb
     381000 (    3588) : 00.17%    10.35%    : RegionUsageHeap
          0 (       0) : 00.00%    00.00%    : RegionUsagePageHeap
       1000 (       4) : 00.00%    00.01%    : RegionUsagePeb
       1000 (       4) : 00.00%    00.01%    : RegionUsageProcessParametrs
       2000 (       8) : 00.00%    00.02%    : RegionUsageEnvironmentBlock
       Tot: 7fff0000 (2097088 KB) Busy: 021db000 (34668 KB)

-------------------- Type SUMMARY --------------------------
    TotSize (      KB)   Pct(Tots)  Usage
   7de15000 ( 2062420) : 98.35%   : <free>
    1452000 (   20808) : 00.99%   : MEM_IMAGE
     69f000 (    6780) : 00.32%   : MEM_MAPPED
     6ea000 (    7080) : 00.34%   : MEM_PRIVATE

-------------------- State SUMMARY --------------------------
    TotSize (      KB)   Pct(Tots)  Usage
    1a58000 (   26976) : 01.29%   : MEM_COMMIT
   7de15000 ( 2062420) : 98.35%   : MEM_FREE
     783000 (    7692) : 00.37%   : MEM_RESERVE
As mentioned earlier, fragmentation on the managed heap is used for allocation requests. It's more common to see virtual memory fragmentation caused by temporary large objects that require frequent garbage collection to acquire new managed heap segments from the OS and release empty ones back to the OS.
To verify whether the LOH is causing VM fragmentation, you can set a breakpoint on VirtualAlloc and VirtualFree and see who calls them. For example, if I want to see who tried to allocate VM chunks from the OS that are larger than 8MB, I can set a breakpoint like this:
bp kernel32!virtualalloc "j (dwo(@esp+8)>800000) 'kb';'g'"
This breaks into the debugger and shows me the callstack if VirtualAlloc is called with the allocation size greater than 8MB (0x800000) and doesn't break into the bugger otherwise.
In CLR 2.0 we added a feature called VM Hoarding that may be applicable if you are in a situation where segments (including those for both the large and small object heaps) are frequently acquired and released. To specify VM Hoarding, you specify a startup flag called STARTUP_HOARD_GC_VM via the hosting API (see go.microsoft.com/fwlink/?LinkId=116471). When you specify this, instead of releasing empty segments back to the OS, the memory on these segments is simply decommitted and put on a standby list. The segments on the standby list will be used later to satisfy new segment requests. So next time I need a new segment, I'll use one from this standby list if I can find one that's big enough.
Note that this isn't done for the segments that are too large. This feature is also useful for applications that want to hold onto the segments that they've already acquired, like some server apps that seek to avoid fragmentation of the VM space as much as they can so that they don't cause out-of-memory errors. And they can do this since they are usually the dominating apps on the machine. I strongly recommend you carefully test your application when you use this feature and make sure it has a fairly stable memory usage.
Large objects are expensive. The allocation cost is high because the CLR needs to clear the memory for a newly allocated large object to satisfy the CLR guarantee that memory for all newly allocated objects is cleared. The LOH is collected with the rest of the heap, so carefully analyze how that impacts your app's performance. The recommendation is to reuse large objects if possible to avoid fragmentation on the managed heap and the VM space.
Finally, as of right now, the LOH is not compacted as a part of collection, but that is an implementation detail that should not be relied on. So to make sure something is not moved by the GC, always pin it. Now take your newfound LOH knowledge and go take control of the heap.

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

Maoni Stephens is Senior Developer working on the garbage collector in the CLR team at Microsoft. Before joining CLR, Maoni spent several years in the Operating System group at Microsoft.


Cutting Edge
ASP.NET AJAX And Client-Side Templates
Dino Esposito

Code download available at: CuttingEdge2008_06.exe (239 KB)
Browse the Code Online

Contents
A Typical AJAX Function
Limits of Partial Rendering
Reconsidering the Live Quote Page
Client-Side Templating in ASP.NET AJAX
The Browser-Side Templating Pattern
Further Considerations
The HTML Message Pattern
What makes partial rendering particularly appealing for the development of ASP.NET AJAX applications is its inherent simplicity—lower impact on existing pages and fewer demands on developers' skills. But partial rendering is merely a trick to bypass the browser in the execution of the postback request. Pages that use partial rendering are not truly AJAX pages because they still rely on the old postback method. But what does it mean to be a real AJAX application?
Essentially, a true AJAX application uses the XMLHttpRequest object to bypass the browser and establish direct communication with the Web server and any hosted HTTP endpoints. The application is capable of asynchronously retrieving necessary data and independently refreshing blocks of the user interface. Based on this key behavior, a number of AJAX frameworks have been designed that have different doses of syntactic sugar, larger or smaller feature sets, and richer or simpler families of user interface widgets. ASP.NET AJAX is one of these frameworks.
Designing and building true AJAX applications is not an easy task, and it is even more difficult if you lack the proper programming tools. Compared to other AJAX frameworks, ASP.NET AJAX excels in the support it provides for accessing server-side code. With ASP.NET AJAX, connecting to a scriptable Web or Windows® Communication Foundation (WCF) service is child's play from a developer's perspective. You reference the URL, and the framework generates a JavaScript proxy class for you. It's free and effective. The proxy class hides all the details of XMLHttpRequest plumbing, serialization and deserialization, data formats, and HTTP packaging. You just call a method asynchronously and get a plain data-transfer object (DTO) back with its own set of properties.
ASP.NET AJAX, however, doesn't provide the same efficient mechanism for consuming downloaded data in the browser. No doubt this will improve soon, but for now ASP.NET AJAX doesn't offer a client-side UI model as rich as the server-side service model.
What can you do today to improve the UI model of ASP.NET AJAX pure Web applications? Last month, I introduced the concept of Single-Page Interface (SPI) and presented a couple of simple patterns that can be useful for building SPI pages. This month, I'll discuss client-side templates and data binding.

A Typical AJAX Function
A canonical example to illustrate the power of the AJAX approach is an application that retrieves stock quotes in real time. The non-AJAX Web sites that offer this feature today are using either meta-refresh tags or a plugin-based approach such as Flash, Silverlight™, or ActiveX® controls. Typically, the list of stock values to display is bound to a server-side grid control, and the grid is then refreshed with the rest of the page with the next postback or page request. A page like this can be quickly enhanced with a sprinkle of partial rendering. Let's see how. The markup in Figure 1 wraps a grid control in an UpdatePanel control that is periodically refreshed by a Timer control.
Figure 1 UI for a Real-Time Stock Quote Page
<asp:UpdatePanel runat="server" ID="UpdatePanel1" UpdateMode="Conditional">
  <ContentTemplate>
    <div style="margin:10px;">
      <asp:Label runat="server" ID="Label2" />
      <asp:GridView ID="GridView1" runat="server" SkinID="ClassicGrid"
        AutoGenerateColumns="false"
        OnRowDataBound="GridView1_RowDataBound">
        <Columns>
          <asp:BoundField DataField="Symbol" HeaderText="SYMBOL" />
          <asp:BoundField DataField="Quote" HeaderText="LAST" >
            <ItemStyle HorizontalAlign="Right" />
          </asp:BoundField>
          <asp:BoundField DataField="Change" HeaderText="CHANGE" >
            <ItemStyle HorizontalAlign="Right" />
          </asp:BoundField>
        </Columns>
      </asp:GridView>
      <small><asp:Label runat="server" ID="Label1" /></small>
    </div>
  </ContentTemplate>
  <Triggers>
    <asp:AsyncPostBackTrigger ControlID="Timer1" EventName="Tick" />
  </Triggers>
</asp:UpdatePanel>

<asp:Timer runat="server" id="Timer1" Enabled="true"
  Interval="600000" OnTick="Timer1_Tick" />
The grid control is bound to a collection of objects that feature at least three properties: Symbol, Quote, and Change. The content of the grid is refreshed every 10 minutes. The ASP.NET AJAX Timer control activates a client timer and fires a postback when the interval expires. Because it is wrapped by an UpdatePanel, the grid with stock quotes updates separately from the page. On the server, the timer's tick runs the following code:
protected void Timer1_Tick(object sender, EventArgs e)
{
    Label2.Text = "<b>Last update: </b>" + DateTime.Now.ToLocalTime();
    GridView1.DataSource = picker.Update();
    GridView1.DataBind();
}
The picker object is an instance of a custom helper class named StockPicker. This class incorporates an instance of the service class in charge of retrieving quotes. Here's the constructor of the StockPicker class:
public StockPicker(string stocks)
{
   string provider = ConfigurationManager.AppSettings["StockProvider"];
   _service = GetFactory(serviceProvider, stocks);

    if (_service == null)
      return;

    _desc = _service.GetServiceDescription();
}
The picker reads the name of the service provider class from the configuration file and instantiates it. The picker communicates with the service class through the contract represented by the IQuoteService interface:
interface IQuoteService
{
    StockInfoCollection GetQuotes();
    string GetServiceDescription();
}
The sample code accompanying this column uses a fake quote service that just returns random numbers in lieu of stock quotes. However, the page code can easily be configured to use a real-world quote service. All that you have to do is create a class that implements the IQuoteService interface and connect to a real stock data service. In the sample code, the bindable data is represented as a collection of StockInfo objects:
public class StockInfo
{
    public string Symbol { get; set; }
    public string Quote { get; set; }
    public string Change { get; set; }
    public string Day { get; set; }
    public string Time { get; set; }
}
Figure 2 shows a sample ASP.NET AJAX page that is based on this API in action.
Figure 2 Live Quote Page Using Partial Rendering

Limits of Partial Rendering
Functionally speaking, the page in Figure 2 works as expected. If you're OK with its performance and overall behavior, then you're just fine. However, such a page has a few drawbacks worth noting, even if they won't keep you up at night.
First, the page moves quite a bit of data around each time it's updated. The amount of data may not be problematic for a relatively scanty page like this that refreshes every 10 minutes. If you use Fiddler or Web Development Helper to monitor, you'll see that the size of the payload is around 3KB in download and somewhat less in upload. Again, if you're OK with these numbers, then by all means go for partial rendering.
These numbers, though, lose much of their appeal if you look at the internal mechanics of the page. The view state of the page is sent back and forth for every update. The response contains both data and layout information. Moreover, data is merged with the surrounding markup and can't be separated from it. Finally, if you have other similarly functioning updatable panels on the page, the timer may stop for a while if another partial rendering operation is started in the meantime. Or it may stop another pending operation when the timer triggers.
In the end, while it is quick to learn and apply, partial rendering is not the ideal mechanism to employ when you need to support simultaneous asynchronous calls. Let's see what it takes to rewrite the page in Figure 2 using a pure AJAX approach.

Reconsidering the Live Quote Page
Insights: ASP.NET AJAX

Template-driven rendering has long been one of the major strengths of ASP.NET server controls. Templates offer a number of advantages over older techniques of looping around markup using <% %> and <%= %> blocks. One could cite two-way binding and general cleanliness of the model. On the client, without a framework, even simple <% %> blocks are not available, so a good template engine represents a major improvement. It also enables lots of optimizations that are easy to achieve on the client but a lot more difficult on the server, such as only re-rendering the changed items in a list instead of re-rendering the whole list. On the other hand, rendering performance on the client leaves a lot to be desired, so a template engine needs to be especially well optimized for performance.
Dino describes here a simple approach to client-side template rendering that is both easy to set up and works today. The ASP.NET team of course recognizes the power of templates. In fact, when we shipped the first previews of ASP.NET AJAX, we introduced a very elaborate declarative syntax, called xml-script, which among other things enabled template-driven rendering. Unfortunately, it was perceived as too complex and verbose; also, the performance wasn't as good as we and our users would have liked. Moreover, it lacked tooling support.
It's important to note that there is a lot more to templates than just inserting data into placeholders in an HTML string. First, a template engine must have some sort of expression language to go beyond the simple field insertion. Second, it should enable scenarios of conditional rendering. And most importantly, it should be simple to add rich behavior to the rendered markup. In other words, the engine must make it simple to instantiate components that attach to the markup it created.
In the next version of ASP.NET AJAX, we're going to revisit templates and reintroduce them into the AJAX framework, along with a simple declarative component syntax. Here's what a simple list view could look like:
<body xmlns:sys="javascript:Sys" xmlns:dv=  "javascript:Sys.UI.DataView">
...
<div id="dataview1" sys:type="dv" dv:data="{{someArray}}">
  <div class="sys-template">
    <h2><a href="{{ 'products/' + id }}">{{name}}</a></h2>
    <!--% if (description) { %-->
      <p>{{description}}</p>
    <!--% } %-->
  </div>
</div>
There are a few things to notice here. Expressions are embedded into the markup using {{ }} delimiters. These expressions can be direct references to current data item fields (name, description, and so on) or can be complex JavaScript expressions ('products/' + id). On the body tag, we define a "dv" namespace that maps to a DataView JavaScript component. Later, we set sys:type on the "dataview1" div to "dv", indicating that we want to instantiate a DataView control and attach it to that element.
On the same tag, dv:data="{{someArray}}" sets the data property of the DataView control to the someArray global variable. The same declarative syntax can be used inside of the template to instantiate and attach arbitrary controls and behaviors. The template itself here is the markup inside the dataview1 div, but it could be built from external contents. Finally, the engine supports arbitrary code to be embedded in the template markup using <!--% %--> blocks, which we use here to conditionally render a paragraph containing the description data column.
—Bertrand Le Roy
Program Manager, ASP.NET
How would a pure AJAX approach affect the design of a live quote page? The page sets up the timer and uses XMLHttpRequest to invoke a remote service. The service is part of the application back end and will use the standard Microsoft® .NET Framework API to call the finance Web service and get data. The data will then be returned to the browser as a JavaScript object. Finally, it's up to you to render it to the user.
What's the difference? Firstly, the invoked URL is not the page itself. The page invokes an HTTP endpoint backed by a scriptable Web or WCF service. There's no page lifecycle, no postback events, no view state restoration. As a result, network traffic is significantly reduced. In the case of this sample page, the payload is 10 times smaller than it is with partial rendering. From an architectural standpoint, you see two neatly separated blocks of code at work—the client-side front end and the server-side back end. The former is powered by JavaScript; the latter is based on managed code.
ASP.NET AJAX shines in this context as it manages to unify the programming interface and data types so that the JavaScript client developer sees exactly the same programming interface and contracts that have been defined on the server. The JavaScript Object Notation (JSON) layer ensures that DTOs that arrive to the client mirror the data sent out from the server.
Let's experiment with some code. The new page has a client button that the user clicks to download fresh data. I'm using a button here instead of a timer only for convenience:
<input type="button" id="btnRefresh"
       value="Live Quotes"
       onclick="_getLiveQuotes()" />
The JavaScript handler then invokes a method on a wrapper live quote Web service and gets a collection of StockInfo objects:
<%@ WebService Class="Samples.WebServices.LiveQuoteService" %>
The full source code for the service is shown in Figure 3.
Figure 3 Live Quote Web Service
namespace Samples.WebServices
{
    [WebService(Namespace = "http://samples.ajax/")]
    [ScriptService]
    public class LiveQuoteService : System.Web.Services.WebService
    {
        private static string stocks =
            ConfigurationManager.AppSettings["StockSymbols"];
        private static StockPicker picker = new StockPicker(stocks);

        public LiveQuoteService()
        {
        }

        [WebMethod]
        public StockInfoCollection Update()
        {
            return picker.Update();
        }

        [WebMethod]
        public string GetServiceDescription()
        {
            return picker.GetServiceDescription();
        }
    }
}
In partial rendering, there's no natural separation between the user interface elements (the view) and the core application logic (the model). Everything is assembled on the server and served ready-to-use to the client. With a pure AJAX architecture, the presentation layer is smarter, richer, and physically separated from the business layer. It goes without saying that such a highly decoupled architecture is inherently more flexible and easy to test. In addition, you have a few more places where you can cache data, as shown in Figure 4.
Figure 4 Possible Levels of Caching in an AJAX Architecture
Data can be cached on the server, care of the (Web) service front end and implementation. In addition, data can be cached along the way by an HTTP proxy or even by the JavaScript code running in the browser. More importantly, you're not caching markup; you'll be caching usable data (objects or JSON strings) that can be checked at any time against runtime conditions.
Moving rendering logic to the client is beneficial also because it makes life easier for a busy server. The server saves CPU cycles and memory if it only has to return a small chunk of data and does not have to execute a full page lifecycle with markup generation and view state processing.
It is equally straightforward to use ASP.NET AJAX from the client to interact with remote services and bring down live data to the browser. For example, the following is the code to invoke a remote method:
function _getLiveQuotes()
{
    Samples.WebServices.LiveQuoteService.Update(onDataAvailable);
}
function onDataAvailable(results)
{
    // Update the UI
}
ASP.NET AJAX gives you a JavaScript proxy object with the same name as the server-side service and a bunch of static methods. In the code snippet, the Update method ultimately fetches an array of JavaScript Document Types Definitions (DTDs) and passes it to the callback function ultimately responsible for updating the user interface. The variable named results in the code contains the response from the service—just the data you need to bind to the grid.
Unfortunately, there's no client-side GridView control as there is in the server-based ASP.NET approach. You need a form of client-side data binding, preferably with some templating support. Currently, ASP.NET AJAX is not of much help here. For further explanation on this topic, straight from the Microsoft ASP.NET team, see the sidebar, "Insights: ASP.NET AJAX."
Some major ASP.NET control vendors recently began offering server controls with an equivalent client-side object model. If you're using any of these libraries, you may end up having a JavaScript object that mimics the server-side control, armed with a client Data source property and a DataBind method. ASP.NET AJAX provides you with the scaffolding required to invoke a Web service from the client, but it doesn't provide an entire UI framework designed with AJAX in mind, nor does it include client data binding and templating. An interesting resource on various AJAX approaches from the UI perspective is the post by Miljan Braticevic at go.microsoft.com/fwlink/?LinkID=116054.

Client-Side Templating in ASP.NET AJAX
Do you remember "Atlas"? In early builds of what later become ASP.NET AJAX Extensions, there was an attempt to provide client-side data binding and templates. And it was a pretty good one indeed. For some reason, however, it didn't make its way into the final release of ASP.NET and was then pushed to the ASP.NET Futures library.
Basically, the old Atlas binding model was based on HTML templates and a declarative syntax for expressing bindings between markup elements and data fields. Templates and binding are then tied together in a client control—the List view control. Configured through XML, the Atlas List view control does a lot of parsing work with all of the information it receives and attaches behaviors, controls, and bindings to various parts of the markup.
Let's start from this last point to explore the ways in which you can build your own small but effective data binding and templating framework. Note that the final output has to be a string of HTML markup. The initial input is a collection of objects with a few public properties. Your job is to build a piece of HTML that fulfills the user's expectations. Generally, you start by looping over the bound collection and concatenating the template's text with the value of the object's properties.
What's wrong with this approach? Actually, nothing is wrong with this approach. In fact, there's no radically different approach that I can think of that doesn't do the exact same thing at some point. This means that you can certainly create a framework that abstracts this basic routine. In the catalog of AJAX patterns (see www.ajaxpatterns.org), the key steps for defining a client-side templating model go under the name Browser-Side Templating pattern (BST).

The Browser-Side Templating Pattern
The goal of the BST pattern is to separate the code that produces a view of data from the data itself. A longstanding problem in software systems, separation between view and data has its canonical solution in any variation of the Model View Controller (MVC) pattern.
While display patterns like MVC and BST are not at all mutually exclusive, you can consider BST by itself to be like an MVC, where you have no inherent notion of a controller and keep view and model separated by the actual separation between the browser and server. In Figure 5, you see a diagram of the steps involved in a BST. The user triggers a remote call that downloads some data to the client. The data is managed by a JavaScript callback that instantiates a new breed of component—the markup builder.
Figure 5 Browser-Side Templating in Action
The markup builder returns an HTML string based on a reference to one or more HTML templates in the page document object model (DOM) and the downloaded data. Finally, the callback injects the string in the page's DOM.
Now let's take a look at some code. In this implementation, the heart of BST is in the JavaScript MarkupBuilder class, which accepts up to three HTML templates—header, footer, and item. You can reference these templates directly from the DOM or you can specify them as plain string literals:
function pageLoad()
{
    if (builder === null)
    {
        builder = new Samples.MarkupBuilder();
        builder.loadHeader($get("header"));
        builder.loadFooter($get("footer"));
        builder.loadItemTemplate($get("item"));
   }
}
You can embed HTML templates directly in the page using invisible DIVs. However, this only works if the markup in the block is well formed. A better option would be to embed templates as XML data islands, as shown here:
<xml id="item">
    <tr style="background-color:#F0FAFF;">
        <td align="left">#Symbol</td>
        <td align="right">#Quote</td>
        <td align="right">#Change</td>
    </tr>
</xml>
As you can see, the template is a chunk of HTML that refers to binding fields using a custom notation. In this case, I'm using the #PropertyName expression to indicate the placeholder for a bound value. When data is available, you just invoke the bind method on the markup builder:
function _getLiveQuotes()
{
    Samples.WebServices.LiveQuoteService.Update(onDataAvailable);
}
function onDataAvailable(results)
{
    var temp = builder.bind(results);
    $get("grid").innerHTML = temp;
}
Needless to say, the element named grid is the placeholder for the final output in this example. The MarkupBuilder class is based on the Microsoft AJAX Client Library. Its full source code is found in Figure 6.
Figure 6 MarkupBuilder Class
Type.registerNamespace('Samples');

// Class ctor
Samples.MarkupBuilder = function Samples$MarkupBuilder()
{
    Samples.MarkupBuilder.initializeBase(this);

    // Initializes private members
    this._header = "";
    this._footer = "";
    this._itemTemplate = "";
}
Samples.MarkupBuilder = function Samples$MarkupBuilder(header, footer)
{
   Samples.MarkupBuilder.initializeBase(this);

    // Initializes the private members
    this._header = header;
    this._footer = footer;
    this._itemTemplate = "";
}

// PROPERTY:: header (String)
function Samples$MarkupBuilder$get_header() {
    if (arguments.length !== 0) throw Error.parameterCount();
    return this._header;
}
function Samples$MarkupBuilder$set_header(value) {
    var e = Function._validateParams(arguments, [{name: 'value',
        type: String}]);
    if (e) throw e;

    this._header = value;
}

// PROPERTY:: footer (String)
function Samples$MarkupBuilder$get_footer() {
    if (arguments.length !== 0) throw Error.parameterCount();
    return this._footer;
}
function Samples$MarkupBuilder$set_footer(value) {
    var e = Function._validateParams(arguments, [{name: 'value',
        type: String}]);
    if (e) throw e;

    this._footer = value;
}

// PROPERTY:: itemTemplate (String)
function Samples$MarkupBuilder$get_itemTemplate() {
    if (arguments.length !== 0) throw Error.parameterCount();
    return this._itemTemplate;
}
function Samples$MarkupBuilder$set_itemTemplate(value) {
    var e = Function._validateParams(arguments, [{name: 'value',
        type: String}]);
    if (e) throw e;

    this._itemTemplate = value;
}

// METHOD:: bind()
function Samples$MarkupBuilder$bind(data) {
   var temp = this._generate(data);
   return temp;
}
// METHOD:: loadHeader()
function Samples$MarkupBuilder$loadHeader(domElement) {
   var temp = domElement.innerHTML;
   this._header = temp;
}

// METHOD:: loadFooter()
function Samples$MarkupBuilder$loadFooter(domElement) {
   var temp = domElement.innerHTML;
   this._footer = temp;
}

// METHOD:: loadItemTemplate()
function Samples$MarkupBuilder$loadItemTemplate(domElement) {
   var temp = domElement.innerHTML;
   this._itemTemplate = temp;
}

///////                     ///////
///////  PRIVATE members    ///////
///////                     ///////

function Samples$MarkupBuilder$_generate(data) {
    var _builder = new Sys.StringBuilder(this._header);

    for(i=0; i<data.length; i++)
    {
        var dataItem = data[i];
        var template = this._itemTemplate;

        var pattern = /#\w+/g;  // Finds all #word occurrences
        var matches = template.match(pattern);
        for (j=0; j<matches.length; j++)
        {
            var name = matches[j];
            name = name.slice(1);
            template = template.replace(matches[j], dataItem[name]);
        }

        _builder.append(template);
    }

    _builder.append(this._footer);
    return _builder.toString();
}

// PROTOTYPE
Samples.MarkupBuilder.prototype =
{
    get_header:         Samples$MarkupBuilder$get_header,
    set_header:         Samples$MarkupBuilder$set_header,
    get_footer:         Samples$MarkupBuilder$get_footer,
    set_footer:         Samples$MarkupBuilder$set_footer,
    get_itemTemplate:   Samples$MarkupBuilder$get_itemTemplate,
    set_itemTemplate:   Samples$MarkupBuilder$set_itemTemplate,
    bind:               Samples$MarkupBuilder$bind,
    _generate:          Samples$MarkupBuilder$_generate,
    loadHeader:         Samples$MarkupBuilder$loadHeader,
    loadFooter:         Samples$MarkupBuilder$loadFooter,
    loadItemTemplate:   Samples$MarkupBuilder$loadItemTemplate
}

Samples.MarkupBuilder.registerClass('Samples.MarkupBuilder');
Internally, the markup builder uses a Sys.StringBuilder object to compose the HTML string. It first adds the header template (if any) and then proceeds to loop over the bound data. Finally, it adds the footer template. In this implementation, header and footer templates are not data-bound. (Figure 7 shows a page using the markup builder.)
Figure 7 New Page Using the Markup Builder

Further Considerations
Is there any difference between specifying the template as a plain string or as an embedded DOM subtree or XML data island? From the markup builder's perspective, it doesn't really matter—all that it needs is a string to append to the string builder buffer. From the developer's perspective, using DOM templates may be a better option because you can more easily validate your template and might also be able to download the template from a URL.
Designed to work only with collections of data, the solution presented here follows the guidelines of other free frameworks for client-side templating. One of these frameworks that I would like to specifically mention is PrototypeJS. For more information, samples, and source code, refer to prototypejs.org/api/template.
Is there anything that you can improve? Absolutely! Note that the code presented in this column implements the minimum set of features one would expect from a browser-side template and binding engine.
As you can see in Figure 7, the current implementation does not have colored type to distinguish the prices of rising and falling stocks, as Figure 2 had. In the code of Figure 2, I handle the RowDataBound event of the GridView control and directly modify the style of involved cells:
void GridView1_RowDataBound(object sender, GridViewRowEventArgs e)
{
    if (e.Row.Cells[2].Text.StartsWith("+"))
        e.Row.Cells[2].ForeColor = Color.Green;
    if (e.Row.Cells[2].Text.StartsWith("-"))
        e.Row.Cells[2].ForeColor = Color.Red;
}
Within a partial rendering solution, this styling happens on the server and therefore has the ability to leverage the rich programming model of server data-bound controls. In a client-side solution, you need a more sophisticated markup builder that accepts a function delegate that styles any piece of bound data before it is appended to the buffer.
Another more important difference exists between the code that producedFigures 2 and 7 that doesn't show up through the printed figures. To discover this difference, try running both pages and click on the other buttons you see (Weather Forecasts and Start Some Task). The page depicted in Figure 7 does not stop other tasks while it retrieves stock quotes and the service call is not aborted if the user clicks to start some other task.
What's the point? Remember that with partial rendering, you can only have one request pending at a time per session—just like in a normal non-AJAX page. Of course, you can have any number of simultaneous calls if you control them directly through XMLHttpRequest. Furthermore, if you make direct service calls, you have no view state around and no worries about keeping it consistent across multiple partial rendering calls (which is the real reason why the partial rendering implementation prevents you from executing concurrent operations).

The HTML Message Pattern
To top off this column, let me just make a quick comment on another pattern that really deserves more attention in a future column—it's called the HTML Message pattern. The goal of the HTML Message pattern is to have the server generate blocks of HTML markup to be displayed in the browser. As you can see, it falls somewhere between partial rendering and other models for building true AJAX applications.
How would you use this pattern? One possible implementation would be to make a call to a remote URL (either a service or an ad hoc HTTP handler) and receive an HTML snippet ready for display. Note that it generates more traffic than plain service calls but also less traffic than partial rendering.
On the server, you can use fresh instances of server controls (no view state) to assemble any output you need, styled as you like. I'll return to this pattern in a future column.
In the meantime, remember that when you're working with ASP.NET AJAX, you need programming tools to define an AJAX service layer and call it from the client browser. In addition, you need powerful tools to manipulate data on the client effectively, such as JavaScript-based data binding and templates.
Hopefully when you take a look at the sample implementation of the BST AJAX pattern I presented in this column and compare it to solutions based on partial rendering, you will inevitably come to the same conclusions that I did.

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

Dino Esposito is the author of Programming ASP.NET 3.5 Core References. 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
The Open Closed Principle
Jeremy Miller

Contents
Single Responsibility Principle
The Chain of Responsibility Pattern
Double Dispatch
Liskov Substitution Principle
Finding Closure
This is the first installment of a new MSDN® Magazine column on software design fundamentals. My marching orders are to discuss design patterns and principles in a manner that isn't bound to a specific tool or lifecycle methodology. In other words, my plan is to talk about the bedrock knowledge that can lead you to better designs in any technology or project.
I'd like to start with a discussion of the Open Closed Principle and other related ideas popularized by Robert C. Martin in his book, Agile Software Development, Principles, Patterns, and Practices. Don't be turned off by the word "agile" in the title, because this is all about striving for good software designs.
Ask yourself this: how many times do you start writing a brand new application from nothing versus the number of times you start by adding new functionality to an existing codebase? Chances are good that you spend far more time adding new features to an existing codebase.
Then ask yourself another question: is it easier to write all new code or to make changes to existing code? It's usually far easier for me to write all new methods and classes than it is to break into old code and find the sections I need to change. Modifying old code adds the risk of breaking existing functionality. With new code you generally only have to test the new functionality. When you modify old code you have to both test your changes and then perform a set of regression tests to make sure you didn't break any of the existing code.
So you generally work on an existing codebase, but yet it's easier to write all new code than it is to change old code. Wouldn't you like extending an existing codebase to be as productive and frustration-free as writing all new code? This is where the Open Closed Principle comes into play. To paraphrase, the Open Closed Principle is stated as: software entities should be open for extension but closed for modification.
It sounds like a contradiction in terms, but it's not. All it means is that you should structure an application so that you can add new functionality with minimal modification to existing code. I used to think that the Open Closed Principle just meant using plug-ins, but there's more to the story than that.
What you want to avoid is to have one simple change ripple through the various classes of your application. That makes the system fragile, prone to regression problems, and expensive to extend. To isolate the changes, you want to write classes and methods in such a way that they never need to change once they are written.
So how do you go about structuring code to isolate changes? I'd say that the very first step is to follow the Single Responsibility Principle.

Single Responsibility Principle
In following the Open Closed Principle, I want to be able to write a class or a method and then turn my back on it, comfortable that it does its job and I won't have to go back and change it. You'll never reach true Open Closed nirvana, but you can inch much closer by rigorously following the related Single Responsibility Principle: a class should have one, and only one, reason to change
One of the easiest ways to write classes that never have to change is to write classes that only do one thing. This way, a class only needs to be modified if the exact thing that it does needs to change. Figure 1 shows a sample that does not follow the Single Responsibility Principle. I seriously doubt you're designing a system like this, but it's good to remember just why we don't structure code this way.
Figure 1 This Class Does Too Much
public class OrderProcessingModule {
  public void Process(OrderStatusMessage orderStatusMessage) {
    // Get the connection string from configuration
    string connectionString =
      ConfigurationManager.ConnectionStrings["Main"]
      .ConnectionString;

    Order order = null;

    using (SqlConnection connection =
      new SqlConnection(connectionString)) {
      // go get some data from the database
      order = fetchData(orderStatusMessage, connection);
    }

    // Apply the changes to the Order from the OrderStatusMessage
    updateTheOrder(order);

    // International orders have a unique set of business rules
    if (order.IsInternational) {
      processInternationalOrder(order);
    }

    // We need to treat larger orders in a special manner
    else if (order.LineItems.Count > 10) {
      processLargeDomesticOrder(order);
    }

    // Smaller domestic orders
    else {
      processRegularDomesticOrder(order);
    }

    // Ship the order if it's ready
    if (order.IsReadyToShip()) {
      ShippingGateway gateway = new ShippingGateway();

      // Transform the Order object into a Shipment
      ShipmentMessage message =
        createShipmentMessageForOrder(order);
      gateway.SendShipment(message);
  }
}
The OrderProcessingModule is pretty busy. It's doing data access, grabbing configuration file information, running business rules for order processing (probably very complicated by itself), and transforming completed orders into shipments. Chances are, if you were to build the OrderProcessingModule this way, you would be constantly breaking into this code to make changes. Many changes in system requirements would cause far too many changes to the OrderProcessingModule code, making the system risky and expensive to change.
Instead of one big blob of code, you should follow the Single Responsibility Principle to divide the entire OrderProcessingModule class into a subsystem of related classes, with each class fulfilling its own specialized responsibility. For example, you might put all of the data access functions into a new class called OrderDataService and the order business logic in a different class (I'll go into this in more detail in the next section).
In terms of the Open Closed Principle, by dividing the business logic and data access responsibilities into separate classes, you should be able to change either concern independently without affecting the other. A change in physical database deployment might cause you to replace the data access with something completely different (open for extension), while the order logic classes remain completely untouched (closed for modification).
The point of the Single Responsibility Principle isn't just to write smaller classes and methods. The point is that each class should implement a cohesive set of related functions. An easy way to follow the Single Responsibility Principle is to constantly ask yourself whether every method and operation of a class is directly related to the name of that class. If you find some methods that do not fit with the name of the class, you should consider moving those methods to another class.

The Chain of Responsibility Pattern
Business rules will probably face more changes throughout the lifecycle of a codebase than any other part of the system. In the OrderProcessingModule class, there was quite a bit of branching logic for order processing based on what type of order was received:
if (order.IsInternational) {
  processInternationalOrder(order);
}

else if (order.LineItems.Count > 10) {
  processLargeDomesticOrder(order);
}

else {
  processRegularDomesticOrder(order);
}
It's very likely that a real order processing system would grow to encompass more types of orders as the business grows—and accumulate plenty of special exception cases such as those for government and favored customers, and special of the week offers. It would be very advantageous for you to be able to write and test new order handling logic without risking breaking one of the existing business rules.
To that end, you can move closer to the Open Closed Principle for the order processing example by using a form of the Chain of Responsibility pattern, as demonstrated in Figure 2. The first thing I did was to make every conditional branch in the original OrderProcessingModule into a separate class that implements the IOrderHandler interface:
public interface IOrderHandler {
  void ProcessOrder(Order order);
  bool CanProcess(Order order);
}
Figure 2 Introducing a Chain of Responsibility
public class OrderProcessingModule {
  private IOrderHandler[] _handlers;

  public OrderProcessingModule() {
    _handlers = new IOrderHandler[] {
                new InternationalOrderHandler(),
                new SmallDomesticOrderHandler(),
                new LargeDomesticOrderHandler(),
    };
  }

  public void Process (OrderStatusMessage orderStatusMessage,
    Order order) {
    // Apply the changes to the Order from the OrderStatusMessage
    updateTheOrder(order);

    // Find the first IOrderHandler that "knows" how
    // to process this Order
    IOrderHandler handler =
      Array.Find(_handlers, h => h.CanProcess(order));

    handler.ProcessOrder(order);
  }

  private void updateTheOrder(Order order) {
  }
}
I would then write a separate implementation of IOrderHandler for each type of Order, including the logic that basically says, "I know what to do with this Order, let me handle it."
Now that the business logic for each type of Order is isolated to a separate handler class, you can change the business rules for one type of Order without worrying about breaking the rules for another type of Order. Better yet, you can add completely new types of order processing with very minimal change to the existing code.
For example, let's say that, at a later time, I have to add support for government orders in the system. With the Chain of Responsibility pattern, I can write a completely new class called GovernmentOrderHandler that implements the IOrderHandler interface. Once I'm satisfied that GovernmentOrderHandler works the way it's supposed to, I can add the new government order processing rules by a one-line change to the constructor function of OrderProcessingModule:
public OrderProcessingModule() {
  _handlers = new IOrderHandler[] {
              new InternationalOrderHandler(),
              new SmallDomesticOrderHandler(),
              new LargeDomesticOrderHandler(),
              new GovernmentOrderHandler(),
  };
}
By following the Open Closed Principle with the order processing rules, I've made it much easier to add new types of order handling logic to the system. I was able to add the government order rules with much less risk of destabilizing the other types of orders than I would have faced if a single class had implemented all of the various types of order handling.

Double Dispatch
What if the steps become more complicated in the future? What if pure polymorphism just isn't enough to allow for all the possible variations coming up in the future? We can use a pattern called Double Dispatch to pull out the variation into the subclasses in such a way that we don't break existing interface contracts.
For example, let's say that I am building a composite desktop application that displays one screen at a time in some sort of main panel. Every time I open a new screen in the application I need to a number of things. I might need to change the available menus, check the state of the screens already open, do any number of things to customize the display of the whole screen and, oh yeah, display the new screen in some way.
I typically use some variety of the Model View Presenter (MVP) pattern for my desktop client architectures, and I generally use the Application Controller pattern to coordinate the various MVP triads in the application. Given the usage of MVP with an Application Controller (for more information on MVP, see Jean-Paul Boodhoo's MSDN Magazine Design Patterns column on MVP, available at msdn2.microsoft.com/magazine/cc188690), the screen activation might involve these three basic parts:
  1. A Presenter for a single screen. Each Presenter knows everything there is to know about a single specific screen.
  2. An ApplicationShell for the main form of the application. The ApplicationShell is responsible for displaying individual views within a Panel or TabControl of some kind in itself. The ApplicationShell will also include all the menus.
  3. An ApplicationController to act as the traffic cop of the application. The ApplicationController knows about the ApplicationShell and every Presenter that passes through the application. The ApplicationController governs the screen activation and deactivation lifecycles.
If all I need to do is simply show the View in the ApplicationShell on activation the code might look like Figure 3. This is perfectly workable for a simple application, but what if the application becomes more complicated? What if, in the second release, I have new requirements to add menu items to the main shell when some screens are active? And what if I want to start showing additional controls in a new pane along the left edge of the main screen for some views, but not all?
Figure 3 A Simple View-Based App
public interface IApplicationShell {
  void DisplayMainView(object view);
}

public interface IPresenter {
  // Just exposes a getter for the inner WinForms UserControl or Form
  object View { get; }
}

public class ApplicationController {
  private IApplicationShell _shell;

  public ApplicationController(IApplicationShell shell) {
    _shell = shell;
  }

  public void ActivateScreen(IPresenter presenter) {
    teardownCurrentScreen();

    // Setup the new screen
    _shell.DisplayMainView(presenter.View);
  }

  private void teardownCurrentScreen() {
    // teardown the existing screen
  }
}
I still want the architecture to be pluggable so that I can add new screens to the application by simply plugging in new Presenters, so the knowledge of these new menu and left pane constructs should go into the existing Presenter abstraction. I'd then have to change the ApplicationShell or the ApplicationController to react to the new menu items and the additional controls placed in the left pane.
Figure 4 shows a possible solution. I've added new properties to the IPresenter interface to model the new menu items and any additional controls that might be added to the new left pane. I also added some new members to IApplicationShell for these new concepts. Then I added new code to the ApplicationController.ActivateScreen(IPresenter) method.
Figure 4 Trying to Extend IPresenter
public class MenuCommand
{
    // ...
}
public interface IApplicationShell
{
    void DisplayMainView(object view);

    // New behavior
    void AddMenuCommands(MenuCommand[] commands);
    void DisplayInExplorerPane(object paneView);
}
public interface IPresenter
{
    object View { get; }

    // New properties
    MenuCommand[] Commands{ get; }
    object[] ExplorerViews { get; }
}
public class ApplicationController
    {
    private IApplicationShell _shell;

    public ApplicationController(IApplicationShell shell)
        {
        _shell = shell;
        }

    public void ActivateScreen(IPresenter presenter)
    {
        teardownCurrentScreen();

        // Setup the new screen
        _shell.DisplayMainView(presenter.View);

        // New code
        _shell.AddMenuCommands(presenter.Commands);
        foreach (var explorerView in presenter.ExplorerViews)
        {
        _shell.DisplayInExplorerPane(explorerView);
        }
    }

    private void teardownCurrentScreen()
    {
        // teardown the existing screen
    }
}
So, did this solution conform to the Open Closed Principle? Not in the slightest. First, I had to modify the IPresenter interface. Since it is an interface, I would have had to find every implementer of the IPresenter interface in my codebase and add empty implementations of these new methods just so that my code could compile again. That's often an intolerable change, especially if any of these IPresenter implementers are outside your immediate control. More on this later.
I also had to modify the ApplicationController class so it knows about all of the new types of customizations each screen might need on the main ApplicationShell. Finally, I needed to modify ApplicationShell to support the new shell customizations. The changes were minor, but then again, it's not unlikely I'll want to add even more screen customizations later.
In a real application, the ApplicationController class can get complicated enough without having to assume additional responsibilities for configuring ApplicationShell. It would be nice if we could keep this responsibility back in each Presenter.
The change to each IPresenter implementation could be alleviated by using an abstract class called Presenter instead of an interface. I could just add default implementations to the abstract class as shown in Figure 5. And I wouldn't have to change any of the existing Presenter implementations to add the new behavior.
Figure 5 Using an Abstract Presenter
public abstract class BasePresenter
{
    public abstract object View { get;}

    // Default implementation of Commands
    public virtual MenuCommand[] Commands
    {
         get
         {
             return new MenuCommand[0];
         }
    }

    // Default ExplorerViews
    public virtual object[] ExplorerViews
    {
         get
         {
             return new object[0];
         }
    }
}
There is another way to move closer to the Open Closed Principle ideal that might be cleaner in the end. Instead of putting getters on the IPresenter or BasePresenter abstraction, I could use the double dispatch pattern.
I got an unexpected demonstration of the double dispatch pattern in real life the other day. My team had just moved into a new office space and we were battling networking issues. Our networking guru called me last week and started telling me what my coworker should do to connect to the VPN. He rattled off a bunch of networking mumbo jumbo I didn't understand, so I finally just handed the phone off to my coworker to let them talk directly.
Now, let's do the same thing for the ApplicationController. Instead of the ApplicationController asking each Presenter what needs to be displayed in the ApplicationShell, the Presenter will just skip the middle man and tell the ApplicationShell what it needs to do for each screen (see Figure 6).
Figure 6 Double Dispatch Presenter
public interface IPresenter {
  void SetupView(IApplicationShell shell);
}

public class ApplicationController {
  private IApplicationShell _shell;

  public ApplicationController(IApplicationShell shell) {
    _shell = shell;
  }

  public void ActivateScreen(IPresenter presenter) {
    teardownCurrentScreen();

    // Set up the new screen using Double Dispatch
    presenter.SetupView(_shell);
  }

  private void teardownCurrentScreen() {
    // tear down the existing screen
  }
}
I would have to change ApplicationShell for the new menu customization and left pane controls no matter what I had done at first, but if I had started with the Double Dispatch strategy, I could have made the new changes with fewer modifications to both ApplicationController and each Presenter. I no longer need to touch either the ApplicationController or the Presenter classes to create additional screen concepts. The architecture is open to be extended for new shell concepts, but the ApplicationController and the individual Presenter classes are closed for modification.

Liskov Substitution Principle
As I said earlier, the most common manifestation of the Open Closed Principle is using polymorphism to substitute an existing part of the application with a brand new class. Let's say that at the beginning of the day you have a class called BusinessProcess whose job is to, well, execute a business process. Along the way, it needs to access data from a data source:
public class BusinessProcess {
  private IDataSource _source;

  public BusinessProcess(IDataSource source) {
    _source = source;
  }
}
public interface IDataSource {
  Entity FindEntity(long key);
}
The design follows the Open Closed Principle if you can extend the system by swapping out implementations of IDataSource without making any change to the BusinessProcess class. You might start out with a simple XML file-based mechanism, and then move to using a database for storage, followed eventually by some sort of caching—but you still don't want to change BusinessProcess class. All of that is possible, but only if you follow a related principle: the Liskov Substitution Principle.
Roughly stated, you are following the Liskov Substitution Principle if you can use any implementation of an abstraction in any place that accepts that abstraction. The BusinessProcess should be able to use any implementation of IDataSource without modification. BusinessProcess should not know anything about the internals of IDataSource other than what is communicated through the public interface.
To put it into perspective, Figure 7 shows an example that flunks the Liskov Substitution Principle. This version of the BusinessProcess class has specific logic to bootstrap a FileSource and also relies on knowledge of some specific error handling logic for the DatabaseSource class. You create the implementers of IDataSource such that they can handle all of their specific infrastructure needs. Doing this will enable the BusinessProcess class to be written, as shown in Figure 8.
Figure 7 BusinessProcess that Cannot Abstract IDataSource
public class BusinessProcess {
  private IDataSource _source;

  public BusinessProcess(IDataSource source) {
    _source = source;
  }

  public void Process() {
    long theKey = 112;

    // Special code if we're using a FileSource
    if (_source is FileSource)  {
      ((FileSource)_source).LoadFile();
    }

    try {
      Entity entity = _source.FindEntity(theKey);
    }
    catch (System.Data.DataException) {
      // Special exception handling for the DatabaseSource,
      // This is an example of "Downcasting"
      ((DatabaseSource)_source).CleanUpTheConnection();
    }
  }
}
Figure 8 Better BusinessProcess
public class BusinessProcess {
  private readonly IDataSource _source;

  public BusinessProcess(IDataSource source) {
    _source = source;
  }

  public void Process(Message message) {
    // the first part of the Process() method

    // There is NO code specific to any implementation of     // IDataSource here
    Entity entity = _source.FindEntity(message.Key);

    // the last part of the Process() method
  }
}

Finding Closure
Just remember, the Open Closed Principle is only realized by polymorphism if a class only depends on the public contract of the other classes it interacts with. If a class that uses an abstraction has to downcast to a specific subclass in one section, you're not following the Open Closed Principle.
If a class that uses another class embeds knowledge about the internal workings of its dependency (like assuming that results of a method are always sorted from big to small), then you can't actually substitute another implementation for that dependency. Those types of implicit coupling to a specific implementation are particularly pernicious because they aren't obvious to a reader of your code. Don't let the consumer of an abstraction depend on anything but the public contract of that abstraction.
I would recommend that you treat the Open Closed Principle as a design vector rather than an outright goal. If you try to make everything that you think could possibly change fully pluggable, you're likely going to create an over-designed system that is very difficult to work with. You may not always manage to write code that satisfies the Open Closed Principle in every aspect, but even moving partway there can be beneficial.

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

Jeremy Miller A Microsoft MVP for C#, Jeremy is 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," at codebetter.com/blogs/jeremy.miller, part of the CodeBetter site.


Service Station
Building A WCF Router, Part 2
Michele Leroux Bustamante

Code download available at: ServiceStation2008_06.exe (340 KB)
Browse the Code Online

Contents
Pass-Through Router Scenarios
Forwarding by Action Header
Forwarding with Custom Headers
Registering Services
Inspecting Messages
Routers and Transport Sessions
Duplex Routers
Mixed Transport Sessions
In the April 2008 installment of Service Station, I showed you how to create a simple router that allows messages to flow transparently between the calling client and the target service. In the process, I reviewed important Windows® Communication Foundation (WCF) addressing and message filtering semantics, you learned how to design a router contract to work with untyped messages, and you learned how to configure the bindings and behaviors to allow messages to pass through untouched by the router. In this issue I'll continue the discussion by looking at further implementation details that arise when more practical scenarios for routers are employed.

Pass-Through Router Scenarios
As I mentioned in Part 1, when a pass-through router is inserted between a client and a service, the client's relationship is with the target service, not the router. Although certainly messages must be sent with a transport protocol and message encoder that the router can understand, the entire contents of the message—including security headers and reliable sessions, for example—are not processed by the router. A few examples where a pass-through router might apply are load balancing, content-based routing, or message transformation.
Load balancing and distribution of work across server resources is best suited to Network Load Balancing (NLB) or, better yet, hardware load-balancing devices. Still, a WCF router can be useful for load balancing if services are hosted in environments without these luxuries, when services are installed to physical infrastructures out of your direct control, when you need routing based on domain-specific logic, or when the application simply calls for a lightweight routing solution that is simple to configure. Such a WCF router can be used to distribute messages to services hosted in multiple processes on the same machine or distributed across machines.
Regardless of the distribution model, a load-balancing router certainly requires a few core features. Services must somehow register with the router in order to be included in load distribution. The router must be able to determine the service type and associated endpoint so that it can correctly forward messages. And the router must have an algorithm for distributing load such as a classic round-robin approach or some form or priority-based routing.
Sometimes distribution of messages among services is handled based on the content of the message, as opposed to load balancing. A content-based router will typically inspect either the message headers or the message body for routing information. For example, messages from clients with a valid license key may be forwarded as high priority to a large pool of server machines with more processing power, while those with a trial license are forwarded to a smaller pool of less powerful servers. In this scenario the router must not only know where to forward messages, but it must also be able to inspect each message, its headers or body content, before making the decision on where to forward. The following sections will discuss relevant routing features that support these scenarios.

Forwarding by Action Header
Messages received at the router have two addressing headers that can be useful in forwarding messages to the correct service:
To This header indicates the name of the endpoint. If the header matches the target service and not the router, it will indicate a URL for the service endpoint that the message was intended for.
Action This header indicates the service operation that the message was intended for, but it may not represent a valid URL per se.
In many cases, however, the To header will match the router address and not the service, leaving the Action header as the more reliable source of information as to the correct destination for the message. Recall that the Action header is derived from the service contract namespace, the service contract name, and the operation name. This is sufficient information for a router to uniquely identify the target service, assuming that contracts are not shared across different service types. Consider the following service contracts, each implemented on different service types:
[ServiceContract(Namespace =
"http://www.thatindigogirl.com/samples/2008/01")]
public interface IServiceA {
  [OperationContract]
  string SendMessage(string msg);
}
[ServiceContract(Namespace =
  "http://www.thatindigogirl.com/samples/2008/01")]
public interface IServiceB {
  [OperationContract]
  string SendMessage(string msg);
}
public class ServiceA : IServiceA {...}
public class ServiceB : IServiceB{...}
As Figure 1 illustrates, the router can rely on a mapping between contract namespaces for each service contract and the service endpoints to which messages should be directed.
Figure 1 Mapping Contract Namespace to Service Endpoint
The following shows a dictionary initialized so that each contract namespace entry maps to a configuration element that indicates the correct channel configuration settings to use:
static public IDictionary<string, string> RegistrationList =
  new Dictionary<string, string>();

RegistrationList.Add(
  "http://www.thatindigogirl.com/samples/2008/01/IServiceA",
  "ServiceA");
RegistrationList.Add(
  "http://www.thatindigogirl.com/samples/2008/01/IServiceB",
  "ServiceB");
The code to initialize the channel would then look like this:
string contractNamespace =
  requestMessage.Headers.Action.Substring(0,
  requestMessage.Headers.Action.LastIndexOf("/"));

string configurationName =
  RouterService.RegistrationList[contractNamespace];

using (ChannelFactory<IRouterService> factory =
  new ChannelFactory<IRouterService>(configurationName))
{...}
There are a few important design dependencies in this scenario that you should note:
  • The map of contracts to services would most likely live in a database to simplify configuration and to support multiple router instances.
  • The service contract cannot be implemented on multiple service types unless messages can be processed by any service implementing the contract.
  • If there are multiple instances of the service in a server farm, the configuration for each endpoint should map to a virtual address that the physical load balancers can then distribute accordingly.
  • There is no support for messages that contain an action header other than those for application services.
This last point is important, because if secure sessions or reliable sessions are enabled for application services, then there will be additional messages sent to establish those sessions prior to actual application service messages. These messages use an Action header for their respective protocols and are completely independent of any application service. This means that an alternative to the Action header must be used for message forwarding.

Forwarding with Custom Headers
To ensure that every message contains a routing header that can properly indicate the application service the client is trying to communicate with, a custom header can be specified in the application service endpoint configuration section, as shown here:
<service behaviorConfiguration="serviceBehavior"
  name="MessageManager.ServiceA">
  <endpoint address="http://localhost:8010/RouterService"
    binding="wsHttpBinding" bindingConfiguration="wsHttp"
    contract="IServiceA" listenUri="ServiceA">
    <headers>
      <Route
        xmlns="http://www.thatindigogirl.com/samples/2008/01">
        http://www.thatindigogirl.com/samples/2008/01/IServiceA
      </Route>
    </headers>
  </endpoint>
</service>
Custom headers have a name, a namespace, and a value. In some cases, headers are more dynamic, but in this case the header is fixed to represent the service contract namespace. The Route element indicates the header name, and the namespace is indicated by the xmlns attribute. Since this header is specified as part of the endpoint configuration, it is included in the metadata for the service. As such, when clients generate a proxy, they also generate a client configuration that includes the header, as shown here:
<client>
  <endpoint address="http://localhost:8010/RouterService"
    binding="wsHttpBinding" bindingConfiguration="wsHttp"
    contract="localhost.IServiceA" >
    <headers>
      <Route xmlns="http://www.thatindigogirl.com/samples/2008/01">
        http://www.thatindigogirl.com/samples/2008/01/IServiceA
      </Route>
    </headers>
  </endpoint>
</client>
This makes the presence of the header transparent to the client coding effort and ensures that all messages, including those to establish secure sessions or reliable sessions, include the header. The router can retrieve the header value from any message by its name and namespace, as follows:
string contractNamespace =
  requestMessage.Headers.GetHeader<string>(
  "Route",
  "http://www.thatindigogirl.com/samples/2008/01");
The only change to this implementation from the previous example is in how the router discovers the contract namespace—from the custom Route header instead of the Action header. This allows the router to forward messages related to secure sessions or reliable sessions to the appropriate service endpoint.

Registering Services
Rather than hardcoding endpoints for application services, the router can expose a service endpoint for services to register and unregister as they come online and go offline. In the absence of a software or hardware load balancer, this reduces the configuration overhead of the router when the application services must be scaled out, or when ports or machine names change in their respective endpoint addresses. To support this model, the following steps can be taken:
  • Implement a service registration contract for the router and expose that endpoint to app services behind the firewall.
  • Maintain a registration list for the router.
  • After each ServiceHost is initialized, have it register service endpoints with the router.
  • As each ServiceHost is faulted or closed, unregister service endpoints with the router.
The diagram in Figure 2 illustrates the registration process, which adds entries that hold the contract namespace mapped to a physical endpoint address.
Figure 2 Registering Services with the Router
With this approach, registration only requires a contract namespace and physical address for each service endpoint. Figure 3 shows the IRegistrationService service contract and associated RegistrationInfo details that are passed to the router to register and unregister.
Figure 3 IRegistrationService Contract with Data Contract
[ServiceContract(Namespace =
  "http://www.thatindigogirl.com/samples/2008/01")]
public interface IRegistrationService {
  [OperationContract]
  void Register(RegistrationInfo regInfo);

  [OperationContract]
  void Unregister(RegistrationInfo regInfo);
}

[DataContract(Namespace =
  "http://schemas.thatindigogirl.com/samples/2008/01")]
public class RegistrationInfo {
  [DataMember(IsRequired = true, Order = 1)]
  public string Address { get; set; }

  [DataMember(IsRequired = true, Order = 2)]
  public string ContractName { get; set; }

  [DataMember(IsRequired = true, Order = 3)]
  public string ContractNamespace { get; set; }

  public override int GetHashCode()   {
    return this.Address.GetHashCode() +
    this.ContractName.GetHashCode() +
    this.ContractNamespace.GetHashCode();
  }
}
The router could store a single entry per contract—but that would not allow for more than one service for each contract. In order to support distribution across multiple entries, the router should use a unique key per registration. This code uses a dictionary that uniquely associates each entry with a hash code for the RegistrationInfo instance:
// registration list
static public IDictionary<int, RegistrationInfo>
  RegistrationList =
  new Dictionary<int, RegistrationInfo>();

// to register
if (!RouterService.RegistrationList.ContainsKey(
  regInfo.GetHashCode())) {
  RouterService.RegistrationList.Add(regInfo.GetHashCode(),
    regInfo);
  }

  // to unregister
  if (RouterService.RegistrationList.ContainsKey(
    regInfo.GetHashCode())) {
    RouterService.RegistrationList.Remove(
      regInfo.GetHashCode());
  }
When the router receives messages, it should gather the contract namespace and look for a suitable item in the dictionary that matches—and if more than one exists, use selection criteria to forward the message to an appropriate service endpoint (see Figure 4).
Figure 4 Matching Messages to Appropriate Endpoints
string contractNamespace =
  requestMessage.Headers.Action.Substring(0,
  requestMessage.Headers.Action.LastIndexOf("/"));

// get a list of all registered service entries for
// the specified contract
var results = from item in RouterService.RegistrationList
  where item.Value.ContractNamespace.Contains(contractNamespace)
  select item;

int index = 0;
// find the next address used ...

// create the channel
RegistrationInfo regInfo = results.ElementAt<KeyValuePair<int,
  RegistrationInfo>>(index).Value;

Uri addressUri = new Uri(regInfo.Address);
Binding binding = ConfigurationUtility.GetRouterBinding    (addressUri.Scheme);
EndpointAddress endpointAddress = new EndpointAddress(regInfo.Address);

ChannelFactory<IRouterService> factory = new
  ChannelFactory<IRouterService>(binding, endpointAddress)
// forward message to the service ...
Aside from filling load balancing needs to services across machines, dynamic registration can be very useful in scenarios where multiple instances of a service may be hosted on the same machine—which requires multiple port assignments if they are hosted in a Windows service.
In order to support this, services should select a dynamic port assignment for the machine. For TCP services, this can be accomplished by setting the listen URI mode to Unique in the endpoint configuration:
<endpoint address="net.tcp://localhost:9000/ServiceA"
  contract=" IServiceA" binding="netTcpBinding"
  listenUriMode="Unique"/>
For named pipes and HTTP, however, this setting does not select a unique port. Instead it appends a GUID to the address:
net.tcp://localhost:64544/ServiceA
http://localhost:8000/ServiceA/66e9c367-b681-4e4f-8d12-80a631b7bc9b
net.pipe://localhost/ServiceA/6660c07e-c9f5-450b-8d40-693ad1a71c6e
To ensure a unique port for TCP and HTTP service endpoints, you can initialize base addresses or explicit endpoint addresses in code:
Uri httpBase = new Uri(string.Format(
  "http://localhost:{0}",
  FindFreePort()));
Uri tcpBase = new Uri(string.Format(
  "net.tcp://localhost:{0}",
  FindFreePort()));
Uri netPipeBase = new Uri(string.Format(
  "net.pipe://localhost/{0}",
  Guid.NewGuid().ToString()));

ServiceHost host = new ServiceHost(typeof(ServiceA),
  httpBase, tcpBase, netPipeBase);
Figure 5 illustrates multiple services hosted on the same machine, registering to the router. This diagram also shows that, in order to remove the single point of failure of the router, a software or physical load balancer may still be necessary to distribute registration calls among instances. Of course, this also implies that the registration list is stored in a shared database.
Figure 5 Registering Services with Dynamic Ports through a Load Balanced Router

Inspecting Messages
Although routers typically forward the original message to application services, they may perform activities based on the content of the message, such as inspecting headers or body elements for content-based routing or rejecting messages based on validity of headers or body elements.
Inspecting headers is trivial since the Message type exposes a Headers property to retrieve addressing headers directly and custom headers by their name and namespace. Consider the following service operation, which uses a message contract to add a custom LicenseKey header for the incoming operation:
// operation
[OperationContract]
SendMessageResponse SendMessage(SendMessageRequest message);

// message contract
[MessageContract]
public class SendMessageRequest {
  [MessageHeader]
  public string LicenseKey { get; set; }

  [MessageBodyMember]
  public string Message { get; set; }
}
Clients will send messages including a LicenseKey header, possibly empty if they don't yet have a license key. The router can retrieve this header, as follows:
string licenseKey =
  requestMessage.Headers.GetHeader<string>(
  "LicenseKey",
  "http://www.thatindigogirl.com/samples/2008/01");
If the same LicenseKey value were to be passed inside the message body, the router must read the message body to access the value (since this information is not directly available through the Message type). The method GetReaderAtBodyContents returns an XmlDictionaryReader that can be used to read the message body, as follows:
XmlDictionaryReader bodyReader =
  requestMessage.GetReaderAtBodyContents();
The State property of the Message can be any of the following MessageType enumeration values: Created, Copied, Read, Written, or Closed. The message begins in Created state—and routers receiving Message parameters to operations do not process messages, thus the state remains Created.
Reading the message body causes the request message to move from Created to Read state. Once read, it cannot be forwarded to application services because the message can only be read once, written to once, or copied once.
Before reading the message, a content-based router implementation should copy the message to a buffer. Using this buffered copy of the message, new copies of the original message can be created and used for processing, as follows:
MessageBuffer messageBuffer =
  requestMessage.CreateBufferedCopy(int.MaxValue);
Message messageCopy = messageBuffer.CreateMessage();
XmlDictionaryReader bodyReader =
  messageCopy.GetReaderAtBodyContents();

XmlDocument doc = new XmlDocument();
doc.Load(bodyReader);
XmlNodeList elements = doc.GetElementsByTagName("LicenseKey");
string licenseKey = elements[0].InnerText;
The same buffer can be used again to create a message for forwarding to application services. The call to CreateMessage returns a new Message instance based on the original message.

Routers and Transport Sessions
In a pass-through router situation, clients must send messages using the transport protocol and encoding format that the router expects, and the router must forward the message to application services using the transport protocol and encoding format they expect. All of the routing features discussed so far work great when both ends are HTTP—with or without sessions. However, when you introduce a transport session such as TCP, some interesting challenges arise. Everything is fine in the simplest case where security is disabled and there are no reliable sessions, but challenges are introduced when these features are added.
Once security is enabled for the application service, the router must provide a signed To header. Normally this means leaving the To header untouched—as it was sent by the client—but by default the router will modify the To header to match the address of the service when messages are sent, unless manual addressing is enabled. If, for example, the router uses TCP protocol to forward messages to a service, manual addressing is not allowed if the outgoing channel is based on a request-reply contract.
Another problem arises if reliable sessions are enabled and the router uses TCP protocol to call the service. In this case, asynchronous acknowledgments are sent back through the router. That requires the router to maintain a session with the service to receive those asynchronous acknowledgments. As a result, the client must maintain a duplex session with the router to receive the same asynchronous acknowledgments.
Both problems can be solved in part by implementing a router that supports sessions and relies on duplex incoming and outgoing channels. Neither the calling client nor the application service need be directly aware of this—it is an implementation detail within the router. There is, however, a dependency on session-aware bindings, and on duplex communication when asynchronous reliable session acknowledgements are introduced.

Duplex Routers
The code in Figure 6 shows an example of a duplex router contract in order to support the scenario where messages are sent over TCP between client, router, and application services. It is different from the traditional request-reply router contract in the following ways:
  • ProcessMessage is now a one-way operation.
  • The service contract requires sessions and has an associated callback contract. It is important for you to note that this does not require the client to implement a callback; this is internal to the router.
  • The callback contract has a single one-way method to receive responses from router calls to application services. Note also that services are not aware that their responses are being sent to a callback channel; they can be request-reply messages.
Figure 6 Duplex Router Contract
[ServiceContract(Namespace =
  "http://www.thatindigogirl.com/samples/2008/01",
  SessionMode = SessionMode.Required,
  CallbackContract = typeof(IDuplexRouterCallback))]

public interface IDuplexRouterService {
  [OperationContract(IsOneWay=true, Action = "*")]
  void ProcessMessage(Message requestMessage);
}

[ServiceContract(Namespace =
  "http://www.thatindigogirl.com/samples/2008/01",
  SessionMode = SessionMode.Allowed)]
public interface IDuplexRouterCallback {
  [OperationContract(IsOneWay=true, Action = "*")]
  void ProcessMessage(Message requestMessage);
}
The architecture for a duplex router is illustrated in Figure 7. As far as the client is concerned, requests are sent and a synchronous reply is expected. The router receives requests to a one-way operation and saves the client's callback channel in order to send the reply. In the meantime, the router forwards messages using a duplex channel and provides a callback channel to receive the reply from the service.
Figure 7 Duplex Router Architecture
The service receives the request and sends a synchronous reply, received by the router's callback channel. This callback channel in turn uses the client callback channel to send a response back to the client. From start to finish, the operation behaves synchronously—but the router decouples activities and relies on duplex communication in the underlying receive and send channels to correlate messages.
The router implementation for this is shown in Figure 8. There are a few relevant changes to the request-reply router implementations. First, the router supports sessions and implements a duplex contract. When the router forwards messages to services, a duplex channel is created using DuplexChannelFactory<T>, which means supplying a callback object that will receive responses from the service.
Figure 8 Duplex Router Implementation
[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession,
  ConcurrencyMode = ConcurrencyMode.Multiple,
  AddressFilterMode=AddressFilterMode.Any,
  ValidateMustUnderstand=false)]

public class DuplexRouterService : IDuplexRouterService, IDisposable {
  object m_duplexSessionLock = new object();
  IDuplexRouterService m_duplexSession;

  public void ProcessMessage(Message requestMessage)  {
    lock (this.m_duplexSessionLock)  {
      if (this.m_duplexSession == null) {
        IDuplexRouterCallback callback =
          OperationContext.Current.GetCallbackChannel
          <IDuplexRouterCallback>();

        DuplexChannelFactory<IDuplexRouterService> factory =
          new DuplexChannelFactory<IDuplexRouterService>
          (new InstanceContext(null,
          new DuplexRouterCallback(callback)), "serviceEndpoint");
        factory.Endpoint.Behaviors.Add(new MustUnderstandBehavior(false));
        this.m_duplexSession = factory.CreateChannel();
      }
    }

    this.m_duplexSession.ProcessMessage(requestMessage);
  }
  public void Dispose() {
    if (this.m_duplexSession != null) {
      try {
        ICommunicationObject obj = this.m_duplexSession as
          ICommunicationObject;
        if (obj.State == CommunicationState.Faulted)
          obj.Abort();
        else
          obj.Close();
      }
      catch {}
    }
  }
}

public class DuplexRouterCallback : IDuplexRouterCallback {

  private IDuplexRouterCallback m_clientCallback;

  public DuplexRouterCallback(IDuplexRouterCallback clientCallback) {
    m_clientCallback = clientCallback;
  }

  public void ProcessMessage(Message requestMessage) {
    this.m_clientCallback.ProcessMessage(requestMessage);
  }
}
The callback object implements the callback contract, and it will receive responses from the service. This callback object must use the client callback channel to return the response back to the client.
The router service instance, the client callback channel reference, and the router callback channel all live for the duration of the session with the client. For this reason, the router must expose endpoints that support sessions and the downstream service must support sessions for this to work.

Mixed Transport Sessions
In some scenarios it may be desirable for the client to send messages to the router over HTTP, while the router forwards those messages over TCP to application services. When security features or reliable sessions are enabled, even the duplex router configuration isn't sufficient to support the scenario.
As I mentioned, manual addressing is only supported with request-reply channels. Otherwise, the service model relies on addressing features to correlate messages. Since TCP doesn't natively support request-reply, manual addressing is not an option unless the contract is one-way. Thus, the send channel from Figure 7 must be created from a one-way contract like IDuplexRouterService. The callback channel is provided to receive the response.
The router's callback channel must also be kept alive until the response is sent, and the client's callback channel must likewise be kept alive. To support this, the client must have a session with the router, and the router must have a session with the service.
Assuming that application services called by the router are secure, manual addressing is a likely necessity to forward messages untouched by the router. If the router calls application services over TCP, this requires a duplex router implementation, as discussed previously—so that the outgoing call can be a one-way channel. This forces the client to send messages over a session-aware binding, which means enabling secure sessions or reliable sessions over HTTP.
If the router is a pass-through router, the entire point is to let the application service process security and reliable session headers. If the router requires secure sessions or reliable sessions for its client endpoints in order to support sessions over HTTP, the router will process those headers and the session will not be established with application services.
Thus, mixing protocols only works in limited scenarios—unless you reach lower into the channel layer to override default behaviors. When security and reliable sessions are disabled, clients can send messages to the router over HTTP while the router forwards over TCP to application services. If security or reliable sessions are enabled, the client must send messages over TCP to the router so the session can be established without enabling reliable sessions or secure sessions for the router channel.

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

Michele Leroux Bustamante is Chief Architect of IDesign Inc., Microsoft Regional Director for San Diego, and a Microsoft MVP for Connected Systems. Her latest book is Learning WCF. Reach her at mlb@idesign.net or visit idesign.net. Michele blogs at dasblonde.net.


Foundations
Bitmaps And Pixel Bits
Charles Petzold

Code download available at: Foundations2008_06.exe (159 KB)
Browse the Code Online

Contents
Using RenderTargetBitmap
Using WriteableBitmap
Arrays of Pixels
Bitmap Pixel Formats
PixelFormats Errata
Premultiplied Alphas
WriteableBitmap Applications
The retained-mode graphics system of Windows® Presentation Foundation (WPF) has revolutionized Windows graphics programming. No longer are programs required to recreate their visual appearance on the screen whenever the system demands. The composition system retains all graphical figures and arranges them into a total visual presentation.
Retained-mode graphics certainly makes life more convenient, but convenience itself has never been a high priority for Windows programmers. It is really the combination of the retained-mode graphics system with notification mechanisms such as dependency properties that unleashes the flexibility and power of WPF. Graphical objects such as paths and brushes seem to remain "alive" within the composition system and continue to respond to property changes and graphics transforms, thus allowing these objects to be targets of data bindings and animations.
I recently discovered that WPF bitmaps have a similar dynamic quality. A rendered bitmap remains responsive to changes—not only to graphics transforms (this we all knew) but also to changes in the actual pixel bits within the bitmap.
The two bitmap classes that reveal this dynamic responsiveness are RenderTargetBitmap and WriteableBitmap, which are among the nine classes that derive from BitmapSource, the abstract class that is the basis for all bitmap support in WPF. Regardless of how a program uses one of these bitmap objects—whether it's displayed with an Image element, or made into a tiled brush with the ImageBrush class, or as part of a larger drawing (perhaps mixed with vector graphics) with the ImageDrawing class—the bitmap is never simply rendered and forgotten. The bitmap remains alive within the visual composition system and continues to be responsive to application changes.
Virtual Lab Bitmaps, Pixels, and WPF
WPF bitmaps are responsive to changes via both graphics transforms and changes to pixels within the bitmap. In this Virtual Lab, you can experiment with the RenderTargetBitmap and WriteableBitmap classes that make your bitmaps responsive to changes within your application. The environment is all set up, including Charles Petzold's sample code, so you can begin coding immediately as you read this installment of the Foundations column.

Experiment in the Virtual Lab
Using RenderTargetBitmap
A RenderTargetBitmap is a bitmap on which you can effectively draw by transferring objects of type Visual to its surface. The only way to create a new object of type RenderTargetBitmap is with a constructor that requires the pixel dimensions of the bitmap, the horizontal and vertical resolution in dots per inch, and an object of type PixelFormat.
I'll have more to say about the PixelFormat structure and the related static PixelFormats class shortly. For creating objects of type RenderTargetBitmap you must use either PixelFormats.Default or PixelFormats.Pbgra32 as the last argument to the RenderTargetBitmap constructor. In either case, you're creating a bitmap with 32 bits per pixel and transparency.
Initially, the RenderTargetBitmap object is entirely transparent. You can then draw on the bitmap by calling the Render method with an object of type Visual (including classes that derive from Visual such as FrameworkElement and Control). You can restore the all-transparent image by calling Clear. If the bitmap is currently being displayed, these calls are reflected in the displayed bitmap without any further ado.
Figure 1 shows a small, complete program that demonstrates RenderTargetBitmap. The program creates a bitmap 1,200 pixels wide and 900 pixels high. These become the PixelWidth and PixelHeight properties of the bitmap object. Each pixel is 4 bytes wide, so the bitmap occupies more than 4 megabytes of memory.
Figure 1 RenderTargetBitmapDemo
class RenderTargetBitmapDemo : Window
{
    RenderTargetBitmap bitmap;

    [STAThread]
    public static void Main()
    {
        Application app = new Application();
        app.Run(new RenderTargetBitmapDemo());
    }
    public RenderTargetBitmapDemo()
    {
        Title = "RenderTargetBitmap Demo";
        SizeToContent = SizeToContent.WidthAndHeight;
        ResizeMode = ResizeMode.CanMinimize;

        // Create RenderTargetBitmap
        bitmap = new RenderTargetBitmap(1200, 900, 300, 300,
                                        PixelFormats.Default);

        // Create Image for bitmap
        Image img = new Image();
        img.Stretch = Stretch.None;
        img.Source = bitmap;
        Content = img;
    }
    protected override void  OnMouseDown(MouseButtonEventArgs args)
    {
        Point ptMouse = args.GetPosition(this);
        Random rand = new Random();
        Brush brush = new SolidColorBrush(
            Color.FromRgb((byte)rand.Next(256), (byte)rand.Next(256),
                                                (byte)rand.Next(256)));

        DrawingVisual vis = new DrawingVisual();
        DrawingContext dc = vis.RenderOpen();
        dc.DrawEllipse(brush, null, ptMouse, 12, 12);
        dc.Close();

        bitmap.Render(vis);
    }
    protected override void OnClosed(EventArgs args)
    {
        PngBitmapEncoder enc = new PngBitmapEncoder();
        enc.Frames.Add(BitmapFrame.Create(bitmap));
        FileStream stream = new FileStream("RenderTargetBitmapDemo.png",
                                      FileMode.Create, FileAccess.Write);
        enc.Save(stream);
        stream.Close();
    }
}
The call to the RenderTargetBitmap constructor also specifies a resolution of 300 dots per inch. The combination of the pixel dimension and the resolution results in the creation of a bitmap that is 4 inches wide and 3 inches tall. The device-independent WPF coordinate system is 96 units to the inch, so the bitmap has a device-independent width of 384 units and a height of 288 units. These are the numbers you'll see if you examine the Width and Height properties defined by BitmapSource.
The RenderTargetBitmapDemo program uses the Image element to display the bitmap without stretching. It also traps MouseDown events. For each mouse click, the program creates a DrawingVisual object of a little filled circle ¼ inch in diameter and then calls the Render method to add it to the bitmap image. The circle then shows up on the displayed bitmap. You can think of this program as a primitive painting application that combines rendering and storage functionality in a single bitmap.
You might know (or can probably guess) that the Image element displays a bitmap by calling the DrawImage method of the DrawingContext object passed to it during its OnRender method. The Image class does not get repeated calls to its OnRender method when the RenderTargetBitmapDemo program changes the bitmap. These changes to the bitmap are occurring much deeper in the visual composition system.
The RenderTargetBitmapDemo program saves the resultant bitmap in a PNG file format when the program terminates. If you examine the bitmap saved from RenderTargetBitmapDemo, you'll find that it is 1,200 by 900 pixels in size, and that each of the circles is 75 pixels in diameter—which is ¼ inch in units of 300 dots per inch.
Using WriteableBitmap
The WriteableBitmap class has two constructors, one of which is very similar to the RenderTargetBitmap constructor. The first four arguments are the pixel dimensions of the bitmap and the resolution in dots per inch. The fifth argument is a PixelFormat object, but you have much more flexibility than with RenderTargetBitmap. The WriteableBitmap constructor has an additional parameter for a color palette for those bitmap formats that require one.
The pixels of the WriteableBitmap are initialized to all zeroes. What this means depends on the pixel format. In many cases, the bitmap is entirely black. If the bitmap supports transparency, the bitmap is transparent. If the bitmap has a color palette, the entire bitmap is colored with the first color in the palette.
Changing a WriteableBitmap is very different from changing a RenderTargetBitmap. For WriteableBitmap you must call a method named WritePixels that copies actual pixel bits from a local array into the bitmap. Obviously it's crucial to match the format and size of the data in the array to the dimensions and pixel format of the bitmap.
Let's begin with a relatively easy example. The AnimatedBitmapBrush.cs program shown in Figure 2 creates a WriteableBitmap and uses it as the basis of a tiled ImageBrush that it sets to the Background property of the window. The program then sets a timer for 100 milliseconds and repeatedly calls WritePixels to change the bitmap.
Figure 2 AnimatedBitmapBrush
class AnimatedBitmapBrush : Window
{
    const int COLS = 48;
    const int ROWS = 48;

    WriteableBitmap bitmap;
    byte[] pixels = new byte[COLS * ROWS];
    byte pixelLevel = 0x00;

    [STAThread]
    public static void Main()
    {
        Application app = new Application();
        app.Run(new AnimatedBitmapBrush());
    }
    public AnimatedBitmapBrush()
    {
        Title = "Animated Bitmap Brush";
        Width = Height = 300;

        bitmap = new WriteableBitmap(COLS, ROWS, 96, 96,
                                     PixelFormats.Gray8, null);
        ImageBrush brush = new ImageBrush(bitmap);
        brush.TileMode = TileMode.Tile;
        brush.Viewport = new Rect(0, 0, COLS, ROWS);
        brush.ViewportUnits = BrushMappingMode.Absolute;
        Background = brush;

        DispatcherTimer tmr = new DispatcherTimer();
        tmr.Interval = TimeSpan.FromMilliseconds(100);
        tmr.Tick += TimerOnTick;
        tmr.Start();
    }

    void TimerOnTick(object sender, EventArgs args)
    {
        for (int row = 0; row < ROWS; row++)
            for (int col = 0; col < COLS; col++)
            {
                int index = row * COLS + col;

                double distanceFromCenter =
                    2 * Math.Max(Math.Abs(row - ROWS / 2.0) / ROWS,
                                 Math.Abs(col - COLS / 2.0) / COLS);
                pixels[index] =
                    (byte)(0x80 * (1 + distanceFromCenter * pixelLevel));
            }

        bitmap.WritePixels(new Int32Rect(0, 0, COLS, ROWS), pixels, COLS, 0);
        pixelLevel++;
    }
}
The constant COLS and ROWS values define the pixel dimensions of this bitmap. These same values are used for the tiled brush Viewport rectangle and also in the Tick event handler for the timer. The pixel format is set to PixelFormats.Gray8, which means that every pixel in the bitmap is represented by an 8-bit value that indicates a gray shade—the pixel value 0x00 is black and 0xFF is white. The last argument to the WriteableBitmap constructor is set to null because the Gray8 format does not require a palette.
Because each pixel is 1 byte, the dimension of the byte array that I've called pixels is calculated simply as COLS × ROWS. That pixels array is defined as a field so it doesn't have to be recreated in every call to the Tick event handler. The data in the array must begin with the topmost row from left to right, then the second row and so on. The Tick event handler has two loops for the rows and columns of the bitmap, but it combines those two values into a one-dimensional array index:
int index = row * COLS + col;
WritePixels will not accept multi-dimensional arrays. The first argument to WritePixels is an Int32Rect structure in units of pixel coordinates to indicate the rectangular subset of the bitmap to update. The X and Y properties of the Int32Rect object describe the coordinates of the upper-left corner of the rectangle relative to the upper-left corner of the bitmap; the Width and Height properties indicate the pixel dimensions of this rectangle. For updating the entire bitmap, set X and Y to 0 and Width and Height to the bitmap PixelWidth and PixelHeight properties. I'll discuss the final two arguments to WritePixels shortly.
I must confess that I was intent on coding a rather different animated pattern for this bitmap, but the one that I stumbled upon here seems to be rather entertaining—at least in small doses. One of the images is shown in Figure 3.
Figure 3 AnimatedBitmapBrush Display
Arrays of Pixels
The mechanics of calling WritePixels can be more complex when the bitmap doesn't have a one-byte-per-pixel format and when only a rectangular subset of the bitmap is updated. It's an important technique to learn because the same array format of pixel bits is required in the static BitmapSource.Create method to create a new bitmap and in the CopyPixels methods of BitmapSource to copy pixel bits from a bitmap to an array. In all three methods you can alternatively use an IntPtr to point to a local buffer, but I'm going to focus on the array approach.
The total number of pixels in the bitmap is the product of the PixelWidth and PixelHeight properties defined by the BitmapSource class. BitmapSource also defines a get-only Format property of type PixelFormat, which itself defines a get-only property named BitsPerPixel that can range from 1 to 128. At one extreme, a single byte stores data for 8 consecutive pixels; at the other extreme, each pixel requires 16 bytes of data. You'll probably restrict yourself to arrays of byte, ushort, uint, or float for the pixel bits.
The Int32Rect object you supply to the WritePixels method defines a rectangular subset within the bitmap. The number of bytes in the pixel array must contain sufficient data for the number of rows and columns indicated by the Int32Rect object. This gets a little complicated because several pixel formats store multiple pixels in a single byte. For these formats, each row of data must begin on a byte boundary.
For example, suppose you're working with a bitmap with a format of 4 bits per pixel. The rectangular area of the bitmap that you're accessing or updating is 5 pixels wide and 12 pixels high. These are the Width and Height properties of the Int32Rect object you supply. The first byte in the array contains data for the first two pixels, the second for the next two pixels, but the third byte contains data for only the fifth pixel in the first row. The next byte corresponds to the first two pixels of the second row.
Each row of data requires 3 bytes, and the whole rectangular area requires 36 bytes. To help out with this calculation, the WritePixels method requires an argument called the stride. This is the number of bytes for each row of pixel data. The general calculation of the stride is this:
int stride = (width * bitsPerPixel + 7) / 8;
Width is equal to the Width property of the Int32Rect structure. Even if you use an array of ushort, uint, or float values, the stride value is always in units of bytes. You can then calculate the total number of bytes in the array like this:
int dimension = height * stride;
Divide by 2 or 4 or 8 if you're using an array of ushort, uint, or float, respectively.
You may recall that the Windows API required that each row of bitmap data begin on a 32-bit memory boundary so the stride had to be a multiple of four. This is not required in WPF. However, you can set the stride larger that the value calculated with the formula if that is convenient for you. For example, you might be working with a bitmap that has one byte per pixel, but your array is of type uint rather than byte. In this case, each element in the array stores four pixels. You might want to begin each row of the array on a unit boundary, even though that's not strictly required, because on many current hardware platforms, aligned copies are typically faster than unaligned copies.
Bitmap Pixel Formats
Each pixel in a bitmap is represented by one or more bits that define the color of that bitmap. In WPF, a particular pixel format is represented by an object of the structure type PixelFormat. The static PixelFormats class defines 26 static properties of type PixelFormat that you can use when creating a bitmap. These are shown in Figure 4, divided into two groups: writeable formats and non-writeable formats. With three exceptions (Bgr555, Bgr565, and Bgr101010), any number in the property name is the same as the number of bits per pixel.
Figure 4 Static Properties of the PixelFormat Class
Writeable Formats
Indexed1
Indexed2
Indexed4
Indexed8
BlackWhite
Gray2
Gray4
Gray8
Bgr555
Bgr565
Bgr32
Bgra32
Pbgra32
Non-Writeable Formats
Default
Bgr24
Rgb24
Bgr101010
Cmyk32
Gray16
Rgb48
Rgba64
Prgba64
Gray32Float
Rgb128Float
Rgba128Float
Prgba128Float
When creating a bitmap with BitmapSource.Create, you can use any of the static properties of the PixelFormats class except PixelFormats.Default. When creating a bitmap of type WriteableBitmap, you can only use the writeable formats.
The formats that begin with the word Indexed are those that require a ColorPalette object in the static BitmapSource.Create method or the WriteableBitmap constructor. Each pixel is an index into the ColorPalette object, so these four formats are associated with a maximum of 2, 4, 16, and 256 colors, respectively. The ColorPalette doesn't have to be as large as the maximum number of colors if the actual pixel bits don't go as high as they could.
For formats of fewer than 8 bits per pixels, the most significant bits in a byte correspond to the leftmost pixels. For example, with the Indexed2 format, a byte of 0xC9 is equivalent to the binary 11001001 and corresponds to four 2-bit values of 11, 00, 10, and 01. These, in turn, correspond to the fourth, first, third, and second colors in the ColorPalette collection.
The BlackWhite, Gray2, Gray4, and Gray8 formats are gray-shaded bitmaps with 1, 2, 4, or 8 bits per pixel. A pixel of all zeros is black and a pixel of all ones is white.
The remaining five writeable formats are color formats. The letters B, G, and R stand for the blue, green, and red primaries. The letter A stands for alpha channel and indicates that the bitmap supports transparency. The letter P stands for pre-multiplied alpha, which I'll discuss shortly.
The Bgr555 and Bgr565 formats both require 16 bits (or 2 bytes) per pixel. The Bgr555 format uses 5 bits for each color primary (thus allowing 32 gradations) with one bit left over. If the bits of the blue primary are represented by B0 (least significant bit) through B4 (most significant) and similarly for green and red, two consecutive bytes of data store the three primaries, as shown in Figure 5.
Figure 5 Two-Byte Pixel Format
Notice that the green bits spread over 2 bytes. This arrangement makes much more sense when you realize that the pixel is really a 16-bit unsigned integer with the least-significant byte stored first. The diagram in Figure 6 shows how the primaries are encoded in a single short integer.
Figure 6 Short Integer Pixel Format
Just so you can assure yourself that this is the case, the Gradient555Demo program shown in Figure 7 creates a bitmap of this format and writes pixels to it that display a gradient from blue on the left to green on the right. Notice that the dimension of the ushort array is just the product of the total rows and columns.
Figure 7 Gradient555Demo
class Indexed2Demo : Window
{
    const int COLS = 50;
    const int ROWS = 20;

    [STAThread]
    public static void Main()
    {
        Application app = new Application();
        app.Run(new Indexed2Demo());
    }
    public Indexed2Demo()
    {
        Title = "Bgr555 Bitmap Demo";

        WriteableBitmap bitmap = new WriteableBitmap(COLS, ROWS, 96, 96,
                                        PixelFormats.Bgr555, null);

        ushort[] pixels = new ushort[ROWS * COLS];

        for (int row = 0; row < ROWS; row++)
            for (int col = 0; col < COLS; col++)
            {
                int index = row * COLS + col;
                int blue = (COLS - col) * 0x1F / COLS;
                int green = col * 0x1F / COLS;
                ushort pixel = (ushort)(green << 5 | blue);
                pixels[index] = pixel;
            }

        int stride = (COLS * bitmap.Format.BitsPerPixel + 7) / 8;
        bitmap.WritePixels(new Int32Rect(0, 0, COLS, ROWS), pixels,
                           stride, 0);

        Image img = new Image();
        img.Source = bitmap;
        Content = img;
    }
}
This code demonstrates the advantage of using an array of a type other than byte that corresponds to the number of bytes per pixel. For any row and column pixel address, the array index is simply the column plus the product of the row times the number of pixels per column.
The Bgr565 format is very similar to Bgr555 except that it uses 6 bits for green (to which the eye is most sensitive). The remaining three writeable formats are much easier to work with. All use 4 bytes per pixel beginning with blue. In the Bgr32 format, the last of the 4 bytes is zero; there is no transparency. In the other two formats, the fourth byte is the alpha channel. The alpha value ranges from 0x00 for transparent to 0xFF for opaque. When the pixel is treated as an unsigned 32-bit integer, the least significant 8 bits encode blue, and the most significant 8 bits are either zero or the alpha channel.
In general, the ordering of bytes in the bitmap corresponds to the ordering of the letters B, G, R, and A in the property name. The list of non-writeable formats begins with several color formats that use only 16 or 24 bits per pixel. The Bgr101010 format uses 32 bits per pixel, but 10 bits for each primary. When the pixel is represented as a 32-bit unsigned integer, the least significant 10 bits are for blue. The Cmyk32 format encodes levels of cyan, magenta, yellow, and black used in printing.
The Gray16, Rgb48, Rgba64, and Prgba64 formats encode a 16-bit gray shade and 16-bit color primaries. If you work with hardware and applications that require this much color precision—medical imaging, for example—you might be quite happy that you can now store and display such high-resolution bitmap data. However, there is no real reason to use these formats otherwise. The additional color precision is ignored on 8 bit-per-primary color displays or when saving to 8 bit-per-primary file formats.
The list of pixel formats concludes with four formats that use single-precision floating point values to represent color levels and transparency. These formats are based on the scRGB color space and a gamma value of 1, rather than the customary sRGB color space and a gamma value of 2.2. (See pages 24-25 in my book, Applications = Code + Markup, for an explanation.) A floating-point color value of 0.0 corresponds to a byte value of 0x00 (black), and a floating-point color value of 1.0 corresponds to a byte value of 0xFF, but the floating-point color values might exceed 1 for display devices that have a wider color gamut than video displays.
PixelFormats Errata
There seems to be some confusion in the PixelFormats documentation about some formats. The Gray16, Rgb48, Rgba64, and Prgba64 formats are all documented as being based on a gamma value of 1, but—except for Gray16—they're also paradoxically documented as being an sRGB format. This is just not so. Only the Float pixel formats use the scRGB color format and a gamma value of 1.
You might want a generalized method to break apart pixels into their color components, or to construct pixels from color components. The PixelFormat structure contains a property named Mask that is a collection of objects of type PixelFormatChannelMask. There is one PixelFormatChannelMask object for each color channel in the order blue, green, red, and alpha.
The PixelFormatChannelMask structure defines a Mask property that is a collection of bytes, the number of which equals the number of bytes per pixel, and which correspond to the byte ordering of the pixel. For example, for the Bgr555 format, there are three PixelFormatChannelMask objects, each of which has 2 bytes. For blue, the 2 bytes are 0x1F and 0x00; for green, they are 0xE0 and 0x03; for red, they're 0x00 and 0x7C. If you want to use this data, you'll have to derive your own bit-shifting factors.
I said that you can use any of the PixelFormats members except for PixelFormats.Default for the BitmapSource.Create method, but only the writeable formats of Figure 4 for the WriteableBitmap constructor. If you examine the WriteableBitmap documentation, you'll discover an alternative constructor that creates a WriteableBitmap object from any BitmapSource object.
You can indeed first create a BitmapSource object from a non-writeable format of Figure 4 and then create a WriteableBitmap based on that BitmapSource. But don't assume you're getting around the restriction: any bitmap with a non-writeable format is converted to a Bgr32 or Pbgra32 format depending on the presence of an alpha channel.
You can save any bitmap that you create to a file in any of the supported file formats, specifically BMP, GIF, PNG, JPEG, TIFF, and Microsoft Windows Media Photo. However, the bitmap data might be converted to a different format in the process. For example, when saving as a GIF file, the bitmap is always converted first to an Indexed8 format. When saving as a JPEG file, the bitmap is always converted to either Gray8 or Bgr32. At the present time, there is no combination of PixelFormat and BitmapEncoder that will leave you with a file that contains more than 8 bits of data per color primary.
Premultiplied Alphas
Three of the static properties of the PixelFormats class begin with the letter P, which stands for Premultiplied Alphas. This is a technique used to improve bitmap rendering efficiency for pixels that are partially transparent. It only applies to bitmaps that have an alpha channel.
Suppose you created a SolidColorBrush with a color calculated like this:
Color.FromArgb(128, 0, 0, 255)
That's a blue brush with 50 percent transparency. When that brush is rendered, the color must be combined with the existing color of the display surface. Drawn against a black background, the resultant RGB color is (0, 0, 128). Against a white background, the resultant color is (127, 127, 255). It's a simple weighted-average calculation.
The subscripts in the following formulas indicate the result of rendering a partially transparent pixel on an existing surface:
Rresult = [(255 – Apixel) * Rsurface + Apixel * Rpixel] / 255;
Gresult = [(255 – Apixel) * Gsurface + Apixel * Gpixel] / 255;
Bresult = [(255 – Apixel) * Bsurface + Apixel * Bpixel] / 255;
This calculation can be sped up if the R, G, and B values of the pixel have already been multiplied by the A value and divided by 255. The second multiplication in each formula can then be eliminated. For example, suppose a pixel in a Bgra32 bitmap is the ARGB value (192, 40, 60, 255). In a Pbgra32 bitmap, the same pixel would be (192, 30, 45, 192). The RGB values have already been multiplied by the alpha value of 192 and divided by 255.
For any pixel in a Pbgra32 bitmap, none of the R, G, or B values should be greater than the A value. Nothing will blow up if that's not the case. The values are bound to a maximum of 255, but you won't get the level of transparency you want.
WriteableBitmap Applications
You might make use of WriteableBitmap in applications where you need to display some simple dynamic graphics—perhaps a bar chart—and you find that you can update a bitmap faster than WPF can draw the corresponding vector graphics.
Perhaps the most common application for WriteableBitmap is in performing real-time image processing and nonlinear transforms. The TwistedBitmap project lets you load any 8 bit-per-pixel or 32 bit-per-pixel bitmap and use a Slider control to twist the image around its center, as shown in Figure 8. Use smaller images for best results.
Figure 8 Twisted Bitmap
The program uses BitmapFrame.Create to load a bitmap from a file and then calls CopyPixels to copy all the pixel bits in an array named pixelsSrc. The SliderOnValueChanged event handler shown in Figure 9 is responsible for transforming the pixels from pixelsSrc into an array named pixelsNew that it uses for calling WritePixels.
Figure 9 Transform in TwistedBitmap
void SliderOnValueChanged(object sender,
                          RoutedPropertyChangedEventArgs<double> args)
{
    if (pixelsSrc == null)
        return;

    Slider slider = sender as Slider;
    int width = bitmap.PixelWidth;
    int height = bitmap.PixelHeight;
    int xCenter = width / 2;
    int yCenter = height / 2;
    int bytesPerPixel = bitmap.Format.BitsPerPixel / 8;

    for (int row = 0; row < bitmap.PixelHeight; row += 1)
    {
        for (int col = 0; col < bitmap.PixelWidth; col += 1)
        {
            // Calculate length of point to center and angle
            int xDelta = col - xCenter;
            int yDelta = row - yCenter;
            double distanceToCenter = Math.Sqrt(xDelta * xDelta +
                                                yDelta * yDelta);
            double angleClockwise = Math.Atan2(yDelta, xDelta);

            // Calculate angle of rotation for twisting effect
            double xEllipse = xCenter * Math.Cos(angleClockwise);
            double yEllipse = yCenter * Math.Sin(angleClockwise);
            double radius = Math.Sqrt(xEllipse * xEllipse +
                                      yEllipse * yEllipse);
            double fraction = Math.Max(0, 1 - distanceToCenter / radius);
            double twist = fraction * Math.PI * slider.Value / 180;

            // Calculate the source pixel for each destination pixel
            int colSrc = (int) (xCenter + (col - xCenter) *
                                Math.Cos(twist)
                (row - yCenter) * Math.Sin(twist));
            int rowSrc = (int) (yCenter + (col - xCenter) *
                                Math.Sin(twist)
                + (row - yCenter) * Math.Cos(twist));
            colSrc = Math.Max(0, Math.Min(width - 1, colSrc));
            rowSrc = Math.Max(0, Math.Min(height - 1, rowSrc));

            // Calculate the indices
            int index = stride * row + bytesPerPixel * col;
            int indexSrc = stride * rowSrc + bytesPerPixel * colSrc;

            // Transfer the pixels
            for (int i = 0; i < bytesPerPixel; i++)
                pixelsNew[index + i] = pixelsSrc[indexSrc + i];
        }
    }
    // Write out the array
    bitmap.WritePixels(rect, pixelsNew, stride, 0);
}
When working with bitmap transforms, it is crucial to perform the transform in reverse. If you examine every pixel in the original bitmap and determine where it should go in the new bitmap, it is very likely that different pixels in the original bitmap could map to the same pixel in the new bitmap. That means that some pixels in the new bitmap will not be set to any value! The image will have "holes."
Instead, for every pixel in the new bitmap, you must find what pixel in the original bitmap maps to that particular row and column. This approach ensures that every pixel in the new bitmap has a calculated value.

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

Charles Petzold is a Contributing Editor to MSDN Magazine. His most recent book is The Annotated Turing: A Guided Tour through Alan Turing’s Historic Paper on Computability and the Turing Machine.


Windows With C++
Decoding Windows Vista Icons With WIC
Kenny Kerr

Contents
The History of Windows Icons
The Windows Icon Format
A Basic Decoder
Discovery
What's Next
In the April issue of MSDN® Magazine I introduced the Windows® Imaging Component (WIC), showing you how you can use it to encode and decode different image formats. This month I'm going to show you how you can extend WIC by writing your own codecs. In particular, I'll walk through the initial steps for developing an alternative decoder for the Windows icon format. First, however, let me discuss the process of writing a codec.
For the most part, writing a codec is quite straightforward. A codec supporting the encoding of a particular image format must provide a COM class that implements the IWICBitmapEncoder interface. Similarly, a codec supporting the decoding of a particular image format must provide a COM class that implements the IWICBitmapDecoder interface. These are the same interfaces used by developers using WIC for image processing. In fact, the codec's COM classes are loaded in-process and accessed directly by the developer's application code. This provides a very efficient abstraction, allowing consumers to achieve high-performance image processing.
An encoder must also provide an implementation of the IWICBitmapFrameEncode interface, which supplies methods for encoding the individual frames of an image. Even image formats that don't support multiple frames still use the IWICBitmapFrameEncode interface to represent the image pixels. Similarly, a decoder must also supply an implementation of the IWICBitmapFrameDecode interface, which has methods for decoding the individual frames of an image.
Once the codec is written, it can be created directly by a consumer using the CoCreateInstance function, but that is not very interesting. To truly integrate the codec with WIC, a few more steps are required. In particular, the encoder and decoder must include additional metadata in the registry describing their capabilities. Any DLLs containing encoders or decoders must also be signed. The metadata allows WIC to identify whether or not the codec provides the necessary features when WIC attempts to find an appropriate encoder for a particular image format or a decoder for a particular image file. Since the particular implementation that a consumer receives may be determined at run time, WIC attempts to provide a certain degree of assurance to the consumer by only allowing signed codecs to participate in the discovery and arbitration process.
With the general concepts in place, I want to now take a look at a concrete example. I'll focus on the implementation of an alternative decoder of the Windows icon format. I chose the icon format for two reasons. Firstly, Windows Vista® introduced an update to the icon format, which is notable in itself; I'll explore the changes in a moment. Secondly, the built-in decoder that ships with Windows Vista does not actually support the updated icon format.

The History of Windows Icons
As with many facets of Windows, the icon format is steeped in history. In the early days of the 16-bit Windows operating system only the device-dependent bitmap (DDB) format was supported. Such a bitmap specified a width and height in pixels as well as a table that mapped pixels to entries in a particular device's color palette. Because different devices naturally supported different resolutions and had different color capabilities, these bitmaps were not easily moved from one device to another. DDBs were, however, very efficient and are in fact still used today for certain operations. A device-independent bitmap (DIB) format was introduced to correct all of the problems inherent in DDBs. Such a bitmap included its own color table independent of any particular device. The bitmap's pixels then mapped to the bitmap's color table, which unambiguously defined the pixel colors using red, green, and blue (RGB) color values.
Naturally, it made sense for the icon format to make use of the DIB format, but there was a problem. DIB predated the use of alpha channels for representing transparency. The hardware of the time also did not permit the extravagance of an extra byte per pixel that would have been required by an alpha channel. A different solution was required. The DIB would carry an extra bitmap following the color bitmap that was effectively a bitmask identifying the transparent and opaque pixels in the color bitmap. The bits in the bitmask could easily and, more importantly, efficiently, be combined with the target device's surface using Boolean operations by means of a bit-block transfer using the BitBlt function.
The icon format itself included multiple DIB structures, each with its associated bitmask for different sizes. This allowed a single icon to provide an image for different scenarios. For example, if an icon was displayed on the desktop, a 32×32 pixel DIB would be used. If an icon was displayed on a window's title bar, a 16×16 pixel DIB would be used. The icon format also needed to cater to different display capabilities, so additional DIBs with color tables of different sizes were also supported.
Eventually, icons could forgo the use of a color table and instead store 24 bits per pixel (bpp) directly, 8 bits per red, green, and blue value. This allowed for vibrant icons, but because a bitmask was still used to define the transparency, the edges were often quite harsh. Fortunately, icon bitmaps were usually small so this didn't prove to be a big problem.
During the development of Windows XP, Microsoft wanted to introduce larger, higher quality icons and the bitmask approach for specifying transparency just did not cut it. An alpha channel was required so that each pixel could have any degree of transparency, allowing for effects such as shadows. Icons in Windows XP started using 32bpp, accommodating an alpha channel where each pixel specified the degree of transparency it required. These icons still carried with them a bitmask for compatibility, but it was quite obvious when a legacy application incorrectly used the bitmask instead of the alpha channel as the icon's outline was often very jagged and lacked the shadows and other visual effects the icon's designers had intended. Nevertheless, an application properly written for Windows XP could include stunning 32bpp icons. Windows XP also began promoting larger icons (up to 48×48 pixels in size) further adding to the visual effect.
During the development of Windows Vista, Microsoft realized that the trend it had begun in Windows XP could not continue. Although the DIB format is very efficient at run time, as the bitmaps become larger they start consuming far too much space on disk and in memory. Increases in computing power meant that it was feasible to employ a far more capable image format, and Microsoft chose PNG. Icons in Windows Vista can embed PNG images instead of DIBs, and these are now used throughout Windows to allow icons to provide bitmaps 256×256 pixels in size at a stunning 32bpp and at a fraction of the space requirements that DIBs would demand. Figure 1 shows some icons in Windows Vista.
Figure 1 PNG-Based Icons in Windows Vista
Windows Vista takes advantage of these high quality PNG images inside of icons to create the illusion that icons are vector images that can be scaled from 16×16 pixels all the way to 256×256 pixels right in front of your eyes. ﻿If you want to see this in action, open Windows Explorer, hold the Ctrl key and scroll the mouse wheel. The effect is impressive. Of course Windows Vista goes beyond this by creating folder icons with a preview of the folder's contents, but this is beyond the scope of the icon format itself and a feature specific to Windows Explorer.

The Windows Icon Format
The structure of the icon format is depicted in Figure 2. The first WORD (2 bytes) is always 0. The second WORD is always 1. The latter can be thought of as the resource type. Icons and cursors happen to have a very similar format. The way to tell them apart is by checking the second WORD, which is always 1 for icons and 2 for cursors. The third WORD indicates the number of images that are contained within the icon.
Figure 2 Icon Format Structure
Following these three WORD values is a series of structures describing the images. The only values in this substructure that are truly necessary are the image size and image offset values. The rest of the values are merely a hint and should not be relied upon because they may not always be populated correctly. In most cases you should simply ignore them since you can learn everything you need to know about the images by inspecting the DIB or PNG image bits themselves. The image size indicates how many bytes are occupied by the image. The image offset indicates the offset from the beginning of the file to the start image bits.﻿

A Basic Decoder
Now let's take a look at developing a basic WIC decoder for icons. For the most part, it is just a matter of implementing the IWICBitmapDecoder interface appropriately. However, you'll need to know some information about the eight most important interface methods: QueryCapability, Initialize, GetFrame, GetContainerFormat, GetDecoderInfo, CreateComponentInfo, GetFrameCount, and GetFrame.
The QueryCapability method inspects a given stream and identifies whether or not it is capable of decoding the image. If it is, it indicates whether it can decode all the frames within the image (WICBitmapDecoderCapabilityCanDecodeAllImages) or only a subset of the frames (WICBitmap-DecoderCapabilityCanDecodeSomeImages). Other capability flags may also be specified. Remember to restore the stream position before returning. QueryCapability is where you might read the basic structure of the icon format I described in the previous section to ensure that it is what your decoder expects. You might also want to enumerate the images within the icon to ensure that they can be loaded.
The Initialize method provides the stream that the decoder should read from. Depending on the provided options, it should either load all frames immediately (WICDecodeMetadataCacheOnLoad) or only load them when they are specifically requested (WICDecodeMetadataCacheOnDemand) using the GetFrame method. In the case of the latter, you will need to hold onto the stream until all the frames have been loaded.
Here's something that I do and that you might find helpful: I find it useful to create a substream based on the image size and offset for each image in the icon and pass these substreams to my IWICBitmapFrameDecode interface implementations. Fortunately, the WIC imaging factory object that I introduced in my April 2008 column makes this quite easy. Figure 3 shows my CreateSubStream helper function for creating substreams with the help of the WIC stream object.
Figure 3 Creating Substreams
HRESULT CreateSubStream(IWICImagingFactory* factory,
                               IStream* stream,
                               ULONGLONG offset,
                               ULONGLONG maxSize,
                               IStream** subStream)
{
    ASSERT(0 != factory);
    ASSERT(0 != stream);
    ASSERT(0 != subStream);

    *subStream = 0;

    CComPtr<IWICStream> wicStream;
    HR(factory->CreateStream(&wicStream));

    ULARGE_INTEGER quadOffset = { 0 };
    quadOffset.QuadPart = offset;
    ULARGE_INTEGER quadMaxSize = { 0 };
    quadMaxSize.QuadPart = maxSize;

    HR(wicStream->InitializeFromIStreamRegion(stream,
                                              quadOffset,
                                              quadMaxSize));

    return wicStream.QueryInterface(subStream);
}
The GetContainerFormat method indicates the image format that the decoder represents. In this particular case, we can simply return the built-in icon container format identifier (GUID_ContainerFormatIco).
The GetDecoderInfo method returns an IWICBitmapDecoderInfo interface describing the decoder. Although not particularly complicated, the interface is quite large, and it would certainly be tedious to implement. Happily, it really only acts as an abstraction over the codec's metadata stored in the registry. The WIC API provides a stock implementation that you can take advantage of. Again, this is provided courtesy of the imaging factory object. If you look at Figure 4, you'll see a typical GetDecoderInfo implementation. All you need to do is pass the decoder's CLSID to the CreateComponentInfo method and it will create an object populated with the decoder's metadata from the registry.
Figure 4 Implementing GetDecoderInfo
HRESULT Kerr::IconDecoder::GetDecoderInfo(__out IWICBitmapDecoderInfo** decoderInfo)
{
    if (0 == m_imagingFactory)
    {
        return E_UNEXPECTED;
    }

    if (0 == decoderInfo)
    {
        return E_POINTER;
    }

    *decoderInfo = 0;

    CComPtr<IWICComponentInfo> componentInfo;

    HR(m_imagingFactory->CreateComponentInfo(__uuidof(IconDecoder),
                                             &componentInfo));

    return componentInfo.QueryInterface(decoderInfo);
}
As you might expect, the GetFrameCount method returns the number of frames within the image being decoded.
And finally, the GetFrame method returns an IWICBitmapFrameDecode interface representing a particular frame within the image.
So far I've talked about implementing the IWICBitmapDecoder interface. Given such an implementation, you would be able to use the CoCreateInstance to create an instance of the decoder, but with a little more work you could fully integrate your codec into the discovery and arbitration framework provided by WIC so that applications can automatically take advantage of it without prior knowledge of your codec.
Applications can take advantage of the available codecs on a particular computer in a number of ways. For starters, they can literally enumerate all of the encoders and decoders to find the one they want to use or to provide the user with the option of choosing a preferred codec. Look at Figure 5 for an example of how you can enumerate encoders. Note that the resulting IWICBitmapEncoderInfo interface provides a wealth of helpful information about the capabilities of each encoder.
Figure 5 Enumerating Encoders
HRESULT EnumerateEncoders()
{
    CComPtr<IWICImagingFactory> imagingFactory;
    HR(imagingFactory.CoCreateInstance(CLSID_WICImagingFactory));

    CComPtr<IEnumUnknown> enumerator;

    HR(imagingFactory->CreateComponentEnumerator(WICEncoder,
                 WICComponentEnumerateDefault, &enumerator));

    CComPtr<IUnknown> unknown;

    while (S_OK == enumerator->Next(1,
                                    &unknown,
                                    0)) // ignored
    {
        CComQIPtr<IWICBitmapEncoderInfo> info(unknown);
        unknown.Release();

        if (info)
        {
            CLSID clsid = { 0 };
            HR(info->GetCLSID(&clsid));

            UINT count = 0;

            HR(info->GetFriendlyName(0, // no buffer length
                                     0, // no buffer
                                     &count));

            CString friendlyName;

            HR(info->GetFriendlyName(count,
                                     friendlyName.GetBufferSetLength(count),
                                     &count));

            friendlyName.ReleaseBuffer(count - 1);

            TRACE(L"%s\n", friendlyName);
        }
    }

    return S_OK;
}
Alternatively, an application may want to rely on WIC to automatically select an appropriate codec. As I mentioned in my last column, the imaging factory provides the CreateDecoder method, allowing you to create a decoder for a particular image format without regard for its implementation. The CreateDecoderFromStream method goes further by choosing an appropriate decoder for you automatically by examining the stream and comparing that with the registration information from the available decoders on the computer.

What's Next
That's all for this month. Although the Windows Imaging Component doesn't fully support the new high-resolution icon format in Windows Vista, you can extend WIC with your own codec to handle it. At the end of the day, WIC is perhaps not that well suited for decoding icon images as there is no clear way to distinguish between different image frames with different resolutions but the exercise of writing a decoder is helpful in understanding how WIC is designed. The LoadImage function is still the best way to load icon images in most cases.

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. Reach Kenny at weblogs.asp.net/kennykerr.


Concurrent Affairs
Simplified APM With The AsyncEnumerator
Jeffrey Richter

Contents
Using My AsyncEnumerator Class
AsyncEnumerator's Architecture
Manipulating the Wait and Inbox Counters
Thread-Safe Morphing
Tune In for Even More
In my last column (msdn2.microsoft.com/magazine/cc163323), I introduced some concepts about how new C# language features—anonymous methods, lambda expressions, and iterators—could be used to simplify asynchronous programming. I ended that column showing how asynchronous programming could be accomplished using ﻿a synchronous programming model by way of a C# iterator. The example iterator is shown in Figure 1. However, you can't just use a normal C# foreach statement to execute the iterator's code because the code would always be executed by the thread calling foreach, and execution would run continuously without pausing for the asynchronous I/O operations to complete.
In this column, I introduce my AsyncEnumerator class, which intelligently drives an iterator so that different thread pool threads can execute the code at different times, and I ensure that the iterator only advances after asynchronous I/O operations complete. I am also going to explain the architecture of my AsyncEnumerator class and how it works.

Using My AsyncEnumerator Class
Here is the definition of my AsyncEnumerator class:
public class AsyncEnumerator {
   // Methods called by code outside of the iterator
   public AsyncEnumerator();
   public void Execute(IEnumerator<Int32> enumerator);

   // Methods called by code inside the iterator
   public AsyncCallback End();
   public IAsyncResult DequeueAsyncResult();
}
Using my AsyncEnumerator class is quite simple. Let's talk first about how to implement your iterator member and then I'll explain how to invoke it.
Define your iterator member to accept any parameters you want and add an additional parameter that is a reference to an AsyncEnumerator object. Your iterator member must be prototyped as returning a collection of Int32s; in other words, it must have a return type of IEnumerator<Int32>.
Then, inside your iterator member, start each asynchronous operation by calling the appropriate BeginXxx method. As you know, when you call a BeginXxx method, it is important that you pass it the name of a method that should be called when the asynchronous operation completes.
Instead of defining your own method, call the AsyncEnumerator object's End method. The End method returns an AsyncCallback delegate that identifies a private method defined inside my AsyncEnumerator class. So, as each asynchronous operation completes, code in an AsyncEnumerator object is notified. This code then places the IAsyncResult object for the completed operation into a List<IAsyncResult> object, which I refer to as the inbox.
In your code, after calling a BeginXxx method, place a yield return statement that returns the number of asynchronous operations that you've queued up. In Figure 1, since I called just one BeginXxx method (BeginRead), I yield return 1. The yield return statement suspends your iterator method and stops anymore code in it from executing.
Figure 1 C# Iterator
private static IEnumerator<Int32> ApmPatternWithIterator(
   AsyncEnumerator ae, String pathname) {
   using (FileStream fs = new FileStream(pathname, FileMode.Open,
      FileAccess.Read, FileShare.Read, 8192, FileOptions.Asynchronous)) {

      Byte[] data = new Byte[fs.Length];
      fs.BeginRead(data, 0, data.Length, ae.End(), null);
      yield return 1;

      Int32 bytesRead = fs.EndRead(ae.DequeueAsyncResult());
      ProcessData(data);
   }
}
I'll show other examples later where I yield return values other than 1, but, for many applications, returning 1 will be appropriate. The number you specify in a yield return statement tells the AsyncEnumerator object how many asynchronous operations need to complete before resuming your iterator. So, while your iterator is suspended, any asynchronous operations you initiated start completing. As each completes, an entry is added to the AsyncEnumerator's inbox. When the count of items in the inbox is equal to the number you specified in your yield return statement, the AsyncEnumerator object resumes your iterator and allows its code to continue executing.
Insights: AsyncEnumeration in Context
Using C# iterators to perform asynchronous processing is one part of a much larger set of challenges related to concurrent programming. Microsoft currently has several development initiatives that seek to address these challenges.
One of these is the Concurrency and Coordination Runtime (CCR), a more generic framework that can be used to address a variety of both asynchronous- and concurrency-related problems.
CCR includes an implementation for performing asynchronous enumeration using C# iterators. For example, the following demonstrates how you could asynchronously process a file using the iterators in the CCR:
IEnumerator<ITask> CcrIterator(string pathname) {
  var resultPort = new Port<IAsyncResult>();
  using (FileStream fs = new FileStream(pathname,
    FileMode.Open, FileAccess.Read, FileShare.Read,
    8192, FileOptions.Asynchronous)) {
      Byte[] data = new Byte[fs.Length];
      fs.BeginRead(data, 0, data.Length, resultPort.Post, null);
      yield return resultPort;
      IAsyncResult ar = resultPort;
      Int32 bytesRead = fs.EndRead(ar); }
    ProcessData(data);
  }
}
In addition to supporting iterators, CCR also provides extended support for exception handling and coordination primitives such as arbiters. For more information on CCR, check out the CCR User Guide (msdn2.microsoft.com/library/bb905447), the Concurrent Affairs column from September 2006 (msdn2.microsoft.com/magazine/cc163556), and CCR on Channel 9 (channel9.msdn.com/showpost.aspx?postid=219308).
—Howard Dierking, Editor-in-Chief
After the yield return statement, you call the corresponding EndXxx method. When you call an EndXxx method, you need to pass it an IAsyncResult object. Fortunately, the AsyncEnumerator object has been queuing these up in its inbox for you, so you just need to dequeue them by calling the AsyncEnumerator object's DequeueAsyncResult method. Items are dequeued from the inbox using a first-in-first-out (FIFO) algorithm.
Once the EndXxx method returns, you can process the result of the asynchronous operation directly inside the iterator! This is very cool, as you now have a synchronous programming model even though you're performing asynchronous operations.
In many scenarios, it is useful to now queue up yet another asynchronous operation by calling an additional BeginXxx method. In the iterator, you can call another BeginXxx method and then have another yield return 1 statement followed by calling the corresponding EndXxx method. This allows you to easily execute a sequence of asynchronous operations, one after another, without blocking any threads. Plus, you get to write all the code using a synchronous programming model!
As an example, the HtmlToFile iterator shown in Figure 2 reads HTML from a Web server in 1 kilobyte (KB) chunks and saves it to a local file. Invoking the iterator is very simple: you construct an AsyncEnumerator object, and then you call its Execute method, passing it the name of your iterator member. You can pass arguments to your iterator member, and you'll also need to pass a reference to the AsyncEnumerator object into your iterator so that the iterator can call the End and DequeueAsyncResult methods. Here is code that invokes the HtmlToFile iterator:
AsyncEnumerator ae = new AsyncEnumerator();
ae.Execute(HtmlToFile(
  ae,
  "http://www.Wintellect.com/",
  "LocalFile.html"));
Figure 2 HtmlToFile Iterator
private static IEnumerator<Int32> HtmlToFile(AsyncEnumerator ae,
   String url, String file) {

   // Issue asynchronous web request operation
   WebRequest webRequest = WebRequest.Create(url);
   webRequest.BeginGetResponse(ae.End(), null);
   yield return 1;

   WebResponse webResponse;
   try {
      webResponse = webRequest.EndGetResponse(ae.DequeueAsyncResult());
   }
   catch (WebException e) {
      Console.WriteLine("Failed to contact server: {0}", e.Message);
      yield break;
   }

   using (webResponse) {
      Stream webResponseStream = webResponse.GetResponseStream();

      // Read the stream data and write it to a file in 1KB chunks
      Byte[] data = new Byte[1024];
      using (FileStream fs = new FileStream(file, FileMode.Create,
         FileAccess.Write, FileShare.None, data.Length,
         FileOptions.Asynchronous)) {

         // See support.microsoft.com/kb/156932
         fs.SetLength(webResponse.ContentLength);

         while (true) {
            // Issue asynchronous web response stream read operation
            webResponseStream.BeginRead(data, 0, data.Length,
               ae.End(), null);
            yield return 1;

            // Get result of web response stream read operation
            Int32 bytesRead = webResponseStream.EndRead(
               ae.DequeueAsyncResult());
            if (bytesRead == 0) break; // Stream end: close file & exit

            // Issue asynchronous file write operation
            fs.BeginWrite(data, 0, bytesRead, ae.End(), null);
            yield return 1;

            // Get result of file write operation
            fs.EndWrite(ae.DequeueAsyncResult());
         }
      }
   }
}
My AsyncEnumerator's Execute method will not return until the iterator member either exits or executes a yield break statement. While the main thread is blocked, thread pool threads will continue to execute the iterator as asynchronous operations complete. All of this means that each part of your iterator's code could theoretically be executed by a different thread, and therefore your iterator code should not depend on a thread-specific state such as thread local storage, culture, UI culture, Principal, or priority.
By the way, having the thread that calls Execute block until the iterator is finished running is not something that I'm in love with. But it makes explaining how my AsyncEnumerator class works easier and can simplify experimentation and debugging. However, I want to point out that there is a way to get my AsyncEnumerator to not block while executing the iterator, and this is important in order to obtain scalability and responsiveness if you want to invoke an iterator from a GUI thread in a Windows® Form or a Windows Presentation Foundation (WPF) application. In the next installment of this column, I'll show you how to execute your iterator member asynchronously.

AsyncEnumerator's Architecture
My AsyncEnumerator class defines the private fields shown in Figure 3. The m_enumerator field refers to your iterator member, the constructor initializes this field to null, and Execute sets this field to the value passed to it. The m_inbox field refers to a collection of IAsyncResult objects. The m_waitAndInboxCounts field is a structure that contains two 16-bit integer values; I'll explain how these values get manipulated later in this column.
Figure 3 AsyncEnumerator Fields
public partial class AsyncEnumerator {
   // Refers to the iterator member's code
   private IEnumerator<Int32> m_enumerator;

   // Collection of completed async operations (the inbox)
   private List<IAsyncResult> m_inbox =
      new List<IAsyncResult>();

   // Structure with Wait & Inbox counters
   private WaitAndInboxCounts m_waitAndInboxCounts;
}
As I discussed in my last column, an iterator is really an easy way to get the compiler to create a class that implements the IEnumerator<T> interface. Normally, the way you advance through an IEnumerator<T> object is with the foreach statement. However, there is nothing stopping you from explicitly calling the IEnumerator<T> MoveNext method and Current property in code, which is exactly what my AsyncEnumerator class does.
AsyncEnumerator's Execute method internally calls a private method called ResumeIterator (shown in Figure 4). This method is responsible for starting the iterator and also for resuming it from a suspended state.
Figure 4 ResumeIterator
private void ResumeIterator() {
   Boolean continueIterating;

   // While there are more operations to perform...
   while (continueIterating = m_enumerator.MoveNext()) {

      // Get the value returned from the enumerator
      UInt16 numberOpsToWaitFor = checked((UInt16) m_enumerator.Current);

      // If inbox has fewer items than requested, keep iterator suspended
      if (!m_waitAndInboxCounts.AtomicSetWait(numberOpsToWaitFor)) break;

      // Inbox has enough items, loop to resume the iterator
   }

   // The iterator is suspended, just return
   if (continueIterating) return;

   // The iterator has exited, execute the iterator's finally code
   m_enumerator.Dispose();
}
When a thread calls ResumeIterator, it calls the IEnumerator<T> MoveNext method, which wakes up and runs the iterator. If the iterator exits or executes a yield break statement, then the IEnumerator<T> MoveNext method returns false, indicating that it has no more work to do. When my ResumeIterator method's continueIterating variable is set to false, it exits the loop and then calls the IEnumerator<T> object's Dispose method, allowing it to clean up. My ResumeIterator method then returns because the iterator has completed all its work.
On the other hand, if the enumerator object's MoveNext method returns true, then it has initiated some asynchronous operations and has suspended its execution by executing a yield return statement. My ResumeIterator method now needs to know what number the IEnumerator<T> object specified in its yield return statement. This number indicates the number of asynchronous operations that should complete before resuming the iterator. To get the number, ResumeIterator queries the enumerator object's Current property; this property returns the last value specified via a yield return statement.
ResumeIterator then calls the WaitAndInboxCounts AtomicSetWait method, which sets the number of items that the iterator should wait for. If AtomicSetWait sees that the number of items in the inbox is less than this wait count, then AtomicSetWait returns false, causing ResumeIterator to return because this thread has nothing else to do. If AtomicSetWait sees that the number of items in the inbox is greater than or equal to the wait count, then AtomicSetWait returns true and loops around, calling the enumerator object's MoveNext method again and allowing the iterator to resume execution so it can process the completed operations.
Inside the iterator, all BeginXxx methods pass the same method for the AsyncCallback method. This private method, called EnqueueAsyncResult, is acquired by calling AsyncEnumerator object's End method and is implemented like this:
private void EnqueueAsyncResult(IAsyncResult result) {
   // Add this item to the inbox
   lock (m_inbox) { m_inbox.Add(result); }

   // Add 1 to inbox count. If inbox has enough items
   // in it; this thread calls ResumeIterator
   if (m_waitAndInboxCounts.AtomicIncrementInbox())
      ResumeIterator();
}
In a thread-safe way, this method adds the completed operation's IAsyncResult object to the inbox and then calls the WaitAndInboxCounts AtomicIncrementInbox method, which adds one to the number of items in the inbox. If AtomicIncrementInbox sees that the number of items in the inbox is less than the wait count, then AtomicIncrementInbox returns false, which causes the thread pool thread to return to the pool so it can be used to perform other work.
If AtomicIncrementInbox sees that the number of items in the inbox is equal to the wait count, then AtomicIncrementInbox returns true and calls my AsyncEnumerator's ResumeIterator method, which in turn calls the enumerator object's MoveNext method, resuming the iterator's execution so it can then process the completed operations.

Manipulating the Wait and Inbox Counters
Each AsyncEnumerator object maintains a 16-bit Wait count and a 16-bit Inbox count; of course, both counts have a range from 0 to 65535. The Wait count indicates the number of asynchronous operations that must complete before the enumerator object is resumed. An iterator sets this value by way of its yield return statement. The Inbox count maintains the number of asynchronous operations that have completed. The Wait and Inbox counts must be modified and checked using thread-safe techniques since multiple threads could be executing asynchronous operation completion code concurrently while the iterator is also executing its yield return statement.
The fastest way to update these counts in a thread-safe manner is to put them both in a single Int32 and then to use interlocked methods to update the Int32. To make the code more readable and maintainable, I decided to define a WaitAndInboxCounts structure to manage these two counts (see Figure 5). The structure defines a private Int32 field and offers internal members to manipulate the Int32 in a thread-safe way. The AsyncEnumerator code calls these members.
Figure 5 Thread-Safe Wait and Inbox Counts
private struct WaitAndInboxCounts {
   private const UInt16 c_MaxWait = 0xFFFF;
   // Wait=High 16 bits, Inbox=low-16 bits
   private Int32 m_waitAndInboxCounts;

   private UInt16 Wait {
      get { return (UInt16) (m_waitAndInboxCounts >> 16); }
      set { m_waitAndInboxCounts = (Int32) ((value << 16) | Inbox); }
   }
   private UInt16 Inbox {
      get { return (UInt16) m_waitAndInboxCounts; }
      set { m_waitAndInboxCounts =
         (Int32)((m_waitAndInboxCounts &
            0xFFFF0000)|value); }
   }

   private WaitAndInboxCounts(Int32 waic) { m_waitAndInboxCounts = waic; }
   private Int32 ToInt32() { return m_waitAndInboxCounts; }

   internal void Initialize() { Wait = c_MaxWait; }

   internal Boolean AtomicSetWait(UInt16 numberOpsToWaitFor) {
      return InterlockedEx.Morph<Boolean, UInt16>(
         ref m_waitAndInboxCounts,
         numberOpsToWaitFor, SetWait);
   }

   private static Int32 SetWait(Int32 i, UInt16 numberOpsToWaitFor,
      out Boolean shouldMoveNext) {
      WaitAndInboxCounts waic = new WaitAndInboxCounts(i);
      // Set the number of items to wait for
      waic.Wait = numberOpsToWaitFor;
      shouldMoveNext = (waic.Inbox >= waic.Wait);

      // Does the inbox contain enough items to MoveNext?
      if (shouldMoveNext) {
         // Subtract the number of items from the inbox
         waic.Inbox -= waic.Wait;
         // The next wait is indefinite
         waic.Wait = c_MaxWait;
      }
      return waic.ToInt32();
   }

   internal Boolean AtomicIncrementInbox() {
      return InterlockedEx.Morph<Boolean, Object>(
         ref m_waitAndInboxCounts,
         null, IncrementInbox);
   }

   private static Int32 IncrementInbox(Int32 i, Object argument,
      out Boolean shouldMoveNext) {
      WaitAndInboxCounts waic = new WaitAndInboxCounts(i);
      // Add 1 to the inbox count
      waic.Inbox++;
      shouldMoveNext = (waic.Inbox == waic.Wait);

      // Does the inbox contain enough items to MoveNext?
      if (shouldMoveNext) {
         // Subtract the number of items from the inbox
         waic.Inbox -= waic.Wait;
         // The next wait is indefinite
         waic.Wait = c_MaxWait;
      }
      return waic.ToInt32();
   }
}
The two internal methods available are AtomicSetWait and AtomicIncrementInbox. Earlier in this column, I explained what these methods do. Now I'd like to explain how they do it, as this is a useful technique that could be used in many scenarios where you need to manipulate multiple values in an atomic fashion.
As I'm sure many of you are aware, the Microsoft® .NET Framework Class Library's Interlocked class offers several methods to manipulate an Int32 value in a thread-safe way. There are methods to increment an Int32 by 1, decrement an Int32 by 1, add a positive or negative value to an Int32, change an Int32 to a new value, check whether an Int32 is a specific value, and, if so, change it to another value. In short, the interlocked methods are great, but they offer just a few ways to manipulate an Int32.

Thread-Safe Morphing
In my very first Concurrent Affairs column (msdn.microsoft.com/msdnmag/issues/05/10/ConcurrentAffairs), I showed a well-known pattern for how to use the Interlocked class's CompareExchange method to manipulate an Int32 value in richer ways. Specifically, I showed how to perform an atomic bitwise AND, OR, or XOR operation on the Int32. However, it is easy to extend this pattern to perform atomic multiply, divide, min, and max operations, and many, many more.
In fact, what I decided to do was to extend the pattern by turning it into a generic method called Morph<TResult, TArgument>, which looks like this:
public static TResult Morph<TResult, TArgument>(ref Int32 target,
   TArgument argument, Morpher<TResult, TArgument> morpher) {

   TResult morphResult;
   Int32 i, j = target;
   do {
      i = j;
      j = Interlocked.CompareExchange(ref target,
         morpher(i, argument, out morphResult), i);
   } while (i != j);
   return morphResult;
}
When you call this method, you pass it (by reference) the Int32 whose value you wish to manipulate atomically; you can also pass an additional argument to be used by your morpher. Finally, you pass a method whose signature matches the Morpher delegate, defined as the following:
delegate Int32 Morpher<TResult, TArgument>(Int32 startValue,
   TArgument argument, out TResult morphResult);
Your Morpher method is passed the initial value in the target Int32 and the additional argument passed to Morph. The Morpher method applies any algorithm to the Int32 value and returns the desired new value. If the original Int32 value was not modified by another thread while the algorithm was executing its code, then the value in target is assigned the value returned by the Morpher method. If the original Int32 value was changed by another thread while the algorithm was executing its code, then the Morph method calls the Morpher method again, passing the new Int32 value (as modified by the other thread).
You'll notice that the Morpher method must also set an out parameter, morphResult. When Morph successfully modifies the target, this out parameter is the value that the Morph method returns to its caller. The beautiful thing about all of this is that the code inside the Morpher method does not have to be thread safe at all. It can be thousands of lines long and can perform several manipulations; the Morph method is responsible for ensuring that the original Int32 value is manipulated in a thread-safe way.
So now, with the Morph method and the Morpher delegate defined, I can use this infrastructure to implement the WaitAndInboxCounts AtomicSetWait and AtomicIncrementInbox methods.
Internally, AtomicSetWait calls Morph and passes it a Morpher method that sets the new Wait count to the value returned by the iterator's yield return statement. If the Inbox count is less than the new Wait count, then the new Wait count is set atomically. Also, false is returned to Morph's caller telling the caller that the enumerator object's MoveNext method should not be called since the iterator indicates that it wants to wait for more items to appear in the inbox.
If the Morph method sees that the Inbox count is greater than or equal to the new Wait count, then the Morph method subtracts the Wait count from the Inbox count (since it's logically removing these items from the Inbox) and the Wait count is set to its maximum (65535) so that items being added to the inbox (by other threads) won't cause the iterator to resume execution. However, when all of this executes successfully, the Morph method will return true to its caller and this thread will call the enumerator object's MoveNext method, resuming the iterator so that it can process the completed items that it was waiting for.
Internally, AtomicIncrementInbox calls Morph, passing it a Morpher method that adds 1 to the Inbox count. If the Inbox count is not equal to the current Wait count, then the Wait count is set atomically and false is returned to Morph's caller, telling the caller that the enumerator object's MoveNext method should not be called since the iterator indicates that it wants to wait for more items to appear in the inbox.
As with Morph, if the Morpher method sees that the Inbox count is equal to the current Wait count, then the Morpher method subtracts the Wait count from the Inbox count (since it's logically removing these items from the Inbox) and the Wait count is set to its maximum so that items being added to the inbox (by other threads) won't cause the iterator to resume execution. However, when all of this executes successfully, the Morph method will return true to its caller and this thread will call the enumerator object's MoveNext method, resuming the iterator so that it can process the completed items that it was waiting for.
The WaitAndInboxCounts structure defines some additional private members that are used internally to manipulate the Int32 value in a non-thread-safe way. The private constructor effectively casts an Int32 to a WaitAndInboxCounts structure. The private ToInt32 method returns the Int32 value inside of a WaitAndInboxCounts structure. Also, there are private Wait and Inbox properties to get and set the Int32 field's low and high 16-bit values.

Tune In for Even More
Many developers understand how valuable asynchronous programming is in allowing you to implement high-performance, scalable applications and components. However, in practice, many programmers have found the asynchronous programming model to be so difficult to use that they have avoided it, accepting poor performance in their applications. It is my hope that my AsyncEnumerator class, along with C# iterators, makes asynchronous programming so easy that programmers will embrace it, thereby improving the performance and scalability of their applications by reducing the number of threads and context switches.
In my next column, I will show additional features that my AsyncEnumerator class has to offer, and I will also show various usage patterns that it supports. Until next time.

Send your questions and comments for Jeffrey to mmsync@microsoft.com.

Jeffrey Richter is a cofounder of Wintellect (www.Wintellect.com), an architecture review, consulting, and training firm. He is the author of several books, including CLR via C#. Jeffrey is also a contributing editor to MSDN Magazine and has been consulting with Microsoft since 1990.


Going Places
Adaptable Apps For Windows Mobile
Michael Saffitz

Contents
Adaptable Applications
Design and Architecture
Display Differences
Resolution Awareness for Native Applications
Resolution Awareness for Managed Applications
Basic Device Differences
Other Device Differences
Testing and Further Exploration
When Microsoft first shipped Pocket PC 2000, and for a few years following, developers could relatively easily write one application that ran well on all devices. Generally, all devices had the same capabilities and characteristics: touch support, screen resolutions, portrait orientation, API sets, and so forth. Consequently, you could focus almost exclusively on your application's functionality. You didn't need to worry about these other elements of the device, and you definitely didn't need to worry about the potential that they could change.
But change is inevitable. As the market and technology developed, more and more devices became available, and these devices started to have divergent designs. Fast forward to 2008 and there are now more than 140 different Windows Mobile® phones available that support a variety of different options—12-key and QWERTY keyboards; candy bar and clam shell styles; with and without GPS; square, portrait, and landscape screens; Wi-Fi, Bluetooth, and infrared communications; and other capabilities that vary from device to device. Unlike Pocket PC 2000, it's now much easier for customers to find a device that matches their needs, tastes, and budget.

Adaptable Applications
This growth in the diversity of Windows Mobile devices, however, has made it necessary for developers to be aware of these differences and to plan for them in their applications. Developers now ﻿need to build what are called adaptable applications—apps that work well and look great on all Windows Mobile devices.
Fortunately, as an operating system, Windows Mobile offers one of the most consistent core API sets of any mobile platform across devices. Windows Mobile developers will find the same core API set (designed in many places to match those found on the desktop) regardless of the device's mobile operator or hardware manufacturer.
As a result, most developers building adaptable applications will find that addressing different display resolutions, dots per inch (DPI), and orientations will be the predominant area of focus. For a smaller number of developers, differences in device capabilities (such as presence of telephony, GPS, and so on), API changes between major releases of Windows Mobile, and designing to target both touch and non-touch devices will also be areas to consider.
I'm going to show you some of the tools and techniques that developers can use to build adaptable applications. I'll look at some general design and architecture principles and then dig into the specifics around adapting to differences in screens and capabilities.
While there's certainly some additional care and consideration that must be taken when you choose to build an adaptable application, the benefits of the upfront investment often far outweigh the alternative: developing and testing a version of your application against every current (and future) device, or electing to not support a device and, thus, limiting your potential user base.

Design and Architecture
When building adaptable applications, following time-tested practices and good architectural patterns is essential. From a practices perspective, by carefully and explicitly identifying your requirements, you can begin to understand the minimum device profile that your application needs. You'll also identify the optional capabilities that, when present, your application can use dynamically. In taking this approach, you can be sure that your application runs on the largest number of devices without having to code to the lowest common denominator.
As a brief example, let's say that I have been asked to build a simple package delivery tracking application. I investigated my requirements and determined that I need to collect signatures to indicate that a package has been successfully delivered. As a nice-to-have feature, the application should upload package status to a server for online tracking. As a result of the need to collect signatures, my application will be limited to touch devices (Windows Mobile Professional and Classic). Having identified this, I'm now free to use the additional functionality requiring touch (such as the button control).
At the same time, I should be careful about architecting the connectivity components. If I assumed my application would have access to cellular data connections, for example, I would unnecessarily eliminate Classic devices that don't contain a phone but could have Wi-Fi.
Finally, you should note that if my client changes her mind and removes the signature requirement, I wouldn't necessarily be able to support non-touch devices (Window Mobile Standard), given my subsequent use of the button control.

Display Differences
As mentioned earlier, the differences in screen resolution, DPI, and orientation is frequently the most pressing issue when building adaptable applications. Here too, planning for these differences and being thoughtful in your architecture will have significant impact when implementing your solution.
The currently supported Windows Mobile 6 resolutions, DPIs, orientations, and icon dimensions are shown in Figure 1. In addition to these, Microsoft occasionally adds new configurations, original equipment manufacturers (OEMs), and mobile operators. Also, some devices support dynamic screen orientation rotation. For example, a device with a 240×320 portrait display may rotate to a 320×240 landscape display when its keyboard slides out.
Figure 1 Windows Mobile 6 Display Options
Windows Mobile Professional and Classic (with Touch Screen)
Resolution | DPI | Orientation | Small Icon | Large Icon
240×240 | 96 | Square | 16×16 | 32×32
240×320 | 96 | Portrait and Landscape | 16×16 | 32×32
240×400 | 96 | Portrait and Landscape | 16×16 | 32×32
320×320 | 128 | Square | 21×21 | 43×43
480×480 | 192 | Square | 32×32 | 64×64
240×240 | 192 | Portrait and Landscape | 32×32 | 64×64
240×240 | 192 | Portrait and Landscape | 32×32 | 64×64
Windows Mobile Standard (without Touch Screen)
Resolution | DPI | Orientation | Small Icon | Large Icon
176×220 | 96 | Portrait | 16×16 | 32×32
240×320 | 131 | Portrait and Landscape | 22×22 | 44×44
320×320 | 131 | Square | 22×22 | 44×44
240×400 | 131 | Portrait and Landscape | 22×22 | 44×44
440×240 | 131 | Landscape | 22×22 | 44×44
More than ever, it's critical that your application not assume one or more screen characteristics and instead be written to dynamically adapt and support all resolutions, orientations, and at least 96 DPI and 131 DPI. (192 DPI is important, too, but tends to be limited to a very small number of devices. 128 DPI is close enough to 131 DPI to not cause major issues.)
There are several resources and tools available for both native and managed application development that make this task easier. I will look at a few of these and review some general approaches and best practices you can use when in the process of building resolution-aware applications.

Resolution Awareness for Native Applications
The Windows Mobile 6 SDK provides two primary resources for writing resolution-aware applications in native code: the reusable ScreenLib class in the UILayout sample and the DeviceResolutionAware.h header. The UILayout sample can be found in the \Samples\Common\CPP\Win32 directory of the Windows Mobile SDK. DeviceResolutionAware.h is installed to the \VC\ce\atlmfc\include directory of the Microsoft® Visual Studio® installation directory.
ScreenLib provides a set of helper functions for aligning elements on the screen. For example, you can use the DockControl function to dock a given control to a screen edge—or to all four edges, filling the client area. The OptimizeWidth and OptimizeHeight functions align and resize a control (or multiple controls, in the case of OptimizeWidth) with the display, leaving a small margin at the left and right or top and bottom, respectively. There are additional functions that provide for alignment of controls and for resizing a set of controls to be the same size. Given these functions, ScreenLib tends to be most useful when working heavily with form-based applications.
DeviceResolutionAware.h picks up where ScreenLib leaves off and provides more than 20 functions and macros that assist in building more complex adaptable applications. These start with basic functions and macros that provide the building blocks for adaptable user interfaces such as GetDisplayMode (which provides display characteristics and capabilities).
You'll find SCALEX, SCALEY, SCALERECT, and SCALEPT, which scale values appropriately for the current resolution. Next, there are functions such as StretchIcon and ImageList_StretchBitmap, which can help scale images for the current display characteristics. And functions such as RelayoutDialog can be used to automatically adjust the layout of a dialog when an orientation change occurs.
ScreenLib and DeviceResolutionAware.h provide a strong foundation on which to build your native resolution-aware applications. At the same time, however, it's important to note that they're not a substitute for designs and solutions that may be unique to your situations, especially when directly interacting with the display buffer or building complex UI.

Resolution Awareness for Managed Applications
For managed-code applications, the Microsoft .NET Compact Framework provides a set of display properties that can assist when creating applications that are resolution-aware. Similar to the functionality in ScreenLib, the .NET Compact Framework provides a Control.Dock property that will bind the specified control to an edge of its parent. Control.Anchor provides similar functionality by binding a control at a fixed distance from an edge of its parent. Using the Control.AutoScroll property will automatically add a scrollbar if the controls within the form do not fit on the display. Furthermore, Control.AutoScale tracks the resolution that the form was designed against, and it will dynamically scale the form if the DPI or resolution changes. As you might imagine, the Control.AutoScale property works well for simpler forms, but as your forms become more complex, the magic that it's able to perform becomes more limited.
For more complex forms, these properties provide a starting point, but they aren't necessarily a complete solution, especially when it comes to dynamically adjusting for orientation changes. One approach is to use the Orientation Aware Control (OAC) that the Microsoft patterns & practices group has released as part of the Mobile Client Software Factory (msdn2.microsoft.com/library/aa480471). The OAC delivers an easy way to target multiple orientations, especially for forms-based applications.
Once installed, the OAC allows you to use the managed form designer in Visual Studio to lay out your UI in a portrait mode and then, using the OAC, rotate to landscape. Once in this new orientation, you can adjust your UI as appropriate for landscape. The OAC will track the changes so that the appropriate layout will be used at run time when the end user is in portrait or landscape mode.
There are downsides, however, in using the OAC. First, the OAC is essentially allowing you to design specific orientation and resolution combinations; this approach is discouraged, as the supported orientations and resolutions can change in the future. It further doesn't allow you to explicitly design for different DPIs or for square screens that have recently become popular on Windows Mobile Standard-based smartphone devices. Finally, given that the OAC is creating and managing multiple layouts for each of your screens, there is a performance degradation that becomes more significant as you add additional forms and complexity (at the extreme, this can add noticeably to your application's launch time).
Because of these downsides, the Windows Mobile team has been encouraging developers to move away from the OAC. The group is releasing a new version of the Windows Mobile Line of Business Accelerator (go.microsoft.com/fwlink/?LinkId=115317) that includes a component to assist in building resolution-aware applications that have a single UI and make use of docking, anchoring, and other techniques.

Basic Device Differences
Despite the various tools, and even with the new accelerator, there's no single cure-all for writing adaptable applications. Each approach has advantages and disadvantages that need to be evaluated against your needs and situation. But regardless of the approach you take, there's some general guidance that may be helpful.
Start with the three basic orientations—square, portrait, and landscape—and think about how you'll lay out your UI for each. With this complete, you can then focus on ensuring that your UI will scale appropriately across the various resolutions and DPIs. For a complex UI, it may be easier to adjust the design and spread it across multiple forms than to keep it on a single form and rearrange it when an orientation change occurs.
As you implement your application for visual adaptation, it will become even more important to have a clean separation between your UI and your application's logic. By thinking of your UI as points of interaction and avoiding a form-based mindset, you can encapsulate your UI elements in management classes that centralize and abstract the details of how these elements map to individual forms.
It may be tempting to design exclusively for square screens, docking controls to the top and left, delivering a sort of adaptability by effectively reducing portrait and landscape orientations to square. But when you do this, you're robbing your application and the user of between one-third and two-thirds of potential screen real estate. Further, what at first appears to be a development time saver may end up taking more time—with even less screen real estate, you're forced to either design your UI more rigorously or include additional screens.

Other Device Differences
While addressing the differences in display characteristics is often the most significant portion of writing adaptable applications, there are other aspects as well. The version of Windows Mobile is important, as APIs have been introduced, modified, and deprecated over the years. There are device-specific capabilities that you may want to employ when they are available.
For these and other situations, it's still possible to write applications in a way that allows them to run on all devices. One technique for you to consider is the factory pattern, especially in combination with interfaces that define base capabilities and have device-specific implementations.
Let's look at a simple example that includes some of the design and requirements gathering practices discussed earlier. I've been asked to build a city guide that includes restaurant reviews. My core requirements are to include a directory of restaurants and reviews, and the ability to select and view a specific restaurant and read its review. My application must run on Windows Mobile 2003 and later versions. Finally, I have a requirement that when I'm using a device that provides telephony, I can directly call the restaurant from the review screen.
For this example, I'm going to use C#, but the concepts presented are applicable in Visual Basic® and C++ as well. The managed telephony APIs were first introduced in Windows Mobile 5.0, and, as a result, my app will need to know which version of Windows Mobile it's running on and use the appropriate implementation.
I'll start by creating a telephony interface that defines the common functionality I require, regardless of the device and any specific implementation:
interface ITelephony {
  bool HasPhone {
    get;
  }
  void MakeCall(string phoneNumber);
}
Next, Figure 2 shows my two implementations—one for devices prior to Windows Mobile 5.0 and one for devices running Windows Mobile 5.0 or later. For brevity, I've omitted the P/Invoke that is required on devices prior to Windows Mobile 5.0.
Figure 2 Implementing ITelephony
class PreWindowsMobile5 : ITelephony {
  public bool supportsTelephony {
    get { return File.Exists(@"\Windows\Phone.dll"); }
  }

  public void MakeCall(string phoneNumber) {
    // call Native Phone API
  }
}

class PostWindowsMobile5 : ITelephony {
  public bool supportsTelephony   {
    get { return SystemState.PhoneRadioPresent; }
  }

  public void MakeCall(string phoneNumber) {
    Phone thePhone = new Phone();
    thePhone.Talk(phoneNumber);
  }
}
Finally, I'll create a TelephonyFactory class that centralizes and isolates the different implementations from my app's core logic (see Figure 3). For this example, I've elected to have my TelephonyFactory class contain awareness of whether the device supports telephony, and in cases where it's not supported, throw an exception. Now, when I want to use telephony within my application, I can simply run the following:
try {
    ITelephony myTelephony =
      TelephonyFactory.GetTelephony();
    myTelephony.MakeCall(phoneNumber);
  }
  ...
Figure 3 TelephoneFactory
class TelephonyFactory {
  static ITelephony _myTelephony = null;

  public static ITelephony GetTelephony() {
    if (_myTelephony == null) {
      if (Environment.OSVersion.Version.Major >= 5)
        myTelephony = new PostWindowsMobile5();
      else
        myTelephony = new PreWindowsMobile5();
    }
    if ( ! myTelephony.supportsTelephony)
      throw(new NotImplementedException());

    return _myTelephony;
  }
}
Through the use of this pattern, I've isolated the differences that occur between devices and made the application easier to update and service, all while delivering adaptability and ensuring that my application can run on all Windows Mobile devices.

Testing and Further Exploration
Good design and attentive coding are two of three aspects to writing adaptable applications. Fortunately, the final aspect—testing—is made easier by the diversity of emulator images provided as part of the Windows Mobile SDK and in standalone packages. The emulator images allow you to test your application under almost all possible display characteristics, including dynamic rotation.
Additional tools in the SDK allow for the simulation of GPS functionality, multiple types of cellular networks, and even various security configurations, allowing you to test dynamic capability detection and use. Finally, much of the emulator environment is programmable through the Device Emulator Manager Automation APIs and the Core Connectivity Framework, allowing you to automate aspects of testing multiple device configurations.
Providing a platform where a single application can target a rich diversity of devices is just one way that Windows Mobile offers the best mobile development platform today. Whether you're a seasoned veteran or new to the platform, the Windows Mobile developer Web site (msdn.microsoft.com/windowsmobile) offers documentation, tutorials, and tools that, in concert with the broad APIs and advanced technologies, make the development possibilities on Windows Mobile limitless. Additional materials and up-to-date information about the adaptability issues discussed in this column are available at msdn.microsoft.com/windowsmobile/adaptyourapp.
Special thanks to Jim Wilson (pluralsight.com/blogs/jimw), whose "Adapt Your App" talks inspired and contributed material to this column.

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

Michael Saffitz is a Program Manager on the Windows Mobile Developer Experience team at Microsoft. He focuses on application compatibility, platform consistency, and ISV evangelism.


{ End Bracket }
Election Results Even Voters Can Trust
Josh Benaloh

Cryptography has numerous important and familiar applications including data privacy, identity authentication, and message integrity. But one surprising application is to the electoral process. I'm not merely speaking about encrypting voting data to preserve voters' privacy and ensuring that only authorized personnel have access to sensitive systems. Cryptography can be used to change the game completely—to allow every individual voter to check the accuracy and integrity of an election tally. What's most surprising is that this can be done entirely without trust in election equipment, software, or personnel.
But how is this possible? Don't I need to trust programmers, hardware vendors, system managers, or someone or something? Actually, no. To see this, imagine using Web postings for an open-ballot election. Voters post their names and votes to a public Web site which is frozen at the close of the election. The final contents of this site remain readable and are also published in local newspapers and other widely available media. All voters then have the opportunity to check that their own votes are properly listed, that all votes are from eligible voters, and that the tally matches the actual votes cast. The accuracy of the tally can be verified without having to trust anyone or anything. (Of course, denial-of-service attacks could prevent the successful completion of this or any election, but denial-of-service and other forms of cheating are public and easily detectable. The claim is simply that voters can tell whether or not an election is fair and accurate.)
The one thing that is missing from this simple, fully verifiable election is privacy, and this is where cryptography shines. Imagine that we modify the election process described above by asking voters to post their names and encryptions of their votes. We have now restored privacy, but we seem to have lost verifiability. With a little effort, however, we can also restore the elusive verifiability property. The goal will be to create a mathematical proof that the set of posted encrypted votes corresponds to a claimed election tally. If this can be done so that the proof can be checked by anyone, then we will have a secret-ballot election with full end-to-end verifiability—any voter or even a casual observer would be able to check the accuracy of the tally (something which can't be done with an ordinary paper trail or any other method in current use).
Simple encryption techniques do not have all the properties necessary here: we need the encryption function to be public; we need a robust, distributed decryption process so that no single entity can decrypt individual votes; and we need some special homomorphic properties that allow basic computations such as addition or multiplication to be performed directly on encrypted values without requiring intermediate decryption and re-encryption. Fortunately, the research literature contains several thoroughly studied encryption functions with exactly these properties. With such a function, we can build a system that allows individually encrypted votes to be combined or transformed to produce a tally together with a proof that the tally is correct. Voters would be able to check and see for themselves that their secret votes had been properly counted.
One question remains. How are voters to encrypt their votes? It might seem as though the publication of a public key should be enough to allow voters to encrypt their votes using their own equipment. But this would subject voters to coercion and vote buying—not to mention the possibility that their home machines may have been corrupted in order to change their votes.
A coercion-free election is best conducted by having votes cast in person at monitored poll sites. The monitoring forces voters to cast their votes in private—away from any undue influences. But this also forces voters to use equipment out their control. Several methods have been developed to allow voters to check that untrusted equipment is encrypting their votes properly—without enabling voters to prove how they voted to third parties. The difficulty is keeping things simple for voters by not forcing them to do anything more complicated than what is ordinarily required in current elections. One fairly simple approach is to unobtrusively provide voters with the option to either challenge or cast (but never both) any votes that have been encrypted on their behalf. This provides some confidence that the cast votes are also correct. The voter interface is the most active area of research on the subject, and newer and better methods for ordinary humans to verify the accuracy of an encryption are appearing with great rapidity. To learn more, visit research.microsoft.com/crypto/voting.

Josh Benaloh is Senior Cryptographer in Microsoft Research. He served eight years on the Board of Directors of the International Association for Cryptologic Research, and his extensive publications include his 1987 doctoral dissertation, "Verifiable Secret-Ballot Elections."