Transactional pipeline components and error handling

A question came up on the Commerce Server newsgroups recently about transactional pipeline components. It boiled down to: “What is the proper way to build a transactional SQL pipeline component?”. Well, it turns out there’s really nothing special you need to do. By default, any SqlConnection you create and use in your pipeline component will automatically enlist in the DTC transaction if there is one. According to this MSDN reference on Accessing the Current Transaction, “For database connections, ADO.NET checks Transaction.Current automatically when the Connection.Open method is called, and transparently enlists the connection in that transaction (unless the Enlist keyword is set to false in the connection string).”

I’ve included the sample component I built to test this out with the Commerce Server 2007 Starter Site, but the same code should work with a Commerce Server 2002 Feature Pack 1 site, I believe.

The proper way to use transactions with the checkout process is often misunderstood. You should mark the entire checkout page as transacted:

On the checkout page you need to run all three of the main pipelines together before committing the order: basket, total, and checkout, in that order. The checkout pipeline is the only one that needs to be configured as transacted in the Web.config. This just means a transaction is required for that pipeline to execute. The other pipelines will participate in the outer page transaction if one exists (to COM+ they are registered as transactions Supported, but not required). The Basket.SaveAsOrder() method will also participate in the transaction. Thus if any failure (or warning) is reported by any pipeline component in any of the pipelines, the transaction will be rolled back and the basket will remain in the pre-checkout state.

Pipeline components can report their completion status in a couple of different ways. If the component fails for some fatal/unrecoverable reason such as SQL server being unavailable, then the component can throw an exception. In COM terms, that means setting the HRESULT to the appropriate failure code and setting the IErrorInfo on the thread. For .NET components, they can simply throw an exception and let the CLR’s .NET interop facilities translate that into an HRESULT. Another way a component can denote failure (not recommended) is by returning a value greater or equal to Error (3). In this case the OrderGroup.RunPipeline() method will throw a PipelineExecutionException.

If the component excecutes successfully but needs to report a business validation error, it should return an error level of Warning (2). This indicates the component executed successfully but reported warnings (use Success (1) to indicate completion with no errors or warnings; you shouldn’t use an error level of zero as that’s not defined). A well-behaved component that reports such a warning should also add a string to either the _Basket_Errors or _Purchase_Errors lists, depending on which pipeline the component is associated with (_Basket_Errors for the basket and total pipelines and _Purchase_Errors for the checkout pipeline is the general guideline – the distinction is mostly legacy – you should check for and display messages from both lists as a rule).

A transactional pipeline will not vote to commit the transaction if the error level returned by a component is Warning (2) or Error (3) (or higher). You can find out the error level by checking the return value of OrderGroup.RunPipeline (a PipelineExecutionResult enum value). If it is Warning (2), the site code should be prepared to display any messages from the _Basket_Errors and _Purchase_Errors lists. These messages are usually retrieved by the pipeline component from the COM MessageManager object that is configured for the site (MessageManager is a legacy carryover from before the days of .NET ResourceManagers). MessageManager will return the localized display message corresponding to well-defined error code strings.

The below code sample is what I came up with for demonstrating and playing with this. To build this pipeline component,

• Create a C# class library project in VS.NET 2005
  
• Add references to Microsoft.CommerceServer.Interop.dll, Microsoft.CommerceServer.Shared.dll, and Microsoft.CommerceServer.Runtime.dll
  
• Configure the project to register components with COM so that a .tlb will be generated
  
• Regasm the assembly (with the /codebase option unless you are deploying it to the GAC)
  
• Use the pipeline registration tool in the Commerce Server SDK (pipereg.exe) to register the component as a pipeline component

After the component has been verified to execute correctly in your checkout scenario, to test out the rollback, the easiest thing to do is add a Scriptor component to the pipeline configured to execute after the sample component. Edit the scriptor (right click in pipeline editor and select “properties”, then click the “Edit Script” button) and modify it to return error level Warn (2) or Error (3) instead of the default value of Success (1). Note that if you get back error level Warn (2) from a transacted pipeline running on a page that is set to require transactions and ignore the return value and try to run OrderGroup.SaveAsOrder anyway, then .NET will complain loudly (by throwing an exception) because you’re trying to perform SQL operations within a DTC transaction that’s already been rolled back by the pipeline infrastructure. It looks like our CS2006 Starter Site currently has this bug – moral of the story – check that return value from the pipeline!

One more thing about pipeline error levels that is little known (not sure how useful it is, but that’s a different matter) is that in the pipeline editor you can configure the “error level tolerance” of each stage in the pipeline. This can be used to skip executing certain components (entire stages, really) when the error level is greater than the configured threshold. So for example if the error threshold for the Accept stage of the checkout pipeline is one (it is, trust me), then components in that stage will not execute if any component that came before returned an error level of two or greater. Also note that the final error level returned from pipeline execution is the greatest of the error level return values from all of the components executed within the pipeline.

The final figure below the code sample is the dump output showing all the keys and values in the entire OrderForm and PipelineContext dictionaries when my component was executed in the checkout pipeline of the CS2007 starter site (current builds). The technique I used to generate that HTML is just the few lines of code starting at line 59. The DumpUtils class in the Microsoft.CommerceServer.Runtime.Diagnostics namespace is very useful when it comes to inspecting Commerce Server object hierarchies that include the COM types such as Dictionary, SimpleList, and ContentList. DumpUtils is legacy code from CS2002 (and too tightly tied to System.Web.UI), so maybe one of these days I’ll find time to update that to emit XML that can be styled instead (that would be more useful, eh?).