Table 6-1. List of Projects Within Exception Management Solution Project Name Description BootCamp.Orchestration. Contains the EAIProcess orchestration schedule and references the Exception.Process BootCamp.Orchestration.Exception.Schemas and Msft.Samples. BizTalk.Exception.Schemas projects as well as the Msft.Samples. BizTalk.Exception.dll assembly. BootCamp.Orchestration. Contains the schemas and maps used by the EAIProcess Exception.Schemas orchestration. BootCamp.Orchestration. Contains two orchestrations (EAIGenericHandler, Exception.FaultHandler EAIProcessHandler) that demonstrate strongly-typed and typeless options of using the Failed Orchestration Routing API. References the BootCamp.Orchestration.Exception.Schemas and Msft.Samples. BizTalk.Exception.Schemas project as well as the Msft.Samples. BizTalk.Exception.dll assembly. Add an exception handler to the Execution Scope shape and configure it to capture all System.Exceptions. Once the exception is generated, control will jump to the exception handler. Within the exception handler, you need to follow a fairly simple methodology: 1. Create a Fault message. 2. Add the ApprovedRequest message to the Fault message. 3. Add the DeniedRequest message to the Fault message. 4. Add the Exception object (caught by the exception handler) to the Fault message. 5. Publish the Fault message to the Messagebox. So, how would you do this? By using an API to enable this functionality, which is embod- ied within the two projects listed in Table 6-2. Table 6-2. Failed Orchestration Routing API Projects Project Name Description Msft.S amples.BizTalk. Contains all public methods for handling Fault-message processing within Exception orchestrations. The public methods are CreateFaultMessage, AddMesssage, SetException, GetException, GetMessage, and GetMessages. This assembly must be registered in the local GAC. Msft.Samples.BizTalk. Contains Fault message schema and system property schema. Deploys to Exception.Schemas the BizTalk.Sample.ExceptionMgmt application container. The Msft.Samples.BizTalk.Exception.Schemas project assembly must be referenced by ev er y B izTalk project that references or uses the Fault message schema. It contains two schemas, one that defines an instance of a Fault message (FaultMessage.xsd) and one that defines the property schema (System-Properties.xsd). These must be deployed in the BizTalk environment. The class outline is sho wn in Figure 6-16. CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES 235 6994ch06final.qxd 10/2/06 12:30 AM Page 235 The Msft.Samples.BizTalk.Exception.Schemas project must be referenced by all BizTalk projects that need to create an instance of the Fault message for publication. Many of the properties have been promoted or defined as distinguished properties. For the developer, the next step would be to define a Fault message using the FaultMessage.xsd schema reference. Once the message variable is created (name it FaultMsg) within the orchestration view window, an instance of it needs to be created within the Excep- tion Handler shape using the API exposed in the Msft.Samples.BizTalk.Exception project. Just as in the case of the Msft.Samples.BizTalk.Exception.Schemas project, the Msft. S amples.BizTalk.Exception project assembly must be referenced as well by all BizTalk projects that need to use the API. The API exposes public methods to create Fault messages, and man- age and retrieve them for processing, as described in Table 6-3. CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES236 Figure 6-16. Msft.Samples.BizTalk.Exception.Schemas project displaying the FaultMessage.xsd schema 6994ch06final.qxd 10/2/06 12:30 AM Page 236 Table 6-3. Public Failed Orchestration Routing API Class.Method Use Case Description ExceptionMgmt. Exception handler scope public static XmlDocument CreateFaultMessage() CreateFaultMessage Accepts no arguments. Returns an instance of the Fault message (XmlDocument), populated with the current orches- tration name and the orchestration instance ID (GUID). ExceptionMgmt. Exception handler scope public static void AddMessage(XLANGMessage AddMesssage faultMsg, XLANGMessage message) Accepts the created Fault message as the first argu- ment. Accepts any existing message instance within the orchestration as the second argument. This method will persist the added message instance and its message context properties into the Fault mes- sage and make it available for later retrieval via the GetMessage() API. Returns void. ExceptionMgmt. Exception handler scope public static void SetException(XLANGMessage SetException faultMsg, Object exception) Accepts the created Fault message as the first argu- ment. Accepts the existing Exception object caught within the exception handler as the second argument. This method will persist the Exception object into the Fault message and make it available for later retrieval via the GetException() API. Returns void. ExceptionMgmt. Subscriber/processor public static XLANGMessage GetMessage GetMessage (XLANGMessage faultMsg, string msgName) Accepts the received (via subscription) Fault mes- sage as the first argument. Accepts the name of the message previously added to the Fault message from the originating Orchestration Exception Handler shape. Returns the fully typed XLANGMessage that matches the msgName ar gument. The XLANGMessage will con- tain all or iginal context properties, including custom promoted properties. ExceptionMgmt. Subscriber/processor public static MessageCollection GetMessages GetMessages (XLANGMessage faultMsg) Accepts the received (via subscription) Fault mes- sage as the ar gument. Returns a MessageCollection class populated with all XL ANGM essages pr eviously added to the F ault message fr om the or iginating Orchestration Excep- tion H andler shape. The XLANGMessages will contain all original context properties, including custom promoted properties. Continued CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES 237 6994ch06final.qxd 10/2/06 12:30 AM Page 237 Table 6-3. Continued Class.Method Use Case Description ExceptionMgmt. Subscriber/processor public static System.Exception GetException GetException (XLANGMessage faultMsg) Accepts the received (via subscription) Fault mes- sage as the argument. Returns the System.Exception object previously added to the Fault message from the originating Orchestration Exception Handler s hape. FaultSeverity Exception handler scope Exposes public properties simulating the following and subscriber/processor enumeration: enum FaultCodes { Information = 0, Warning = 1, Error = 2, Severe = 3, Critical = 4 } Used to either set or compare against the FaultSeverity value in the Fault message. MessageCollection Subscriber/processor Returned by the ExceptionMgmt.GetMessages API. This class derives from an ArrayList and implements an enumerator allowing MoveNext() operations. CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES238 Using the APIs listed in Table 6-3, you can add the following shapes to your exception handler and execute the methodology previously discussed. Add the following to the EAIProcess orchestration’s exception handler: • Message Assignment shape enclosed within the Construct shape • Send shape (for Fault message) • Outbound Direct Bound Port (one-way) shape • Terminate shape • Send shape (for ApprovedRequest message) Next, set the Construct shape to create a new Fault message. Name the Fault message variable FaultMsg. Within the Message Assignment shape, add the following code: // Create Fault exception message FaultMsg.Body = Msft.Samples.BizTalk.Exception.ExceptionMgmt.CreateFaultMessage(); // Set Fault message properties FaultMsg.Body.Application = "EAI Process Application"; FaultMsg.Body.FailureCategory = "MessageBuild"; FaultMsg.Body.FaultCode = "1001"; FaultMsg.Body.FaultDescription = "Some error occurred"; FaultMsg.Body.FaultSeverity = Msft.Samples.BizTalk.Exception.FaultSeverity.Severe; FaultMsg.Body.Scope = "Execution Scope"; 6994ch06final.qxd 10/2/06 12:30 AM Page 238 / / Add each message you want to process later to the Fault message Msft.Samples.BizTalk.Exception.ExceptionMgmt.AddMessage(FaultMsg, ApprovedRequest); M sft.Samples.BizTalk.Exception.ExceptionMgmt.AddMessage(FaultMsg, DeniedRequest); // Add the exception object you may want to inspect later to the Fault message Msft.Samples.BizTalk.Exception.ExceptionMgmt.SetException(FaultMsg, _ sysExc); Lastly, set the Message property of the Send shape to use the FaultMsg message and con- nect the Send shape with the Outbound Direct Bound Port. Once complete, the orchestration should look like the one shown in Figure 6-17. CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES 239 Figure 6-17. Msft.Samples.B izT alk.E x ceptionM anagement solution displaying the EAIP r ocess orchestration 6994ch06final.qxd 10/2/06 12:30 AM Page 239 The orchestration described in Figure 6-17 receives the ApprovedRequest message and executes a map to create the DeniedRequest message. Within the execution scope it generates an exception by dividing by zero. An exception handler has been added to the scope to build the Fault message, set the properties on it, and publish it directly to the BizTalk Messagebox. Running the EAIProcess The EAIProcess orchestration can be started by binding the logical RequestPort port to a physical port configured to receive files from a folder. Once the project is built and deployed, ensure that there is a subscriber (send port) built for the Fault message and that it is enlisted and stopped; otherwise a persistence exception will be reported. Post a sample file into the folder being monitored, execute the orchestration, and generate the exception, thereby pub- lishing the Fault message. You can inspect the properties of the generated Fault message using the BizTalk Server 2006 Administration Console as displayed in Figure 6-18. Each message added to the F ault message in the ex ception handler gets persisted as dynamic message parts to the original Fault message. The Message Details dialog box illus- trates some of the niceties r esulting from the use of the Failed Orchestration Routing API. First, the message published fr om the ex ception handler is still defined as the F ault message CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES240 Figure 6-18. M essage D etails dialog box displaying pr oper ties of the suspended F ault message 6994ch06final.qxd 10/2/06 12:30 AM Page 240 derived from your FaultMessage.xsd schema as shown by the message type context property. However, notice two additional message parts listed in the left-hand pane. In the EAIProcess orchestration, the FaultMsg message variable was set to a multipart message type of one part, body. The API dynamically adds the individual messages as message parts to the current Fault message. If you examine the context properties of the Fault message (as shown in Figure 6-19), you can see all of the fault properties you set in the Message Assignment shape, as well as some that the API sets for you (i.e., ServiceName and ServiceInstanceID). Figures 6-20, 6-21, and 6-22 show the Message Details dialog box displaying the content of the or iginal ApprovedRequest and DeniedRequest messages. CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES 241 Figure 6-19. Message Details dialog box displaying the promoted properties of the suspended Fault message. These properties were set in the exception handler as well as within the API. 6994ch06final.qxd 10/2/06 12:30 AM Page 241 CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES242 Figure 6-20. Message Details dialog box displaying the content of the original Fault message pub- lished from the EAIProcess exception handler Figure 6-21. Message Details dialog box displaying the contents of the ApprovedRequest message that was added to the F ault message 6994ch06final.qxd 10/2/06 12:30 AM Page 242 Processing and Retrieving Messages and Exceptions from the Fault Message Having published the Fault message with the two persisted messages (ApprovedRequest and DeniedRequest) and a persisted Exception object from the EAIProcess orchestration, we’ll move forward and demonstrate how to extract the messages and the Exception objects in secondary orchestration schedules. There is really only one method for extracting an Exception object: the GetException() API. However, there are two methods for extracting messages. One provides a typeless method to retrieve all messages persisted to the Fault message. The other provides a strongly-typed approach. Typeless Message Retrieval The typeless approach is useful if you have a general logging need, or you don’t have access to the schema assembly used in the originating orchestration that persisted the messages. In this case, a collection of messages can be returned using MoveNext() to enumerate through them. This allows developers to inspect the message context properties and do whatever they want with them, e.g., process them, send them out to a SharePoint site, etc. For example, a generic orchestration exception process may do the following: • R etr ieve array of messages from Fault message. • Inspect context properties to determine message type or retrieve other context values. CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES 243 Figure 6-22. Message Details dialog box displaying the contents of the DeniedRequest message that was added to the Fault message 6994ch06final.qxd 10/2/06 12:30 AM Page 243 • Based on message type or other criteria, look up processing instructions via Business Rule Engine. • Process individual messages per business rule evaluation. This makes for an extremely decoupled exception processing solution. The EAIGenericHandler orchestration, located in the BootCamp.Orchestration.Exception. FaultHandler project, is a good example demonstrating the typeless approach and is shown in Figure 6-23. In this example, the orchestration is configured as follows: 1. The Receive shape is configured with a filter expression: (“Msft.Samples.BizTalk. Exception.Schemas.FaultCode” == “1001”). This effectively subscribes the orchestra- tion to any Fault messages published where the FaultCode equals 1001. 2. The Receive shape is bound to a direct bound receive port. 3. The Expression shape directly below the Receive shape has the following code snippet that calls the GetMessages() API: msgs = Msft.Samples.BizTalk.Exception.ExceptionMgmt.GetMessages(FaultMsg); The msgs variable is declared of type MessageCollection. This returns an array of mes- sages, including their original context properties, from the Fault message. 4. A Loop shape is configured to call msgs.MoveNext() 5. Within the Loop shape, an Expression shape is configured to retrieve the current message in the collection by calling TmpMsg = msgs.Current; TmpMsg is a message variable declared as a System.Xml.XmlDocument. 6. Each message in the collection is then published to a direct bound port. 7. A physical send por t is configured to serialize each message to a folder. ■Note Message Construct shapes are not necessary within the example. The API for the exception handler takes care of constructing new messa ges within the BizT alk runtime. When this orchestration executes, it will retrieve all the messages from the Fault mes- sage (i.e., ApprovedRequest and DeniedRequest) and serialize them to disk via the send port subscription. CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES244 6994ch06final.qxd 10/2/06 12:30 AM Page 244 [...]... context property values on the messages; the context properties were set from the originating orchestration (see Figure 6- 26) Figure 6- 26 Message Details dialog box displaying the properties of the ApprovedRequest message retreived from the Fault message using the GetMessage() API 69 94ch06final.qxd 10/2/ 06 12:31 AM Page 249 CHAPTER 6 s BIZTALK DESIGN PATTERNS AND PRACTICES s Note In Figure 6- 26, the... by the originating orchestration The EAIProcessHandler orchestration, located in the BootCamp.Orchestration Exception.FaultHandler project, is a good example demonstrating the strongly-typed approach The orchestration flow is shown in Figure 6- 24 245 69 94ch06final.qxd 2 46 10/2/ 06 12:31 AM Page 2 46 CHAPTER 6 s BIZTALK DESIGN PATTERNS AND PRACTICES Figure 6- 24 EAIProcessHandler orchestration demonstrating... state that applies to any BizTalk subsystem The final step would be to dynamically generate business intelligence data from the Fault messages going through the BizTalk environment That’s right; you call that BAM in BizTalk Server 20 06 15 Samples and compiled API to be provided for download at www.apress.com 249 69 94ch06final.qxd 250 10/2/ 06 12:31 AM Page 250 CHAPTER 6 s BIZTALK DESIGN PATTERNS AND... new instances BizTalk uses the default thread pool provided by the NET common language runtime (CLR); tuning the thread pool is simply a matter of setting the proper values in the BizTalk Server 20 06 Administration Tools for the particular BizTalk host With automatic throttling in BizTalk 20 06, you will not have to worry as much about their servers recycling, but tuning the server with the proper values... the instance before shutting itself down 265 69 94ch07final.qxd 266 10/2/ 06 12:38 AM Page 266 CHAPTER 7 s WHAT THE MAESTRO NEEDS TO KNOW: ADVANCED ORCHESTRATION CONCEPTS transaction scope Proper solution load testing and load modeling can give you indications of the number of persistence points over time, and contention over the database may be predicted and proper sizing of the servers implemented to... message RequestMsg = Msft.Samples .BizTalk. Exception.ExceptionMgmt.GetMessage(FaultMsg, "ApprovedRequest"); DeniedMsg = Msft.Samples .BizTalk. Exception.ExceptionMgmt.GetMessage(FaultMsg, "DeniedRequest"); 69 94ch06final.qxd 10/2/ 06 12:31 AM Page 247 CHAPTER 6 s BIZTALK DESIGN PATTERNS AND PRACTICES //Retrieve the System.Exception from the original service newExc = Msft.Samples .BizTalk. Exception.ExceptionMgmt.GetException(FaultMsg);... API call or a statement to properly optimize their algorithms, BizTalk developers need to understand the use and cost of orchestration shapes to properly optimize their orchestrations Table 7-1 lists the different orchestration shapes and describes what they are used for and what their cost is Table 7-1 Orchestration Shapes (Microsoft, BizTalk Server 20 06 Documentation,” 20 06) 5 Icon Shape Description... saved, the engine will not record that it has received the message and will receive it again upon restarting 69 94ch07final.qxd 10/2/ 06 12:38 AM Page 265 CHAPTER 7 s WHAT THE MAESTRO NEEDS TO KNOW: ADVANCED ORCHESTRATION CONCEPTS According to the BizTalk Server 20 06 documentation (Microsoft, 20 06) , the orchestration state is persisted under the following circumstances:11 • The end of a transactional scope... Transactional scopes cannot be nested inside nontransactional scopes or orchestrations • You can nest scopes up to 44 levels deep 10 Copyright © 20 06 by Microsoft Corporation Reprinted with permission from Microsoft Corporation 263 69 94ch07final.qxd 264 10/2/ 06 12:38 AM Page 264 CHAPTER 7 s WHAT THE MAESTRO NEEDS TO KNOW: ADVANCED ORCHESTRATION CONCEPTS • Call Orchestration shapes can be included inside scopes,... The InfoPath form is designed to submit repaired data to a BizTalk HTTP receive location configured under the receive port for the EAIProcess orchestration d DeniedMsg is published to a direct bound port e A physical send port is configured to serialize the message to a folder 247 69 94ch06final.qxd 248 10/2/ 06 12:31 AM Page 248 CHAPTER 6 s BIZTALK DESIGN PATTERNS AND PRACTICES 5 If repair is not needed: . PATTERNS AND PRACTICES2 36 Figure 6- 16. Msft.Samples .BizTalk. Exception.Schemas project displaying the FaultMessage.xsd schema 69 94ch06final.qxd 10/2/ 06 12:30 AM Page 2 36 Table 6- 3. Public Failed Orchestration. original context properties, including custom promoted properties. Continued CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES 237 69 94ch06final.qxd 10/2/ 06 12:30 AM Page 237 Table 6- 3. Continued Class.Method. context property values on the messages; the context properties were set from the originating orchestration (see Figure 6- 26) . CHAPTER 6 ■ BIZTALK DESIGN PATTERNS AND PRACTICES248 Figure 6- 26. Message