Microsoft just unveiled the Azure Services Platform during the keynote address at the Professional Developer Conference this morning. Windows Azure promises to provide a flexible environment in the cloud for hosting high demand and high availability apps.

You can follow any new developments at the wiki which has been set up here: http://www.mycloudapp.net/

Business Activity Monitoring is a feature of BizTalk Server that allows businesses to capture important pieces of information throughout a BizTalk Solution. Once the information is captured, or recorded, any reporting tool such as SQL reporting services, Crystal Reports, or even Performance Point can view the information and display it in a very graphical/ statistical and possibly analytical way.

The baseline architecture in BAM is a "wiretap" pattern. Various BAM components live inside a BizTalk Solution to "spy" on various pieces of data, and events. This "wiretap" pattern is implemented through components the BAM infrastructure calls "Interceptors". Interceptors "intercept" data as it flows through the system, recording information such as Date and times, as well as the actual data at various stages of execution. Interceptors implement a "notification" or callback system. Every interceptor that exists inside of BAM contains two major functions; one to "intercept" or gather the data (check points), and another to listen for the interception and record it to the BAM data store. The interceptors use a rich non-blocking design to listen and record data; thus minimally affecting the overall performance of the whole system, while recording data.

BizTalk provides many interceptors out of the box for the three out of four major artifacts of a BizTalk solution. An interceptor is included for Adapters, Pipelines, and Orchestrations, and where there are missing areas, BizTalk provides a framework for manually invoking the interceptors through code (for example to handle maps).

Pipeline Interceptors are implemented through the Messaging Event Bus, while Orchestration Interceptors are implemented through the Orchestration Event Bus. Currently BizTalk only supports one type of Adapter interceptor, the WCF interceptor which is implemented through a Direct Event Bus. An Event Bus is commonly referred to as an "Event Stream". The Event Stream is none other than a group of classes that stream the captured data into the BAM Data store. There is also support for Windows Workflow, a WF Interceptor is implemented also through a Direct Event Bus. If these interceptors are not enough, BizTalk also provides a framework and example to create your own interceptors using the BAM application programming interfaces that support BizTalk Messaging, Orchestration and direct event busses which update the BAM Data stores.

No matter which interceptor you choose, the design is the same. An interceptor must be created and configured. Configuration of an interceptor requires information about the BAM Data store and BAM activity to record the data that is being tracked, and the actual data or event being tracked of course. How to configure the interceptor widely depends on the type of interceptors. Messaging and Orchestration interceptors utilize a graphical designer for configuration. This designer is known as the BizTalk Tracking Profile Editor (TPE). The output of the TPE is an XML file that contains the complete configuration of the Pipeline and Orchestration interceptors. The TPE also allows you to create the interceptors, and, in lack of a better word, "execute" them, or as in the words of the editor, "Apply the tracking profile". Configuration of the WCF and WF interceptors currently requires a manual configuration. Simply put, one must build this configuration file by hand. To help, BizTalk provides three base schemas: CommonInterceptorConfig.xsd, WCFInterceptorConfig.xsd, and WFInterceptorConfig.xsd, to help with the validation of an Interceptor Configuration file for WCF and WF. Configuration of the programmatic framework is done, as expected, inside of code.

The purpose of this article however, is not to explain how to use the TPE, nor use the BAM Framework, for this is discussed well in other documents. The purpose is to explain how the major components of the WCF interceptor work under the hood, in hopes to help eliminate some of the difficulty in using WCF Interceptors.

First off, to really understand how WCF Interceptors work, understanding of WCF extensible points are required. Here’s a couple a good architecture images to help explain what is being insinuated:

In the image above, WCF is best explained with three basic architectural layers: Data, ServiceModel and Channel. Each layer design is duplicated and created in both a Client Proxy application as well as a Server dispatcher application. The Data model contains the actual data or message flow of the data in and out the system. The Service Model layer contains the endpoints, addresses, contracts and binding elements that do not deal with protocols, encoding nor transports. The Channel layer deals with the protocol, encoding and transport binding elements.

The Extensibility Points:

WCF contains many areas where it can be extended to include features and customization not supported by default. These areas include Behaviors: Service, Operation, and Endpoints, as well as Custom binding elements, encoders, and transports. BizTalk contains a framework to build custom Binding Elements, encoders and transports known as the WCF LOB Adapter SDK. (See an upcoming article). For the WCF Interceptor, BizTalk has included a custom Endpoint Behavior, implemented specifically through the Parameter Inspector and Message Inspector classes to gather the BAM checkpoints, listen for various events, and create the direct event stream to record the data to the BAM database.

So let’s get dirty shall we???

The WCF BAM Interceptor allows a WCF Service (dispatcher) or WCF Client (proxy) to participate within a BAM activity by recording Key Performance Indicators (KPI’s) and events into the BAM Infrastructure. The interceptor provides for all the capabilities that BAM offers such as continuations, adding references to other documents, starting, updating, and completing BAM records. The WCF Interceptor accomplishes this using a WCF dispatcher or proxy configured to use the WCF BAM Endpoint Behavior. The endpoint behavior attaches itself to a WCF Endpoint, which is contained within a WCF Channel (Binding Element). Once the WCF Channel is opened, the endpoint loads all behaviors attached to it.

In the case of BizTalk server, in a WCF Receive adapter (a dispatcher), a WCF Channel is opened by means of a ServiceHost Base derived class that is created when you start an in process hosted receive location. In the case of an out of process hosted receive location, a Service Host factory derived class opens the WCF Channel. For all WCF Send adapters (proxies), the WCF Send adapter does a lazy initialization pattern. The Send adapter doesn’t create and open the WCF Channel until a subscription is fulfilled for the adapter. At this point internally a dynamic ChannelFactory is created using either IOutputChannel or IReqeustChannel interfaces to open the WCF Channel and send the message out. (See my WCF Sending Adapter blog for more details...)

The WCF Endpoint Behavior that is attached to one of these WCF Channels is found inside the Microsoft.BizTalk.Interceptors.dll. Within this assembly, you can find a BAMEndPointBehaviorExtension, which is a class that contains the implementation to read from a WCF Configuration section named BAMEndPointBehavior. [The actual name of the section is customized according to how it’s configured within the Machine.config file.] This Behavior extension class is used to create and apply the default values for the WCF BAM Endpoint Behavior, such as initializing the WCF BAM Interceptor, reading the connection string to the BAM Primary Import Tables (PIT) Database, and retrieving the polling interval in seconds that checks for new Interceptor configurations inside the BAM PIT. Once the behavior is applied, the interceptor is initialized, and the WCF BAM Interceptor is available until the WCF Channel is disposed. Through the WCF Framework, the WCF endpoint invokes the "ApplyClientBehavior" or "ApplyDispatchBehavior" method of the BAM Endpoint behavior depending on if a Dispatcher (service) or Proxy (client) endpoint has been configured to use it. Within this method call, the WCF BAM Interceptor is loaded and configured.

To expound on this further, the WCF BAM Interceptor is initialized internally by a WCF Configuration manager utility, which invokes even another utility named the InterceptorConfigurationManagement class that queries the BAM database using the bam_Metadata_GetLatestInterceptorConfiguration stored procedure. This stored procedure retrieves the latest version of a WCF BAM Interceptor configuration. The interesting point about this call is that the procedure returns a rowset of InterceptorConfigurations for a given Manifest and Technology. The Manifest and Technology are specified within the Interceptor Configuration file. When you "deploy" this file, the values as well as the configuration are stored inside the BAM database. Currently there are only two supported technology values: WCF and WF, with more possibly in the near future. This limitation is hardcoded within the WCF BAM interceptor and WF BAM Interceptor respectively. This effectively allows a BAM tracking profile to span multiple WCF Services, and Workflows (WF) by loading up multiple interceptor configurations, one for WCF and one for WF, for multiple BAM Activities that use the same .Net assembly which contain the ServiceContracts or Workflows respectively.

To be more WCF specific, you can have multiple interceptor configurations for a given ServiceContract. For WCF, the reason is simple, the manifest is the fully qualified name of the ServiceContract, and the fully qualified name of the assembly which the ServiceContract can be found. Specifying the Manifest and Technology is done using the EventSource section if the WCF interceptor configuration as such:

Above, the event source is names OrderServiceSource and the Technology being used is WCF, along with the OrderService.Contracts.IOrderService service contract located inside the OrderService.Contracts assembly.

One must take care because a BAM activity can be deployed that shares one or more manifests, that uses the exact same EventSourceName within another Interceptor configuration. When this happens, it is possible for the WCF BAM interceptor to record the wrong set of values, to the wrong BAM activity if a general "catch all" filter is applied within multiple interceptor configurations. An example of this is when you are using the WCF Generic Service contracts within a WCF Send adapter as well as with a WCF Client Service that sends BizTalk a message using the same Generic Service Contract. Let’s say a WCF Service is acting as a proxy to one of your BizTalk WCF Receive adapters. The code inside the WCF "proxy" service uses the IRequestChannel interface found inside the System.ServiceModel.Channels namespace. You track a BAM event inside the proxy service using the IRequestChannel interface found inside the System.ServiceModel assembly using an interceptor as such:

This proxy sends a message through a WCF Receive adapter, which through normal BizTalk publish-subscribe rounting forwards the message to a WCF Send Adapter, which also uses the IRequestChannel interface; you can easily see there’s a duplicate source here. Which source will be identified as the correct source? Also, let’s add to this mix that the WCF Send Adapter also uses another WCF Interceptor Endpoint behavior for two different BAM Activities, it is possible that the interceptor will catch WCF Events for the client sending BizTalk a message and record that to the BAM activity that the WCF Send adapter endpoint is using. This can also happen if the WCF Send Adapter or the Client proxy Service uses a filter that simply checks for a "ClientRequest" execution stage and nothing more. We’ll discuss filters in another article. In other words, if the Manifest, and eventSourceName and BAM activity are not unique enough, incorrect data could be applied, and if the filter is not specific enough to set a condition that only applies to the WCF Send adapter or the proxy WCF Service the same could occur.

To avoid the ambiguous issue, first thing is to try not to use the same EventSourceName and Manifest within different interceptor configuration files. Next, if you do use the same Manifest, create a different EventSourceName specific to the project being implemented. Also, look at the WCF client service sending data to BizTalk. If you own the WCF service, avoid using generic contracts when sending from a WCF Service to a BizTalk WCF Receive adapter when using this interceptor, and try to avoid using WCF Services that do the same.

Now, back to the WCF Configuration and Interceptor Configuration utilities, this process continues to poll the BAM DB every so often as configured by the polling interval, reconfiguring the BAM WCF Interceptor for a given endpoint, if need be.

Once the interceptor configuration is retrieved, it is returned as an Xml stream which is then used to configure the interceptor so that it can evaluate its configuration values against different WCF Events or stages of execution. WCF goes through different stages of execution in both a Message inspector and a Parameter Inspector. The stages found within a Message Inspector are four. There are the BeforeSendRequest and the AfterReceiveReply stages that occur inside a proxy; there are the BeforeSendReply and AfterReceiveRequest stages that occur inside a dispatcher. The WCF BAM interceptor also evaluates against the Parameter Inspector stages such as BeforeCall and AfterCall. Evaluation is also done within the Message and Parameter inspectors to check endpoint names as found inside WCF configurations, operation names, as well as the SOAP Header actions of messages, the content of a message, and SoapFaults, if properly configured.

Programmatically, the stages of execution are implemented as an enumeration called the ContractCallpoint. This enumeration is exposed by a method call to the developer within the Interceptor configuration as a WCF Operation named "GetServiceContractCallPoint". It is used within the interceptor configuration such as this:

This method returns one of these values: ClientReply, ClientRequest, ClientFault, ServiceReply, ServiceRequest, ServiceFault, CallbackRequest, CallbackReply, CallbackFault

Which value the method returns is determined by fairly simple rules. If the endpoint behavior is attached to a Dispatch (Service) endpoint, then the value will be one of the ServiceXXX values. If it’s attached to a Proxy (Client) endpoint, then the value will be one of either ClientXXX or CallbackXXX values. Let’s deal with ServiceXXX values first. If you want to filter when a Dispatcher, or a Service Host is receiving a request, you would use the ServiceRequest CallPoint. If you want to filter when a Service Host is sending a response/reply after receipt of a request, you’d use the ServiceReply. If you want to filter when the channel faults, throws an exception, within a ServiceHost you would use the ServiceFault.

Understanding the Proxy filters is just slightly more complex. If a client endpoint contains a Client side Dispatcher, in other words, a client callback contract for use in duplex communication patterns, the value returned from the method GetServiceContractCallPoint is CallBackXXX. If you want to filter when the duplex channel is receiving a request, you would use CallbackRequest. If you want to filter when the duplex channel is sending a response/reply after receipt of a request, you’d use the CallbackReply, and CallbackFault in case of a Duplex Client Side Service Fault. On the other hand, if a client proxy does not contain a Dispatcher, and you are simply sending data to another service, the ClientXXX value is returned. If you want to filter when the proxy sends a request to another service, you’d use the ClientRequest. If you want to filter when the proxy receives a response/reply after sending the request, you’d use the ClientReply, and use ClientFault if the proxy has a channel fault.

When you create a BAM WCF Interceptor configuration, you tell the interceptor which "event"/stages of execution that you’re interested in, and the stages are then filtered out using the BAM Endpoint Behavior, BAM Parameter Inspector, or BAM Message Inspector appropriately. The filter is configured inside the interceptor configuration using the "<Filter>" section of the Interceptor configuration. Such as the one below:

Once the stages of execution are matched through the filter, the WCF BAM Interceptor retrieves the collection of BAM tracking points that are configured within the Interceptor configuration using Correlation, and Update sections within the BAM Interceptor configuration, such as shown below:

These BAM track points must relate back to Key Performance Indicators defined within the deployed BAM activity this interceptor configuration refers to. The BAM Activity is configured in the BAM Activity section just below the EventSource section within an Interceptor Configuration. Multiple BAM activities sections are supported. Its configuration section looks like the following:

Above the BamActivity section defines a BAM Activity named OrderActivityMonitoring. This Bam Activity must already be deployed into the BAM PIT.

Now that you understand how the EventSource and BAM Activities relate, and how the Stages are matched, let’s revisit the ambiguity issue as outlined before. If you’re still not sure why you may receive incorrect updates due to duplicate event sources, the reasoning is simplified. In the example above, both a WCF proxy service sending to a BizTalk WCF Receive adapter, and a WCF Send Adapter, that happens to be running on the same computer, could be at the "ClientRequest" stage. Thus, the BAM WCF interceptor for the WCF Send Adapter endpoint, and the WCF proxy will have an interceptor configuration for both the client Service loaded in memory as well as the WCF Send Adapter interceptor configuration loaded into memory. The interceptor for the proxy configuration may be first in the list/collection after the bam_Metadata_GetLatestInterceptorConfiguration stored procedure call, and it will match the correct filters and possibly write whatever Update values to the BAM infrastructure for all Activities found in the list producing incorrect results. This doesn’t happen often, and with the correct design, can be totally avoided. Once the match has been determined, the KPI track points are then written using a DirectEventStream to the appropriate BAM activity rows.

In summary, this article addressed How The WCF BAM Interceptors work under the hood of the BizTalk BAM infrastructure, however not every aspect was covered. How the Filter is matched, why WCF and WF Interceptors use Reverse Polish Notation, how correlation is applied will be discussed in a future article... until then happy BAM’ng!!!

With the release of the .NET Framework 3.0, and then the .NET Framework 3.5 late last year, you might have settled down and started to integrate some of their more powerful features in your day to day programming. You may have absolutely fallen in love with LINQ, and embraced lambda expressions in C# 3.0. But have you taken a good look at WPF? WPF is not just for flashy effects, perfect transparency, and smooth animations. It's not limited to kiosks and Silverlight infused web pages. It provides base components out of the box that can blow your WinForms socks off -- and not just visually.

In this article I will pit System.Windows.Forms.TextBox against System.Windows.Controls.TextBox in a completely biased and unforgiving matchup, and give you 5 reasons why you should ditch the your old WinForms TextBox, and start using WPF. So grab the sample code, and follow along.

0.) It Works in a Windows Forms Environment

The rest of this article would kind of be pointless if this was not included, but you can use the WPF TextBox control from within a Windows Forms application. All you need to do is include some references, and add an ElementHost control to the form. I'm not going to get into specifics here, because there is plenty of coverage of this elsewhere.

1.) It Has Spell Checking Built-In

This is something that I'm surprised has not received more coverage. People get caught up in animations, and the ability to completely change the appearance of controls, and miss the fact that a simple task is now actually simple. You don't have to rely on your users having a $200 piece of productivity software installed to do spell checking on your "Approval Comments" field. You can just use a more intelligent TextBox.

So how much code does it take to get your WPF textbox to do what it's doing in the screenshot? Count for yourself:

But what if you want to actually make your application aware of the individual spelling errors themselves? There are methods provided for that as well. Here's an example of how you might use the built-in methods to build a Dictionary of character positions where spelling errors have occurred, and the text that is spelled incorrectly:

2.) It Has A Real Undo Stack

Have you ever written code that manually called the Undo method of the TextBox control, and been disappointed with the results. Spoilers follow for those who have not tried this: it only keeps track of the last state of the text. Since the advent of Adobe Photoshop* in the late middle ages, people have grown accustomed to programs being able to undo as many actions as they have done. Well with the WPF TextBox control that functionality is built-in. If you find implementing a custom Undo Stack fun, then cling tightly to the WinForms TextBox, if you would rather forego that task so that you can focus on a more important problems continue reading.

What code do you need to get it working? Check it out:

Oh yeah, and whereas the System.Windows.Forms.TextBox control has an Undo method, the WPF equivalent supports this beautiful couple:

Just be sure to never include those two lines of code one right after another like that. People have been immortalized for less.

3.) It Handles Lines Intuitively

Go ahead and click the screenshot to the left. Okay, pop quiz: What line is highlighted? If you said the line beginning with "Integer ac tortor", System.Windows.Forms.TextBox says you're incorrect. Many programmers might agree with the Windows Forms TextBox control, and that's because they're right. Technically the text is word wrapped, and the newline character doesn't occur until the very end of all of the text pictured. But looking at this from a user experience standpoint, it's terrible. When wrapped, that is the third line of text, not the first.

With the Windows Forms TextBox control, you access the lines of text through the Lines property of the control. Unfortunately, I can do that much myself by Splitting the Text property on '\n' and Trimming the result. The WPF TextBox control, on the other hand, does some heavy lifting for you. It can tell you what line, visually speaking, is the current line of text. It can also tell you what line that would be more mechanically speaking. Good luck trying to do that with the Windows Forms TextBox control, but here's how you might do it with the WPF Textbox:

4.) It Uses Anti-aliasing To Make Text Readable

Let's be honest, your grandma's web site makes use of anti-aliasing, and there's no reason your LOB app should avoid it. It's easier on the eyes, easier to read, and makes your text look great in any resolution. With the WPF TextBox control there is zero effort, configuration, or lines of code to achieve this effect. It's supported out of the box and always looks great.

5.) It's Included For Free in the Framework

Since WPF is included as part of version 3.5 of the .NET Framework, you can use it anywhere that you can install it. You don't have to buy a third party component to take advantage of all of the features of the new TextBox, it does not require Windows Vista, you don't need to install Expression Studio, and you don't have to write a line of XAML. You can use your favorite language to leverage the classes you need when and where you need them. You could even use it to implement spell check within an ASP.NET web application. Don't even think about reaching for Word Automation.

Conclusion

The WPF TextBox wins - use it. It also supports the aforementioned flashy effects, perfect animation, etc...

* - Save for Adobe Photoshop LE where they thought it would be fun to limit undo - shame on them

Over the past month I've been working really hard on our new BizTalk Expert Series class for Business Activity Monitoring. I have to say that I'm really excited to start teaching it. In three days, we manage to cover almost everything one could want to know about BAM. The most interesting part of it for me is the data consumption lab. I've never been very fond of the BAM Portal. It's nice, but certainly not something that I'd like to parade in front of a CEO of a big company. Don't get me wrong, the capabilities are awesome, but the way it looks and some of its behaviors aren’t the best. In the consumption lab, we examine how to create custom consumption models for BAM data using PerformancePoint, SQL Reporting Services, and an AJAX based web site. I'd never worked with PerformancePoint before and I was surprised by how easy it was to create a dashboard based on the BAM OLAP cube.

Last week while teaching the BizTalk Developer Immersion, I was demoing how to resume suspended messages using the BizTalk Group Hub. I submitted six messages while my send port was stopped, so all the messages were suspended. I was foolishly trying to show my students that if I resumed the message, it wouldn't be processed because the send port was in a stopped state. I resumed the message and it disappeared, actually, it went out through the send port. This confused me, I had six suspended messages, I resumed one and it was processed so I only had five. But why? I couldn't figure it out, the port is stopped, the message shouldn't be processed but if one went through why not all of them. I was stumped, then it occurred to me. If I were in production there are dozens of scenarios where I could have dozens or hundreds of messages in the MessageBox waiting for my send port to start, but before I actually start it all up, I want to send a few specific messages as a test. By stopping the port I can see all the messages that the port subscribes to and choose which ones should go through. So now I think it's pretty cool.

QuickLearn has just released a new series of BizTalk Server 2006 R2 training classes for advanced BizTalk developers. The Expert Series classes provide a drill-down on specific BizTalk features and toolsets that are currently covered only at a high level in our BizTalk Developer Immersion and BizTalk Developer Deep Dive courses. The Expert Series classes are 2-3 days long and cover BAM, RFID, ESB, EDI, BRE, and Testing. You can learn more about these classes here.

I was recently asked about how dynamic adapters work... Dynamic adapters enable the ability to register a Dynamic Adapter alias, or "scheme," that defines how the End Point Manager resolves which endpoint to configure. Each adapter registers its scheme using either the "AliasesXML" or "ProtocolAlias" registry keys. Below are the registered aliases for various BizTalk adapters:

 

Adapter	Registered Alias
WCF-NetMsmq	net.msmq://
FTP	ftp://
WCF-BasicHttp	http://
FILE	file://
SQL	sql://
SOAP	soap://
WCF-NetTCP	net.tcp://
SMTP	mailto://
MSMQT	Direct=
WCF-Custom	wcf://
MQSeries	MQS://
Windows SharePoint Services	WSS://
MSMQ	MSMQ://
WCF-NetNamedPipes	net.pipe://
wcf://	wcf://
HTTP	http://
WCF-WSHttp	http://

Students frequently ask my opinion on which BizTalk Books will be most helpful. I have reviewed several books, and will recommend a few of them here. I haven’t really seen any terrible BizTalk 2006 books (and believe me, I have seen some terrible technical books in the past!), so this is really a ranking of several really good books. It should be noted that many of the books below mention BizTalk Server 2006 R2 only in passing, because they were all written prior to the release of R2. I do not know if updates are planned for them.

In the interest of full disclosure, I should mention that QuickLearn has received a slew of books from Apress that we occasionally pass out in classes (thanks, Apress). Also, Darren Jefford, the author of one of the other books, is a friend and has provided signed copies of books that we have given away at various conferences. Despite my affiliations, I hope to provide a fair assessment of the literature.

The top of my list is Professional BizTalk Server 2006, by Darren Jefford, Kevin B. Smith, and Ewan Fairweather, published by Wrox Publishers. "Wrox" is pronounced like "Rocks," which is exactly what this book does. It’s very telling that, as I was writing this post, Amazon has eight listed reviews, and all eight give the book full marks (five stars) - I would definitely give it the same. Because this book assumes a moderate level of existing BizTalk knowledge, it is definitely not a good book to learn BizTalk from scratch (it's a great companion book to our Deep Dive). Nevertheless, it's a book by three guys who have been there, done that, and own the tee shirt when it comes to BizTalk implementation. This is a book that I refer to frequently.

Coming in at a close second on my list of favorites is Pro BizTalk 2006, by George Dunphy and Ahmed Metwally, published by Apress. (These books share more than a similarity in their names!) This is also an excellent book with very similar coverage to the Wrox book (Deep Dive level). If you own either of these books, you’re in good shape. I prefer the writing style of the authors of the Wrox book, but you may like this one better. Either one or the other of these is great, but you probably won’t need both.

If you’re looking for a book for someone totally new to BizTalk, consider Foundations of BizTalk Server 2006, by Daniel Woolston, published by Apress. This book contains good, concise description of common BizTalk terms (BizTalk vocabulary on steroids), and is a great pre-class primer for QuickLearn's BizTalk Server Developer Immersion. If you've already attended any of QuickLearn's BizTalk classes, you will probably find this book overly simple.

If you've identified a problem in your design/development, and you're looking for a quick way to solve it, your best choice is BizTalk 2006 Recipes: A Problem-Solution Approach, by Mark Beckner, Ben Goeltz, Brandon Gross, and Brennan O'Reilly, published by Apress. This may not be the best book for learning BizTalk from scratch, but it's a necessity for every BizTalk shop. This book takes a no-nonsense approach to "Here’s the problem, now how do I fix it?", and identifies the implementation of the patterns necessary to solve the problem.

Although not a BizTalk book, per se, a good general overview of messaging and other integration patterns can be found in Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions, by Gregor Hohpe and Bobby Woolf. DO NOT EXPECT TO LEARN ANYTHING ABOUT BIZTALK FROM THIS BOOK! I am recommending this book as an excellent resource about integration in general non-Microsoft terms; however, many BizTalk-related documents, available from Microsoft sources, reference the patterns revealed in this book. So do the BizTalk 2006 scenarios (more on these later, if you aren’t familiar with them). Gregor maintains a site http://www.eaipatterns.com that contains much of the information available in the book, but the book still makes a great paperweight, (it’s big and hardcover) J. I have been referencing it in my classes for so long that I thought I better mention it here as well.

Ever had the need to create an enumeration of values for a field or element within a BizTalk Schema? Did you know that you can store those values inside an Access database for synchronization with the enumeration values for the schema?

The BizTalk schema provides a CodeList feature that can be used to point to an Access 2003 database. When setting the appropriate properties, the values are pulled from the database and stored as enumerated values for the field/element.

In order to do this, create an Access database (MDB file extension) that has a table with a name that contains an underscore (e.g. Xml_OrderTypes). The table should contain at least 3 special columns: code, value, and desc (short for description). It can contain more columns than this; however, these column names are hard coded in the schema codelist feature to retrieve the enumerated values (see image below).

The code column allows you to specify a collection type that will then be used with an element/field's restricted, derivative CodeList property value. The value column will be the enumerated values added to the enumeration xs:restriction section of the schema. The desc column will contain the description of the each value, if populated, inside a dialog box that allows you to select which values are valid for a particular field/element within a schema. Populate the table with appropriate values for each column and save the database.

Next, create a standard schema and open its Schema node properties. There are a couple of properties that are used to enable the CodeList feature. First, set the CodeList Database path to a file path containing an Access 2003 database (see image below).

Next, set the Standard and StandardVersion properties to the name of the Access 2003 table containing the possible enumerated values. The algorithm is to set each respective property so that the concatenation of Standard and StandardVersion properties equals the Table Name within the Access 2003 database joined with an underscore. For example, if the Access 2003 database was named XmlSchemaTypes.mdb, and you have a table named SchemaTypes_v1, you should set the Standard property value to SchemaTypes and the StandardVersion property value to v1. You can use whatever naming scheme that you'd like, as long as it follows the algorithm (see image below).

Once you've set up the Access database and the schema standard properties, you can start creating fields/elements with their enumerated values from the Access database.

Next, create an element/field, set its Derived By property to Restriction, and type in the name of the collection type specified inside the Access 2003 database table for the CodeList property. For example, in the Access database image (first screenshot), the code column contains collection types for orderTypes, creditCardTypes, and cardTypes. If this element contains collections for OrderTypes, specify orderTypes as the value for the CodeList. When this property is set, you can successfully click the ellipsis (...) button next to it, invoking the display of a dialog box that shows all the possible enumerated values from the database. This gives you the opportunity to select all the values, or just a few for the element/field (see image below).

Select all the values you like for the allowable enumerations.

So how does it all work? After you've configured all the settings for the element/field, an annotation is added to the schema, allowing the BizTalk Schema editor to query the Access database table for the specified values. These values are added to the schema as an xs:enumeration-restriction, thus they are actually embedded into the schema with the values (see image below).

Whenever you need to update the values, reload the schema inside the designer, and reset the CodeList property.  This will reload the dialog, invoking the BizTalk editor to re-query the Access database.

Happy coding!!!

Here is a good question that I recently answered in a BizTalk Forum. I thought it would be of interest to others so I’m posting my response in this blog.

“I also have an orchestration that includes a custom .net component for writing BAM activities.  I'm utilizing serializable classes and strongly typed APIs (GenerateTypedBAMAPI tool) to write to the BAM db.  My question centers around how to access the unique Activity ID in my net code, which was initially created in the pipeline.   I presume that I have to pass this data to the orchestration.  I would really like to see an example of how this is done.”

This is a good question, not hard, just good!

You have a number of options here.  Logically, you need a way of storing the Activity ID and then passing it along to the orchestration from the time the message is processed through the pipeline to when it is processed inside the Orchestration. One way to keep track of this ActivityID is to push the id to the header section of the Message (aka… the MessageContext). To push it here you need to "Promote" the Activity ID value. However, property promotion does come at a cost because you're adding overhead to the message process for purposes of BAM Tracking.  If you are not concerned with the additional processing overhead then this option may work for you.

You can promote the value two ways, 1) you can use Property Field promotion, or 2) distinguished field promotion. Property Field promotion dictates that you need a special "property" schema deployed that contains a element and element type of the data (a string for ActivityID) that you are promoting eventually inside the pipeline.  Distinguished field promotion is just when you add a value to the MessageContext.

Code:
//For writing a distinguished field value
iinMsg.Context.Write( "/*[local-name()='MyBamInfo' and namespace-uri()='http://mycompany.com']/*[local-name()='ActivityID' and namespace-uri()='']", http://schemas.microsoft.com/BizTalk/2003/btsDistinguishedFields", ActivityID);
 
//Create and deploy a custom property schema, and add an element and derive it from the MessageContextPropertyBase (if not in message payload, otherwise MessageDataPropertyBase if it will be in the message: this is set underneath the Propery Base Schema property)
//For writing a property field value
inMsg.Context.Promote( "propertySchem.ActivityID", "http://schemas.microsoft.com/BizTalk/2003/system-properties", ActivityID);

In either case, you can use these promoted values inside the Orchestration instance for your BAM tracking purposes. Depending on whether you use Property Field or a Distinguished Field, the methods you use to access promoted values are going to be different. For Distinguished fields, you must use code within the orchestration to get the distinguished field values. Whereas, Property promoted values can be exposed with the Message(PropertySchema.ActivityID) syntax for the value that you promoted.
 
Another option is to add this ActivityID to your message schema and populate the ID within the message (inside the pipeline if you want) and then promote the values using either a Distinguished or Property field. Then you can access the values using the normal msg.ActivityID, or Msg(PropertySchema.ActivityID) options.

Note: if you're using continuation you don't want to call EndActivity within the pipeline component, because that will mark the activity instance record as "IsComplete" which commits the tracking record.

Here is a link for more help:
http://blogs.msdn.com/keithlim/archive/2006/02/08/527227.aspx
(It's kind of old but it's still good.)